<!-- examples/README-s4.md -->

# S4 arithmetic reference

Run `python3 examples/s4.py` from the repository root with Python 3.9 or newer.
There are no third-party dependencies. The script checks deterministic numerical
identities and prints errors; it does not train a model or load a checkpoint.

The five source regions are `hippo`, `discretize`, `recurrence`, `structure`,
and `kernel`. The annotated panels depend on shared helpers in the complete
file. Copy the full file to run them together. The rank-one kernel fixture is a
three-state real DPLR system with explicitly authored parameters, not the
complex diagonalization of a pretrained HiPPO model. The script verifies the
finite-length Cauchy/Woodbury construction using dense preprocessing and a
quadratic DFT. It demonstrates correctness, not S4's asymptotic speed.

Primary references:

- Gu, Goel and Ré, S4, ICLR 2022; arXiv v3:
  https://arxiv.org/abs/2111.00396v3
- Official implementation pinned at e757cef57d89e448c413de7325ed5601aceaac13:
  https://github.com/state-spaces/s4/blob/e757cef57d89e448c413de7325ed5601aceaac13/models/s4/s4.py

The JavaScript visualizations independently implement the same arithmetic.
`node --test test/s4-model.test.mjs` verifies identities and cross-language
agreement. Polynomial projection in the browser is an approximate midpoint
quadrature illustration, not an exact online HiPPO solver. No figures or model
outputs were copied from the paper.
