Generalized LIF (GLIF)
from livn.models.glif import GLIF
from livn.system import predefined
GLIF(level=5, mechanism="hard") # full Allen GLIF5
GLIF(level=1, mechanism="hard") # leaky integrate-and-fire
GLIF(level=5, mechanism="escape") # stochastic spike mechanism
GLIF.leaky_integrate_and_fire() # the textbook LIF, parameters and allGLIF is livn's point neuron. It is not one model among several but a space with two axes with a level (1–5, which parameters are in play) and a mechanism (hard or escape, how a spike is decided).
For fitting, a level is exactly a mask over the trainable parameter set:
GLIF(level=3).trainable_params()
# ('tau_m', 'E_L', 'g_L', 'V_threshold_base', 'theta_decay_rate', 'asc_amp_1', ...)Units
GLIF is a delibarate exception to the unit convention so parameters keep their Allen Institute names without suffix. Everything is in mV / pA / ms: tau_m and t_ref in ms, E_L and the threshold in mV, g_L in nS (so I/g_L is a voltage), decay rates in 1/ms. A stimulus reaching env.run on the diffrax backend is scaled by current_scale (nA by default) before it is added.
Mechanisms
Both mechanisms watch the same quantity, V − Θ, and differ only in what they do with it.
hard | escape | |
|---|---|---|
| a spike is | the root of V − Θ | the root of S = ∫λ dt, with λ = exp((V − Θ)/σ)/τ_s |
| deterministic | yes | no: S restarts from log(U) − α after every spike |
| backends | diffrax, brian2 | diffrax |
| extra parameters | — | sigma, tau_s, alpha |
GLIF(mechanism="escape", params={"sigma": 1.0})Networks
env = Env(predefined("EI")), model=GLIF(level=1)).init()
env.module.network # (cells, cells), w[pre, post]; None when unconnectedWeights must be set before init() on the diffrax backend since the connectivity is baked into the module:
env = Env(predefined("S1")), model=GLIF()).set_weights({"EXC_EXC": 400.0}).init()Each cell carries a synaptic current i_syn that decays with tau_syn and jumps by w[pre, post] at every presynaptic spike, scaled by any mechanism's presynaptic() output (e.g. a depression resource).
Synaptic channels
Synapses at several timescales, e.g. fast AMPA, NMDA and GABA_B, are a stack of weight matrices, one channel each, with a tau_syn per channel:
from livn.models.glif import GlifNeurons
network = np.stack([w_fast, w_nmda, w_gaba_b]) # (channels, cells, cells)
neurons = GlifNeurons(n, {"tau_syn": [10.0, 200.0, 600.0]}, network=network)
solution = neurons.solve(current, 0.0, 1000.0, 0.1, record={"spikes", "i_syn"})
solution.i_syn # (cells, T, channels)- Each channel is its own state column per cell, jumping by
w_c[pre, post]and decaying with itstau_cwith the cell driven by their sum. A sharedWwith a per-channel split by presynaptic sign is the stackw_c = W⁺ q_c⁺ + W⁻ q_c⁻. tau_synbroadcasts from the trailing axis to(cells, channels)so(channels,)is one decay per channel,(cells, channels)one per cell and channel.- A
(cells, cells)matrix, or a stack of one, is the single-channel network, with the same state layout and bit-identical results. - The channels sit at
layout.i_syn_columnsof the state, soy0andyTcarry all of them. Synaptic currents keep decaying through a cell's refractory period. - Channels add state columns, not event conditions, so they do not slow root finding.
A network is one event-driven solve that integrates between events and restarts at every spike and every end of a refractory period, anywhere in the network:
from livn.models.eventloop import SolverConfig
GLIF(config=SolverConfig(
vectorized_events=True, # the default: one event condition for the whole network
dt_solver=0.1, # Euler step between events, in ms
max_segment_span=1.0, # cut a solve 1 ms after its last restart
checkpoints=1 << 30, # reverse mode: store every segment and step
))vectorized_events(the default) hands the solver the largest of the cells' conditions instead of one condition per cell, so a step does not grow with the network, and the earliest crossing in a step is the one located. Root finding on the maximum relies on a monotone interpolant: use it withEuler.vectorized_events=Falsegives the solver one condition per cell, which other solvers need; then two cells crossing within one step fire in the order of their index, and the one located second starts the next solve above threshold and loses its spike.- Recording nothing but spikes skips the sampled trace and keeps only the state at each segment's end; the spikes are the same.
- Batched with
vmap, every window waits for the longest solve of an iteration, so a quiet stretch in one window holds up all of them; short segments bound that.max_segment_span=math.infrestarts only at events, which suits a single window. - Reverse mode recomputes each loop about twice unless
checkpointsis raised; the state of a segment is small and its steps are bounded, so storing all of them costs little memory. - Events are located on the step's interpolant, so a coarse
dt_solvermoves spike times by its integration error, not by the step.
Noise
sigma_v is a membrane diffusion amplitude, available to either mechanism. The Brownian path is a structural part of the solve, so it has to be asked for:
GLIF(diffusion=True, params={"sigma_v": 1.0})
env.set_noise({"sigma_v": 1.0}) # equivalently, per runBatching
num_samples runs independent realisations of the same stimulus and every returned array gains a leading sample axis:
run = env.run(100.0, stimulus, dt=0.1, num_samples=8)
run.voltage # (8, cells, T)
run.spikes.padded.times # (8, cells, k)
run.spikes.raster(0.1) # (8, cells, T)Spikes come back as a rectangle — one row per cell, inf-padded — because that is the shape the solver can allocate before it knows how many events there will be. A batched run has no ragged form at all, since the number of spikes differs per sample, so run.spike_times raises there and points you at .padded or .raster().
Recordable states
Beyond spikes and voltage, GLIF exposes the rest of its state to env.record(). Each lands on the run's own dt grid as a Series channel:
| signal | shape | what it is |
|---|---|---|
threshold | [n_cells, T] | Θ(t) = Θ_inf + θ_s(t) + θ_v(t), the value the voltage is compared against |
theta_s | [n_cells, T] | the spike-driven component θ_s, zero at levels 1 and 3 |
theta_v | [n_cells, T] | the voltage-coupled component θ_v, level 5 only |
AScurrents | [n_cells, T, 2] | the two after-spike currents, zero at levels 1 and 2 |
env = env.record_voltage()
env = env.record("threshold")
run = env.run(100)
run["threshold"].values # [n_cells, T]env = env.record_voltage(dt=dt)
env = env.record("threshold")
env = env.record_spikes()
run = env.run(duration, stimulus, dt=dt)
run.spikes.padded.times # exact event times, differentiableInserting mechanisms
GLIF can be extended using GlifMechanism, an equinox.Module whose fields are its parameters, returned in the Model's diffrax_mechanisms(env):
import equinox as eqx
import jax.numpy as jnp
import numpy as np
from livn.env import Env
from livn.models.glif import GLIF, GlifMechanism, cell_populations
from livn.stimulus import Stimulus
class LightCurrent(GlifMechanism):
# its state columns, after the cell's own, and the stimulus modes it reads besides
# the current
states: tuple[str, ...] = eqx.field(static=True, default=("s",), kw_only=True)
inputs: tuple[str, ...] = eqx.field(static=True, default=("irradiance",), kw_only=True)
g: jnp.ndarray # pA at full activation, per cell
tau: float = 5.0 # parameters
def drift(self, t, v, states, inputs):
s = states[:, 0]
ds = (inputs["irradiance"] * (1.0 - s) - s) / self.tau
return self.g * s, ds[:, None] # current into V in pA, d states / dt
class OptoGLIF(GLIF):
def diffrax_mechanisms(self, env):
populations = cell_populations(env) # one name per cell, in module order
return (LightCurrent(g=jnp.asarray(np.where(populations == "EXC", 50.0, 0.0))),)
env = Env(system, model=OptoGLIF(level=5)).init()
run = env.run(100.0, Stimulus.from_current(current) + Stimulus.from_irradiance(light))| member | ||
|---|---|---|
states | static field (eqx.field(static=True, kw_only=True)) | names of its state columns; also what env.record() takes once the model lists them in recordable_states() |
inputs | static field | what it reads: the stimulus modes irradiance, conductance, current_density, or current (the injected current in pA), the cell's own threshold state theta_s, theta_v or threshold, and dt, the step its states are integrated with (0 under an adaptive controller), for a stiff mechanism to take its fast transitions exactly |
initial(n_cells) | optional | [cells, len(states)] at t0; zeros by default |
drift(t, v, states, inputs) | required | (current [cells] in pA, d states / dt [cells, len(states)]) between events; inputs is {mode: [cells]} at t |
on_spike(fired, states[, inputs]) | optional | the states after the cells in fired [cells] spiked; only fired rows are kept. If it takes inputs, they are read just before the spike |
presynaptic(states) | optional | [cells] scaling each cell's outgoing synaptic jumps (from the states before on_spike), or None |
The cells are from env.simulated_gids(everywhere=True) with cell_populations(env) naming each one's population.
What a spike does to a mechanism:
- The voltage reset does not touch its states, so an opsin carries through a spike.
on_spikeacts at the spike time. The cell's own threshold and after-spike jumps land at the end of the refractory cut instead, which is Allen's ordering.- Across the refractory cut the states keep integrating with V held at its reset value, as the threshold and after-spike currents keep decaying there. The current a mechanism injects is dropped while V is clamped, like every other current.
A stimulus mode is accepted only when a mechanism reads it so a GLIF Env without one refuses an irradiance stimulus. With no mechanisms the model is exactly the GLIF above. Mechanisms run on the diffrax backend only.
Opsins
To use livn.models.opsins.chr2 (ChR2[H134R], Williams et al. 2013) in GLIF, activate the livn.models.opsins.ChR2H134R mechanism:
from livn.models.glif import GLIF, cell_populations
from livn.models.opsins.glif import ChR2H134R
class OptoGLIF(GLIF):
def diffrax_mechanisms(self, env):
exc = cell_populations(env) == "EXC"
return (ChR2H134R(g_nS=jnp.asarray(np.where(exc, 40.0, 0.0)), celsius=34.0),)Its two light-driven transitions (C1 → O1, C2 → O2) move over each fixed solver step what an exact decay would (Rush–Larsen), so bright light cannot destabilise the explicit step: their rates grow with irradiance, and with the plain rates the occupancies diverged above about 2 / (0.19 dt_solver) mW/mm² between spikes and about 140 mW/mm² in a 7 ms refractory cut.