State update

In Brian, a state updater transforms a set of equations into an abstract state update code (and therefore is automatically target-independent). In general, any function (or callable object) that takes an Equations object and returns abstract code (as a string) can be used as a state updater and passed to the NeuronGroup constructor as a method argument.

The more common use case is to specify no state updater at all or chose one by name, see Choice of state updaters below.

Explicit state update

Explicit state update schemes can be specified in mathematical notation, using the ExplicitStateUpdater class. A state updater scheme contains a series of statements, defining temporary variables and a final line (starting with x_new =), giving the updated value for the state variable. The description can make reference to t (the current time), dt (the size of the time step), x (value of the state variable), and f(x, t) (the definition of the state variable x, assuming dx/dt = f(x, t). In addition, state updaters supporting stochastic equations additionally make use of dW (a normal distributed random variable with variance dt) and g(x, t), the factor multiplied with the noise variable, assuming dx/dt = f(x, t) + g(x, t) * xi.

Using this notation, simple forward Euler integration is specified as:

x_new = x + dt * f(x, t)

A Runge-Kutta 2 (midpoint) method is specified as:

k = dt * f(x,t)
x_new = x + dt * f(x +  k/2, t + dt/2)

When creating a new state updater using ExplicitStateUpdater, you can specify the stochastic keyword argument, determining whether this state updater does not support any stochastic equations (None, the default), stochastic equations with additive noise only ('additive'), or arbitrary stochastic equations ('multiplicative'). The provided state updaters use the Stratonovich interpretation for stochastic equations (which is the correct interpretation if the white noise source is seen as the limit of a coloured noise source with a short time constant). As a result of this, the simple Euler-Maruyama scheme (x_new = x + dt*f(x, t) + dW*g(x, t)) will only be used for additive noise.

An example for a general state updater that handles arbitrary multiplicative noise (under Stratonovich interpretation) is the derivative-free Milstein method:

x_support = x + dt*f(x, t) + dt**.5 * g(x, t)
g_support = g(x_support, t)
k = 1/(2*dt**.5)*(g_support - g(x, t))*(dW**2)
x_new = x + dt*f(x,t) + g(x, t) * dW + k

Note that a single line in these descriptions is only allowed to mention g(x, t), respectively f(x, t) only once (and you are not allowed to write, for example, g(f(x, t), t)). You can work around these restrictions by using intermediate steps, defining temporary variables, as in the above examples for milstein and rk2.

Choice of state updaters

As mentioned in the beginning, you can pass arbitrary callables to the method argument of a NeuronGroup, as long as this callable converts an Equations object into abstract code. The best way to add a new state updater, however, is to register it with brian and provide a method to determine whether it is appropriate for a given set of equations. This way, it can be automatically chosen when no method is specified and it can be referred to with a name (i.e. you can pass a string like 'euler' to the method argument instead of importing euler and passing a reference to the object itself).

If you create a new state updater using the ExplicitStateUpdater class, you have to specify what kind of stochastic equations it supports. The keyword argument stochastic takes the values None (no stochastic equation support, the default), 'additive' (support for stochastic equations with additive noise), 'multiplicative' (support for arbitrary stochastic equations).

After creating the state updater, it has to be registered with StateUpdateMethod:

new_state_updater = ExplicitStateUpdater('...', stochastic='additive')
StateUpdateMethod.register('mymethod', new_state_updater)

The preferred way to do write new general state updaters (i.e. state updaters that cannot be described using the explicit syntax described above) is to extend the StateUpdateMethod class (but this is not strictly necessary, all that is needed is an object that implements a __call__ method that operates on an Equations object and a dictionary of variables). Optionally, the state updater can be registered with StateUpdateMethod as shown above.

Implicit state updates

Note

All of the following is just here for future reference, it’s not implemented yet.

Implicit schemes often use Newton-Raphson or fixed point iterations. These can also be defined by mathematical statements, but the number of iterations is dynamic and therefore not easily vectorised. However, this might not be a big issue in C, GPU or even with Numba.

Backward Euler

Backward Euler is defined as follows:

x(t+dt)=x(t)+dt*f(x(t+dt),t+dt)

This is not a executable statement because the RHS depends on the future. A simple way is to perform fixed point iterations:

x(t+dt)=x(t)
x(t+dt)=x(t)+dt*dx=f(x(t+dt),t+dt)    until increment<tolerance

This includes a loop with a different number of iterations depending on the neuron.