BrianGlobalPreferences class

(Shortest import: from brian2.core.preferences import BrianGlobalPreferences)

class brian2.core.preferences.BrianGlobalPreferences[source]

Bases: _abcoll.MutableMapping

Class of the prefs object.

Used for getting/setting/validating/registering preference values. All preferences must be registered via register_preferences. To get or set a preference, you can either use a dictionary-based or an attribute-based interface:

prefs['core.default_float_dtype'] = float32
prefs.core.default_float_dtype = float32

Preferences can be read from files, see load_preferences and read_preference_file. Note that load_preferences is called automatically when Brian has finished importing.

Attributes

as_file Get a Brian preference doc file format string for the current preferences
defaults_as_file Get a Brian preference doc file format string for the default preferences
toplevel_categories The toplevel preference categories

Methods

check_all_validated() Checks that all preferences that have been set have been validated.
do_validation() Validates preferences that have not yet been validated.
eval_pref(value) Evaluate a string preference in the units namespace
get_documentation([basename, link_targets]) Generates a string documenting all preferences with the given basename.
load_preferences() Load all the preference files, but do not validate them.
read_preference_file(file) Reads a Brian preferences file
register_preferences(prefbasename, …) Registers a set of preference names, docs and validation functions.
reset_to_defaults() Resets the parameters to their default values.

Details

as_file

Get a Brian preference doc file format string for the current preferences

defaults_as_file

Get a Brian preference doc file format string for the default preferences

toplevel_categories

The toplevel preference categories

check_all_validated()[source]

Checks that all preferences that have been set have been validated.

Logs a warning if not. Should be called by Network.run() or other key Brian functions.

do_validation()[source]

Validates preferences that have not yet been validated.

eval_pref(value)[source]

Evaluate a string preference in the units namespace

get_documentation(basename=None, link_targets=True)[source]

Generates a string documenting all preferences with the given basename. If no basename is given, all preferences are documented.

load_preferences()[source]

Load all the preference files, but do not validate them.

Preference files are read in the following order:

  1. brian2/default_preferences from the Brian installation directory.
  2. ~/.brian/user_preferences from the user’s home directory
  3. ./brian_preferences from the current directory

Files that are missing are ignored. Preferences read at each step override preferences from previous steps.

read_preference_file(file)[source]

Reads a Brian preferences file

The file format for Brian preferences is a plain text file of the form:

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

Blank and comment lines are ignored, all others should be of one of the following two forms:

key = value
[section]

eval is called on the values, so strings should be written as, e.g. '3' rather than 3. The eval is called with all unit names available. Within a section, the section name is prepended to the key. So in the above example, it would give the following unvalidated dictionary:

{'a.b.c': 1,
 'a.b.d': 2,
 'a.b.e': 3,
 }
Parameters:

file : file, str

The file object or filename of the preference file.

register_preferences(prefbasename, prefbasedoc, **prefs)[source]

Registers a set of preference names, docs and validation functions.

Parameters:

prefbasename : str

The base name of the preference.

prefbasedoc : str

Documentation for this base name

**prefs : dict of (name, BrianPreference) pairs

The preference names to be defined. The full preference name will be prefbasename.name, and the BrianPreference value is used to define the default value, docs, and validation function.

Raises

PreferenceError
If the base name is already registered.

See also

BrianPreference

reset_to_defaults()[source]

Resets the parameters to their default values.