.. _libdoc_config:

=======================================
:mod:`config` -- Aesara Configuration
=======================================

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


Guide
=====

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

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

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

The order of precedence is:

1. an assignment to ``aesara.config.<property>``
2. an assignment in :envvar:`AESARA_FLAGS`
3. an assignment in the ``.aesararc`` file (or the file indicated in :envvar:`AESARARC`)

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

.. code-block:: bash

    python -c 'import aesara; print(aesara.config)' | less

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


.. envvar:: AESARA_FLAGS

    This is a list of comma-delimited key=value pairs that control
    Aesara's behavior.

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

    .. code-block:: bash

        AESARA_FLAGS='floatX=float32,device=cuda0,gpuarray__preallocate=1'  python <myscript>.py

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

.. envvar:: AESARARC

    The location(s) of the ``.aesararc`` file(s) in `ConfigParser` format.
    It defaults to ``$HOME/.aesararc``. On Windows, it defaults to
    ``$HOME/.aesararc:$HOME/.aesararc.txt`` to make Windows users' life
    easier.

    Here is the ``.aesararc`` equivalent to the ``AESARA_FLAGS`` in the example above:

    .. code-block:: cfg

        [global]
        floatX = float32
        device = cuda0

        [gpuarray]
        preallocate = 1

    Configuration attributes that are available directly in ``config``
    (e.g. ``config.device``, ``config.mode``) should be defined in the
    ``[global]`` section.
    Attributes from a subsection of ``config`` (e.g. ``config.gpuarray__preallocate``,
    ``config.dnn__conv__algo_fwd``) should be defined in their corresponding
    section (e.g. ``[gpuarray]``, ``[dnn.conv]``).

    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 ``AESARARC=/etc/aesararc:~/.aesararc``. To load configuration files in
    the current working directory, append ``.aesararc`` to the list of configuration
    files, e.g. ``AESARARC=~/.aesararc:.aesararc``.

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

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

.. code-block:: bash

    python -c 'import aesara; print(aesara.config)' | less

.. attribute:: device

    String value: either ``'cpu'``, ``'cuda'``, ``'cuda0'``, ``'cuda1'``,
    ``'opencl0:0'``, ``'opencl0:1'``, ...

    Default device for computations. If ``'cuda*``, change the default to try
    to move computation to the GPU using CUDA libraries. If ``'opencl*'``,
    the OpenCL libraries will be used. To let the driver select the device,
    use ``'cuda'`` or ``'opencl'``. If we are not able to use the GPU,
    either we fall back on the CPU, or an error is raised, depending
    on the :attr:`force_device` flag.

    This flag's value cannot be modified during the program execution.

    Do not use upper case letters, only lower case even if NVIDIA uses
    capital letters.

.. attribute:: force_device

    Bool value: either ``True`` or ``False``

    Default: ``False``

    If ``True`` and ``device=gpu*``, we raise an error if we cannot
    use the specified :attr:`device`. If ``True`` and ``device=cpu``,
    we disable the GPU.  If ``False`` and ``device=gpu*``, and if the
    specified device cannot be used, we warn and fall back to the CPU.

    This is useful to run Aesara's tests on a computer with a GPU, but
    without running the GPU tests.

    This flag's value cannot be modified during the program execution.

.. attribute:: init_gpu_device

    String value: either ``''``, ``'cuda'``, ``'cuda0'``, ``'cuda1'``,
    ``'opencl0:0'``, ``'opencl0:1'``, ...

    Initialize the gpu device to use.
    When its value is ``'cuda*'`` or ``'opencl*'``, the aesara
    flag :attr:`device` must be ``'cpu'``.
    Unlike :attr:`device`, setting this flag to a specific GPU will not
    try to use this device by default, in particular it will **not** move
    computations, nor shared variables, to the specified GPU.

    This flag is useful to run GPU-specific tests on a particular GPU, instead
    of using the default one.

    This flag's value cannot be modified during the program execution.

.. attribute:: print_active_device

    Bool value: either ``True`` or ``False``

    Default: ``True``

    Print active device at when the GPU device is initialized.

.. attribute:: floatX

    String value: ``'float64'``, ``'float32'``, or ``'float16'`` (with limited support)

    Default: ``'float64'``

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

.. attribute:: warn_float64

    String value: either ``'ignore'``, ``'warn'``, ``'raise'``, or ``'pdb'``

    Default: ``'ignore'``

    When creating a TensorVariable with dtype float64, what should be done?
    This is useful to help find upcast to float64 in user code.

.. attribute:: deterministic

    String value: either ``'default'``, ``'more'``

    Default: ``'default'``

    If `more`, sometimes we will select some implementation that
    are more deterministic, but slower. In particular, on the GPU,
    we will avoid using AtomicAdd. Sometimes we will still use
    non-deterministic implementaion, e.g. when we do not have a GPU
    implementation that is deterministic. Also see the dnn.conv.algo*
    flags to cover more cases.

.. attribute:: allow_gc

    Bool value: either ``True`` or ``False``

    Default: ``True``

    This sets the default for the use of the Aesara garbage collector
    for intermediate results. To use less memory, Aesara frees the
    intermediate results as soon as they are no longer needed.
    Disabling Aesara garbage collection allows Aesara to reuse buffers
    for intermediate results between function calls. This speeds up
    Aesara by no longer spending time reallocating space. This gives
    significant speed up on functions with many ops that are fast to
    execute, but this increases Aesara's memory usage.

.. note:: if :attr:`config.gpuarray__preallocate` is the default value
    or not disabled (-1), this is not useful anymore on the GPU.

.. attribute:: config.scan__allow_output_prealloc

    Bool value, either ``True`` or ``False``

    Default: ``True``

    This enables, or not, an optimization in Scan in which it tries to
    pre-allocate memory for its outputs. Enabling the optimization can
    give a significant speed up with Scan at the cost of slightly increased
    memory usage.

.. attribute:: config.scan__allow_gc

    Bool value, either ``True`` or ``False``

    Default: ``False``

    Allow/disallow gc inside of Scan.

    If :attr:`config.allow_gc` is ``True``, but :attr:`config.scan__allow_gc` is
    ``False``, then we will gc the inner of scan after all
    iterations. This is the default.

.. attribute:: config.scan__debug

    Bool value, either ``True`` or ``False``

    Default: ``False``

    If True, we will print extra scan debug information.

.. attribute:: cycle_detection

    String value, either ``regular`` or ``fast```

    Default: ``regular``

    If :attr:`cycle_detection` is set to ``regular``, most inplaces are allowed,
    but it is slower. If :attr:`cycle_detection` is set to ``faster``,
    less inplaces are allowed, but it makes the compilation faster.

    The interaction of which one give the lower peak memory usage is complicated and
    not predictable, so if you are close to the peak memory usage, trying both
    could give you a small gain.

.. attribute:: check_stack_trace

    String value, either ``off``, ``log``, ``warn``, ``raise``

    Default: ``off``

    This is a flag for checking the stack trace during the optimization process.
    If :attr:`check_stack_trace` is set to ``off``, no check is performed on the
    stack trace. If :attr:`check_stack_trace` is set to ``log`` or ``warn``, a
    dummy stack trace is inserted that indicates which optimization inserted the
    variable that had an empty stack trace but, in ``warn`` a warning is also
    printed.
    If :attr:`check_stack_trace` is set to ``raise``, an exception is raised if a
    stack trace is missing.

.. attribute:: openmp

    Bool value: either ``True`` or ``False``

    Default: ``False``

    Enable or disable parallel computation on the CPU with OpenMP.
    It is the default value used when creating an Op that supports it.
    It is best to define it in ``.aesararc``
    or in the environment variable ``AESARA_FLAGS``.

.. attribute:: openmp_elemwise_minsize

    Positive int value, default: 200000.

    This specifies the vectors minimum size for which elemwise `Op`s
    use OpenMP, if OpenMP is enabled.

.. attribute:: cast_policy

    String value: either ``'numpy+floatX'`` or ``'custom'``

    Default: ``'custom'``

    This specifies how data types are implicitly figured out in Aesara, e.g. for
    constants or in the results of arithmetic operations. The 'custom' value
    corresponds to a set of custom rules originally used in
    Aesara (which can be partially customized, see e.g. the in-code help of
    ``tensor.NumpyAutocaster``), and will be deprecated in the future.
    The ``'numpy+floatX'`` setting attempts to mimic the numpy casting rules,
    although it prefers to use float32 numbers instead of float64 when
    ``config.floatX`` is set to ``'float32'`` and the user uses data that is not
    explicitly typed as float64 (e.g. regular Python floats).
    Note that ``'numpy+floatX'`` is not currently behaving exactly as planned (it
    is a work-in-progress), and thus you should consider it as experimental.
    At the moment it behaves differently from numpy in the following
    situations:

    * Depending on the value of :attr:`config.int_division`, the resulting type
      of a division of integer types with the ``/`` operator may not match
      that of numpy.
    * On mixed scalar and array operations, NumPy tries to prevent the scalar
      from upcasting the array's type unless it is of a fundamentally
      different type. Aesara does not attempt to do the same at this point,
      so you should be careful that scalars may upcast arrays when they
      would not when using numpy. This behavior should change in the near
      future.

.. attribute:: int_division

    String value: either ``'int'``, ``'floatX'``, or ``'raise'``

    Default: ``'int'``

    Specifies what to do when one tries to compute ``x / y``, where both ``x`` and
    ``y`` are of integer types (possibly unsigned). 'int' means an integer is
    returned (as in Python 2.X), but this behavior is deprecated. 'floatX'
    returns a number of type given by ``config.floatX``. 'raise' is the safest
    choice (and will become default in a future release of Aesara) and raises
    an error when one tries to do such an operation, enforcing the use of the
    integer division operator (``//``) (if a float result is intended, either
    cast one of the arguments to a float, or use ``x.__truediv__(y)``).

.. attribute:: mode

    String value: ``'Mode'``, ``'DebugMode'``, ``'FAST_RUN'``,
    ``'FAST_COMPILE'``

    Default: ``'Mode'``

    This sets the default compilation mode for aesara functions. By default the
    mode Mode is equivalent to FAST_RUN. See Config attribute linker and optimizer.

.. attribute:: profile

    Bool value: either ``True`` or ``False``

    Default: ``False``

    Do the vm/cvm linkers profile the execution time of Aesara functions?

    See :ref:`tut_profiling` for examples.

.. attribute:: profile_memory

    Bool value: either ``True`` or ``False``

    Default: ``False``

    Do the vm/cvm linkers profile the memory usage of Aesara functions?
    It only works when profile=True.

.. attribute:: profile_optimizer

    Bool value: either ``True`` or ``False``

    Default: ``False``

    Do the vm/cvm linkers profile the optimization phase when compiling an Aesara function?
    It only works when profile=True.

.. attribute:: config.profiling__n_apply

    Positive int value, default: 20.

    The number of Apply nodes to print in the profiler output

.. attribute:: config.profiling__n_ops

    Positive int value, default: 20.

    The number of Ops to print in the profiler output

.. attribute:: config.profiling__min_memory_size

    Positive int value, default: 1024.

    For the memory profile, do not print Apply nodes if the size
    of their outputs (in bytes) is lower than this.

.. attribute:: config.profiling__min_peak_memory

    Bool value: either ``True`` or ``False``

    Default: ``False``

    Does the memory profile print the min peak memory usage?
    It only works when profile=True, profile_memory=True

.. attribute:: config.profiling__destination

    String value: ``'stderr'``, ``'stdout'``, or a name of a
    file to be created

    Default: ``'stderr'``

    Name of the destination file for the profiling output.
    The profiling output can be either directed to stderr
    (default), or stdout or an arbitrary file.

.. attribute:: config.profiling__debugprint

    Bool value: either ``True`` or ``False``

    Default: ``False``

    Do a debugprint of the profiled functions

.. attribute:: config.profiling__ignore_first_call

    Bool value: either ``True`` or ``False``

    Default: ``False``

    Do we ignore the first call to an Aesara function while profiling.

.. attribute:: config.lib__amblibm

    Bool value: either ``True`` or ``False``

    Default: ``False``

    This makes the compilation use the
    `amdlibm <https://developer.amd.com/amd-cpu-libraries/amd-math-library-libm/>`__
    library, which is faster than the standard libm.

.. attribute:: config.gpuarray__preallocate

    Float value

    Default: 0 (Preallocation of size 0, only cache the allocation)

    Controls the preallocation of memory with the gpuarray backend.

    The value represents the start size (either in MB or the fraction
    of total GPU memory) of the memory pool. If more memory is needed,
    Aesara will try to obtain more, but this can cause memory
    fragmentation.

    A negative value will completely disable the allocation cache.
    This can have a severe impact on performance and so should not be
    done outside of debugging.

        * < 0: disabled
        * 0 <= N <= 1: use this fraction of the total GPU memory (clipped to .95 for driver memory).
        * > 1: use this number in megabytes (MB) of memory.

    .. note::

        This could cause memory fragmentation. So if you have a memory
        error while using the cache, try to allocate more memory at
        the start or disable it.

    .. note::

        The clipping at 95% can be bypassed by specifying the exact
        number of megabytes. If more then 95% are needed, it will try
        automatically to get more memory. But this can cause
        fragmentation, see note above.


.. attribute:: config.gpuarray__sched

    String value: ``'default'``, ``'multi'``, ``'single'``

    Default: ``'default'``

    Control the stream mode of contexts.

    The sched parameter passed for context creation to pygpu.  With
    CUDA, using "multi" mean using the parameter
    cudaDeviceScheduleBlockingSync. This is useful to lower the CPU overhead
    when waiting for GPU. One user found that it speeds up his other
    processes that was doing data augmentation.


.. attribute:: config.gpuarray__single_stream

    Boolean value

    Default: ``True``

    Control the stream mode of contexts.

    If your computations are mostly lots of small elements, using
    single-stream will avoid the synchronization overhead and usually
    be faster.  For larger elements it does not make a difference yet.
    In the future when true multi-stream is enabled in libgpuarray,
    this may change.  If you want to make sure to have optimal
    performance, check both options.


.. attribute:: config.gpuarray__cache_path

   Default: ``config.compiledir``/gpuarray_kernels

   Directory to cache pre-compiled kernels for the gpuarray backend.


.. attribute:: linker

    String value: ``'c|py'``, ``'py'``, ``'c'``, ``'c|py_nogc'``

    Default: ``'c|py'``

    When the mode is Mode, it sets the default linker used.
    See :ref:`using_modes` for a comparison of the different linkers.

.. attribute:: optimizer

    String value: ``'fast_run'``, ``'merge'``, ``'fast_compile'``, ``'None'``

    Default: ``'fast_run'``

    When the mode is Mode, it sets the default optimizer used.

.. attribute:: on_opt_error

    String value: ``'warn'``, ``'raise'``, ``'pdb'`` or ``'ignore'``

    Default: ``'warn'``

    When a crash occurs while trying to apply some optimization, either warn
    the user and skip this optimization ('warn'), raise the exception
    ('raise'), fall into the pdb debugger ('pdb') or ignore it ('ignore').
    We suggest to never use 'ignore' except in tests.

.. attribute:: assert_no_cpu_op

    String value: ``'ignore'`` or ``'warn'`` or ``'raise'`` or ``'pdb'``

    Default: ``'ignore'``

    If there is a CPU op in the computational graph, depending on its value;
    this flag can either raise a warning, an exception or stop the
    compilation with pdb.

.. attribute:: on_shape_error

    String value: ``'warn'`` or ``'raise'``

    Default: ``'warn'``

    When an exception is raised when inferring the shape of some apply
    node, either warn the user and use a default value ('warn'), or
    raise the exception ('raise').


.. attribute:: config.warn__ignore_bug_before

    String value: ``'None'``, ``'all'``, ``'0.3'``, ``'0.4'``, ``'0.4.1'``,
    ``'0.5'``, ``'0.6'``, ``'0.7'``, ``'0.8'``, ``'0.8.1'``, ``'0.8.2'``,
    ``'0.9'``, ``'0.10'``, ``'1.0'``, ``'1.0.1'``, ``'1.0.2'``, ``'1.0.3'``,
    ``'1.0.4'``,``'1.0.5'``

    Default: ``'0.9'``

    When we fix an Aesara bug that generated bad results under some
    circumstances, we also make Aesara raise a warning when it encounters
    the same circumstances again. This helps to detect if said bug
    had affected your past experiments, as you only need to run your
    experiment again with the new version, and you do not have to
    understand the Aesara internal that triggered the bug. A better
    way to detect this will be implemented. See this `ticket
    <http://www.assembla.com/spaces/theano/tickets/514>`__.

    This flag allows new users not to get warnings about old bugs, that were
    fixed before their first checkout of Aesara.
    You can set its value to the first version of Aesara
    that you used (probably 0.3 or higher)

    ``'None'`` means that all warnings will be displayed.
    ``'all'`` means all warnings will be ignored.

    It is recommended that you put a version, so that you will see future
    warnings.
    It is also recommended you put this into your ``.aesararc``, so this setting
    will always be used.

    This flag's value cannot be modified during the program execution.

.. attribute:: base_compiledir

    Default: On Windows: ``$LOCALAPPDATA\\Aesara`` if ``$LOCALAPPDATA`` is defined,
    otherwise and on other systems: ``~/.aesara``.

    This directory stores the platform-dependent compilation directories.

    This flag's value cannot be modified during the program execution.

.. attribute:: compiledir_format

    Default: ``"compiledir_%(platform)s-%(processor)s-%(python_version)s-%(python_bitwidth)s"``

    This is a Python format string that specifies the subdirectory
    of ``config.base_compiledir`` in which to store platform-dependent
    compiled modules. To see a list of all available substitution keys,
    run ``python -c "import aesara; print(aesara.config)"``, and look
    for compiledir_format.

    This flag's value cannot be modified during the program execution.

.. attribute:: compiledir

    Default: ``config.base_compiledir``/``config.compiledir_format``

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

    This flag's value cannot be modified during the program execution.

.. attribute:: config.blas__ldflags

    Default: ``'-lblas'``

    Link arguments to link against a (Fortran) level-3 blas
    implementation.  The default will test if ``'-lblas'`` works. If not,
    we will disable our C code for BLAS.

.. attribute:: config.experimental__local_alloc_elemwise_assert

    Bool value: either ``True`` or ``False``

    Default: ``True``

    When the local_alloc_optimization is applied, add an assert to highlight
    shape errors.

    Without such asserts this optimization could hide errors in the user code.
    We add the assert only if we can't infer that the shapes are equivalent.
    As such this optimization does not always introduce an assert in the graph.
    Removing the assert could speed up execution.

.. attribute:: config.dnn__enabled

    String value: ``'auto'``, ``'True'``, ``'False'``

    Default: ``'auto'``

    If ``'auto'``, automatically detect and use
    `cuDNN <https://developer.nvidia.com/cudnn>`_ if it is available.
    If cuDNN is unavailable, raise no error.

    If ``'True'``, require the use of cuDNN.  If cuDNN is unavailable, raise an error.

    If ``'False'``, do not use cuDNN or check if it is available.

    If ``'no_check'``, assume present and the version between header and library match (so less compilation at context init)",

.. attribute:: config.dnn__include_path

    Default: ``include`` sub-folder in CUDA root directory, or headers paths defined for the compiler.

    Location of the cudnn header.

.. attribute:: config.dnn__library_path

    Default: Library sub-folder (``lib64`` on Linux) in CUDA root directory, or libraries paths defined for the compiler.

    Location of the cudnn library.

.. attribute:: config.conv__assert_shape

    If True, AbstractConv* ops will verify that user-provided
    shapes match the runtime shapes (debugging option,
    may slow down compilation)

.. attribute:: config.dnn.conv.workmem

    Deprecated, use :attr:`config.dnn__conv__algo_fwd`.


.. attribute:: config.dnn.conv.workmem_bwd

    Deprecated, use :attr:`config.dnn__conv__algo_bwd_filter` and
    :attr:`config.dnn__conv__algo_bwd_data` instead.

.. attribute:: config.dnn__conv__algo_fwd

    String value:
    ``'small'``, ``'none'``, ``'large'``, ``'fft'``, ``'fft_tiling'``,
    ``'winograd'``, ``'winograd_non_fused'``, ``'guess_once'``, ``'guess_on_shape_change'``,
    ``'time_once'``, ``'time_on_shape_change'``.

    Default: ``'small'``

    3d convolution only support ``'none'``, ``'small'``, ``'fft_tiling'``, ``'guess_once'``,
    ``'guess_on_shape_change'``, ``'time_once'``, ``'time_on_shape_change'``.

.. attribute:: config.dnn.conv.algo_bwd

    Deprecated, use :attr:`config.dnn__conv__algo_bwd_filter` and
    :attr:`config.dnn__conv__algo_bwd_data` instead.

.. attribute:: config.dnn__conv__algo_bwd_filter

    String value:
    ``'none'``, ``'deterministic'``, ``'fft'``, ``'small'``, ``'winograd_non_fused'``, ``'fft_tiling'``, ``'guess_once'``,
    ``'guess_on_shape_change'``, ``'time_once'``, ``'time_on_shape_change'``.

    Default: ``'none'``

    3d convolution only supports ``'none'``, ``'small'``, ``'guess_once'``,
    ``'guess_on_shape_change'``, ``'time_once'``, ``'time_on_shape_change'``.

.. attribute:: config.dnn__conv__algo_bwd_data

    String value:
    ``'none'``, ``'deterministic'``, ``'fft'``, ``'fft_tiling'``, ``'winograd'``,
    ``'winograd_non_fused'``, ``'guess_once'``, ``'guess_on_shape_change'``, ``'time_once'``,
    ``'time_on_shape_change'``.

    Default: ``'none'``

    3d convolution only support ``'none'``, ``'deterministic'``, ``'fft_tiling'``
    ``'guess_once'``, ``'guess_on_shape_change'``, ``'time_once'``,
    ``'time_on_shape_change'``.

.. attribute:: config.magma__enabled

    String value: ``'True'``, ``'False'``

    Default: ``'False'``

    If ``'True'``, use `magma <http://icl.cs.utk.edu/magma/>`_ for matrix
    computations.

    If ``'False'``, disable magma.

.. attribute:: config.magma__include_path

    Default: ``''``

    Location of the magma headers.

.. attribute:: config.magma__library_path

    Default: ``''``

    Location of the magma library.

.. attribute:: config.ctc__root

    Default: ``''``

    Location of the warp-ctc folder. The folder should contain either a build,
    lib or lib64 subfolder with the shared library (libwarpctc.so), and another
    subfolder called include, with the CTC library header.

.. attribute:: config.gcc__cxxflags

    Default: ``""``

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

.. attribute:: cxx

    Default: Full path to g++ if g++ is present. Empty string otherwise.

    Indicates which C++ compiler to use. If empty, no C++ code is
    compiled.  Aesara automatically detects whether g++ is present and
    disables C++ compilation when it is not.  On darwin systems (Mac
    OS X), it preferably looks for clang++ and uses that if available.

    We print a warning if we detect that no compiler is present. It is
    recommended to run with C++ compilation as Aesara will be much
    slower otherwise.

    This can be any compiler binary (full path or not) but things may
    break if the interface is not g++-compatible to some degree.

.. attribute:: config.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``, where
    inplace_opt is the name of that optimization.

    This flag's value cannot be modified during the program execution.

.. attribute:: optimizer_including

    Default: ``""``

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

    This flag's value cannot be modified during the program execution.

.. attribute:: optimizer_requiring

    Default: ``""``

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

    This flag's value cannot be modified during the program execution.

.. attribute:: optimizer_verbose

    Bool value: either ``True`` or ``False``

    Default: ``False``

    When True, we print on the stdout the optimization applied.

.. attribute:: nocleanup

    Bool value: either ``True`` or ``False``

    Default: ``False``

    If False, source code files are removed when they are not needed anymore.
    This means files whose compilation failed are deleted.
    Set to True to keep those files in order to debug compilation errors.

.. attribute:: compile

    This section contains attributes which influence the compilation of
    C code for ops.  Due to historical reasons many attributes outside
    of this section also have an influence over compilation, most
    notably 'cxx'.  This is not expected to change any time soon.

.. attribute:: config.compile__timeout

    Positive int value, default: :attr:`compile__wait` * 24

    Time to wait before an unrefreshed lock is broken and stolen.  This
    is in place to avoid manual cleanup of locks in case a process
    crashed and left a lock in place.

    The refresh time is automatically set to half the timeout value.

.. attribute:: config.compile__wait

    Positive int value, default: 5

    Time to wait between attempts at grabbing the lock if the first
    attempt is not successful. The actual time will be between
    :attr:`compile__wait` and :attr:`compile__wait` * 2 to avoid a
    crowding effect on lock.

.. attribute:: DebugMode

    This section contains various attributes configuring the behaviour
    of mode :class:`~debugmode.DebugMode`. See directly this section
    for the documentation of more configuration options.

.. attribute:: config.DebugMode__check_preallocated_output

    Default: ``''``

    A list of kinds of preallocated memory to use as output buffers for
    each Op's computations, separated by ``:``. Implemented modes are:

    * ``"initial"``: initial storage present in storage map
      (for instance, it can happen in the inner function of Scan),
    * ``"previous"``: reuse previously-returned memory,
    * ``"c_contiguous"``: newly-allocated C-contiguous memory,
    * ``"f_contiguous"``: newly-allocated Fortran-contiguous memory,
    * ``"strided"``: non-contiguous memory with various stride patterns,
    * ``"wrong_size"``: memory with bigger or smaller dimensions,
    * ``"ALL"``: placeholder for all of the above.

    In order not to test with preallocated memory, use an empty string, ``""``.

.. attribute:: config.DebugMode__check_preallocated_output_ndim

    Positive int value, default: 4.

    When testing with "strided" preallocated output memory, test
    all combinations of strides over that number of (inner-most)
    dimensions. You may want to reduce that number to reduce memory or
    time usage, but it is advised to keep a minimum of 2.

.. attribute:: config.DebugMode__warn_input_not_reused

    Bool value, default: ``True``

    Generate a warning when the destroy_map or view_map tell that an op work
    inplace, but the op did not reuse the input for its output.

.. attribute:: config.NanGuardMode__nan_is_error

    Bool value, default: ``True``

    Controls whether NanGuardMode generates an error when it sees a nan.

.. attribute:: config.NanGuardMode__inf_is_error

    Bool value, default: ``True``

    Controls whether NanGuardMode generates an error when it sees an inf.

.. attribute:: config.NanGuardMode__big_is_error

    Bool value, default: ``True``

    Controls whether NanGuardMode generates an error when it sees a
    big value (>1e10).

.. attribute:: compute_test_value

    String Value: ``'off'``, ``'ignore'``, ``'warn'``, ``'raise'``.

    Default: ``'off'``

    Setting this attribute to something other than ``'off'`` activates a
    debugging mechanism, where Aesara executes the graph on-the-fly, as it is
    being built. This allows the user to spot errors early on (such as
    dimension mis-match), **before** optimizations are applied.

    Aesara will execute the graph using the Constants and/or shared variables
    provided by the user. Purely symbolic variables (e.g. ``x = T.dmatrix()``) can be
    augmented with test values, by writing to their ``'tag.test_value'``
    attribute (e.g. ``x.tag.test_value = numpy.random.rand(5, 4)``).

    When not ``'off'``, the value of this option dictates what happens when
    an Op's inputs do not provide appropriate test values:

        - ``'ignore'`` will silently skip the debug mechanism for this Op
        - ``'warn'`` will raise a UserWarning and skip the debug mechanism for
          this Op
        - ``'raise'`` will raise an Exception

.. attribute:: compute_test_value_opt

    As ``compute_test_value``, but it is the value used during Aesara
    optimization phase. Aesara user's do not need to use this. This is
    to help debug shape error in Aesara optimization.

.. attribute:: print_test_value

    Bool value, default: ``False``

    If ``'True'``, Aesara will override the ``__str__`` method of its variables
    to also print the tag.test_value when this is available.

.. attribute:: reoptimize_unpickled_function

    Bool value, default: False

    Aesara users can use the standard python pickle tools to save a compiled
    aesara function. When pickling, both graph before and after the optimization
    are saved, including shared variables. When set to ``True``, the graph is
    reoptimized when being unpickled. Otherwise, skip the graph optimization and
    use directly the optimized graph.

.. attribute:: exception_verbosity

    String Value: ``'low'``, ``'high'``.

    Default: ``'low'``

    If ``'low'``, the text of exceptions will generally refer to apply nodes
    with short names such as ``'Elemwise{add_no_inplace}'``. If ``'high'``,
    some exceptions will also refer to apply nodes with long descriptions like:

    ::

        A. Elemwise{add_no_inplace}
              B. log_likelihood_v_given_h
              C. log_likelihood_h


.. attribute:: config.cmodule__warn_no_version

    Bool value, default: ``False``

    If True, will print a warning when compiling one or more Op with C
    code that can't be cached because there is no ``c_code_cache_version()``
    function associated to at least one of those Ops.

.. attribute:: config.cmodule__remove_gxx_opt

    Bool value, default: ``False``

    If True, will remove the ``-O*`` parameter passed to g++.
    This is useful to debug in gdb modules compiled by Aesara.
    The parameter ``-g`` is passed by default to g++.

.. attribute:: config.cmodule__compilation_warning

    Bool value, default: ``False``

    If True, will print compilation warnings.

.. attribute:: config.cmodule__preload_cache

    Bool value, default: ``False``

    If set to True, will preload the C module cache at import time

.. attribute:: config.cmodule__age_thresh_use

    Int value, default: ``60 * 60 * 24 * 24``  # 24 days

    In seconds. The time after which a compiled c module won't be
    reused by Aesara. Automatic deletion of those c module 7 days
    after that time.

.. attribute:: config.cmodule__debug

    Bool value, default: ``False``

    If True, define a DEBUG macro (if not exists) for any compiled C code.

.. attribute:: config.traceback__limit

    Int value, default: 8

    The number of user stack level to keep for variables.

.. attribute:: config.traceback__compile_limit

    Bool value, default: 0

    The number of user stack level to keep for variables during Aesara
    compilation. If higher then 0, will make us keep Aesara internal
    stack trace.

.. attribute:: config.metaopt__verbose

    Int value, default: 0

    The verbosity level of the meta-optimizer. 0 for silent.
    1 to only warn if we cannot meta-optimize some op.
    2 for full output of separate timings and selected implementation


.. attribute:: config.metaopt__optimizer_excluding

    Default: ``""``

    A list of optimizer tags that we don't want included in the Meta-optimizer.
    If multiple tags, separate them by ':'.

.. attribute:: config.metaopt__optimizer_including

    Default: ``""``

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