braincell.quad.dhs_voltage_step

braincell.quad.dhs_voltage_step#

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

Advance the membrane voltage by one implicit-Euler DHS step.

Solves the linearized cable equation on a multi-compartment cell using the dendritic hierarchical solver (DHS): the axial coupling matrix is cast onto the node-tree representation of the morphology, the membrane derivative is linearized around the current voltage, and one implicit Euler update of the form

\[(I - \Delta t \, J)\, V_{n+1} = V_n + \Delta t \, b\]

is solved by a leaf-to-root forward elimination followed by a recursive-doubling back substitution. Both phases are pure jax.numpy kernels and run inside jit/vmap without dynamic shapes.

The public cell voltage lives on CV midpoints with shape [..., n_cv]. DHS solves the linear system on node-tree rows with shape [batch, n_point] plus one sentinel row used by the recursive doubling back-substitution. The full point solution is retained for point mechanisms and probes, while its midpoint rows update the public voltage state.

Parameters:

  • target (DiffEqModule) – A node-tree aware cell that exposes node_tree(), node_scheduling("dhs"), a voltage state V, and a per-CV capacitance/area description. In practice this is a braincell.Cell instance.

  • t (Quantity[s]) – Current simulation time. Used by compute_membrane_derivative and any time-dependent input bound through args.

  • dt (Quantity[s]) – Numerical time step for the implicit Euler update. Must carry units of time (e.g. 0.025 * u.ms).

  • *args – Extra arguments forwarded to target.compute_membrane_derivative (typically the injected currents).

Returns:

The full point voltage and target.V.value midpoint voltage are updated in place.

Return type:

None

Raises:

TypeError – If target does not expose the node_tree / node_scheduling attributes required by the DHS solver.

See also

staggered_step

Combines this DHS voltage step with an exponential Euler update for ion channels.

Notes

t and dt are keyword-only and optional, defaulting to the active brainstate.environ context, so this step matches the (target, *args) convention the hosts call and is selectable through Cell(solver="dhs_voltage"). staggered_step() passes both explicitly because it has already read them.

Note that this advances the voltage only; selecting it directly leaves gating variables and ion concentrations frozen. "staggered" is the solver that pairs it with a channel update.

The static topology metadata produced by _build_dhs_static_source (row lookup tables, edge ordering, recursive-doubling jump table) is assembled as NumPy integer data. Continuous coefficients are assembled from runtime cable arrays, and cached only outside tracing. Per-step numerical operands follow the current JAX precision, retaining units on voltage and dt * conductance factors.