Train state-space sequence models with PyTorch, with optional guarantees on their input/output gain.
Use neural-ssm for nonlinear system identification, streaming predictions, and
learning models for control. Start with a small recurrent model, train it with
ordinary PyTorch operations, then add a gain bound or context when you need it.
First model · Gain bounds · Model choices · Metrics · Context · Tutorials
The core package requires Python 3.9+ and PyTorch 2.2+. From a terminal:
git clone https://github.com/DecodEPFL/SSM.git
cd SSM
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .Run the examples below in Python. They use small synthetic sequences and require no dataset download. For the plotting and benchmark tools, also install:
python -m pip install -e ".[experiments]"For CUDA, install the PyTorch build matching your machine before installing the package. The project does not install a CUDA runtime itself.
Follow these steps in order, in the same Python session.
import torch
from neural_ssm import DeepSSM
u = torch.randn(1, 8, 1) # one sequence, eight time steps, one input featureEvery sequence uses the shape (batch, time, features). For example,
(4, 100, 3) means four independent sequences, each with 100 samples and three
input features.
model = DeepSSM(
d_input=1, d_output=1, param="lru",
d_model=4, d_state=8, n_layers=1,
)
y, state = model(u)
print(y.shape) # torch.Size([1, 8, 1]): one prediction per time stepThis is a stable LRU recurrent baseline. Its weights are trainable; it does not have a prescribed whole-model gain bound.
| Setting | Meaning in this example |
|---|---|
d_input=1, d_output=1 |
One input and one output value per sample |
d_model=4 |
Four features inside the network |
d_state=8 |
Eight memory coordinates in each recurrent layer |
n_layers=1 |
One recurrent block |
state contains one final memory tensor per layer. Here, state[0] has shape
(1, 8). LRU memory is complex-valued; pass the returned tensor back unchanged.
For a tiny example, ask the model to predict 0.3 times its input:
target = 0.3 * u # replace this with your measured output sequence
optimizer = torch.optim.Adam(model.parameters(), lr=1e-2)
model.train()
for step in range(20):
optimizer.zero_grad(set_to_none=True) # clear previous gradients
prediction, _ = model(u) # start a fresh sequence
loss = (prediction - target).square().mean()
loss.backward() # differentiate through the sequence
optimizer.step() # update the weightsWith your own data, supply input and target tensors with matching batch and time
axes. The target's last dimension is d_output.
Pass the first chunk's final state into the second chunk:
model.eval() # disable training-time dropout
with torch.no_grad():
first, state = model(u[:, :4], detach_state=True)
second, state = model(u[:, 4:], state=state, detach_state=True)
y_streamed = torch.cat((first, second), dim=1)This produces the same predictions as processing the complete sequence, up to
floating-point differences. An explicit state continues from that memory;
without it, a call starts a fresh trajectory by default.
For training across chunks, keep detach_state=False (the default). Use True
at a truncated-backpropagation boundary to discard the preceding gradient
history. reset_state=False instead continues from the model's stored internal
state; model.reset() clears that state.
Keep the same dimensions, and choose a certified recurrent core and bounded feedforward branch:
bounded = DeepSSM(
1, 1, d_model=4, d_state=8, n_layers=1,
param="defect", ff="LGLU2", gamma=1.0,
)
y, state = bounded(u)
print(bounded.certified_gain_bound().item()) # at most the requested gammagamma=1.0 means that, starting from zero state, the output sequence's
squared energy cannot exceed the input sequence's squared energy. More generally:
This is an upper bound enforced by the parametrization throughout training. It is not an estimate from sampled inputs, and the model's actual gain can be smaller. It bounds the full sequence, rather than each output sample separately.
Use a certified core from the table below and one of LGLU2, BLGLU2
(BudgetedLGLU2 is an alias), MBLIP, or TLIP for ff. Ordinary MLP/GLU
and the historical LGLU/LMLP choices require gamma=None. Keep
learn_x0=False for the zero-state statement; a nonzero initial state needs an
additional storage-energy term, available through storage_value(state).
A zero-state gain bound and an incremental bound are different guarantees:
the latter controls differences between two input/output trajectories.
MetricDeepSSM below provides an incremental certificate. Input-dependent
selective cells do not automatically provide that stronger guarantee.
Each DeepSSM block combines a recurrence that carries memory with a feedforward
branch that mixes features at each time step. param selects the recurrence;
ff selects the feedforward. LTI cores keep their matrices fixed over time;
selective cores can change their matrices at each sample.
The following modes apply to DeepSSM:
param |
What it provides | Execution modes |
|---|---|---|
lru |
Stable complex diagonal LTI baseline; use gamma=None |
scan, conv, loop |
defect |
Certified real-block LTI core using thin defect completion | scan, loop |
l2n |
Certified LTI core using full-system norm normalization | scan, loop; conv with identity storage only |
tv |
Certified selective diagonal dynamics depending on input/context | scan, loop |
tvc |
Selective dynamics with an additional direct input/output term | scan, loop |
l2ru, zak |
Legacy certified LTI constructions | scan, loop |
l2nt |
Legacy dense normalized LTI construction | loop |
scan evaluates the recurrence in parallel over time. loop is the sequential
reference. Where supported, conv evaluates the LTI response using FFT
convolution. Compare supported modes on your sequence sizes and device.
To reuse settings across models, collect them in a configuration:
from dataclasses import replace
from neural_ssm import SSMConfig
config = SSMConfig(d_model=4, d_state=8, n_layers=1,
param="defect", ff="LGLU2", gamma=1.0)
normalized = DeepSSM(1, 1, config=replace(config, param="l2n"))
selective = DeepSSM(1, 1, config=replace(config, param="tv"))When you pass config, it supplies the model settings; make changes in the
configuration itself. gamma is the fixed whole-stack target. train_gamma
controls the cells' internal gain parameters, and train_ff_lip controls the
feedforward gain parameters.
The state metric defect
and l2n support a full, learned
full_l2n = DeepSSM(1, 1, config=replace(config,
param="l2n", l2n_state_metric="full"))
full_defect = DeepSSM(1, 1, config=replace(config,
defect_state_metric="full", defect_max_radius=1.0, defect_factor_margin=0.0))Identity storage is the default and has cheaper matrix preparation. Full storage allows the small blocks to share a dense certificate, covering generic strictly gain-bounded LTI input/output maps. This statement concerns the LTI core; it does not claim completeness of the nonlinear network. Exact larger Jordan chains may require larger blocks. The defect settings above remove fixed pole and contraction margins from that construction.
Identity L2N uses rotation pairs and requires even d_state. Full L2N uses
general real 2×2 blocks and accepts an odd state size with a final scalar; use
scan or loop. Defect's default block size is two. Its full storage supports
block sizes one through four, with a final scalar for odd sizes when the block
size is two. Larger identity-storage blocks are also available through
defect_block_size.
Full storage adds dense preparation and backward work; the small-block recurrence stays fast. See the defect construction and measured full-metric comparison for the details and computational tradeoffs.
MetricDeepSSM learns feature-energy metrics gamma=1.0 bounds output differences by input differences when the
two executions start from equal states.
from neural_ssm import MetricDeepSSM
metric = MetricDeepSSM(
1, 1, d_model=4, d_state=8, n_layers=2,
param="defect", gamma=1.0, state_metric="full",
)
y = metric(u, return_state=False) # predictions onlyThis is a separate architecture: an LTI core, an activation, and an optional
coupled residual feedforward in each layer. Built-in cores are defect and
l2n; ff is residual (the default) or none. Activations are tanh (the
default), relu, arctan, and identity. Execution modes are scan and loop.
Use MetricSSMConfig when collecting these settings in a configuration.
The feature metric state_metric="full" additionally enables
dense state storage inside either LTI core. A tighter certificate does not
promise an exact gain calculation or better prediction accuracy.
State returns differ from the ordinary stack:
| Call | Return |
|---|---|
model(u) or controller(u, z) |
(y, final_states) |
metric(u) |
(y, state_trajectories), including the initial state |
metric(u, return_state=False) |
y |
metric(u, return_state=False, return_last=True) |
(y, final_states) for streaming |
For streaming a metric model, pass those final states into the next call with
state=final_states; the same detach_state choices apply. Keep certificate
parameters in float32 or float64. Read the
metric tutorial for a gradual introduction,
or the architecture guide for the equations.
Context is a second sequence, such as an operating condition or reference. Start by adding it as an extra input feature:
from neural_ssm import ContextualDeepSSM
z = torch.ones(1, 8, 1) # same batch and time axes as u
controller = ContextualDeepSSM(
1, 1, 1, ssm_config=config,
context_modes="input", context_filter="none",
)
y, state = controller(u, z)The positional dimensions are d_input, d_context, and d_output. Here,
"none" leaves context unchanged. With the input port, the gain certificate
applies to the combined input [u, filtered_context]; context contributes
its own energy and may produce output even when u is zero.
Introduce the other ports one at a time, then combine them using a tuple such
as context_modes=("gate", "select"):
| Port | What context changes |
|---|---|
input |
Adds filtered context to the input features |
gate |
Attenuates residual branches with gates in [0, 1] |
mixer |
Applies a context-dependent output matrix with a fixed norm cap |
select |
Schedules the recurrent dynamics; requires tv or tvc |
The context tutorial covers these ports,
finite/decaying windows, difference filtering, context encoders, and streaming.
For chunked filtering, time_offset counts samples already processed;
difference filtering also needs the previous raw context sample via
previous_context.
A fixed-context incremental certificate needs select_input="context",
context-only gates/mixing (gate_include_disturbance=False,
mixer_include_disturbance=False), and no additive input port. Both runs must
use the same exogenous context and initial state. Check
controller.incremental_gain_bound() for this guarantee and
controller.gain_diagnostics() for the zero-state certificate and filter details.
These diagnostics do not establish stability of an arbitrary feedback loop.
Move the model and its inputs to the same device. For inference, combine
eval() with disabled gradients to reuse prepared matrices safely:
model.eval()
with torch.inference_mode():
y, state = model(u)Training and evaluation with gradients rebuild the required computation graph. Caches are invalidated after parameter updates, checkpoint loads, or dtype/device changes; see parameter caching.
torch.compile(model) is optional and has a warm-up cost. Keep shapes stable
and measure it on your hardware. Compile regression tests cover the main stacks;
they do not guarantee a speedup with every backend. For fixed-shape CUDA
selective scans, set use_cuda_graph=True in SSMConfig. REN remains eager.
The lessons start with small examples and add one concept at a time. Each uses
numbered # %% cells, which supporting editors can run individually.
| Start here | What you will learn |
|---|---|
| DeepSSM tutorial | Construction, training, streaming, current/legacy cores, and feedforward choices |
| Context tutorial | Each context port separately, filters, streaming, and combinations |
| Metric tutorial | Shared metrics, state returns, training, and energy checks |
Run a complete lesson from the repository root:
python Test_files/Tutorial_DeepSSM.py
python Test_files/Tutorial_ContextualSSM.py
python Test_files/Tutorial_MetricDeepSSM.pyThe written walkthrough follows the same progression.
With the experiments extra installed, discover available datasets and models:
python Test_files/run_benchmarks.py --listThen run a short CPU comparison on the Cascaded Tanks benchmark:
python Test_files/run_benchmarks.py \
--benchmarks Cascaded_Tanks --models defect l2n metric_defect metric_l2n \
--device cpu --epochs 10The runner downloads the selected benchmark data, evaluates the official
validation split, and saves figures and reports under Test_files/benchmark_runs/.
Use --device cuda on a CUDA machine. --mode auto selects convolution for LRU
and identity L2N, and scan for the other current SSMs. Add
--l2n-state-metric full --defect-state-metric full to enable dense storage in
both ordinary and metric models. --metric-ff controls the metric stack's
feedforward independently of --ff.
For a desktop form, run python Test_files/benchmark_ui.py (requires Tk support).
For the standalone delayed-cue robot navigation task, click Delayed navigation…
in that window, or run python -m delayed_navigation.ui directly. Load
delayed_navigation/configs/ui-l2n-comparison.json
in the example window. It exports final PNG/PDF comparisons and optional GIFs.
The navigation guide explains the exact tank,
bistable memory, GRU/LSTM/L2RU/L2N/REN baselines, metrics and initial CPU results.
For a synthetic four-way timing comparison of identity/full L2N and defect,
run python scripts/compare_defect_vs_normalization.py. Add
--l2n-state-metric full --defect-state-metric full to compare only full storage.
The retained L2RU/ZAK comparison covers legacy
constructions.
src/neural_ssm/
├── ssm/
│ ├── config.py, registry.py shared settings and model construction
│ ├── layers.py DeepSSM and residual blocks
│ ├── metric_layers.py MetricDeepSSM and its feature metrics
│ ├── contextual.py context ports and filters
│ └── cells/ lti/, selective/, legacy/
├── static_layers/ ordinary and bounded feedforward layers
├── rens/ren.py robust acyclic recurrent equilibrium network
└── utils/ scan, Lyapunov, state, and cache helpers
Public imports include DeepSSM, SSMConfig, MetricDeepSSM, MetricSSMConfig,
ContextualDeepSSM, and REN. Standalone cells are also exported from
neural_ssm; see the package guide for canonical
imports, compatibility aliases, and adding a cell.
For development:
python -m pip install -e ".[dev,experiments]"
python -m pytestFor the original L2-bounded SSM parametrizations, cite Leonardo Massai, Muhammad Zakwan, and Giancarlo Ferrari-Trecate, L2RU: a Structured State Space Model with prescribed L2-bound.
The metric-transfer approach has a separate precedent in LipSSM: Structurally Lipschitz-Bounded Cascaded State-Space Model via Metric Transfer between Consecutive SSM Layers. The package's current core choices and metric residual layers extend beyond the original L2RU paper; consult the linked construction guides for their assumptions.