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.md

GitHub

Numerical 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 --gif or snapshot mode produces the demo animation from the same scripted run.

Verification loop

  1. Unit tests against analytic values pass with stated tolerances.
  2. Conservation checks over long runs pass.
  3. Convergence test shows the expected order.
  4. Regenerate plots and compare with the previous version.

Pitfalls

  • CFL violations make explicit schemes explode; derive the maximum stable dt and 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.