Why a Lagrangian kernel exists, and what it compares against.

The engine, in seven figures

Lifted from the paper (Lagra: A differentiable physics kernel for verifiable domain operations) — the same diagrams, with shorter captions for the web.

→ full paper: action-kernel/main.pdf · LaTeX source in paper/action-kernel/main.tex

Why we have fifty physics engines

The engine on the landing page would be three separate codebases anywhere else. Rigid bodies live in PhysX or Bullet. Molecular dynamics lives in LAMMPS or GROMACS. RNA folding lives in ViennaRNA or Rosetta. Fluids live in OpenFOAM or LiquidFun. None of them compose.

The split isn't accidental — it's the structure each tool optimised against. PhysX's contact solver assumes a contact graph, not pairwise potentials over 10⁵ particles. LAMMPS's neighbour list assumes short-cutoff non-bonded forces, not deformable continua. ViennaRNA's dynamic-programming kernel doesn't accept a force field at all. Each engine made a different cut for a different audience, and the cuts don't line up.

So adding fluids to MuJoCo means reimplementing fluids. Adding EM coupling to an RNA scene means rewriting ViennaRNA. Adding deformables to a PhysX game means swapping engines mid-pipeline. The cross-domain tax — porting, validating, re-tuning — usually exceeds the cost of the physics itself.

A Lagrangian doesn't care which subset you pick. HarmonicBond and LennardJones and QcdCoulomb are the same kind of node in the same kind of graph, evaluated by the same kernel. Choosing which terms run for a given scene becomes a scene-level declaration — not a tooling decision. The live 1000-block stack on the landing page runs on the same evaluator the LJ fluid and the pendulum chain run on. That's the whole pitch.

See the live 1000-block stack at index.html#demos — same evaluator, same scene file. uses newtonian.classical_mechanics.avbd; render "rigid_body".

Subsystems as units of compute

.lagra files describe nodes in the graph. Like Lean for proofs, each file is a self-contained unit the compiler can check, optimise, and compose. Coarse-graining is a node choice, not an engine choice.

The scene below is the harmonic-oscillator demo from the landing page — verbatim, no shortened-for-the-website magic. Two particles, one bond, one declared invariant, one solver block:

scene solver_walkthrough_oscillator {
    uses newtonian.classical_mechanics
    description "Two-bead harmonic oscillator. Only the harmonic bond contributes nonzero force."
    wasm true                                // flag for the landing-page bundle

    entity { type: ball_small, position: [-1.35, 0, 0], mass: 1.0, size: 0.35 }
    entity { type: ball_small, position: [ 1.35, 0, 0], mass: 1.0, size: 0.35 }

    bond harmonic [0, 1] { k: 2.0, r0: 2.0, damping: 0.04 }
    @expect momentum_conservation                  // CI gate
    solver { dt: 0.002, steps_per_frame: 12 }
}

The compiler checks before the kernel runs. Conservation invariants are derived from the active graph and inserted as runtime assertions — if the first step would violate them, the scene doesn't compile. Entity catalogs enforce scientific references: entity ball_small {…} in configs/entities/classical.lagra carries the citation alongside the mass, size, and color, and custom entities go through LagraDef validation against those catalogs.

Each node also owns its own optimisation hints. Pairwise terms can request a cell list; bonded terms can request a neighbour list; whole subgraphs can target a GPU compute pass. The planner reads the hints and composes the dispatch — the kernel's shape is fixed but the dispatch is per-scene.

Qualitative recovery — Lagra reproduces LAMMPS liquid structure

Five independent trajectories per engine on a 256-particle Lennard-Jones liquid at ρ*=0.80, T*=1.5, run from identical Maxwell-Boltzmann initial conditions with the same dt = 0.005τ_LJ. Both engines run symplectic integrators (Lagra: discrete-action variational; LAMMPS: velocity-Verlet). The radial distribution function — the canonical liquid-structure observable — matches across the full r range.

g(r) first-peak height

Lagra 2.793 ± 0.009 · LAMMPS 2.785 ± 0.015 · +0.27%

g(r) RMSD (r > 0.8σ)

0.00670 · max |diff| 0.0245

energy drift

Lagra 1.09e-03 · LAMMPS 9.83e-04 · ratio 1.10×

<E>/N

Lagra -4.1048 · LAMMPS -4.1081 ± 0.000140

throughput (honest)

Lagra 6,808 steps/s · LAMMPS is faster — speed parity is not the claim.

Pipeline: benchmarks/qualitative_recovery/scripts/{generate_initial_conditions, run_lagra, analyze_rdf, compare_lj}.py. Raw outputs and aggregated JSON in the same directory.

Per-scene benchmarks · molecular dynamics (LAMMPS)

22 scenes from the LAMMPS regression suite. Each row plays the actual engine output side by side — Lagra on the left, LAMMPS on the right, both at the same scene parameters. Note: the per-scene drift numbers below use the legacy bench scenes (ε=0.001 reduced-LJ units) rather than the aligned ε=1.0 set above; they're reported as raw drift, not as a parity claim. The aligned LJ result is the headline.

Per-scene benchmarks · RNA folding (ViennaRNA)

24 scenes from the ViennaRNA benchmark set. Vienna predicts a secondary structure via dynamic programming on the Turner-2004 free-energy table; Lagra simulates the same nucleotide system as MD with first-principles charged-base potentials. Outputs are not directly comparable (structure-prediction vs trajectory); each card shows what each engine produces. Vienna's own predictions are parameter-sensitive — the dangles sweep shows how much.

hp_gcgcaaagcgc

RNA · ViennaRNA reference

length

11 nt

ground truth

((((...))))

Vienna (d=2)

((((...)))) · MFE -3.8 kcal/mol

dangles sweep

1 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 0.0 kcal/mol

Lagra MD

159,662 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

hp_gggaaaccc

RNA · ViennaRNA reference

length

9 nt

ground truth

(((...)))

Vienna (d=2)

(((...))) · MFE -1.2 kcal/mol

dangles sweep

1 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 0.0 kcal/mol

Lagra MD

248,230 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

hp_ggggaaaacccc

RNA · ViennaRNA reference

length

12 nt

ground truth

((((....))))

Vienna (d=2)

((((....)))) · MFE -5.4 kcal/mol

dangles sweep

1 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 0.0 kcal/mol

Lagra MD

145,531 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

hp_ccccuuuugggg

RNA · ViennaRNA reference

length

12 nt

ground truth

((((....))))

Vienna (d=2)

((((....)))) · MFE -6.4 kcal/mol

dangles sweep

1 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 0.0 kcal/mol

Lagra MD

145,563 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

hp_au_only

RNA · ViennaRNA reference

length

10 nt

ground truth

..........

Vienna (d=2)

.......... · MFE 0.0 kcal/mol

dangles sweep

1 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 0.0 kcal/mol

Lagra MD

200,958 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

duplex_gcgc

RNA · ViennaRNA reference

length

4 nt

ground truth

(())

Vienna (d=2)

.... · MFE 0.0 kcal/mol

dangles sweep

1 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 0.0 kcal/mol

Lagra MD

664,676 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

duplex_ggcc

RNA · ViennaRNA reference

length

4 nt

ground truth

(())

Vienna (d=2)

.... · MFE 0.0 kcal/mol

dangles sweep

1 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 0.0 kcal/mol

Lagra MD

820,266 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

polyA_20

RNA · ViennaRNA reference

length

20 nt

ground truth

....................

Vienna (d=2)

.................... · MFE 0.0 kcal/mol

dangles sweep

1 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 0.0 kcal/mol

Lagra MD

48,776 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

iloop_gc_2x2

RNA · ViennaRNA reference

length

10 nt

ground truth

((..(..)))

Vienna (d=2)

(((....))) · MFE -2.6 kcal/mol

dangles sweep

1 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 0.0 kcal/mol

Lagra MD

192,333 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

bulge_gc_1nt

RNA · ViennaRNA reference

length

11 nt

ground truth

(((....))).

Vienna (d=2)

((((...)))) · MFE -4.6 kcal/mol

dangles sweep

1 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 0.0 kcal/mol

Lagra MD

146,670 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

two_hairpins_30nt

RNA · ViennaRNA reference

length

30 nt

ground truth

—

Vienna (d=2)

(((...))).((((((((....)))))))) · MFE -12.3 kcal/mol

dangles sweep

2 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 1.4 kcal/mol

Lagra MD

22,460 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

multiloop_3way

RNA · ViennaRNA reference

length

41 nt

ground truth

—

Vienna (d=2)

(((.((((((.(((((((....)))))))...))))))))) · MFE -23.9 kcal/mol

dangles sweep

1 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 0.0 kcal/mol

Lagra MD

11,877 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

trna_anticodon_17nt

RNA · ViennaRNA reference

length

17 nt

ground truth

(((((.......)))))

Vienna (d=2)

.....((((....)))) · MFE -4.7 kcal/mol

dangles sweep

1 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 0.3 kcal/mol

Lagra MD

62,827 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

rnaseP_domain

RNA · ViennaRNA reference

length

30 nt

ground truth

—

Vienna (d=2)

(((((((((......))))..))))).... · MFE -8.8 kcal/mol

dangles sweep

1 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 1.7 kcal/mol

Lagra MD

20,146 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

gc_rich_50nt

RNA · ViennaRNA reference

length

50 nt

ground truth

—

Vienna (d=2)

.(((((((((...((((((((((.....))))))))))...))))))))) · MFE -43.8 kcal/mol

dangles sweep

1 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 0.2 kcal/mol

Lagra MD

7,143 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

au_rich_50nt

RNA · ViennaRNA reference

length

51 nt

ground truth

—

Vienna (d=2)

........(((..((((((....))))))..)))................. · MFE -1.7 kcal/mol

dangles sweep

1 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 0.8 kcal/mol

Lagra MD

6,922 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

5s_rRNA

RNA · ViennaRNA reference

length

120 nt

ground truth

—

Vienna (d=2)

((((((((((((((...)))).(((...))).((((((((((...((.((...(((..((...))..)))...)))).))))))))))..(((.(((....))))))..)))))))))). · MFE -50.9 kcal/mol

dangles sweep

4 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 6.4 kcal/mol

Lagra MD

1,206 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

tRNA_phe

RNA · ViennaRNA reference

length

76 nt

ground truth

—

Vienna (d=2)

(((((((..((((........)))).(((((.......))))).....(((((.......)))))))))))).... · MFE -22.4 kcal/mol

dangles sweep

2 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 3.3 kcal/mol

Lagra MD

2,538 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

SRP_100nt

RNA · ViennaRNA reference

length

105 nt

ground truth

—

Vienna (d=2)

((((.((((....))))..))))((.(((((.(((((((.....((((..((((..((((........))))..)))).)))).....))))))).))))).)). · MFE -34.4 kcal/mol

dangles sweep

2 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 2.0 kcal/mol

Lagra MD

1,680 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

RNaseP_150nt

RNA · ViennaRNA reference

length

145 nt

ground truth

—

Vienna (d=2)

(((((((((......))))..))))).(((((..(((((...)))))..)))))..((((...((((((....)))))).......))))...((((.((.((((((((((....)))))).)))).)).))))........... · MFE -51.3 kcal/mol

dangles sweep

2 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 4.7 kcal/mol

Lagra MD

736 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

pseudoknot_simple

RNA · ViennaRNA reference

length

18 nt

ground truth

[[[(((...]]]...)))

Vienna (d=2)

(((....)))........ · MFE -3.3 kcal/mol

dangles sweep

2 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 0.5 kcal/mol

Lagra MD

58,856 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

pseudoknot_tmRNA

RNA · ViennaRNA reference

length

30 nt

ground truth

—

Vienna (d=2)

((((((....(((....)))..))).))). · MFE -7.2 kcal/mol

dangles sweep

1 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 0.1 kcal/mol

Lagra MD

21,312 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

16S_fragment_200nt

RNA · ViennaRNA reference

length

203 nt

ground truth

—

Vienna (d=2)

.......((.((((((((........)))))))).))...(((((.((((..((((((.(.(((..((.((.((((((((((....))))))).))).....)).))..))).)..)).)))).))))...)))))(((((...(.((.((.((((((....)))))).))...)).)....))))).....((......)). · MFE -50.9 kcal/mol

dangles sweep

4 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 4.7 kcal/mol

Lagra MD

465 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

group_I_intron_250nt

RNA · ViennaRNA reference

length

252 nt

ground truth

—

Vienna (d=2)

..(((((((...(((((((....((((.((((((((.(((((((((....))))))))).(((((....))))).)))).....))))))))...)))))))..)).)))))....((((...(((((((((...)))))))))..))))(((..((((.(((((..((((.....(((((((.....)))))))....)))))))))......(((((....)))))............)))))))..... · MFE -80.1 kcal/mol

dangles sweep

3 distinct structure(s) across dangles {0,1,2,3}; ΔMFE max = 8.9 kcal/mol

Lagra MD

322 steps/s (first-principles dynamics; structure prediction via long-time MD is future work)

Run scene (loading bundle…)

Per-scene benchmarks · protein dynamics (Rosetta)

20 scenes from the Rosetta benchmark set. Rosetta scores a single input pose with the REF2015 statistical energy function; Lagra runs MD on the same structure with physical force terms. Per-residue score reconstruction from Lagra's force-graph (the comparable apples-to-apples metric) is future work.

alanine_dipeptide

Protein · Rosetta reference

PDB / residues

— · 2 residues

Rosetta REF2015

not scored

Lagra MD

159,179 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

chignolin_1UAO

Protein · Rosetta reference

PDB / residues

1UAO · 10 residues

Rosetta REF2015

7,286,685.3 REU

Lagra MD

79,296 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

trp_cage_1L2Y

Protein · Rosetta reference

PDB / residues

1L2Y · 20 residues

Rosetta REF2015

70,355,253.2 REU

Lagra MD

38,881 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

villin_headpiece

Protein · Rosetta reference

PDB / residues

1VII · 36 residues

Rosetta REF2015

518.7 REU

Lagra MD

20,309 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

bba5

Protein · Rosetta reference

PDB / residues

1T8J · 23 residues

Rosetta REF2015

716.1 REU

Lagra MD

170,382 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

protein_g_b1

Protein · Rosetta reference

PDB / residues

1PGB · 56 residues

Rosetta REF2015

11.0 REU

Lagra MD

56,876 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

ubiquitin

Protein · Rosetta reference

PDB / residues

1UBQ · 76 residues

Rosetta REF2015

32.7 REU

Lagra MD

41,586 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

lysozyme

Protein · Rosetta reference

PDB / residues

1AKI · 129 residues

Rosetta REF2015

13.4 REU

Lagra MD

22,325 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

barnase

Protein · Rosetta reference

PDB / residues

1A2P · 110 residues

Rosetta REF2015

-367.5 REU

Lagra MD

7,476 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

SH3_domain

Protein · Rosetta reference

PDB / residues

1SHG · 57 residues

Rosetta REF2015

136.6 REU

Lagra MD

13,528 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

WW_domain

Protein · Rosetta reference

PDB / residues

1PIN · 34 residues

Rosetta REF2015

969.3 REU

Lagra MD

24,818 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

homeodomain

Protein · Rosetta reference

PDB / residues

1ENH · 54 residues

Rosetta REF2015

18.7 REU

Lagra MD

15,036 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

casp12_T0886

Protein · Rosetta reference

PDB / residues

— · ? residues

Rosetta REF2015

not scored

Lagra MD

355,907 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

casp13_T0950

Protein · Rosetta reference

PDB / residues

— · ? residues

Rosetta REF2015

not scored

Lagra MD

1,249 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

casp14_T1049

Protein · Rosetta reference

PDB / residues

— · ? residues

Rosetta REF2015

not scored

Lagra MD

22,289 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

casp14_orf3a

Protein · Rosetta reference

PDB / residues

— · ? residues

Rosetta REF2015

not scored

Lagra MD

6,303 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

insulin_dimer

Protein · Rosetta reference

PDB / residues

4INS · 81 residues

Rosetta REF2015

79.9 REU

Lagra MD

10,648 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

GFP

Protein · Rosetta reference

PDB / residues

1EMA · 238 residues

Rosetta REF2015

174.8 REU

Lagra MD

3,577 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

myoglobin

Protein · Rosetta reference

PDB / residues

1MBN · 153 residues

Rosetta REF2015

not scored

Lagra MD

4,714 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)

DHFR

Protein · Rosetta reference

PDB / residues

1RX2 · 159 residues

Rosetta REF2015

not scored

Lagra MD

5,642 steps/s (score reconstruction via Lagra force terms is future work)

Run scene (loading bundle…)