# utils package

Utility functions for Brian.

Exported members: `BrianLogger`, `get_logger()`, `std_silent`

## `arrays` module

Helper module containing functions that operate on numpy arrays.

Functions

`calc_repeats`(delay) | Calculates offsets corresponding to an array, where repeated values are subsequently numbered, i.e. if there n identical values, the returned array will have values from 0 to n-1 at their positions.

## `caching` module

Module to support caching of function results to memory (used to cache results of parsing, generation of state update code, etc.). Provides the `cached` decorator.

Classes

`CacheKey`() | Mixin class for objects that will be used as keys for caching (e.g. `Variable` objects) and have to define a certain "identity" with respect to caching.

Functions

`cached`(func) | Decorator to cache a function so that it will not be re-evaluated when called with the same arguments.

## `environment` module

Utility functions to get information about the environment Brian is running in.

Functions

`running_from_ipython`() | Check whether we are currently running under ipython.

## `filelock` module

A platform independent file lock that supports the with-statement.

Exported members: `BaseFileLock`, `FileLock`, `SoftFileLock`, `Timeout`, `UnixFileLock`, `WindowsFileLock`

Classes

`BaseFileLock`(lock_file[, timeout]) | Implements the base class of a file lock.

`FileLock` | Alias for the lock, which should be used for the current platform.

`SoftFileLock`(lock_file[, timeout]) | Simply watches the existence of the lock file.

`Timeout`(lock_file) | Raised when the lock could not be acquired in timeout seconds.

`UnixFileLock`(lock_file[, timeout]) | Uses the `fcntl.flock()` to hard lock the lock file on unix systems.

`WindowsFileLock`(lock_file[, timeout]) | Uses the `msvcrt.locking()` function to hard lock the lock file on windows systems.

Functions

`logger`() | Returns the logger instance used in this module.

## `filetools` module

File system tools

Exported members: `copy_directory`, `ensure_directory`, `ensure_directory_of_file`, `in_directory`

Classes

`in_directory`(new_dir) | Safely temporarily work in a subdirectory

Functions

`copy_directory`(source, target) | Copies directory source to target.

`ensure_directory`(d) | Ensures that a given directory exists (creates it if necessary)

`ensure_directory_of_file`(f) | Ensures that a directory exists for filename to go in (creates if necessary), and returns the directory path.

## `logger` module

Brian’s logging module.

### Preferences

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 occurred. If set to `False`, all log files will be kept.

`logging.display_brian_error_message` = `True`

> Whether to display a text for uncaught errors, mentioning the location of the log file, the mailing list and the github issues.

> Defaults to `True`.

`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, DEBUG or DIAGNOSTIC.

`logging.file_log_max_size` = `10000000`

> The maximum size for the debug log before it will be rotated.

> If set to any value `> 0`, the debug log will be rotated once this size is reached. Rotating the log means that the old debug log will be moved into a file in the same directory but with suffix `".1"` and the a new log file will be created with the same pathname as the original file. Only one backup is kept; if a file with suffix `".1"` already exists when rotating, it will be overwritten. If set to `0`, no log rotation will be applied. The default setting rotates the log file after 10MB.

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

Exported members: `BrianLogger`, `get_logger()`, `std_silent`

Classes

`BrianLogger`(name) | Convenience object for logging.

`HierarchyFilter`(name) | A class for suppressing all log messages in a subtree of the name hierarchy.

`LogCapture`(log_list[, log_level, only_from]) | A class for capturing log warnings.

`NameFilter`(name) | A class for suppressing log messages ending with a certain name.

`RemoveBrian2Filter`([name]) | A class for removing the `brian2` prefix from log messages.

`catch_logs`([log_level, only_from]) | A context manager for catching log messages.

`std_silent`([alwaysprint]) | Context manager that temporarily silences stdout and stderr but keeps the output saved in a temporary file and writes it if an exception is raised.

Functions

`brian_excepthook`(exc_type, exc_obj, exc_tb) | Display a message mentioning the debug log in case of an uncaught exception.

`clean_up_logging`() | Shutdown the logging system and delete the debug log file if no error occured.

`get_logger`([module_name]) | Get an object that can be used for logging.

`log_level_validator`(log_level) |

## `stringtools` module

A collection of tools for string formatting tasks.

Exported members: `SpellChecker`, `code_representation`, `deindent`, `get_identifiers`, `indent`, `replace`, `strip_empty_leading_and_trailing_lines`, `strip_empty_lines`, `stripped_deindented_lines`, `word_substitute`

Classes

`SpellChecker`(words[, alphabet]) | A simple spell checker that will be used to suggest the correct name if the user made a typo (e.g. for state variable names).

Functions

`code_representation`(code) | Returns a string representation for several different formats of code

`deindent`(text[, numtabs, spacespertab, ...]) | Returns a copy of the string with the common indentation removed.

`get_identifiers`(expr[, include_numbers]) | Return all the identifiers in a given string `expr`, that is everything that matches a programming language variable like expression, which is here implemented as the regexp `\b[A-Za-z_][A-Za-z0-9_]*\b`.

`indent`(text[, numtabs, spacespertab, tab]) | Indents a given multiline string.

`replace`(s, substitutions) | Applies a dictionary of substitutions.

`strip_empty_leading_and_trailing_lines`(s) | Removes all empty leading and trailing lines in the multi-line string `s`.

`strip_empty_lines`(s) | Removes all empty lines from the multi-line string `s`.

`stripped_deindented_lines`(code) | Returns a list of the lines in a multi-line string, deindented.

`word_substitute`(expr, substitutions) | Applies a dict of word substitutions.

## `topsort` module

Exported members: `topsort`

Functions

`topsort`(graph) | Topologically sort a graph