braincell.quad.implicit_euler_step

braincell.quad.implicit_euler_step#

braincell.quad.implicit_euler_step(target, *args, t=None, dt=None)#

Advance one step with an implicit Newton-solved step.

Solves the trapezoidal (Crank-Nicolson) residual

\[g(y) = y - y_n - \frac{\Delta t}{2} \bigl(f(t_n, y_n) + f(t_{n+1}, y)\bigr) = 0\]

by Newton iteration. Each iteration assembles the full Jacobian \(J = \partial g / \partial y\) and updates \(y \leftarrow y - J^{-1} g(y)\) until either the residual norm or the Jacobian norm falls below 1e-5 or 100 iterations have been spent.

The trapezoidal rule is A-stable with local truncation error \(O(\Delta t^3)\) and global error \(O(\Delta t^2)\). Unlike an L-stable scheme it does not damp high-frequency components, so very stiff problems may ring rather than decay.

Parameters:
  • target (DiffEqModule) – The module whose DiffEqState leaves are advanced.

  • *args – Extra positional arguments forwarded to target’s compute_derivative and pre/post_integral hooks.

  • t (Quantity[s]) – Current simulation time. Defaults to the value in the active brainstate.environ context.

  • dt (Quantity[s]) – Time step; must carry units of time (e.g. 0.025 * u.ms). Defaults to the value in the active brainstate.environ context.

Returns:

target’s differential states are updated in place.

Return type:

None

See also

backward_euler_step

Single-Jacobian linearized backward Euler (one Newton iteration).

staggered_step

Staggered voltage / channel splitting, the solver

multi-compartment

class:braincell.Cell uses by default.

Notes

t and dt are keyword-only and optional, so this step matches the (target, *args) convention the model hosts call (self.solver(self) / self.solver(self, I_ext)) and is selectable through solver="implicit_euler".

The registered name and order=1 metadata describe implicit Euler, but the residual solved here is the trapezoidal one, as the equations above and _implicit_test.py both show. Reconciling the two means either renaming a public solver or changing the scheme, so it is left to a deliberate decision rather than settled by a refactor.

Examples

>>> import brainstate
>>> import brainunit as u
>>> from braincell.quad import implicit_euler_step
>>> with brainstate.environ.context(t=0. * u.ms, dt=0.025 * u.ms):
...     implicit_euler_step(my_neuron)