Generic2dOscillatorStep

Generic2dOscillatorStep#

class brainmass.Generic2dOscillatorStep(in_size, a=-2.0, b=-10.0, c=0.0, d=0.02, e=3.0, f=1.0, g=0.0, alpha=1.0, beta=1.0, gamma=1.0, I=0.0, tau=1.0, init_V=Constant(value=0.0), init_W=Constant(value=0.0), noise_V=None, noise_W=None, method='exp_euler')#

Generic 2D oscillator with configurable nullclines (TVB Generic2dOscillator).

A flexible planar dynamical system with a fast variable \(V\) (membrane-like) and a slow recovery variable \(W\). By tuning the polynomial nullcline coefficients it reproduces a wide range of behaviours — excitability, bistability, relaxation oscillations — and many specific TVB 2-D models are special cases of it [1] [2] [3]:

\[\begin{split}\begin{aligned} \dot V &= d\,\tau\,\bigl(-f V^3 + e V^2 + g V + \alpha W + \gamma I + \gamma c\bigr) + s, \\ \dot W &= \frac{d}{\tau}\,\bigl(a + b V + c_{2} V^2 - \beta W\bigr), \end{aligned}\end{split}\]

where \(c\) is the (long-range + local) coupling input — scaled by \(\gamma\) like the intrinsic drive \(I\) — and \(s\) is a direct additive stimulus/noise term. The coefficient named \(c_2\) below is the quadratic-\(V\) coefficient of the \(W\) nullcline (the constructor argument is c).

Parameters:

  • in_size (int | Sequence[int] | integer | Sequence[integer]) – Spatial shape of the node. An int or tuple of int; all parameters broadcast to this shape.

  • a (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Constant term of the \(W\) nullcline. Default -2.0.

  • b (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Linear-\(V\) coefficient of the \(W\) nullcline. Default -10.0.

  • c (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Quadratic-\(V\) coefficient of the \(W\) nullcline (\(c_2\) in the equations). Default 0.0.

  • d (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Global time-scaling. Default 0.02.

  • e (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Quadratic-\(V\) coefficient of the \(V\) nullcline. Default 3.0.

  • f (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Cubic-\(V\) coefficient of the \(V\) nullcline. Default 1.0.

  • g (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Linear-\(V\) coefficient of the \(V\) nullcline. Default 0.0.

  • alpha (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – \(W \to V\) coupling strength. Default 1.0.

  • beta (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – \(W\) decay rate. Default 1.0.

  • gamma (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Scaling applied to the intrinsic drive \(I\) and the coupling input. Default 1.0.

  • I (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Constant external input current. Default 0.0.

  • tau (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Time-scale separation between \(V\) and \(W\) (tau > 1 makes \(V\) faster). Default 1.0.

  • init_V (Callable) – State initializers. Defaults braintools.init.Constant(0.0).

  • init_W (Callable) – State initializers. Defaults braintools.init.Constant(0.0).

  • noise_V (Noise) – Additive noise processes applied directly to the \(V\) / \(W\) derivatives (the TVB stimulus slot). Default None.

  • noise_W (Noise) – Additive noise processes applied directly to the \(V\) / \(W\) derivatives (the TVB stimulus slot). Default None.

  • method (str) – Integration method, 'exp_euler' (default) or any braintools.quad method (e.g. 'rk4').

Return type:

Any

V#

Fast variable (membrane-like). Shape (batch?,) + in_size.

Type:

brainstate.HiddenState

W#

Slow recovery variable.

Type:

brainstate.HiddenState

Notes

  • State variables are dimensionless; dV() / dW() carry unit 1/ms so an exponential-Euler step with dt in milliseconds is consistent.

  • Parameter regimes (a few of the published ones):

    • Excitable (FitzHugh-Nagumo-like, the defaults): a=-2, b=-10, c=0, d=0.02.

    • Bistable: a=1, b=0, c=-5, d=0.02 — two stable fixed points; the basin is selected by the initial condition.

    • Morris-Lecar-like: a=0.5, b=0.6, c=-4, d=0.02.

References

Examples

>>> import brainmass
>>> import brainstate
>>> import brainunit as u
>>> model = brainmass.Generic2dOscillatorStep(in_size=1)
>>> _ = brainstate.nn.init_all_states(model)
>>> with brainstate.environ.context(dt=0.1 * u.ms):
...     V = model.update()
>>> V.shape
(1,)
__init__(in_size, a=-2.0, b=-10.0, c=0.0, d=0.02, e=3.0, f=1.0, g=0.0, alpha=1.0, beta=1.0, gamma=1.0, I=0.0, tau=1.0, init_V=Constant(value=0.0), init_W=Constant(value=0.0), noise_V=None, noise_W=None, method='exp_euler')[source]#
Parameters:
dV(V, W, V_inp, add=0.0)[source]#

Right-hand side for the fast variable V (unit 1/ms).

V_inp is the coupling input (scaled by gamma like the intrinsic drive I); add is a direct additive stimulus/noise term.

dW(W, V, add=0.0)[source]#

Right-hand side for the slow recovery W (unit 1/ms).

derivative(state, t, V_inp, add_V=0.0, add_W=0.0)[source]#
init_state(batch_size=None, **kwargs)[source]#

Allocate the fast (V) and slow (W) states.

Parameters:

batch_size (int or None, optional) – Optional leading batch dimension. If None, no batch dimension is used. Default is None.

update(V_inp=None)[source]#

Advance the oscillator by one time step.

Parameters:

V_inp (array-like or scalar or None, optional) – Coupling input to the V equation (scaled by gamma). If None, treated as zero. Default is None.

Returns:

The updated fast variable V, same shape as the internal state.

Return type:

array-like