Particle Sandbox Physics

---

name: particle-sandbox-physics description: >- Graduate-grade physics and materials engine for building a particle sandbox simulator: governing equations, canonical numeric parameters (Lennard-Jones eps/sigma, Van der Waals a/b, CODATA 2022 constants), integrator selection, and an executable conservation-law validation harness, plus bundled/fetchable open datasets (periodic table, PDG particles, AME nuclides, COD crystals) with a licensing manifest. Use this skill whenever the user is building, debugging, or reasoning about a particle simulation, physics engine, molecular dynamics, N-body/orbital mechanics, SPH fluids, thermodynamics, electromagnetism, or a subatomic/particle-physics mode; needs physical constants, interatomic potentials, or material properties; asks which numerical integrator to use; or hits energy drift, timestep blow-up, or unit-consistency bugs — even if not explicitly requested. argument-hint: "[classical | md | fluid | em | subatomic | validate | ]"

Particle Sandbox Physics

A graduate-level physics/materials reference for building a real-time particle sandbox. It encodes the governing equations plus the canonical numeric parameters you actually need, a clear integrator-selection rule, an executable validation harness, and open datasets with explicit licensing. The hard-won lessons — symplectic integrators, cutoff shifting, unit consistency — are here because they are the things that silently break a sim that otherwise looks correct.

This skill assumes a NON-COMMERCIAL sandbox. It bundles/fetches PDG data (CC-BY-NC). If the project is or becomes commercial, read LICENSES.md first — some data must be swapped out.

How to use this skill

1. Identify the mode from the request (decision tree below).
2. Open the specific reference file(s) named — don't work from memory for numbers.
3. For any numeric parameter or constant, load it from data/ or a reference table, never retype it (mis-typed constants are a classic silent bug).
4. For anything conservative or long-running, validate with the scripts before trusting it.

Decision tree

• Classical dynamics / collisions / orbits → references/domains.md §1, then pick an integrator from references/integrators.md. Default velocity Verlet. Validate with scripts/validate_integrator.py and scripts/check_conservation.py.
• Molecular dynamics → references/potentials.md (Lennard-Jones + params, cutoff shifting, reduced units) and references/domains.md §2 (thermostats, ensembles, neighbor lists). Integrate with velocity Verlet. Force model in scripts/lj_force.py.
• Thermodynamics / phase transitions → references/domains.md §3 + the Van der Waals gas a,b table in references/potentials.md.
• Fluids (SPH / Navier–Stokes) → references/domains.md §4. Use a Verlet stepper.
• Electromagnetism → references/domains.md §5 + constants in references/constants.md.
• Subatomic / particle physics → references/domains.md §6; fetch the PDG SQLite via scripts/fetch_data.py --download pdg (CC-BY-NC). Work in natural units.
• Constants / units → references/constants.md, references/units.md, data/constants.json.
• Validation / "why is my sim drifting/exploding?" → references/test_cases.md and the scripts below.

The three rules that prevent most silent bugs

1. Symplectic integrator for conservative dynamics. Default velocity Verlet; semi-implicit Euler for the cheapest option. Never forward Euler for orbits/MD; RK4 only for short non-conservative runs, with a drift warning. See references/integrators.md.
2. Unit consistency. Pick one internal unit system; convert only at the boundaries. Never mix amu/kg, Å/m, fs/s. See references/units.md and scripts/unit_convert.py.
3. Shift the LJ potential at the cutoff (default r_c = 2.5 sigma) and initialize on a lattice, not overlapping. See references/potentials.md.

Reference files (progressive disclosure — read on demand)

File	Contents
references/integrators.md	Integrator comparison table, decision rule, velocity Verlet & symplectic Euler forms, timestep stability
references/potentials.md	Lennard-Jones (rare-gas eps/sigma), Coulomb, gravity, Morse, Van der Waals gas a/b table
references/constants.md	CODATA 2022 constants quick table (source of truth: data/constants.json)
references/units.md	Unit rules, conversion table, LJ reduced units, natural units
references/domains.md	Governing equations: mechanics, MD, thermo, fluids/SPH, EM, particle physics
references/test_cases.md	Six canonical validation cases with reference values + common pitfalls

Scripts (deterministic — run them, don't emulate them)

Pure standard library except gen_constants.py (optional scipy). Run from the skill root.

Script	Purpose
scripts/validate_integrator.py	Kepler-orbit drift test across integrators (--self-test)
scripts/check_conservation.py	Momentum/energy checks for elastic & inelastic collisions (--self-test)
scripts/lj_force.py	LJ potential/force with cutoff shifting; verifies the well depth
scripts/unit_convert.py	SI conversions + LJ reduced↔SI helpers (argon anchors)
scripts/gen_constants.py	Regenerate data/constants.json (prefers scipy.constants)
scripts/fetch_data.py	Dry-run/download PDG, AME/NUBASE, COD datasets with license notes

Bundled data

• data/periodic_table.json — 119 elements (Bowserinator, CC-BY-SA 3.0): atomic mass, density, melt/boil (K), electron config, electronegativity, ionization energies, phase.
• data/constants.json — CODATA 2022 fundamental constants (values are facts).

Large/license-gated datasets (PDG particles, AME/NUBASE nuclides, COD crystals) are fetched on demand via scripts/fetch_data.py. Read LICENSES.md before redistributing — the periodic table carries a share-alike obligation, PDG is non-commercial, and no NIST Standard Reference Data (WebBook, ASD, JANAF, REFPROP) may ever be bundled.