Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,159 @@
+# 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/metriplectic-layers-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).