A small headless harness for checking a MuJoCo twin against closed-form physics (friction + restitution)

[markov-studio-llc]

If you're using MuJoCo as a digital twin, here's a 30-minute check worth running before you trust it: drop a ball, slide a block, and see if the numbers match the ones you can derive with a pencil.

I built a small headless harness that does exactly that: https://github.com/markov-studio-llc/markov-twin-fidelity-harness

1. Friction: a sphere slides down a 30° incline, μ=0.15. Closed form: a = g(sinθ − μcosθ). Measured vs analytical: 0.005% off. A match.

2. Restitution: a ball dropped from 1 m, 15 bounces tracked, heights fit to h_n = e^(2n)·h_0. The decay law fits almost perfectly (R² = 0.99995) — but the coefficient I asked for and the one I measured are 9.3% apart (target e=0.75, measured e_eff=0.820). Coefficient of restitution #2081 asked how to translate a coefficient of restitution into solref — this is what happened when I derived solref from the standard damped-oscillator relation and let MuJoCo's native contact model run, instead of applying the contact force manually: the decay stays perfectly exponential, just with a different constant than the one I aimed for.

That second result isn't a bug I didn't fix. MuJoCo has no first-class restitution dial — contacts are a spring-damper model, so you can aim at a target e but what comes out is a measurement, not a guarantee. The gap is config-specific (this mass, this stiffness, this target e) — not a general "MuJoCo is off by 9.3%" claim. If your twin depends on bounce elasticity, it's the kind of gap you want quantified before it costs you.

Closed forms are re-derived in-repo (not quoted from memory), full numbers in results/, plus a writeup of two failed model attempts kept for the lesson — a box stuck to the incline by four redundant coplanar contacts over-supplying friction was the fun one.

Runs on a laptop CPU, no GPU, under a minute end to end.