Add Liquid State Machine (LSM) model on top of SciMLProblemReservoir

[Saswatsusmoy]

Motivation

The fellowship roadmap (#397) originally scoped Liquid State Machines as PR5 (weeks 10-11). PR5 has since been redirected to ESN + Universal Differential Equations (per Francesco 2026-07-30), but LSM still deserves a landed implementation on top of the SciMLProblemReservoir + RCODEReservoirExt infrastructure now in place (#446, #450, #456, #479, #480).

Scope: a solid foundation for continuous-time spiking reservoirs — not a demo — with extension seams for future neuron models, encoders, and readouts. Modelled on how ContinuousESN landed.

Architectural principles

• Neuron model is pluggable via AbstractSpikingNeuron. Ship LIF; future Izhikevich / AdEx / HH slot in without touching the model layer.
• Input encoding is a first-class abstraction. Ship current-injection + Poisson rate encoders.
• Readout is a first-class abstraction. Ship spike-count, exponential-filter, and filtered-voltage readouts.
• E/I structure baked into initializers (Dale-compliant), not just rand_sparse.
• Callback semantics (refractory, threshold crossing, reset ordering) implemented once, correctly.

Files to add

Core dynamics

• src/layers/abstract_spiking.jl — AbstractSpikingNeuron contract: neuron_rhs!, reset!, spike_condition.
• src/layers/lif_cell.jl — LIFCell <: AbstractSpikingNeuron. Parameters: τ_m, V_rest, V_reset, V_th, τ_ref, R_m.

Connectivity

• src/inits/inits_lsm.jl — dale_sparse (E/I-balanced, default 4:1 per Maass), distance_dependent_sparse (optional).

Input encoding

• src/encoders/abstract_encoder.jl — AbstractInputEncoder contract.
• src/encoders/current_injection.jl — CurrentInjection (direct scaled current).
• src/encoders/poisson_rate.jl — PoissonRateEncoder (rate-coded Poisson spikes, RNG state in st.encoder).

Readouts (spike-side)

• src/readouts/spike_readout.jl — AbstractSpikeReadout contract.
• SpikeCountReadout(window) — binned counts, non-differentiable, ridge-only, teacher-forced only.
• ExponentialFilterReadout(τ) — leaky low-pass over spike train, smooth, supports AR.
• FilteredVoltageReadout — samples membrane potential (diagnostics / parity).

Model

• src/models/lsm.jl — LSM(in_dims, res_dims, out_dims; neuron=LIFCell(), encoder=CurrentInjection(), readout=ExponentialFilterReadout(...), connectivity=dale_sparse, kwargs...). Wires into SciMLProblemReservoir with VectorContinuousCallback for threshold crossings + refractory bookkeeping.

Extension wiring

• ext/RCODEReservoirExt.jl — verify remake preserves callbacks; extend as needed. Compose encoder-driven callbacks + reset callbacks via CallbackSet.

Validation

Unit correctness

• Single LIF neuron, constant suprathreshold current → analytical ISI within <1% of τ_m·ln((RI − V_rest)/(RI − V_th)).
• Refractory period enforced exact to callback tolerance.
• Reset atomic at threshold crossing.
• dale_sparse E/I ratio + row-sum balance within tolerance.
• Determinism: same seed → identical spike train.

Network dynamics

• Rich vs quiet regime demo: W scaling to land mean firing rate in 5–30 Hz for random input.
• ESP-equivalent: two initializations converge on same input stream (van Rossum spike distance).

End-to-end

• Regression: Mackey-Glass or Lorenz continuation, same protocol as ContinuousESN tutorial. Report honest NRMSE (expected ~2-3× worse than ContinuousESN at same N — spiking has lower capacity per neuron).
• Classification: one binary temporal task (pattern discrimination on random spike inputs, or MNIST-1D) with train/test split + baseline.

State-collection parity

• collectstates(::LSM, ...) returns (state_dims, T) — shape-compatible with ContinuousESN code paths.

Docs

• docs/src/api/models.md — LSM entry.
• docs/src/api/layers.md — LIFCell, AbstractSpikingNeuron.
• docs/src/api/encoders.md — new section (encoders + readouts).
• docs/src/tutorials/lsm.md — mathematical intro (LIF + Maass framework), one regression + one classification task, capacity caveat vs ContinuousESN.
• docs/src/refs.bib — Maass 2002, Legenstein & Maass 2007 (edge of chaos), Vreeken 2003 (LSM review), Gerstner & Kistler LIF chapter.

Risks + mitigations

• Callback × adaptive stepper — rare spike misses on stiff regimes. Default Tsit5 with explicit dtmax = τ_ref/4; document tradeoffs; test suite includes stiff-regime case.
• Poisson encoder reproducibility. RNG state lives in st.encoder, never in global state.
• remake + callbacks. Verify SciMLBase behavior early; ship workaround with upstream issue link if broken.
• AR predict with SpikeCountReadout. No continuous inverse — teacher-forced only, documented in docstring. ExponentialFilterReadout supports AR.

Deferred (extension seams left in place)

• Additional neuron models (Izhikevich, AdEx, HH) — mechanical via AbstractSpikingNeuron.
• STDP / online plasticity — needs train! extension.
• More encoders (temporal, phase, delta).
• Multi-compartment / columnar connectivity.
• Perf pass (sparse spike callbacks, GPU) — parallel to how perf(ext): reuse ODE integrator across AR predict windows #479 / perf(ext): sparse jac_prototype on the cell-path ODE #480 followed feat(models): ContinuousESN #456.

Scope

• ~1500-2500 LOC (code + tests + docs).
• Single PR (or 2 stacked: infra + model+demos).
• Estimated ~3 weeks solid work, mirroring ContinuousESN (feat(models): ContinuousESN #456) delivery cadence.

Related: #397 (fellowship tracking).

[Saswatsusmoy]

Hey @MartinuzziFrancesco — design pass on this before any src/ work. Closest template is ContinuousESN / RCODEReservoirExt.

remake + callbacks (the unknown from the issue): default remake(prob; tspan, p, u0) keeps problem-level callbacks with the same object. The real footgun is mutable state closed over by the callback (refractory clocks etc.) surviving across solves — not remake dropping the callback. For the built-in cell I would build a fresh ODEProblem + CallbackSet at collectstates time, same as ContinuousESN does today, and document initialize for anyone who attaches spiking callbacks to a bare SciMLProblemReservoir.

Shape I am aiming at: 3-field LSM → LSMCell <: AbstractSciMLProblemReservoir with pluggable neuron / encoder / spike-side feature readout, outer LinearReadout still ridge-trained. Spike features stay on the cell (not a new AbstractSampler). Poisson RNG only in st, event times precomputed so adaptive condition evals cannot re-draw.

Need your call before coding:

1. Name. LIF neuron as LIFCell (issue text) vs something like LeakyIFCell so it does not sit next to LIFESN (Local Information Flow). I lean LIFCell + clear docs unless you prefer the longer name.
2. Recurrent spikes. (a) instantaneous u[i] += W[i,j] in affect!, or (b) small exponential synaptic current in the continuous state. I lean (b) for the adaptive solver and AR path.
3. dtmax. Soft-default dtmax = τ_ref/4 on LSM when the user does not pass one, or document only and leave solve kwargs alone? I lean document-only unless you want the soft default.
4. Defaults. Ship with CurrentInjection, ExponentialFilterReadout, dale_sparse as in the issue text?

Will start implementation once these are settled. Happy to adjust any of the above.

[MartinuzziFrancesco]

Overall this feels like a solid sketch of the possible direction that LSMs would take in this package. I especially like the idea of having a high level LSM where we can simply change little pieces. I am just wondering if having these models live in the same RCODEReservoirExt file is the (conceptual) best way to go at this. For the moment I don't think it's a blocking issue though

1. naming is the most annoying issue, since sadly we have two models with identical acronyms. I would tend to just go with LIFCell and be extremely clear in the docs about the differences.
2. I would go with b) as well
3. let's go with document only
4. the defaults and approach seem well structured, I would start with that yes