LorenzStep

LorenzStep#

class brainmass.LorenzStep(in_size, sigma=10.0, rho=28.0, beta=2.6666666666666665, init_x=Constant(value=1.0), init_y=Constant(value=1.0), init_z=Constant(value=1.0), noise_x=None, method='exp_euler')#

Lorenz chaotic system as a network node.

The classic three-variable Lorenz (1963) system [1], a low-dimensional deterministic flow that exhibits sensitive dependence on initial conditions (deterministic chaos) for the standard parameters. The Virtual Brain ships it as a canonical non-neural test fixture for validating integration and network coupling. Structural coupling enters the \(x\) equation:

\[\begin{split}\begin{aligned} \dot x &= \sigma\,(y - x) + c, \\ \dot y &= x\,(\rho - z) - y, \\ \dot z &= x\,y - \beta\,z, \end{aligned}\end{split}\]

where \(c\) is the coupling/external input to \(x\). With the default \((\sigma, \rho, \beta) = (10, 28, 8/3)\) the system has a positive largest Lyapunov exponent (\(\approx 0.9\) per natural time unit): nearby trajectories separate exponentially while remaining bounded on the Lorenz attractor.

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.

  • sigma (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Prandtl number \(\sigma\). Default is 10.0.

  • rho (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Rayleigh number \(\rho\). Default is 28.0 (chaotic regime).

  • beta (Callable | Array | ndarray | bool | number | bool | int | float | complex | Quantity | Param) – Geometric parameter \(\beta\). Default is 8/3.

  • init_x (Callable) – State initializers. Defaults reproduce the canonical initial condition (1.0, 1.0, 1.0).

  • init_y (Callable) – State initializers. Defaults reproduce the canonical initial condition (1.0, 1.0, 1.0).

  • init_z (Callable) – State initializers. Defaults reproduce the canonical initial condition (1.0, 1.0, 1.0).

  • noise_x (Noise) – Additive noise process for the \(x\) equation. If provided, its output is added to the coupling input x_inp at each update. Default is None.

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

Return type:

Any

x, y, z

The three Lorenz coordinates (dimensionless). Shape (batch?,) + in_size.

Type:

brainstate.HiddenState

Notes

  • State variables are dimensionless; each right-hand side carries unit 1/ms so an exponential-Euler step with dt in milliseconds is consistent. One “natural” Lorenz time unit therefore corresponds to 1 ms here; a step of dt = 0.01 * u.ms reproduces the classic dimensionless dt = 0.01.

  • Because the flow is chaotic, two integrations that differ only in round-off (or integrator) diverge after a short horizon. Trajectory comparisons must use a short horizon; long-run agreement is not expected and is not a bug.

References

Examples

>>> import brainmass
>>> import brainstate
>>> import brainunit as u
>>> model = brainmass.LorenzStep(in_size=1)
>>> _ = brainstate.nn.init_all_states(model)
>>> with brainstate.environ.context(dt=0.01 * u.ms):
...     x = model.update()
>>> x.shape
(1,)
__init__(in_size, sigma=10.0, rho=28.0, beta=2.6666666666666665, init_x=Constant(value=1.0), init_y=Constant(value=1.0), init_z=Constant(value=1.0), noise_x=None, method='exp_euler')[source]#
Parameters:
derivative(state, t, x_inp)[source]#
dx(x, y, x_inp)[source]#

Right-hand side for x (unit 1/ms); x_inp is the coupling input.

dy(y, x, z)[source]#

Right-hand side for y (unit 1/ms).

dz(z, x, y)[source]#

Right-hand side for z (unit 1/ms).

init_state(batch_size=None, **kwargs)[source]#

Allocate the three Lorenz coordinates at their canonical initial values.

Parameters:

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

update(x_inp=None)[source]#

Advance the Lorenz node by one time step.

Parameters:

x_inp (array-like or scalar or None, optional) – Structural coupling/external input to the x equation. If None, treated as zero. If noise_x is set, its output is added. Default is None.

Returns:

The updated x coordinate, same shape as the internal state.

Return type:

array-like