.. currentmodule:: brian

.. index::
	single: preferences

.. _preferences:

Preferences
===========

Functions
---------

Setting and getting global preferences is done with the following
functions:

.. autofunction:: set_global_preferences
.. autofunction:: get_global_preference

Global configuration file
-------------------------

If you have a module named ``brian_global_config`` anywhere on your Python path,
Brian will attempt to import it to define global preferences. For example, to
automatically enable weave compilation for all your Brian projects, create a
file ``brian_global_config.py`` somewhere in the Python path with the following
contents::

	from brian.globalprefs import *
	set_global_preferences(useweave=True)

.. INSERT_GLOBAL_PREFERENCES_HERE


Global preferences for Brian
----------------------------

The following global preferences have been defined:

``defaultclock = Clock(dt=0.1*msecond)``
    The default clock to use if none is provided or defined
    in any enclosing scope.
``useweave_linear_diffeq = False``
    Whether to use weave C++ acceleration for the solution
    of linear differential equations. Note that on some
    platforms, typically older ones, this is faster and on
    some platforms, typically new ones, this is actually
    slower.
``useweave = False``
    Defines whether or not functions should use inlined compiled
    C code where defined. Requires a compatible C++ compiler.
    The ``gcc`` and ``g++`` compilers are probably the easiest
    option (use Cygwin on Windows machines). See also the
    ``weavecompiler`` global preference.
``weavecompiler = gcc``
    Defines the compiler to use for weave compilation. On Windows machines, installing
    Cygwin is the easiest way to get access to the gcc compiler.
``gcc_options = ['-ffast-math']``
    Defines the compiler switches passed to the gcc compiler. For gcc versions
    4.2+ we recommend using ``-march=native``. By default, the ``-ffast-math``
    optimisations are turned on - if you need IEEE guaranteed results, turn
    this switch off.
``openmp = False``
    Whether or not to use OpenMP pragmas in generated C code. If supported
    on your compiler (gcc 4.2+) it will use multiple CPUs and can run
    substantially faster. However, if you are already running several
    simulations in parallel this will not improve the speed and may even
    slow it down. In addition, for smaller networks or for simpler neuron
    models the parallelisation overheads can make it take longer.
``usecodegen = False``
    Whether or not to use experimental code generation support.
``usecodegenweave = False``
    Whether or not to use C with experimental code generation support.
``usecodegenstateupdate = True``
    Whether or not to use experimental code generation support on state updaters.
``usecodegenreset = False``
    Whether or not to use experimental code generation support on resets.
    Typically slower due to weave overheads, so usually leave this off.
``usecodegenthreshold = True``
    Whether or not to use experimental code generation support on thresholds.
``usenewpropagate = False``
    Whether or not to use experimental new C propagation functions.
``usecstdp = False``
    Whether or not to use experimental new C STDP.
``brianhears_usegpu = False``
    Whether or not to use the GPU (if available) in Brian.hears. Support
    is experimental at the moment, and requires the PyCUDA package to be
    installed.
``magic_useframes = True``
    Defines whether or not the magic functions should search
    for objects defined only in the calling frame or if they
    should find all objects defined in any frame. This should
    be set to ``False`` if you are using Brian from an interactive
    shell like IDLE or IPython where each command has its own
    frame, otherwise set it to ``True``.