dc_generator

dc_generator#

class brainpy.state.dc_generator(in_size=1, amplitude=Quantity(0., 'pA'), start=Quantity(0., 'ms'), stop=None, origin=Quantity(0., 'ms'), name=None)#

DC current generator – NEST-compatible stimulation device.

Generate a constant current pulse and gate it with a half-open activity window using NEST-compatible parameter semantics.

1. Model equations

For each output channel, the generated current is

\[\begin{split}I(t) = \begin{cases} A & \text{if } t_{\mathrm{start}} \le t < t_{\mathrm{stop}}, \\ 0 & \text{otherwise}, \end{cases}\end{split}\]

where \(A\) is amplitude and

\[t_{\mathrm{start}} = t_0 + t_{\mathrm{start,rel}}, \qquad t_{\mathrm{stop}} = t_0 + t_{\mathrm{stop,rel}}.\]

If stop is None, then \(t_{\mathrm{stop}} = +\infty\) and the generator runs indefinitely from \(t_{\mathrm{start}}\) onward.

2. Timing semantics, assumptions, and constraints

The active interval is the half-open set \([t_{\mathrm{start}},\, t_{\mathrm{stop}})\). Since neuron states are advanced from t to t + dt in each step, a current enabled at \(t_{\mathrm{start}}\) first affects the membrane trajectory after that update (observable at \(t_{\mathrm{start}} + dt\)); the last active update starts at \(t_{\mathrm{stop}} - dt\).

This implementation is stateless: update() recomputes a boolean mask at each call using the environment time, then applies u.math.where(). Assumptions and constraints:

If stop <= start (after adding origin), the active set is empty and the output is identically zero for all t.
amplitude, start, stop, and origin must each be broadcastable to self.varshape; the shape check is performed by braintools.init.param() during __init__().
Unitless numerics in start, stop, and origin are treated as milliseconds; unitless numerics in amplitude are treated as pA.

3. Computational implications

Per-call complexity is \(O(\prod \mathrm{varshape})\), dominated by one broadcast allocation amplitude * ones(varshape) and one masked selection. No recurrent state is maintained, so the model is fully replayable given the same environment time sequence.

Parameters:

in_size (Size, optional) – Output size/shape specification understood by brainstate.nn.Dynamics. The emitted current shape is self.varshape derived from in_size. Default is 1.
amplitude (ArrayLike, optional) – Constant current amplitude \(A\) (typically pA). Scalars or arrays are accepted and broadcast to self.varshape via braintools.init.param(). Default is 0. * u.pA.
start (ArrayLike, optional) – Relative start time \(t_{\mathrm{start,rel}}\) (typically ms), broadcast to self.varshape. Effective start is origin + start (inclusive). Default is 0. * u.ms.
stop (ArrayLike or None, optional) – Relative stop time \(t_{\mathrm{stop,rel}}\) (typically ms), broadcast to self.varshape when provided. Effective stop is origin + stop (exclusive). None means the pulse never deactivates. Default is None.
origin (ArrayLike, optional) – Time origin \(t_0\) (typically ms) added to start and stop, broadcast to self.varshape. Default is 0. * u.ms.
name (str or None, optional) – Optional node name passed to brainstate.nn.Dynamics.

Parameter Mapping

Table 23 Parameter mapping to model symbols#
Parameter	Default	Math symbol	Semantics
`amplitude`	`0. * u.pA`	\(A\)	Constant current value emitted during the active window.
`start`	`0. * u.ms`	\(t_{\mathrm{start,rel}}\)	Relative start time; effective inclusive lower bound is `origin + start`.
`stop`	`None`	\(t_{\mathrm{stop,rel}}\)	Relative stop time; effective exclusive upper bound is `origin + stop`.
`origin`	`0. * u.ms`	\(t_0\)	Global offset applied to both window boundaries.

Raises:

ValueError – If in_size is invalid or if any array-like parameter cannot be broadcast to self.varshape by braintools.init.param().
TypeError – If invalid unitful/unitless arithmetic is provided (for example, values with incompatible units in current or time comparisons).

Notes

NEST recommends using neuron parameter I_e when a constant bias current is needed throughout the full simulation. Use dc_generator when the current must be switched on/off at specific simulation times.

See also

ac_generator: Sinusoidal current stimulation device.
step_current_generator: Piecewise-constant current stimulation.
noise_generator: Gaussian white-noise current stimulation.

References

Examples

>>> import brainpy
>>> import brainstate
>>> import saiunit as u
>>> with brainstate.environ.context(dt=0.1 * u.ms):
...     gen = brainpy.state.dc_generator(
...         in_size=1,
...         amplitude=500.0 * u.pA,
...         start=10.0 * u.ms,
...         stop=50.0 * u.ms,
...     )
...     with brainstate.environ.context(t=10.0 * u.ms):
...         current = gen.update()
...     _ = current.shape

>>> import brainpy
>>> import saiunit as u
>>> dc1 = brainpy.state.dc_generator(
...     amplitude=300.0 * u.pA,
...     start=0.0 * u.ms,
...     stop=100.0 * u.ms,
... )
>>> dc2 = brainpy.state.dc_generator(
...     amplitude=-200.0 * u.pA,
...     start=50.0 * u.ms,
...     stop=150.0 * u.ms,
... )

update()[source]#

Compute the window-gated constant current at environment time t.

Returns:

current – Current-like quantity with shape self.varshape and units inherited from amplitude. Values equal amplitude on channels where origin + start <= t < origin + stop (or t >= origin + start when stop is None), and zero elsewhere.

Return type:

jax.Array

Raises:

KeyError – If the environment time key 't' is not available in brainstate.environ.
TypeError – If t, start, stop, or origin cannot be compared due to incompatible units/dtypes.

Notes

Start is inclusive and stop is exclusive, matching NEST semantics. If stop <= start (after adding origin), the active set is empty and the output is identically zero for all t. The model carries no internal state, so repeated calls with the same environment time produce identical results.

dc_generator

Contents

dc_generator#