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/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.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.

codegen.target = 'numpy'

Default target for code generation.

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

  • 'numpy' by default because this works on all platforms, but may not be maximally efficient.
  • '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.

Or it can be a CodeObject class.

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);

Found at http://stackoverflow.com/questions/2487653/avoiding-denormal-values-in-c.

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 is for gcc.

codegen.runtime.cython

Cython runtime codegen preferences

codegen.runtime.cython.extra_compile_args = ['-w', '-O3']

Extra compile arguments to pass to compiler

codegen.runtime.cython.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.runtime.numpy

Numpy runtime codegen preferences

codegen.runtime.numpy.discard_units = False

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

codegen.runtime.weave

Weave runtime codegen preferences

codegen.runtime.weave.compiler = 'gcc'

Compiler to use for weave.

codegen.runtime.weave.extra_compile_args = ['-w', '-O3']

Extra compile arguments to pass to compiler

codegen.runtime.weave.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.

core

Core Brian preferences

core.default_float_dtype = float64

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

core.default_integer_dtype = int32

Default dtype for all arrays of integer scalars’

devices

Device preferences

devices.cpp_standalone

C++ standalone preferences

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.optimisation_flags = '-O3'

Optimisation flags to pass to the compiler

logging

Logging system preferences

logging.console_log_level = 'WARNING'

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

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

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 = 'DEBUG'

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 or DEBUG.

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.