config
– Aesara Configuration#
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 some
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 they can be
overridden via a user’s .aesararc
file and the AESARA_FLAGS
environment variable.
The order of precedence is:
an assignment to
aesara.config.<property>
the
.aesararc
file (or the file indicated byAESARARC
)
The current/effective configuration can be shown at any time by printing the
object aesara.config
. For example, to see a list of all active
configuration variables, type this from the command-line:
python -c 'import aesara; print(aesara.config)' | less
Environment Variables#
- AESARA_FLAGS#
This is a list of comma-delimited
key=value
pairs that control Aesara’s behavior.For example, in
bash
, one can override theAESARARC
defaults for a script<myscript>.py
with the following:AESARA_FLAGS='floatX=float32' python <myscript>.py
If a value is defined several times in
AESARA_FLAGS
, the right-most definition is used, so, for instance, ifAESARA_FLAGS='floatX=float32,floatX=float64'
is set, thenfloat64
will be used.
- AESARARC#
The location(s) of the
.aesararc
file(s) inConfigParser
format. It defaults to$HOME/.aesararc
. On Windows, it defaults to$HOME/.aesararc:$HOME/.aesararc.txt
.Here is the
.aesararc
equivalent to theAESARA_FLAGS
in the example above:[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 ofconfig
(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
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:
python -c 'import aesara; print(aesara.config)' | less
- config.force_device[source]#
Bool value: either
True
orFalse
Default:
False
This flag’s value cannot be modified during the program execution.
- config.print_active_device[source]#
Bool value: either
True
orFalse
Default:
True
Print the active device when the device is initialized.
- config.floatX[source]#
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.
- config.warn_float64[source]#
String value: either
'ignore'
,'warn'
,'raise'
, or'pdb'
Default:
'ignore'
This option determines what’s done when a
TensorVariable
with dtype equal tofloat64
is created. This can be used to help find upcasts tofloat64
in user code.
- config.deterministic[source]#
String value: either
'default'
,'more'
Default:
'default'
If
more
, sometimes Aesara will selectOp
implementations that are more “deterministic”, but slower. See thednn.conv.algo*
flags for more cases.
- config.allow_gc[source]#
Bool value: either
True
orFalse
Default:
True
This determines whether or not Aesara’s garbage collector is used for intermediate results. To use less memory, Aesara frees the intermediate results as soon as they are no longer needed. Disabling Aesara’s garbage collection allows Aesara to reuse buffers for intermediate results between function calls. This speeds up Aesara by spending less time reallocating space during function evaluation and can provide significant speed-ups for functions with many fast
Op
s, but it also increases Aesara’s memory usage.
- config.scan__allow_output_prealloc[source]#
Bool value, either
True
orFalse
Default:
True
This enables, or disables, a rewrite in
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.
- config.scan__allow_gc[source]#
Bool value, either
True
orFalse
Default:
False
Allow garbage collection inside of
Scan
Op
s.If
config.allow_gc
isTrue
, butconfig.scan__allow_gc
isFalse
, then Aesara will perform garbage collection during the inner operations of aScan
after each iterations.
- config.cycle_detection[source]#
String value, either
"regular"
or"fast"`
Default:
"regular"
If
cycle_detection
is set to"regular"
, most in-place operations are allowed, but graph compilation is slower. Ifcycle_detection
is set to"fast"
, less in-place operations are allowed, but graph compilation is faster.
- config.check_stack_trace[source]#
String value, either
"off"
,"log"
,"warn"
,"raise"
Default:
"off"
This is a flag for checking stack traces during graph rewriting. If
check_stack_trace
is set to"off"
, no check is performed on the stack trace. Ifcheck_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. Ifcheck_stack_trace
is set to"raise"
, an exception is raised if a stack trace is missing.
- config.openmp[source]#
Bool value: either
True
orFalse
Default:
False
Enable or disable parallel computation on the CPU with OpenMP. It is the default value used by
Op
s that support OpenMP. It is best to specify this setting in.aesararc
or in the environment variableAESARA_FLAGS
.
- config.openmp_elemwise_minsize[source]#
Positive int value, default: 200000.
This specifies the minimum size of a vector for which OpenMP will be used by
Elemwise
Op
s, when OpenMP is enabled.
- config.cast_policy[source]#
String value: either
'numpy+floatX'
or'custom'
Default:
'custom'
This specifies how data types are implicitly determined by Aesara 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 Aesara. These rules can be partially customized (e.g. see the in-code help ofaesara.scalar.basic.NumpyAutocaster
). This will be deprecated in the future.The
'numpy+floatX'
setting attempts to mimic NumPy casting rules, although it prefers to usefloat32` `numbers instead of ``float64
whenconfig.floatX
is set to'float32'
and the associated data is not explicitly typed asfloat64
(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
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. Aesara 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.
- config.int_division[source]#
String value: either
'int'
,'floatX'
, or'raise'
Default:
'int'
Specifies what to do when one tries to compute
x / y
, where bothx
andy
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 byconfig.floatX
.'raise'
is the safest choice (and will become default in a future release of Aesara). 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 usex.__truediv__(y)
.
- config.mode[source]#
String value:
'Mode'
,'DebugMode'
,'FAST_RUN'
,'FAST_COMPILE'
Default:
'Mode'
This sets the default compilation mode when compiling Aesara functions. By default the mode
'Mode'
is equivalent to'FAST_RUN'
.
- config.profile[source]#
Bool value: either
True
orFalse
Default:
False
When
True
, the VM and CVM linkers profile the execution time of Aesara functions.See Profiling Aesara function for examples.
- config.profile_memory[source]#
Bool value: either
True
orFalse
Default:
False
When
True
, the VM and CVM linkers profile the memory usage of Aesara functions. This only works whenprofile=True
.
- config.profile_optimizer[source]#
Bool value: either
True
orFalse
Default:
False
When
True
, theVM
andCVM
linkers profile the rewriting phase when compiling an Aesara function. This only works whenprofile=True
.
- config.profiling__n_apply[source]#
Positive int value, default: 20.
The number of
Apply
nodes to print in the profiler output.
- config.profiling__n_ops[source]#
Positive int value, default: 20.
The number of
Op
s to print in the profiler output.
- config.profiling__min_memory_size[source]#
Positive int value, default: 1024.
During memory profiling, do not print
Apply
nodes if the size of their outputs (in bytes) is lower than this value.
- config.profiling__min_peak_memory[source]#
Bool value: either
True
orFalse
Default:
False
When
True
, print the minimum peak memory usage during memory profiling. This only works whenprofile=True
andprofile_memory=True
.
- config.profiling__destination[source]#
String value:
'stderr'
,'stdout'
, or a name of a file to be createdDefault:
'stderr'
Name of the destination file for the profiling output. The profiling output can be directed to stderr (default), stdout, or an arbitrary file.
- config.profiling__debugprint[source]#
Bool value: either
True
orFalse
Default:
False
When
True
, usedebugprint
to print the profiled functions.
- config.profiling__ignore_first_call[source]#
Bool value: either
True
orFalse
Default:
False
When
True
, ignore the first call to an Aesara function while profiling.
- config.lib__amblibm[source]#
Bool value: either
True
orFalse
Default:
False
When
True
, use the amdlibm library, which is faster than the standardlibm
.
- config.linker[source]#
String value:
'c|py'
,'py'
,'c'
,'c|py_nogc'
Default:
'c|py'
When the mode is
'Mode'
, it sets the default linker used. See Configuration Settings and Compiling Modes for a comparison of the different linkers.
- config.optimizer[source]#
String value:
'fast_run'
,'merge'
,'fast_compile'
,'None'
Default:
'fast_run'
When the mode is
'Mode'
, it sets the default rewrites used during compilation.
- config.on_opt_error[source]#
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 thepdb
debugger (i.e.'pdb'
), or ignore it (i.e.'ignore'
). We suggest never using'ignore'
except during testing.
- config.assert_no_cpu_op[source]#
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 drop into the frame withpdb
.
- config.on_shape_error[source]#
String value:
'warn'
or'raise'
Default:
'warn'
When an exception is raised while inferring the shape of an
Apply
node, either warn the user and use a default value (i.e.'warn'
), or raise the exception (i.e.'raise'
).
- config.warn__ignore_bug_before[source]#
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 an Aesara bug that generated a bad result is fixed, we also make Aesara raise a warning when it encounters the same circumstances again. This helps users determine whether or not said bug has affected past runs, since one only needs to perform the same runs again with the new version, and one does not have to understand the Aesara internals that triggered the bug.
This flag lets users ignore 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.This flag’s value cannot be modified during program execution.
- config.base_compiledir[source]#
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 program execution.
- config.compiledir_format[source]#
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, runpython -c "import aesara; print(aesara.config)"
and look forcompiledir_format
.This flag’s value cannot be modified during program execution.
- config.compiledir[source]#
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.
- config.blas__ldflags[source]#
Default:
'-lblas'
Link argument to link against a (Fortran) level-3 blas implementation. Aesara will test if
'-lblas'
works by default. If not, it will disable C code for BLAS.
- config.experimental__local_alloc_elemwise_assert[source]#
Bool value: either
True
orFalse
Default:
True
When
True
, add asserts that highlight shape errors.Without such asserts, the underlying rewrite could hide errors in user code. Aesara 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.
- config.dnn__enabled[source]#
String value:
'auto'
,'True'
,'False'
,'no_check'
Default:
'auto'
If
'auto'
, automatically detect and use cuDNN when it is available. If cuDNN is unavailable, do not raise an error.If
'True'
, require the use of cuDNN. If cuDNN is unavailable, raise an error.If
'False'
, neither use cuDNN nor check if it is available.If
'no_check'
, assume cuDNN is present and that the versions between the header and library match.
- config.dnn__include_path[source]#
Default:
include
sub-folder in CUDA root directory, or headers paths defined for the compiler.Location of the cuDNN header.
- config.dnn__library_path[source]#
Default: Library sub-folder (
lib64
on Linux) in CUDA root directory, or libraries paths defined for the compiler.Location of the cuDNN library.
- config.conv__assert_shape[source]#
If
True
,AbstractConv*
Op
s will verify that user-provided shapes match the run-time shapes. This is a debugging option, and may slow down compilation.
- config.dnn.conv.workmem[source]#
Deprecated, use
config.dnn__conv__algo_fwd
.
- config.dnn.conv.workmem_bwd[source]#
Deprecated, use
config.dnn__conv__algo_bwd_filter
andconfig.dnn__conv__algo_bwd_data
instead.
- config.dnn__conv__algo_fwd[source]#
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'
.
- config.dnn.conv.algo_bwd[source]#
Deprecated, use
config.dnn__conv__algo_bwd_filter
andconfig.dnn__conv__algo_bwd_data
instead.
- config.dnn__conv__algo_bwd_filter[source]#
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'
.
- config.dnn__conv__algo_bwd_data[source]#
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 supports
'none'
,'deterministic'
,'fft_tiling'
'guess_once'
,'guess_on_shape_change'
,'time_once'
,'time_on_shape_change'
.
- config.magma__enabled[source]#
String value:
'True'
,'False'
Default:
'False'
If
'True'
, use magma for matrix computations.If
'False'
, disable magma.
- config.ctc__root[source]#
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.
- config.gcc__cxxflags[source]#
Default:
""
Extra parameters to pass to
gcc
when compiling. Extra include paths, library paths, configuration options, etc.
- config.cxx[source]#
Default: Full path to
g++
ifg++
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 (e.g. Mac OS X), it looks forclang++
and uses that when available.Aesara 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.
- config.optimizer_excluding[source]#
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 theElemwise
in-place rewrites, use the flags:optimizer_excluding:inplace_opt
, whereinplace_opt
is the name of the rewrite group.This flag’s value cannot be modified during the program execution.
- config.optimizer_including[source]#
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.
- config.optimizer_requiring[source]#
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.
- config.optimizer_verbose[source]#
Bool value: either
True
orFalse
Default:
False
When
True
, print the rewrites applied to stdout.
- config.nocleanup[source]#
Bool value: either
True
orFalse
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 toTrue
to keep files for debugging.
- config.compile[source]#
This section contains attributes which influence the compilation of C code for
Op
s. Due to historical reasons many attributes outside of this section also have an influence over compilation, most notablycxx
.
- config.compile__timeout[source]#
Positive int value, default:
compile__wait
* 24Time 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.
- config.compile__wait[source]#
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
compile__wait
andcompile__wait
* 2 to avoid a crowding effect on the lock.
- config.DebugMode[source]#
This section contains various attributes configuring the behaviour of
DebugMode
.
- config.DebugMode__check_preallocated_output[source]#
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 ofScan
),"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,
""
.
- config.DebugMode__check_preallocated_output_ndim[source]#
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.
- config.DebugMode__warn_input_not_reused[source]#
Bool value, default:
True
Generate a warning when a
destroy_map
orview_map
says that anOp
will work inplace, but theOp
does not reuse the input for its output.
- config.NanGuardMode__nan_is_error[source]#
Bool value, default:
True
Controls whether
NanGuardMode
generates an error when it sees anan
.
- config.NanGuardMode__inf_is_error[source]#
Bool value, default:
True
Controls whether
NanGuardMode
generates an error when it sees aninf
.
- config.NanGuardMode__big_is_error[source]#
Bool value, default:
True
Controls whether
NanGuardMode
generates an error when it sees a big value (i.e. a value greater than1e10
).
- config.compute_test_value[source]#
String Value:
'off'
,'ignore'
,'warn'
,'raise'
.Default:
'off'
Setting this attribute to something other than
'off'
activates a debugging mechanism, for which 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-matches) before rewrites are applied.Aesara will execute the graph using constants and/or shared variables provided by the user. Purely symbolic variables (e.g.
x = aesara.tensor.dmatrix()
) can be augmented with test values, by writing to their.tag.test_value
attributes (e.g.x.tag.test_value = np.ones((5, 4))
).When not
'off'
, the value of this option dictates what happens when anOp
’s inputs do not provide appropriate test values:'ignore'
will do nothing'warn'
will raise aUserWarning
'raise'
will raise an exception
- config.compute_test_value_opt[source]#
As
compute_test_value
, but it is the value used during Aesara’s rewriting phase. This is used to help debug shape errors in Aesara’s rewrites.
- config.print_test_value[source]#
Bool value, default:
False
If
'True'
, Aesara will include the test values in a variable’s__str__
output.
- config.exception_verbosity[source]#
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 toApply
nodes with long descriptions like:A. Elemwise{add_no_inplace} B. log_likelihood_v_given_h C. log_likelihood_h
- config.cmodule__warn_no_version[source]#
Bool value, default:
False
If
True
, will print a warning when compiling one or moreOp
with C code that can’t be cached because there is noc_code_cache_version()
function associated to at least one of thoseOp
s.
- config.cmodule__remove_gxx_opt[source]#
Bool value, default:
False
If
True
, Aesara will remove the-O*
parameter passed tog++
. This is useful for debugging objects compiled by Aesara. The parameter-g
is also passed by default tog++
.
- config.cmodule__compilation_warning[source]#
Bool value, default:
False
If
True
, Aesara will print compilation warnings.
- config.cmodule__preload_cache[source]#
Bool value, default:
False
If set to
True
, Aesara will preload the C module cache at import time
- config.cmodule__age_thresh_use[source]#
Int value, default:
60 * 60 * 24 * 24
# 24 daysThe time after which a compiled C module won’t be reused by Aesara (in seconds). C modules are automatically deleted 7 days after that time.
- config.cmodule__debug[source]#
Bool value, default:
False
If
True
, define a DEBUG macro (if one doesn’t already exist) for all compiled C code.
- config.traceback__limit[source]#
Int value, default: 8
The number of traceback stack levels to keep for Aesara variable definitions.
- config.traceback__compile_limit[source]#
Bool value, default: 0
The number of traceback stack levels to keep for variables during Aesara compilation. When this value is greater than zero, it will make Aesara keep internal stack traces.
- config.metaopt__verbose[source]#
Int value, default: 0
The verbosity level of the meta-rewriter:
0
for silent,1
to only warn when Aesara cannot meta-rewrite anOp
,2
for full output (e.g. timings and the rewrites selected).