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