numerical-simulation
Use when writing physics or numerical simulations — choosing an integrator (RK4, symplectic, semi-Lagrangian, split-step), validating against analytic solutions and conserved quantities, unit tests wi
SKILL.mdskills/tech/numerical-simulation/SKILL.md
GitHubNumerical simulation
Default: state as plain arrays/structs, one step(state, dt) function, an integrator chosen for the physics, tests that compare against analytic results with explicit tolerances, plots generated by a script from a scripted run.
Public examples (small C11 programs): lift-pilot (flight dynamics), current-swimmer (2D fluid), gravity-well (orbits), relativity-rider (special relativity), quantum-wave-hopper (Schrödinger equation), field-ripple (sine-Gordon field).
Choose the integrator for the physics
| Problem | Integrator | Why |
|---|---|---|
| Smooth ODEs (flight, rigid bodies) | RK4 | Accurate per step, simple |
| Orbits, Hamiltonian systems | Leapfrog / velocity Verlet | Symplectic: energy error stays bounded over long runs |
| Incompressible fluids | Stable Fluids (semi-Lagrangian advection + pressure projection) | Unconditionally stable, good for interaction |
| Time-dependent Schrödinger | Split-step Fourier or Crank–Nicolson | Preserves the norm (probability) |
| Wave/field equations | Leapfrog on a staggered grid | Stable under the CFL condition |
Validation is the product
Each simulation gets tests that a physicist would accept:
- Analytic solutions: e.g. phugoid period vs Lanchester's approximation; Hohmann transfer Δv vs the closed form; proper time of a constant-acceleration rocket vs the hyperbolic formulas; tunnelling probability vs the rectangular-barrier result; soliton contraction vs the Lorentz factor.
- Conserved quantities: energy, momentum, probability norm, divergence of velocity — check drift over long runs.
- Convergence: halve
dt(or the grid spacing) and check the error falls at the expected order. - Assert with tolerances that reflect the method (e.g. "within 0.3 %"), and print the measured error so regressions are visible.
Interactivity without lying
- Fixed simulation time step independent of frame rate; render interpolated states.
- Clamp user inputs to physical ranges; show units in the interface.
- Provide a scripted mode (no input) that produces the same run every time for tests, plots and demo animations.
Documentation outputs
make plots(or a script) runs the scripted scenario, writes CSV, and renders SVG charts; the README embeds those files, so the images always match the code.- A
--gifor snapshot mode produces the demo animation from the same scripted run.
Verification loop
- Unit tests against analytic values pass with stated tolerances.
- Conservation checks over long runs pass.
- Convergence test shows the expected order.
- Regenerate plots and compare with the previous version.
Pitfalls
- CFL violations make explicit schemes explode; derive the maximum stable
dtand assert it. - Units mixing (degrees vs radians, km vs m) — keep SI internally, convert at input/output.
- Single precision accumulates error quickly; use double.
- Boundary conditions often dominate errors; test them separately (reflecting, periodic, absorbing).
- "Looks right" is not validation; a plausible animation can be off by a factor of two.