tanh_rate_ipn

class brainpy.state.tanh_rate_ipn(in_size, tau=Quantity(10., 'ms'), lambda_=1.0, sigma=1.0, mu=0.0, g=1.0, theta=0.0, mult_coupling=False, linear_summation=True, rectify_rate=0.0, rectify_output=False, rate_initializer=Constant(value=0.0), noise_initializer=Constant(value=0.0), name=None)

NEST-compatible tanh_rate_ipn nonlinear rate neuron with input noise.

Stochastic rate model with hyperbolic-tangent nonlinearity applied to network inputs, matching NEST’s rate_neuron_ipn template instantiated with tanh_rate gain function.

1. Model equations

The state \(X(t)\) evolves according to the Langevin equation

\[\tau\,dX(t)= \left[-\lambda X(t)+\mu+\phi(\cdot)\right]dt +\left[\sqrt{\tau}\,\sigma\right]dW(t),\]

where the input nonlinearity is

\[\phi(h)=\tanh(g(h-\theta)).\]

Here \(W(t)\) is a standard Brownian motion, \(\lambda\) is the passive decay rate, \(\mu\) is a constant drive, \(g\) is the gain, and \(\theta\) is the horizontal shift of the tanh function.

2. Numerical integration and noise implementation

For \(\lambda > 0\), integration uses the stochastic exponential Euler (exact for the Ornstein-Uhlenbeck process):

\[\begin{split}P_1 &= \exp(-\lambda h / \tau), \\ P_2 &= \frac{1 - P_1}{\lambda}, \\ X_{n+1} &= P_1 X_n + P_2 \left[\mu + \phi(\cdot)\right] + \sqrt{\frac{1-P_1^2}{2\lambda}} \sigma \xi_n,\end{split}\]

with \(\xi_n \sim \mathcal{N}(0,1)\). For \(\lambda = 0\), it reduces to Euler-Maruyama:

\[X_{n+1} = X_n + \frac{h}{\tau} \left[\mu + \phi(\cdot)\right] + \sqrt{\frac{h}{\tau}} \sigma \xi_n.\]

3. Update ordering (matching NEST ``rate_neuron_ipn`` with tanh)

Each simulation step proceeds as follows:

1. Store outgoing delayed value as current rate.

2. Draw noise = sigma * xi from the standard normal distribution.

3. Propagate intrinsic dynamics with stochastic exponential Euler (Euler-Maruyama for lambda=0).

4. Read delayed and instantaneous input buffers.

5. Apply input contributions:

   • linear_summation=True: apply tanh to summed branch inputs.

   • linear_summation=False: apply tanh per event before summation.

6. Apply rectification when rectify_output=True (clamp to >= rectify_rate).

7. Store outgoing instantaneous value as updated rate.

4. Timing semantics, assumptions, and constraints

• Noise term is white (independent at each step, variance scales with \(dt\)).

• For \(\lambda > 0\), integration exactly preserves stationary variance of the OU process.

• For \(\lambda = 0\), the process is non-stationary (variance grows linearly with time).

• Multiplicative coupling factors are fixed to 1 for tanh_rate models (mult_coupling has no effect; kept for NEST API compatibility).

5. Computational implications

Per update() call:

• Random number generation: \(O(\prod \mathrm{varshape})\).

• Exponential operations for \(P_1, P_2\) when \(\lambda > 0\).

• Event processing is linear in number of events per step.

• Broadcasting parameters and inputs over self.varshape.

Parameters:

• in_size (Size) – Population shape specification consumed by brainstate.nn.Dynamics. Determines output rate array shape.

• tau (ArrayLike, optional) – Time constant \(\tau\) of rate dynamics. Must be positive. Accepts scalar or array broadcast to self.varshape. Unitful values are converted to ms; unitless are interpreted as ms. Default 10.0 * u.ms.

• lambda (ArrayLike, optional) – Passive decay rate \(\lambda\) (dimensionless). Must be non-negative. For \(\lambda > 0\), uses stochastic exponential Euler; for \(\lambda = 0\), uses Euler-Maruyama. Default 1.0.

• sigma (ArrayLike, optional) – Input noise scale (dimensionless). Must be non-negative. Scales the Wiener increment. Broadcast to self.varshape. Default 1.0.

• mu (ArrayLike, optional) – Mean drive \(\mu\) (dimensionless). Constant additive input. Broadcast to self.varshape. Default 0.0.

• g (ArrayLike, optional) – Gain of tanh nonlinearity (dimensionless). Controls steepness of tanh. Broadcast to self.varshape. Default 1.0.

• theta (ArrayLike, optional) – Threshold (horizontal shift) of tanh nonlinearity (dimensionless). Shifts the input \(h\) before applying tanh. Broadcast to self.varshape. Default 0.0.

• mult_coupling (bool, optional) – Kept for NEST compatibility. For tanh_rate models, multiplicative coupling factors are identically 1, so this switch has no effect. Default False.

• linear_summation (bool, optional) – Controls nonlinearity application order. If True, sum inputs then apply tanh. If False, apply tanh per event then sum weighted results. Default True.

• rectify_rate (ArrayLike, optional) – Lower bound for output rate when rectify_output=True (dimensionless). Must be non-negative. Broadcast to self.varshape. Default 0.0.

• rectify_output (bool, optional) – If True, clamp updated rate to >= rectify_rate after all dynamics. Default False.

• rate_initializer (Callable, optional) – Initializer for state variable rate. Called as rate_initializer(self.varshape, batch_size) in init_state(). Default braintools.init.Constant(0.0).

• noise_initializer (Callable, optional) – Initializer for state variable noise (recording). Default braintools.init.Constant(0.0).

• name (str or None, optional) – Module name passed to brainstate.nn.Dynamics.

Parameter Mapping

Table 19 Parameter mapping to model symbols

Parameter	Default	Math symbol	Semantics
tau	10.0 * u.ms	\(\tau\)	Time constant of rate dynamics (ms).
lambda_	1.0	\(\lambda\)	Passive decay rate (dimensionless, >= 0).
sigma	1.0	\(\sigma\)	Input noise scale (dimensionless, >= 0).
mu	0.0	\(\mu\)	Constant mean drive (dimensionless).
g	1.0	\(g\)	Gain of tanh nonlinearity (dimensionless).
theta	0.0	\(\theta\)	Horizontal shift of tanh nonlinearity (dimensionless).
rectify_rate	0.0	\(r_{\min}\)	Lower clamp bound when rectify_output=True.

Raises:

• ValueError – If tau <= 0, lambda_ < 0, sigma < 0, or rectify_rate < 0.

• ValueError – If instant_rate_events specify non-zero delay_steps, or if delayed_rate_events specify negative delay_steps.

See also

tanh_rate_opn

Output-noise variant of tanh_rate.

sigmoid_rate_ipn

Sigmoid nonlinearity with input noise.

lin_rate_ipn

Linear (identity) nonlinearity with input noise.

gauss_rate_ipn

Gaussian nonlinearity with input noise.

Notes

Runtime events:

• instant_rate_events : applied in the current step (delay_steps=0).

• delayed_rate_events : scheduled with integer delay_steps >= 0.

Event format supports dict or tuple:

• Dict: {'rate': value, 'weight': w, 'delay_steps': d, 'multiplicity': m}

• Tuple: (rate, weight), (rate, weight, delay_steps), or (rate, weight, delay_steps, multiplicity)

References

[1]

NEST Simulator documentation for rate_neuron_ipn: https://nest-simulator.readthedocs.io/en/stable/models/rate_neuron_ipn.html

[2]

Hahne, J., Dahmen, D., Schuecker, J., Frommer, A., Bolten, M., Helias, M., & Diesmann, M. (2017). Integration of continuous-time dynamics in a spiking neural network simulator. Frontiers in Neuroinformatics, 11, 34.

Examples

>>> import brainpy
>>> import brainstate
>>> import saiunit as u
>>> import jax.numpy as jnp
>>> with brainstate.environ.context(dt=0.1 * u.ms):
...     net = brainpy.state.tanh_rate_ipn(
...         in_size=10,
...         tau=10.0 * u.ms,
...         lambda_=1.0,
...         sigma=0.5,
...         mu=0.0,
...         g=1.0,
...         theta=0.0,
...         rectify_output=True,
...         rectify_rate=0.0,
...     )
...     net.init_all_states()
...     rate = net.update(x=0.1)
...     _ = rate.shape  # (10,)

init_state(**kwargs)

Initialize state variables and internal buffers.

Create rate, noise, instant_rate, delayed_rate, and step counter states. Initialize delay queues.

Parameters:

**kwargs – Unused compatibility parameters accepted by the base-state API.

Notes

State variables are initialized from rate_initializer and noise_initializer. Both instant_rate and delayed_rate are initialized as copies of rate.

property receptor_types

Mapping of receptor type names to indices.

Returns:

{'RATE': 0} for rate-based connections.

Return type:

dict

property recordables

List of recordable state variables.

Returns:

['rate', 'noise'].

Return type:

list of str

update(x=0.0, instant_rate_events=None, delayed_rate_events=None, noise=None)

Advance rate dynamics by one simulation step.

Execute stochastic exponential Euler integration with input noise, process delayed and instant events, apply tanh nonlinearity, and optionally rectify output.

Parameters:

• x (ArrayLike, optional) – External current input (dimensionless). Broadcast to state shape and summed with mu. Default 0.0.

• instant_rate_events (list or None, optional) – Rate events to apply in the current step (delay_steps=0). Each event can be dict, tuple, or scalar. Default None.

• delayed_rate_events (list or None, optional) – Rate events to schedule with integer delays (delay_steps >= 0). Default None.

• noise (ArrayLike or None, optional) – Custom noise samples \(\xi\) drawn from \(\mathcal{N}(0,1)\). If None, random samples are drawn internally. Useful for reproducibility or testing. Default None.

Returns:

rate – Updated rate values with shape self.varshape (float64).

Return type:

ndarray

Notes

Update sequence:

1. Extract current step index and state shape.

2. Drain queued delayed inputs scheduled for this step.

3. Schedule new delayed events and accumulate zero-delay events.

4. Accumulate instant events and split delta inputs by sign.

5. Draw noise (or use provided noise).

6. Compute stochastic exponential Euler step:

   • For \(\lambda > 0\): use OU-exact propagators.

   • For \(\lambda = 0\): use Euler-Maruyama.

7. Apply tanh nonlinearity to summed inputs (if linear_summation=True) or use pre-transformed per-event values (if False).

8. Rectify output if rectify_output=True.

9. Update state variables and increment step counter.