Group class

(Shortest import: from brian2 import Group)

class brian2.groups.group.Group(*args, **kwds)[source]

Bases: brian2.core.base.BrianObject

Mix-in class for accessing arrays by attribute.

# TODO: Overwrite the __dir__ method to return the state variables # (should make autocompletion work)

Methods

add_attribute(name) Add a new attribute to this group.
custom_operation(*args, **kwds)
get_states([vars, units, format, ...]) Return a copy of the current state variable values.
resolve(identifier[, user_identifier, ...]) Resolve an identifier (i.e.
resolve_all(identifiers[, user_identifiers, ...]) Resolve a list of identifiers.
run_regularly(code[, dt, clock, when, ...]) Run abstract code in the group’s namespace.
runner(*args, **kwds)
set_states(values[, units, format, level]) Set the state variables.
state(name[, use_units, level]) Return the state variable in a way that properly supports indexing in

Details

add_attribute(name)[source]

Add a new attribute to this group. Using this method instead of simply assigning to the new attribute name is necessary because Brian will raise an error in that case, to avoid bugs passing unnoticed (misspelled state variable name, un-declared state variable, ...).

Parameters:

name : str

The name of the new attribute

Raises

AttributeError
If the name already exists as an attribute or a state variable.
custom_operation(*args, **kwds)[source]
get_states(vars=None, units=True, format='dict', subexpressions=False, level=0)[source]

Return a copy of the current state variable values. The returned arrays are copies of the actual arrays that store the state variable values, therefore changing the values in the returned dictionary will not affect the state variables.

Parameters:

vars : list of str, optional

The names of the variables to extract. If not specified, extract all state variables (except for internal variables, i.e. names that start with '_'). If the subexpressions argument is True, the current values of all subexpressions are returned as well.

units : bool, optional

Whether to include the physical units in the return value. Defaults to True.

format : str, optional

The output format. Defaults to 'dict'.

subexpressions: bool, optional :

Whether to return subexpressions when no list of variable names is given. Defaults to False. This argument is ignored if an explicit list of variable names is given in vars.

level : int, optional

How much higher to go up the stack to resolve external variables. Only relevant if extracting subexpressions that refer to external variables.

Returns:

values :

The variables specified in vars, in the specified format.

resolve(identifier, user_identifier=True, additional_variables=None, run_namespace=None, level=0)[source]

Resolve an identifier (i.e. variable, constant or function name) in the context of this group. This function will first lookup the name in the state variables, then look for a standard function or unit of that name and finally look in Group.namespace and in run_namespace. If the latter is not given, it will try to find the variable in the local namespace where the original function call took place. See External variables and functions.

Parameters:

identifiers : str

The name to look up.

user_identifier : bool, optional

Whether this is an identifier that was used by the user (and not something automatically generated that the user might not even know about). Will be used to determine whether to display a warning in the case of namespace clashes. Defaults to True.

additional_variables : dict-like, optional

An additional mapping of names to Variable objects that will be checked before Group.variables.

run_namespace : dict-like, optional

An additional namespace, provided as an argument to the Network.run() method.

level : int, optional

How far to go up in the stack to find the original call frame.

Returns:

obj : Variable or Function

Returns a Variable object describing the variable or a Function object for a function. External variables are represented as Constant objects

Raises

KeyError
If the identifier could not be resolved
resolve_all(identifiers, user_identifiers=None, additional_variables=None, run_namespace=None, level=0)[source]

Resolve a list of identifiers. Calls Group.resolve() for each identifier.

Parameters:

identifiers : iterable of str

The names to look up.

user_identifiers : iterable of str, optional

The names in identifiers that were provided by the user (i.e. are part of user-specified equations, abstract code, etc.). Will be used to determine when to issue namespace conflict warnings. If not specified, will be assumed to be identical to identifiers.

additional_variables : dict-like, optional

An additional mapping of names to Variable objects that will be checked before Group.variables.

run_namespace : dict-like, optional

An additional namespace, provided as an argument to the Network.run() method.

level : int, optional

How far to go up in the stack to find the original call frame.

do_warn : bool, optional

Whether to warn about names that are defined both as an internal variable (i.e. in Group.variables) and in some other namespace. Defaults to True but can be switched off for internal variables used in templates that the user might not even know about.

Returns:

variables : dict of Variable or Function

A mapping from name to Variable/Function object for each of the names given in identifiers

Raises

KeyError
If one of the names in identifier cannot be resolved
run_regularly(code, dt=None, clock=None, when='start', order=0, name=None, codeobj_class=None)[source]

Run abstract code in the group’s namespace. The created CodeRunner object will be automatically added to the group, it therefore does not need to be added to the network manually. However, a reference to the object will be returned, which can be used to later remove it from the group or to set it to inactive.

Parameters:

code : str

The abstract code to run.

dt : Quantity, optional

The time step to use for this custom operation. Cannot be combined with the clock argument.

clock : Clock, optional

The update clock to use for this operation. If neither a clock nor the dt argument is specified, defaults to the clock of the group.

when : str, optional

When to run within a time step, defaults to the 'start' slot.

name : str, optional

A unique name, if non is given the name of the group appended with ‘run_regularly’, ‘run_regularly_1’, etc. will be used. If a name is given explicitly, it will be used as given (i.e. the group name will not be prepended automatically).

codeobj_class : class, optional

The CodeObject class to run code with. If not specified, defaults to the group‘s codeobj_class attribute.

Returns:

obj : CodeRunner

A reference to the object that will be run.

runner(*args, **kwds)[source]
set_states(values, units=True, format='dict', level=0)[source]

Set the state variables.

Parameters:

values : depends on format

The values according to format.

units : bool, optional

Whether the values include physical units. Defaults to True.

format : str, optional

The format of values. Defaults to 'dict'

level : int, optional

How much higher to go up the stack to resolve external variables. Only relevant when using string expressions to set values.

state(name, use_units=True, level=0)[source]

Return the state variable in a way that properly supports indexing in the context of this group

Parameters:

name : str

The name of the state variable

use_units : bool, optional

Whether to use the state variable’s unit.

level : int, optional

How much farther to go down in the stack to find the namespace.

Returns :

——- :

var : VariableView or scalar value

The state variable’s value that can be indexed (for non-scalar values).