======================================
:mod:`mode` -- controlling compilation
======================================

.. module:: mode
   :platform: Unix, Windows
   :synopsis: controlling compilation
.. moduleauthor:: LISA

Guide
=====

The ``mode`` parameter to :func:`theano.function` controls how the
inputs-to-outputs graph is transformed into a callable object.

Theano defines the following modes by name:

- ``'FAST_COMPILE'``: Apply just a few graph optimizations and only use Python implementations.
- ``'FAST_RUN'``: Apply all optimizations, and use C implementations where possible.
- ``'DEBUG_MODE'``: Verify the correctness of all optimizations, and compare C and python 
    implementations. This mode can take much longer than the other modes, 
    but can identify many kinds of problems.

The default mode is typically ``FAST_RUN``, but it can be controlled via the
configuration variable :attr:`config.mode`, which can be
overridden by passing the keyword argument to :func:`theano.function`.

.. TODO::

    For a finer level of control over which optimizations are applied, and whether
    C or Python implementations are used, read.... what exactly?


Reference
=========

.. attribute:: FAST_COMPILE

.. attribute:: FAST_RUN

.. attribute:: DEBUG_MODE

.. attribute:: PROFILE_MODE

.. class:: Mode(object)

    Compilation is controlled by two attributes: the `optimizer` controls how
    an expression graph will be transformed; the `linker` controls how the
    optimized expression graph will be evaluated.

    .. attribute:: optimizer

        An :class:`optimizer` instance.

    .. attribute:: linker

        A :class:`linker` instance.

    .. method:: including(*tags)

        Return a new Mode instance like this one, but with an
        optimizer modified by including the given tags.

    .. method:: excluding(*tags)

        Return a new Mode instance like this one, but with an
        optimizer modified by excluding the given tags.

    .. method:: requiring(*tags)

        Return a new Mode instance like this one, but with an
        optimizer modified by requiring the given tags.

