README.md

# Metriplex

> **A neural layer class whose invariants hold *exactly, per layer, to machine
> precision* — the discrete, learnable form of GENERIC dynamics, built for
> physical AI: models that must roll out learned dynamics for long horizons
> without their physics unraveling.**

Continuous-time metriplectic networks learn vector fields whose invariants
hold in the continuous limit — and any integrator used in deployment
introduces drift. **MetriplecticLayer** makes the invariant *algebraic*: one
forward pass is one step of a metriplectic flow, and each channel's invariant
holds for every parameter value, at every step, after any amount of training,
because it is a property of the map itself.

**Paper:** [manuscript.pdf](manuscript.pdf) (Nature Machine Intelligence
format). Every number in the paper reads from a committed JSON under
`results/` — never hand-typed. Figures and `results/summary.tex` (the macro
file the manuscript is typeset from) regenerate with one script.

**Live:** project site on GitHub Pages
(https://sehajr-singhs.github.io/metriplex/); the committed
results on Kaggle
(https://www.kaggle.com/datasets/sehajrsingh/metriplex-results);
trained checkpoints (safetensors + model cards + zero-install `usage.py`)
and the papers on a Hugging Face model repo
(https://huggingface.co/Sejibeji/Metriplex); a mirror of the site
on Hugging Face Spaces
(https://sejibeji-metriplex.static.hf.space).

## The layer

One discrete metriplectic step, three channels:

```text
h' = h + Δt·Φ(h) − Δt·γ·F(h)         [+ R(h), optional]

  Φ(h)  flux:        h + W·φ(h) with 𝟙ᵀW = 0     →  Σh' = Σh, exact, any φ
  F(h)  friction:    Cayley transform of BBᵀ ⪰ 0  →  ‖h'‖ ≤ ‖h‖, exact
  R(h)  rotation:    Cayley transform of S = −Sᵀ   →  ‖h'‖ = ‖h‖, exact
  γ     gate:        learnable, starts closed (σ ≈ 0); must be opened to
                     represent dissipation
```

- **Balanced flux** is the discrete-divergence form of a conservation law:
  the residual of the channel is an exchange, never a source or sink — the
  exact, learnable counterpart of divergence-free (Hamiltonian) flows.
- **Metric friction** is the second law as a structural fact: the map cannot
  create "energy" out of nothing; the learned subspace `B` decides *where*
  energy is dissipated, the sign is not learned.
- **The gate forces the model to decide, from data, whether its world is
  open.** Conservative systems leave it closed; dissipative systems open it.

The same class instantiates as an MLP (depth is integration time), an RNN
(the layer is the cell, applied every rollout step), and a GNN (flux message
passing on a mesh — the *predicted field* conserves mass).

## What survived contact with the mathematics

1. **Exactness survives training and deployment.** Latent drift sits at the
   machine-precision floor for every metriplectic model — ~10⁻¹³ in
   structural float64 measurement, ~10⁻⁷ in float32 deployment. Baselines
   have no conserved quantity by construction, so there is nothing to
   measure on their side: that is the point. On advection–diffusion the
   invariant is *physical*: the metriplectic GNN conserves the predicted
   field's mass to ~10⁻¹³ while the plain GNN with identical data and
   parameters leaks a substantial fraction of it.
2. **Structure shows in the shape of the error curve, not its height.**
   NeuralODE, a continuous-time map in the raw state space, is the tightest
   one-step fitter on these smooth small-state ODE benchmarks; the
   metriplectic model sits in the MLP-family band. On the spring its
   horizon growth ratio is far below NeuralODE, LSTM, and HNN and
   of the same order as ResMLP; on damped spring the error is essentially
   flat with horizon (metriplectic ≈ ResMLP ≈ NeuralODE), while the LSTM
   compounds.
3. **Channel choice is the physics of the target system.** The exact
   ablation isolates it: on the spring, the channel that matches the physics wins: circulation
   (conserving the energy-like ‖h‖) fits measurably better than flux (0.457
   vs 0.585); on Kepler the same switch *hurts* (1.373 vs 0.396), because
   circulation conserves the wrong quantity there. Structure matters
   exactly when it matches — and measurably when it does not.
4. **The friction gate is born closed and stays closed on these data.** The
   measured gates end at σ(γ) ≈ 0.003 even on the damped spring: the flux
   channel alone suffices to fit the transitions. The guarantee that
   survives is the sign of the channel — the friction map is a contraction
   wherever the gate sits, so the model can never represent a growing latent
   norm.
5. **Recurrent long-horizon stability.** The metriplectic RNN (reversible
   channel as the cell, skew generator conditioned on the physical
   parameters) conserves its latent norm step after step over 2× the
   training horizon (~3.8×10⁻¹⁶): the Cayley map is orthogonal for every
   parameter value, so the state is bounded forever by construction. The
   LSTM fits the transitions more tightly on this benchmark (0.44 vs 0.95
   final error), but its latent carries no conserved quantity — nothing
   about its long-horizon behavior is guaranteed.

## Measured results (nothing extrapolated; medians over 5 seeds, per-seed values committed)

| Claim | Where |
|---|---|
| Latent drift, structural (float64) | ~10⁻¹³, all metriplectic models | 
| Field mass drift, metriplectic GNN vs plain GNN | ~10⁻¹³ vs ~10⁻¹ on advection–diffusion |
| One-step fidelity | NeuralODE is tightest; metriplectic in the MLP band (reported plainly) |
| Horizon growth ratio (spring) | far below NeuralODE/LSTM/HNN, comparable to ResMLP |
| Channel choice | circulation matches the spring's energy-like invariant (0.457 vs 0.585); hurts on Kepler (1.373 vs 0.396) |
| Friction gate | born closed; measured ≈ 0.003 on damped spring |
| RNN over 2× horizon | metriplectic: norm exact (~3.8×10⁻¹⁶), bounded by construction; LSTM fits tighter (0.44 vs 0.95) but no conserved quantity |
| Data efficiency | invariant exact at every budget (25/50/100%) |
| Higher-dimensional payoff | tightest MLP-family baseline on 6-D coupled springs (HNN included); lowest horizon growth on the chaotic double pendulum (3.9 vs 5.8 NeuralODE / 8.3 HNN) |

## Repo layout

```
manuscript.tex / .pdf      the paper (NMI format)
ieee_paper.tex / .pdf      the paper (IEEE format)
supplementary_information.tex / .pdf
index.html                 the project website
src/metnet/                layers.py (the class + theorems), models.py,
                           benchmarks.py, train.py, test_metnet.py
scripts/                   run_experiments.py, make_figs.py,
                           train_lightning.py (PyTorch Lightning training),
                           export_models.py (train + export the headline
                           models to safetensors)
export/                    trained checkpoints: model.safetensors + config.json
                           + per-model cards + usage.py (zero-install demo)
results/                   committed result JSONs + manifest + summary.tex
tests/                     the invariant theorems, float64 + float32 floor
figs/                      regenerated by scripts/make_figs.py
```

## Reproduce

```bash
pip install -r requirements.txt
python -m unittest tests.test_metnet     # 17 tests: the theorems, pinned
python scripts/run_experiments.py --seeds 3   # all benchmarks, ablations,
                                              # data efficiency, RNN stress
python scripts/make_figs.py              # figures + results/summary.tex
cd .. && pdflatex manuscript.tex         # the paper

# the same protocol on PyTorch Lightning (CPU / GPU / distributed with one flag):
python scripts/train_lightning.py --bench spring --seeds 3 --epochs 100

# train + export the headline models to safetensors (also on Hugging Face):
python scripts/export_models.py
```

## Honest gaps

The friction channel contracts the state norm — the right structure for
these benchmarks, but not the full GENERIC degeneracy. The conserved quantity
is a *learned* latent invariant: the layer guarantees that *some* quantity is
conserved exactly, and the network must discover the physically meaningful
one (the field GNN is the case where the invariant lives in the predicted
state and is therefore physically exact). Extending exactness from latent
structure to named physical invariants is the central open problem.

## License

MIT — see [LICENSE](LICENSE).