README.md

---
license: mit
library_name: pytorch
tags:
  - physics-simulation
  - projective-dynamics
  - neural-physics
  - graphics
  - fluid-simulation
  - soft-body
  - from-scratch
  - research
---

# 🌊 Neural Physics Engine — learned constraint projectors

**A projective-dynamics (PD) engine in which the per-element *local* constraint
projections are learned neural networks, while rotations and the *global* solve stay
exactly analytic.** One tiny network, shared across every element and across constraint
*types* via material tokens, sits inside an exact reduced global solve.

> **Status: work in progress.** This is a research artifact from an 8-week build; the
> local-projector results are strong, the global-reduction results are proven
> in-distribution, and the fully-learned-solver path is deliberately left for later. It
> was not finished — see *Roadmap & what's next* below.

Try it [here](https://quazim0t0-neural-physics-engine-demo.static.hf.space/)
---

## What's in here

| File | What it is | Params |
|---|---|---|
| `unified_projector.pt` | A tied constraint projector serving **5 solid materials *and* the fluid** via material tokens. Encoder→latent→decoder; rotation stays analytic. Ships `state_dict`, `materials`, `k`, and `fluid_scales` (the water-token calibration). | ~10k |
| `warm_start_net.pt` | A rotation-**equivariant** net that predicts the PD solver's converged correction as a residual on classical extrapolation — cuts iterations at fixed tolerance. | ~1.5k |
| `engine3d/` | The engine: `solver.py` (PD solid solver, exact reduced global step), `fluid.py` (PBF-3D with a `lambda_fn` hook), `neural.py` (`NeuralTiedProjector`, `WarmStartNet`), `rotation.py`, `strain.py`, `materials.py`, `mesh.py`. |
| `images/` | Validation figures (below). |
| `*.html` | Standalone browser demos (WebGPU). |
| `neural_physics_engine_roadmap.md` | The full design/scaling roadmap this was built against. |

---

## The core idea

Every system here follows one skeleton:

```
per-element LOCAL PROJECTION   →   GLOBAL RECONCILIATION
(tied / shared across elements)     (exact reduced solve)
```

The bet: **replace each hand-derived local projection with a learned one, keep the
skeleton, and keep the analytic symmetry handling.** Rotations are *not* learned — polar
decomposition (closed-form 2D, Müller-iterative 3D) is exact and cheap, and removing it
from the learning problem is what lets a tiny latent suffice. Two guards are baked into
the architecture (not patched on):

- **Rejection form** `f(e) = e − r(e)`: the network learns what to *remove*, so admissible
  strains pass at gain ≈ 1 (mirrors PCA's within-subspace gain of exactly 1; avoids
  artificial damping inside the solver loop).
- **Zero-anchoring** `r(0) = 0`: rest strain maps exactly to rest.

A **new material is a new token row, not a new network** — the tied-embedding thesis. The
fluid is just a 6th token: PBF's density constraint is another tied local projector, so the
same weights that serve the solids also compute the fluid's λ multiplier.

---

## Measured results

- **One tied projector matched five per-material PCAs.** Local-step accuracy, train and OOD:
  steel 0.99901 · rubber 0.99693 · foam 0.99901 · composite 0.99913 · gel 0.99244 — the
  water token added later caused **no interference** with the solids.
- **Fluid unification held in-loop.** Running the full dam break on the *neural* λ held the
  same density as the exact analytic solver: **0.0121 (neural) vs 0.0124 (analytic)**.
- **Learned warm start cut solver work** by ~**32%** fewer PD iterations at fixed tolerance,
  with **zero correctness risk** (it only moves the loop's starting iterate; the fixed point
  is unchanged — classical warm starts are exact special cases of its form).
- Earlier 2D findings that motivated the scale-up: one 8-float strain matrix **transferred to
  unseen load cases at 99%+**, co-rotation reduced strain to an exactly 3-D space, and
  constraint folding was algebraically exact (free 3.25×).

### Figures

**Neural tied projector vs per-material PCA** — one token-conditioned network matches five separate bases (train + OOD).
![neural projector](images/neural_projector_validation.png)

**Fluid token, in the loop** — dam break driven by the neural λ vs the analytic rule; density maintenance tracks.
![fluid token](images/fluid_token_validation.png)

**PBF-3D validation** — density error over a dam break.
![pbf](images/pbf_validation.png)

**Learned warm start** — PD iterations saved at fixed tolerance.
![warm start](images/warm_start_validation.png)

**3D tied-basis solid** — co-rotated strain in a reduced basis.
![tied basis 3d](images/tied_basis_3d_validation.png)

**Cantilever beam** — tip settle + energy signature (correctness/invariant check).
![beam](images/beam3d_validation.png)

---

## How it was trained

Small models, cheap runs. The 2D corpus and all solid experiments ran on CPU in seconds; the
3D neural projector trained on a single GPU.

1. **Tied strain bases (3D)** — replicate the 2D PCA results in 3D: co-rotated 6-D symmetric
   strain compressed to k≈3, shared across all tets (`experiments/w3_tied_basis.py`).
2. **Neural tied projector with material tokens** — one network over 5 materials, per-material
   input scaling, rejection + zero-anchor guards; trained to beat the per-material PCAs
   (`w45_neural_projector.py`, corpus `w45_corpus.npz`).
3. **Learned warm start** — trained to predict the converged correction as a residual on linear
   extrapolation, from per-vertex history invariants (`w6_warm_start.py`).
4. **Fluid token** — a 6th "water" token learns the PBF density-constraint rule
   `λ = −C/(Σ‖∇C‖² + ε)`; blanketed with synthetic samples across the plausible (C, g²) domain
   to survive in-loop distribution shift, then validated in-loop against the analytic solver
   (`w7_fluid_token.py`).

Losses prioritized trajectory matching (positions **and** velocities — velocity error caught an
over-damping bug), constraint residuals, long-horizon stability, and an energy-gain penalty.

---

## Demos

- **Live (server-side, this repo's [Space](https://quazim0t0-neural-physics-engine-demo.static.hf.space/)):** 
- **Standalone (browser, WebGPU):** `dam_break_gpu.html`, `tied_subspace_water.html` — open in
  Chrome/Edge 113+. These parse the `.pt` files in-browser and run the learned λ in a WebGPU
  compute shader (no server, no ONNX).

---

## Roadmap & what's next (unfinished)

The local-projector thesis has strong evidence; the global reduction is proven in-distribution
with a known literature fix (CROM-style continuous fields) for its OOD weakness; the
fully-learned-solver path is the speculative tail, sequenced last. Remaining steps from the
roadmap: CROM-style global decoder, a unified constraint zoo (strain + density + volume +
contact as tokens through one network), a full GPU/Warp training port, and nested-latent LOD.
See `neural_physics_engine_roadmap.md`.

## Usage

```python
import torch
from engine3d.neural import NeuralTiedProjector
from engine3d.fluid import PBF3D, dam_break_block
import numpy as np

ck = torch.load("unified_projector.pt", map_location="cpu", weights_only=False)
net = NeuralTiedProjector(n_materials=6, k=ck["k"], hidden=64)
net.load_state_dict(ck["state_dict"]); net.eval()
# see the Space's app.py for the water-token λ rule and the dam-break rollout.
```

## Citation

```bibtex
@misc{byrne2026neuralphysics,
  title  = {Neural Physics Engine: learned constraint projectors in an exact
            projective-dynamics solve},
  author = {Byrne, Dean},
  year   = {2026},
  note   = {Work in progress. https://huggingface.co/Quazim0t0}
}
```

*Adjacent work: CROM, differentiable/neural Projective Dynamics, subspace neural physics
(Holden et al.), GNS/MeshGraphNets, NCLaw. The under-explored middle ground here — weight-tied
per-element projectors in co-rotated frames, shared across constraint types via tokens, inside
an exact reduced global solve — is the lane.*