.. _libdoc_config:

=======================================
:mod:`config` -- PyTensor Configuration
=======================================

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


Guide
=====

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

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

PyTensor's code comes with default values for these attributes, but they can be
overridden via a user's ``.pytensorrc`` file and the :envvar:`PYTENSOR_FLAGS`
environment variable.

The order of precedence is:

1. an assignment to ``pytensor.config.<property>``
2. :envvar:`PYTENSOR_FLAGS`
3. the ``.pytensorrc`` file (or the file indicated by :envvar:`PYTENSORRC`)

The current/effective configuration can be shown at any time by printing the
object ``pytensor.config``.  For example, to see a list of all active
configuration variables, type this from the command-line:

.. code-block:: bash

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

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


.. envvar:: PYTENSOR_FLAGS

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

    For example, in ``bash``, one can override the :envvar:`PYTENSORRC` defaults
    for a script ``<myscript>.py`` with the following:

    .. code-block:: bash

        PYTENSOR_FLAGS='floatX=float32'  python <myscript>.py

    If a value is defined several times in ``PYTENSOR_FLAGS``,
    the right-most definition is used, so, for instance, if
    ``PYTENSOR_FLAGS='floatX=float32,floatX=float64'`` is set, then ``float64`` will be
    used.

.. envvar:: PYTENSORRC

    The location(s) of the ``.pytensorrc`` file(s) in `ConfigParser` format.
    It defaults to ``$HOME/.pytensorrc``. On Windows, it defaults to
    ``$HOME/.pytensorrc:$HOME/.pytensorrc.txt``.

    Here is the ``.pytensorrc`` equivalent to the ``PYTENSOR_FLAGS`` in the example above:

    .. code-block:: cfg

        [global]
        floatX = float32
        device = cuda0

    Configuration attributes that are available directly in ``config``
    (e.g. ``config.mode``) should be defined in the ``[global]`` section.
    Attributes from a subsection of ``config``
    (e.g. ``config.dnn__conv__algo_fwd``) should be defined in their
    corresponding section (e.g. ``[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, when
    multiple files specify values for the same configuration option.

    For example, to override system-wide settings with personal ones,
    set ``PYTENSORRC=/etc/pytensorrc:~/.pytensorrc``. To load configuration files in
    the current working directory, append ``.pytensorrc`` to the list of configuration
    files, e.g. ``PYTENSORRC=~/.pytensorrc:.pytensorrc``.

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 ``pytensor`` and print the config variable, as in:

.. code-block:: bash

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

.. attribute:: device

    String value: either ``'cpu'``

.. attribute:: print_active_device

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

    Default: ``True``

    Print the active device when the 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 PyTensor bit width for
    arguments passed as Python floating-point numbers.

.. attribute:: warn_float64

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

    Default: ``'ignore'``

    This option determines what's done when a :class:`TensorVariable` with dtype
    equal to ``float64`` is created.
    This can be used to help find upcasts to ``float64`` in user code.

.. attribute:: allow_gc

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

    Default: ``True``

    This determines whether or not PyTensor's garbage collector is used for
    intermediate results. To use less memory, PyTensor frees the intermediate
    results as soon as they are no longer needed.  Disabling PyTensor's garbage
    collection allows PyTensor to reuse buffers for intermediate results between
    function calls. This speeds up PyTensor by spending less time reallocating
    space during function evaluation and can provide significant speed-ups for
    functions with many fast :class:`Op`\s, but it also increases PyTensor's memory
    usage.

.. attribute:: config.scan__allow_output_prealloc

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

    Default: ``True``

    This enables, or disables, a rewrite in :class:`Scan` that tries to
    pre-allocate memory for its outputs. Enabling the rewrite can give a
    significant speed up at the cost of slightly increased memory usage.

.. attribute:: config.scan__allow_gc

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

    Default: ``False``

    Allow garbage collection inside of :class:`Scan` :class:`Op`\s.

    If :attr:`config.allow_gc` is ``True``, but :attr:`config.scan__allow_gc` is
    ``False``, then PyTensor will perform garbage collection during the inner
    operations of a :class:`Scan` after each iterations.

.. attribute:: cycle_detection

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

    Default: ``regular``

    If :attr:`cycle_detection` is set to ``regular``, most in-place operations are allowed,
    but graph compilation is slower. If :attr:`cycle_detection` is set to ``faster``,
    less in-place operations are allowed, but graph compilation is faster.

.. attribute:: check_stack_trace

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

    Default: ``off``

    This is a flag for checking stack traces during graph rewriting.
    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 rewrite inserted the
    variable that had an empty stack trace, but, when ``warn`` is set, 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 by :class:`Op`\s that support OpenMP.
    It is best to specify this setting in ``.pytensorrc`` or in the environment
    variable ``PYTENSOR_FLAGS``.

.. attribute:: openmp_elemwise_minsize

    Positive int value, default: 200000.

    This specifies the minimum size of a vector for which OpenMP will be used by
    :class:`Elemwise` :class:`Op`\s, when OpenMP is enabled.

.. attribute:: cast_policy

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

    Default: ``'custom'``

    This specifies how data types are implicitly determined by PyTensor during the
    creation of constants or in the results of arithmetic operations.

    The ``'custom'`` value corresponds to a set of custom rules originally used
    in PyTensor.  These rules can be partially customized (e.g. see the in-code
    help of ``pytensor.scalar.basic.NumpyAutocaster``).  This will be deprecated
    in the future.

    The ``'numpy+floatX'`` setting attempts to mimic NumPy casting rules,
    although it prefers to use ``float32`` numbers instead of ``float64`` when
    ``config.floatX`` is set to ``'float32'`` and the associated data 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 it should considered experimental.

    At the moment it behaves differently from NumPy in the following situations:

    * Depending on the value of :attr:`config.int_division`, the resulting dtype
      of a division of integers 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. PyTensor does not attempt to do the same at this point,
      so users should be careful, since scalars may upcast arrays when they
      otherwise wouldn't in 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). This behavior is deprecated.

    ``'floatX'`` returns a number of with the dtype given by ``config.floatX``.

    ``'raise'`` is the safest choice (and will become default in a future
    release of PyTensor).  It raises an error when one tries to perform such an
    operation, enforcing the use of the integer division operator (``//``). If a
    float result is desired, 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 when compiling PyTensor functions. By
    default the mode ``'Mode'`` is equivalent to ``'FAST_RUN'``.

.. attribute:: profile

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

    Default: ``False``

    When ``True``, the VM and CVM linkers profile the execution time of PyTensor functions.

    See :ref:`tut_profiling` for examples.

.. attribute:: profile_memory

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

    Default: ``False``

    When ``True``, the VM and CVM linkers profile the memory usage of PyTensor
    functions.  This only works when ``profile=True``.

.. attribute:: profile_optimizer

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

    Default: ``False``

    When ``True``, the :class:`VM` and :class:`CVM` linkers profile the rewriting phase when
    compiling an PyTensor function.  This only works when ``profile=True``.

.. attribute:: config.profiling__n_apply

    Positive int value, default: 20.

    The number of :class:`Apply` nodes to print in the profiler output.

.. attribute:: config.profiling__n_ops

    Positive int value, default: 20.

    The number of :class:`Op`\s to print in the profiler output.

.. attribute:: config.profiling__min_memory_size

    Positive int value, default: 1024.

    During memory profiling, do not print :class:`Apply` nodes if the size
    of their outputs (in bytes) is lower than this value.

.. attribute:: config.profiling__min_peak_memory

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

    Default: ``False``

    When ``True``, print the minimum peak memory usage during memory profiling.
    This only works when ``profile=True`` and ``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 directed to stderr (default), stdout, or an
    arbitrary file.

.. attribute:: config.profiling__debugprint

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

    Default: ``False``

    When ``True``, use ``debugprint`` to print the profiled functions.

.. attribute:: config.profiling__ignore_first_call

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

    Default: ``False``

    When ``True``, ignore the first call to an PyTensor function while profiling.

.. attribute:: config.lib__amdlibm

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

    Default: ``False``

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

.. 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 rewrites used during compilation.

.. attribute:: on_opt_error

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

    Default: ``'warn'``

    When a crash occurs while trying to apply a rewrite, either warn the
    user and skip the rewrite (i.e. ``'warn'``), raise the exception
    (i.e. ``'raise'``), drop into the ``pdb`` debugger (i.e. ``'pdb'``), or
    ignore it (i.e. ``'ignore'``).
    We suggest never using ``'ignore'`` except during testing.

.. attribute:: on_shape_error

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

    Default: ``'warn'``

    When an exception is raised while inferring the shape of an :class:`Apply`
    node, either warn the user and use a default value (i.e. ``'warn'``), or
    raise the exception (i.e. ``'raise'``).


.. attribute:: base_compiledir

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

    This directory stores the platform-dependent compilation directories.

    This flag's value cannot be modified during 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 sub-directory of
    ``config.base_compiledir`` in which platform-dependent compiled modules are
    stored. To see a list of all available substitution keys, run ``python -c
    "import pytensor; print(pytensor.config)"`` and look for ``compiledir_format``.

    This flag's value cannot be modified during 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 program execution.

.. attribute:: config.blas__ldflags

    Default: ``'-lblas'``

    Link argument to link against a (Fortran) level-3 blas implementation.
    PyTensor will test if ``'-lblas'`` works by default. If not, it will disable C
    code for BLAS.

.. attribute:: config.experimental__local_alloc_elemwise_assert

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

    Default: ``True``

    When ``True``, add asserts that highlight shape errors.

    Without such asserts, the underlying rewrite could hide errors in user
    code.  PyTensor adds the asserts only if it cannot infer that the shapes are
    equivalent.  When it can determine equivalence, this rewrite does not
    introduce an assert.

    Removing these asserts can speed up execution.

.. attribute:: config.conv__assert_shape

    If ``True``, ``AbstractConv*`` :class:`Op`\s will verify that user-provided shapes
    match the run-time shapes. This is a debugging option, and may slow down
    compilation.

.. 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 (e.g. ``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.  PyTensor automatically detects whether ``g++`` is present and
    disables C++ compilation when it is not.  On Darwin systems (e.g. Mac
    OS X), it looks for ``clang++`` and uses that when available.

    PyTensor prints a warning if it detects that no compiler is present.

    This value can point to 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 rewriter tags that shouldn't be included in the default ``Mode``.
    If multiple tags are provided, separate them by ``':'``.
    For example, to remove the ``Elemwise`` in-place rewrites,
    use the flags: ``optimizer_excluding:inplace_opt``, where
    ``inplace_opt`` is the name of the rewrite group.

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

.. attribute:: optimizer_including

    Default: ``""``

    A list of rewriter tags to be included in the default ``Mode``.
    If multiple tags are provided, separate them by ``':'``.

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

.. attribute:: optimizer_requiring

    Default: ``""``

    A list of rewriter tags that are required for rewriting in the default
    ``Mode``.
    If multiple tags are provided, 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``, print the rewrites applied to stdout.

.. attribute:: compiler_verbose

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

    Default: ``False``

    When ``True``, print detailed information about the compilation of a graph. The type of information printed will
    vary depending on the computational backend, and some backends may not provide additional information.

.. attribute:: nocleanup

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

    Default: ``False``

    If ``False``, source code files are removed when they are no longer needed.
    This causes files for which compilation failed to be deleted.
    Set to ``True`` to keep files for debugging.

.. attribute:: compile

    This section contains attributes which influence the compilation of
    C code for :class:`Op`\s.  Due to historical reasons many attributes outside
    of this section also have an influence over compilation, most
    notably ``cxx``.

.. attribute:: config.compile__timeout

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

    Time to wait before an un-refreshed lock is broken and stolen (in seconds).
    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 (in seconds). The actual time will be between
    :attr:`compile__wait` and :attr:`compile__wait` * 2 to avoid a
    crowding effect on the lock.

.. attribute:: DebugMode

    This section contains various attributes configuring the behaviour of
    :class:`~debugmode.DebugMode`.

.. attribute:: config.DebugMode__check_preallocated_output

    Default: ``''``

    A list of kinds of preallocated memory to use as output buffers for
    each :class:`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 :class:`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 a ``destroy_map`` or ``view_map`` says that an
    :class:`Op` will work inplace, but the :class:`Op` does 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 (i.e. a value greater than ``1e10``).

.. 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 :class:`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 :class:`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 :class:`Op`\s.

.. attribute:: config.cmodule__remove_gxx_opt

    Bool value, default: ``False``

    If ``True``, PyTensor will remove the ``-O*`` parameter passed to ``g++``.
    This is useful for debugging objects compiled by PyTensor.  The parameter
    ``-g`` is also passed by default to ``g++``.

.. attribute:: config.cmodule__compilation_warning

    Bool value, default: ``False``

    If ``True``, PyTensor will print compilation warnings.

.. attribute:: config.cmodule__preload_cache

    Bool value, default: ``False``

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

.. attribute:: config.cmodule__age_thresh_use

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

    The time after which a compiled C module won't be reused by PyTensor (in
    seconds). C modules are automatically deleted 7 days after that time.

.. attribute:: config.cmodule__debug

    Bool value, default: ``False``

    If ``True``, define a DEBUG macro (if one doesn't already exist) for all
    compiled C code.

.. attribute:: config.traceback__limit

    Int value, default: 8

    The number of traceback stack levels to keep for PyTensor variable
    definitions.

.. attribute:: config.traceback__compile_limit

    Bool value, default: 0

    The number of traceback stack levels to keep for variables during PyTensor
    compilation. When this value is greater than zero, it will make PyTensor keep
    internal stack traces.
