ExplicitStateUpdater class¶
(Shortest import: from brian2 import ExplicitStateUpdater)
-
class
brian2.stateupdaters.explicit.
ExplicitStateUpdater
(description, stochastic=None, custom_check=None)[source]¶ Bases:
brian2.stateupdaters.base.StateUpdateMethod
An object that can be used for defining state updaters via a simple description (see below). Resulting instances can be passed to the
method
argument of theNeuronGroup
constructor. As other state updater functions theExplicitStateUpdater
objects are callable, returning abstract code when called with anEquations
object.A description of an explicit state updater consists of a (multi-line) string, containing assignments to variables and a final “x_new = …”, stating the integration result for a single timestep. The assignments can be used to define an arbitrary number of intermediate results and can refer to
f(x, t)
(the function being integrated, as a function ofx
, the previous value of the state variable andt
, the time) anddt
, the size of the timestep.For example, to define a Runge-Kutta 4 integrator (already provided as
rk4
), use:k1 = dt*f(x,t) k2 = dt*f(x+k1/2,t+dt/2) k3 = dt*f(x+k2/2,t+dt/2) k4 = dt*f(x+k3,t+dt) x_new = x+(k1+2*k2+2*k3+k4)/6
Note that for stochastic equations, the function
f
only corresponds to the non-stochastic part of the equation. The additional functiong
corresponds to the stochastic part that has to be multiplied with the stochastic variable xi (a standard normal random variable – if the algorithm needs a random variable with a different variance/mean you have to multiply/add it accordingly). Equations with more than one stochastic variable do not have to be treated differently, the part referring tog
is repeated for all stochastic variables automatically.Stochastic integrators can also make reference to
dW
(a normal distributed random number with variancedt
) andg(x, t)
, the stochastic part of an equation. A stochastic state updater could therefore use a description like:x_new = x + dt*f(x,t) + g(x, t) * dW
For simplicity, the same syntax is used for state updaters that only support additive noise, even though
g(x, t)
does not depend onx
ort
in that case.There a some restrictions on the complexity of the expressions (but most can be worked around by using intermediate results as in the above Runge- Kutta example): Every statement can only contain the functions
f
andg
once; The expressions have to be linear in the functions, e.g. you can usedt*f(x, t)
but notf(x, t)**2
.Parameters: description : str
A state updater description (see above).
stochastic : {None, ‘additive’, ‘multiplicative’}
What kind of stochastic equations this state updater supports:
None
means no support of stochastic equations,'additive'
means only equations with additive noise and'multiplicative'
means supporting arbitrary stochastic equations.Raises
ValueError
- If the parsing of the description failed.
Notes
Since clocks are updated after the state update, the time
t
used in the state update step is still at its previous value. Enumerating the states and discrete times,x_new = x + dt*f(x, t)
is therefore understood as \(x_{i+1} = x_i + dt f(x_i, t_i)\), yielding the correct forward Euler integration. If the integrator has to refer to the time at the end of the timestep, simply uset + dt
instead oft
.Attributes
DESCRIPTION
A complete state updater description EXPRESSION
A single expression OUTPUT
The last line of a state updater description STATEMENT
An assignment statement TEMP_VAR
Legal names for temporary variables Methods
DESCRIPTION
A complete state updater description EXPRESSION
A single expression OUTPUT
The last line of a state updater description STATEMENT
An assignment statement TEMP_VAR
Legal names for temporary variables __call__
(eqs[, variables, method_options])Apply a state updater description to model equations. replace_func
(x, t, expr, temp_vars, eq_symbols)Used to replace a single occurance of f(x, t)
org(x, t)
:expr
is the non-stochastic (in the case off
) or stochastic part (g
) of the expression defining the right-hand-side of the differential equation describingvar()
.Details
-
DESCRIPTION
= {[Group:({~{"x_new"} W:(abcd...,abcd...) Suppress:("=") rest of line})]... Group:({Suppress:("x_new") Suppress:("=") rest of line})}¶ A complete state updater description
-
EXPRESSION
= rest of line¶ A single expression
-
OUTPUT
= Group:({Suppress:("x_new") Suppress:("=") rest of line})¶ The last line of a state updater description
-
STATEMENT
= Group:({~{"x_new"} W:(abcd...,abcd...) Suppress:("=") rest of line})¶ An assignment statement
-
TEMP_VAR
= {~{"x_new"} W:(abcd...,abcd...)}¶ Legal names for temporary variables
-
DESCRIPTION
() Requires all given C{ParseExpression}s to be found in the given order. Expressions may be separated by whitespace. May be constructed using the C{‘+’} operator. May also be constructed using the C{‘-‘} operator, which will suppress backtracking.
- Example::
integer = Word(nums) name_expr = OneOrMore(Word(alphas))
expr = And([integer(“id”),name_expr(“name”),integer(“age”)]) # more easily written as: expr = integer(“id”) + name_expr(“name”) + integer(“age”)
-
EXPRESSION
() Token for matching strings that match a given regular expression. Defined with string specifying the regular expression in a form recognized by the inbuilt Python re module. If the given regex contains named groups (defined using C{(?P<name>…)}), these will be preserved as named parse results.
- Example::
- realnum = Regex(r”[+-]?d+.d*”) date = Regex(r’(?P<year>d{4})-(?P<month>dd?)-(?P<day>dd?)’) # ref: http://stackoverflow.com/questions/267399/how-do-you-match-only-valid-roman-numerals-with-a-regular-expression roman = Regex(r”M{0,4}(CM|CD|D?C{0,3})(XC|XL|L?X{0,3})(IX|IV|V?I{0,3})”)
-
OUTPUT
() Converter to return the matched tokens as a list - useful for returning tokens of C{L{ZeroOrMore}} and C{L{OneOrMore}} expressions.
- Example::
ident = Word(alphas) num = Word(nums) term = ident | num func = ident + Optional(delimitedList(term)) print(func.parseString(“fn a,b,100”)) # -> [‘fn’, ‘a’, ‘b’, ‘100’]
func = ident + Group(Optional(delimitedList(term))) print(func.parseString(“fn a,b,100”)) # -> [‘fn’, [‘a’, ‘b’, ‘100’]]
-
STATEMENT
() Converter to return the matched tokens as a list - useful for returning tokens of C{L{ZeroOrMore}} and C{L{OneOrMore}} expressions.
- Example::
ident = Word(alphas) num = Word(nums) term = ident | num func = ident + Optional(delimitedList(term)) print(func.parseString(“fn a,b,100”)) # -> [‘fn’, ‘a’, ‘b’, ‘100’]
func = ident + Group(Optional(delimitedList(term))) print(func.parseString(“fn a,b,100”)) # -> [‘fn’, [‘a’, ‘b’, ‘100’]]
-
TEMP_VAR
() Requires all given C{ParseExpression}s to be found in the given order. Expressions may be separated by whitespace. May be constructed using the C{‘+’} operator. May also be constructed using the C{‘-‘} operator, which will suppress backtracking.
- Example::
integer = Word(nums) name_expr = OneOrMore(Word(alphas))
expr = And([integer(“id”),name_expr(“name”),integer(“age”)]) # more easily written as: expr = integer(“id”) + name_expr(“name”) + integer(“age”)
-
__call__
(eqs, variables=None, method_options=None)[source]¶ Apply a state updater description to model equations.
Parameters: eqs :
Equations
The equations describing the model
variables: dict-like, optional :
The
Variable
objects for the model. Ignored by the explicit state updater.method_options : dict, optional
Additional options to the state updater (not used at the moment for the explicit state updaters).
Examples
>>> from brian2 import * >>> eqs = Equations('dv/dt = -v / tau : volt') >>> print(euler(eqs)) _v = -dt*v/tau + v v = _v >>> print(rk4(eqs)) __k_1_v = -dt*v/tau __k_2_v = -dt*(0.5*__k_1_v + v)/tau __k_3_v = -dt*(0.5*__k_2_v + v)/tau __k_4_v = -dt*(__k_3_v + v)/tau _v = 0.166666666666667*__k_1_v + 0.333333333333333*__k_2_v + 0.333333333333333*__k_3_v + 0.166666666666667*__k_4_v + v v = _v
-
replace_func
(x, t, expr, temp_vars, eq_symbols, stochastic_variable=None)[source]¶ Used to replace a single occurance of
f(x, t)
org(x, t)
:expr
is the non-stochastic (in the case off
) or stochastic part (g
) of the expression defining the right-hand-side of the differential equation describingvar()
. It replaces the variablevar()
with the value given asx
andt
by the value given fort
. Intermediate variables will be replaced with the appropriate replacements as well.For example, in the
rk2
integrator, the second step involves the calculation off(k/2 + x, dt/2 + t)
. Ifvar()
isv
andexpr
is-v / tau
, this will result in-(_k_v/2 + v)/tau
.Note that this deals with only one state variable
var()
, given as an argument to the surrounding_generate_RHS
function.