.. _libdoc_config:

=======================================
:mod:`config` -- Theano Configuration 
=======================================

.. module:: config
   :platform: Unix, Windows
   :synopsis: Library configuration attributes.
.. moduleauthor:: LISA


Guide
=====

The config module contains many attributes that modify Theano's behavior.  Many of these
attributes are consulted during the import of the ``theano`` module and many are assumed to be
read-only.

*As a rule, the attributes in this module should not be modified by user code.*

Theano's code comes with default values for these attributes, but you can
override them from your .theanorc file, and override those values in turn by
the :envvar:`THEANO_FLAGS` environment variable.

The order of precedence is:

1. an assignment to theano.config.<property>
2. an assignment in :envvar:`THEANO_FLAGS`
3. an assignment in the .theanorc file (or the file indicated in :envvar:`THEANORC`)

You can print out the current/effective configuration at any time by printing
theano.config.  For example, to see a list  of all active configuration
variables, type this from the command-line:

.. code-block:: bash
    
    python -c 'import theano; print theano.config' | less

Environment Variables
=====================


.. envvar:: THEANO_FLAGS

    This is a list of comma-delimited key[=value] pairs that control
    Theano's behavior. A key that appears without an '=value' must be
    for a boolean value, and it acts as setting it to True.

    For example, in bash, you can override your :envvar:`THEANORC` defaults
    for <myscript>.py by typing this:

    .. code-block:: bash

        THEANO_FLAGS='floatX=float32,device=gpu0,nvcc.fastmath'  python <myscript>.py

    If a value is defined several times in ``THEANO_FLAGS``,
    the right-most definition is used. So, for instance, if
    ``THEANO_FLAGS='device=cpu,device=gpu0'``, then gpu0 will be used.

.. envvar:: THEANORC

    The location[s] of the .theanorc file[s] in ConfigParser format.
    It defaults to ``$HOME/.theanorc``.

    Here is the .theanorc equivalent to the THEANO_FLAGS in the example above:

    .. code-block:: text

        [global]
        floatX = float32
        device = gpu0

        [nvcc]
        fastmath = True

    Multiple configuration files can be specified by separating them with ':'
    characters (as in $PATH).  Multiple configuration files will be merged,
    with later (right-most) files taking priority over earlier files in the
    case that multiple files specify values for a common configuration option.
    For example, to override system-wide settings with personal ones,
    set ``THEANORC=/etc/theanorc:~/.theanorc``.

The rest of this page describes some of the more common and important flags
that you might want to use.  For the complete list (including documentation),
import theano and print the config variable, as in:

.. code-block:: bash
    
    python -c 'import theano; print theano.config' | less


Config Attributes
=====================

.. attribute:: device

    String value: either 'cpu', gpu, 'gpu0', 'gpu1', 'gpu2', or 'gpu3'

    Choose the default compute device for theano graphs.  Setting this to a
    gpu string will make the corresponding graphics device the default storage
    for shared tensor variables with dtype float32. 'gpu' let the driver select
    the gpu to use, 'gpu?' make theano try to use a specific device. If we are not
    able to use the gpu, we fall back to the cpu.

.. attribute:: force_device

    Bool value: either True or False

    Default False

    If True, we raise an error if we can't use the specified device. If False, we fall back to the cpu.
    Have precedence over the device flag.

.. attribute:: floatX

    String value: either 'float64' or 'float32'.

    Default: 'float64'

    This sets the default dtype returned by tensor.matrix(), tensor.vector(),
    and similar functions.  It also sets the default theano bit width for
    arguments passed as Python floating-point numbers.

.. attribute:: mode

    String value: 'FAST_RUN', 'FAST_COMPILE', 'PROFILE_MODE', 'DEBUG_MODE'

    Default 'FAST_RUN'

    This sets the default compilation mode for theano functions.

.. attribute:: home

    Default: env-variable $HOME

    This is used to compute the compiledir and base_compiledir attributes

.. attribute:: base_compiledir

    Default: $HOME/.theano

    This directory stores the architecture-dependent compilation directories.

.. attribute:: compiledir

    Default: $HOME/.theano/<arch-identifier>

    This directory stores dynamically-compiled modules for a particular
    architecture.

.. attribute:: blas.ldflags

    Default: '-lblas'

    Link arguments to link against a (Fortran) level-3 blas implementation.

.. attribute:: cuda.root

    Default: $CUDA_ROOT or failing that, "/usr/local/cuda"

    A directory with bin/, lib/, include/ folders containing cuda utilities.

.. attribute:: gcc.cxxflags

    Default: ""

    Extra parameters to pass to gcc when compiling.  Extra include paths,
    library paths, configuration options, etc.

.. attribute:: optimizer_excluding

    Default: ""

    A list of optimizer tags that we don't want included in the default Mode.
    If multiple tags, separate them by ':'.
    Ex: to remove the elemwise inplace optimizer(slow for big graph)
        use the flags: optimizer_excluding:inplace_opt
	inplace_opt is the name of that optimization.

.. attribute:: optimizer_including

    Default: ""

    A list of optimizer tags that we want included in the default Mode.
    If multiple tags, separate them by ':'.

.. attribute:: optimizer_requiring

    Default: ""

    A list of optimizer tags that we require for optimizer in the default Mode.
    If multiple tags, separate them by ':'.
