# BrianGlobalPreferences class

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

class brian2.core.preferences.BrianGlobalPreferences

  Bases: `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()

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

    Validates preferences that have not yet been validated.

  eval_pref(value)

    Evaluate a string preference in the units namespace

  get_documentation(basename=None, link_targets=True)

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

  load_preferences()

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

    Preference files are read in the following order:

    1. `~/.brian/user_preferences` from the user’s home directory

    2. `./brian_preferences` from the current directory

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

    See also

    `read_preference_file`

  read_preference_file(file)

    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)

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

    Resets the parameters to their default values.