# Preferences¶

Brian has a system of global preferences that affect how certain objects behave. These can be set either in scripts by using the prefs object or in a file. Each preference looks like codegen.c.compiler, i.e. dotted names.

## Accessing and setting preferences¶

Preferences can be accessed and set either keyword-based or attribute-based. The following are equivalent:

prefs['codegen.c.compiler'] = 'gcc'
prefs.codegen.c.compiler = 'gcc'


Using the attribute-based form can be particulary useful for interactive work, e.g. in ipython, as it offers autocompletion and documentation. In ipython, prefs.codegen.c? would display a docstring with all the preferences available in the codegen.c category.

## Preference files¶

Preferences are stored in a hierarchy of files, with the following order (each step overrides the values in the previous step but no error is raised if one is missing):

• The global defaults are stored in the installation directory.
• The user default are stored in ~/.brian/user_preferences (which works on Windows as well as Linux). The ~ symbol refers to the user directory.
• The file brian_preferences in the current directory.

The preference files are of the following form:

a.b.c = 1
# Comment line
[a]
b.d = 2
[a.b]
b.e = 3


This would set preferences a.b.c=1, a.b.d=2 and a.b.e=3.

## List of preferences¶

Brian itself defines the following preferences (including their default values):

### codegen¶

Code generation preferences

codegen.loop_invariant_optimisations = True

Whether to pull out scalar expressions out of the statements, so that they are only evaluated once instead of once for every neuron/synapse/... Can be switched off, e.g. because it complicates the code (and the same optimisation is already performed by the compiler) or because the code generation target does not deal well with it. Defaults to True.

codegen.string_expression_target = 'numpy'

Default target for the evaluation of string expressions (e.g. when indexing state variables). Should normally not be changed from the default numpy target, because the overhead of compiling code is not worth the speed gain for simple expressions.

Accepts the same arguments as codegen.target, except for 'auto'

codegen.target = 'auto'

Default target for code generation.

Can be a string, in which case it should be one of:

• 'auto' the default, automatically chose the best code generation target available.
• 'weave' uses scipy.weave to generate and compile C++ code, should work anywhere where gcc is installed and available at the command line.
• 'cython', uses the Cython package to generate C++ code. Needs a working installation of Cython and a C++ compiler.
• 'numpy' works on all platforms and doesn’t need a C compiler but is often less efficient.

Or it can be a CodeObject class.

codegen.cpp

C++ compilation preferences

codegen.cpp.compiler = ''

Compiler to use (uses default if empty)

Should be gcc or msvc.

codegen.cpp.define_macros = []

List of macros to define; each macro is defined using a 2-tuple, where ‘value’ is either the string to define it to or None to define it without a particular value (equivalent of “#define FOO” in source or -DFOO on Unix C compiler command line).

codegen.cpp.extra_compile_args = None

Extra arguments to pass to compiler (if None, use either extra_compile_args_gcc or extra_compile_args_msvc).

codegen.cpp.extra_compile_args_gcc = ['-w', '-O3', '-ffast-math', '-fno-finite-math-only', '-march=native']

Extra compile arguments to pass to GCC compiler

codegen.cpp.extra_compile_args_msvc = ['/Ox', '/w', '/arch:SSE2', '/MP']

Extra compile arguments to pass to MSVC compiler (the default /arch: flag is determined based on the processor architecture)
Any extra platform- and compiler-specific information to use when linking object files together.

codegen.cpp.headers = []

A list of strings specifying header files to use when compiling the code. The list might look like [“<vector>”,“‘my_header’”]. Note that the header strings need to be in a form than can be pasted at the end of a #include statement in the C++ code.

codegen.cpp.include_dirs = []

Include directories to use. Note that $prefix/include will be appended to the end automatically, where $prefix is Python’s site-specific directory prefix as returned by sys.prefix.

codegen.cpp.libraries = []

List of library names (not filenames or paths) to link against.

codegen.cpp.library_dirs = []

List of directories to search for C/C++ libraries at link time. Note that $prefix/lib will be appended to the end automatically, where $prefix is Python’s site-specific directory prefix as returned by sys.prefix.

codegen.cpp.msvc_architecture = ''

MSVC architecture name (or use system architectue by default).

Could take values such as x86, amd64, etc.

codegen.cpp.msvc_vars_location = ''

Location of the MSVC command line tool (or search for best by default).

codegen.cpp.runtime_library_dirs = []

List of directories to search for C/C++ libraries at run time.

codegen.generators

Codegen generator preferences (see subcategories for individual languages)

codegen.generators.cpp

C++ codegen preferences

codegen.generators.cpp.flush_denormals = False

Adds code to flush denormals to zero.

The code is gcc and architecture specific, so may not compile on all platforms. The code, for reference is:

#define CSR_FLUSH_TO_ZERO         (1 << 15)
unsigned csr = __builtin_ia32_stmxcsr();
csr |= CSR_FLUSH_TO_ZERO;
__builtin_ia32_ldmxcsr(csr);


codegen.generators.cpp.restrict_keyword = '__restrict'

The keyword used for the given compiler to declare pointers as restricted.

This keyword is different on different compilers, the default works for gcc and MSVS.

codegen.runtime

Runtime codegen preferences (see subcategories for individual targets)

codegen.runtime.cython

Cython runtime codegen preferences

codegen.runtime.cython.cache_dir = None

Location of the cache directory for Cython files. By default, will be stored in a brian_extensions subdirectory where Cython inline stores its temporary files (the result of get_cython_cache_dir()).

codegen.runtime.cython.multiprocess_safe = True

Whether to use a lock file to prevent simultaneous write access to cython .pyx and .so files.

codegen.runtime.numpy

Numpy runtime codegen preferences

codegen.runtime.numpy.discard_units = False

Whether to change the namespace of user-specifed functions to remove units.

### core¶

Core Brian preferences

core.default_float_dtype = float64

Default dtype for all arrays of scalars (state variables, weights, etc.).

Currently, this is not supported (only float64 can be used).

core.default_integer_dtype = int32

Default dtype for all arrays of integer scalars.

core.outdated_dependency_error = True

Whether to raise an error for outdated dependencies (True) or just a warning (False).

core.network

Network preferences

core.network.default_schedule = ['start', 'groups', 'thresholds', 'synapses', 'resets', 'end']

Default schedule used for networks that don’t specify a schedule.

### devices¶

Device preferences

devices.cpp_standalone

C++ standalone preferences

devices.cpp_standalone.extra_make_args_unix = ['-j']

Additional flags to pass to the GNU make command on Linux/OS-X. Defaults to “-j” for parallel compilation.

devices.cpp_standalone.extra_make_args_windows = []

Additional flags to pass to the nmake command on Windows. By default, no additional flags are passed.

devices.cpp_standalone.openmp_spatialneuron_strategy = None

Which strategy to chose for solving the three tridiagonal systems with OpenMP: 'branches' means to solve the three systems sequentially, but for all the branches in parallel, 'systems' means to solve the three systems in parallel, but all the branches within each system sequentially. The 'branches' approach is usually better for morphologies with many branches and a large number of threads, while the 'systems' strategy should be better for morphologies with few branches (e.g. cables) and/or simulations with no more than three threads. If not specified (the default), the 'systems' strategy will be used when using no more than three threads or when the morphology has less than three branches in total.

devices.cpp_standalone.openmp_threads = 0

The number of threads to use if OpenMP is turned on. By default, this value is set to 0 and the C++ code is generated without any reference to OpenMP. If greater than 0, then the corresponding number of threads are used to launch the simulation.

devices.cpp_standalone.run_environment_variables = {'LD_BIND_NOW': '1'}

Dictionary of environment variables and their values that will be set during the execution of the standalone code.

### logging¶

Logging system preferences

logging.console_log_level = 'INFO'

What log level to use for the log written to the console.

Has to be one of CRITICAL, ERROR, WARNING, INFO, DEBUG or DIAGNOSTIC.

logging.delete_log_on_exit = True

Whether to delete the log and script file on exit.

If set to True (the default), log files (and the copy of the main script) will be deleted after the brian process has exited, unless an uncaught exception occured. If set to False, all log files will be kept.

logging.file_log = True

Whether to log to a file or not.

If set to True (the default), logging information will be written to a file. The log level can be set via the logging.file_log_level preference.

logging.file_log_level = 'DIAGNOSTIC'

What log level to use for the log written to the log file.

In case file logging is activated (see logging.file_log), which log level should be used for logging. Has to be one of CRITICAL, ERROR, WARNING, INFO, DEBUG or DIAGNOSTIC.

logging.save_script = True

Whether to save a copy of the script that is run.

If set to True (the default), a copy of the currently run script is saved to a temporary location. It is deleted after a successful run (unless logging.delete_log_on_exit is False) but is kept after an uncaught exception occured. This can be helpful for debugging, in particular when several simulations are running in parallel.

logging.std_redirection = True

Whether or not to redirect stdout/stderr to null at certain places.

This silences a lot of annoying compiler output, but will also hide error messages making it harder to debug problems. You can always temporarily switch it off when debugging. If logging.std_redirection_to_file is set to True as well, then the output is saved to a file and if an error occurs the name of this file will be printed.

logging.std_redirection_to_file = True

Whether to redirect stdout/stderr to a file.

If both logging.std_redirection and this preference are set to True, all standard output/error (most importantly output from the compiler) will be stored in files and if an error occurs the name of this file will be printed. If logging.std_redirection is True and this preference is False, then all standard output/error will be completely suppressed, i.e. neither be displayed nor stored in a file.

The value of this preference is ignore if logging.std_redirection is set to False.