# Simulation > simulation — model from equations, then prove it reproduces a known case - Skill: `skryx-l-a/simulation` (Agent Skill) - Install (CLI): `npx skillmds@latest add skryx-l-a/simulation` - Raw SKILL.md: https://api.skillmd.com/api/skills/skryx-l-a/simulation/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: Skryx-L-A (https://skillmd.com/u/skryx-l-a) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/skryx-l-a/simulation --- # simulation — model from equations, then prove it reproduces a known case ## What this sub-skill is for Standing up a **scientific-computing / numerical simulation**: encode a model's governing equations, integrate/solve them, and **validate the result against a case whose answer is already known** (an analytic solution or an accepted benchmark). Loaded by `new-project` for physics, orbital mechanics, signal/numerical, agent-based, or Monte-Carlo work. This is **modeling, not machine learning** — there is no training set; correctness comes from the math and from reproducing known results, not from a holdout. The organizing idea: **an unvalidated simulation is a hypothesis, not a result.** ## Mandatory grill-questions (fold into the Definition of Ready) - **Domain & model:** what system, and what are the **governing equations / model**? (ODE/PDE, N-body, Maxwell, rigid-body, agent rules, stochastic process — name it.) What's fixed by physics vs. a modeling choice? - **Fidelity vs. speed:** real-time/interactive, or batch high-fidelity? Acceptable error? Stiffness — do you need an implicit solver? - **Language:** Python (numpy/scipy/numba), Julia, or C++? (Python to prototype; numba/Julia/ C++ if the inner loop must be fast.) - **Solver / integrator:** which scheme (RK4 / symplectic / implicit / Verlet / FFT-based), fixed vs. adaptive step, and **why that one** for this system's stability/conservation needs? - **Units system:** SI? non-dimensionalized? **Pick one and enforce it everywhere** — silent unit mismatches are the classic simulation bug. - **Validation cases:** which **analytic solution or published benchmark** will prove it right (e.g. two-body Kepler orbit, harmonic oscillator energy, a manufactured solution)? What tolerance counts as "matches"? - **Visualization:** what plots/animations make the result legible and the validation visible? ## Project sub-agents to generate (`.claude/agents/`) - **model-implementer** — encodes the governing equations and the integrator/solver in the chosen language; keeps the numerics readable and the units explicit (delegate-by-default for the core solver). - **numerical-validator** — **adversarial** (mirror of an honest-eval auditor): runs the analytic/benchmark cases, checks error vs. tolerance, **convergence under step/grid refinement**, conservation laws (energy/momentum/mass), and **unit consistency**; flags a sim that only *looks* right. **Delegate-by-default before any output is reported as real.** Never tunes the model to pass — only validates and reports. - **viz-builder** — produces the plots/animations, including the **validation overlay** (simulated vs. analytic) so correctness is visible, not just asserted. ## Tools / CLIs / MCP / skills needed - Python + `.venv`: numpy, scipy, matplotlib/plotly, `numba` for hot loops, `jupyter` for exploration. Domain libs where they fit: `astropy` + `poliastro` (orbital mechanics), `sympy` (deriving/checking analytic cases), `pint` (unit-checked quantities). Julia or a C++/pybind core if the grill demands speed. Install via `pip` at environment-readiness (surface and offer, never auto-install). - **Global skills/agents to chain:** `deep-research` (**lead with this** — get the governing equations, the right integrator, and a documented benchmark with citations *before* coding), `verify` (run the sim + validation end-to-end on a fresh checkout), `code-review` (numerical correctness, indexing, stability), `market-researcher` (agent) for facts on models/constants/published reference results. ## File / asset nudges (on top of the base set) - **`VALIDATION.md`** — the honest proof doc: the benchmark/analytic case(s), the tolerance chosen up front, the achieved error, the **convergence table** (error vs. step/grid size), conservation-law checks, the units system, and **stated assumptions / regimes where the model breaks**. Failures are recorded straight. - `MODEL.md` — the governing equations, derivation/source, parameters, and the units convention. - `src/` — production solver code (notebooks import from it; not the reverse). - `validation/` — runnable scripts that reproduce each benchmark and emit the error/figure. - `figures/` — generated plots/animations, including the simulated-vs-analytic overlay. - `notebooks/` — exploration only; clear outputs before commit. ## Stack defaults & done-bar **Default stack:** Python 3.x + `.venv`, numpy/scipy core with numba on hot loops, matplotlib for figures, a fixed RNG seed for any Monte-Carlo, units pinned via `pint` or a documented SI convention, validation scripts in `validation/`. Swap to Julia/C++ per the grill. **Done-bar (all must hold):** 1. The sim **reproduces a known analytic or benchmark case within the stated tolerance**. 2. **Convergence is demonstrated** — error shrinks at the expected order as the step/grid refines (table in `VALIDATION.md`). 3. **Units are consistent end-to-end** and **conservation laws hold** to tolerance where the physics requires them. 4. The whole pipeline (run → validate → figure) executes reproducibly on a fresh checkout. 5. `VALIDATION.md` records the case, tolerance, achieved error, convergence, and assumptions. ## Guardrails - **An unvalidated sim is never presented as correct.** No result leaves the project until it has reproduced a known case; "the plot looks plausible" is not validation. - **State tolerances, convergence, and conservation explicitly** — a number without an error bar and a convergence check is not trustworthy. Report the order of accuracy you actually achieved, not the one you hoped for. - **Enforce one units system everywhere** and check it; the most common silent bug is a unit mismatch that produces clean-looking, wrong numbers. - **Document every assumption and the valid regime** — where the model linearizes, what it ignores, where it diverges from reality. An honest "valid only for small angles" beats a hidden failure. - **The numerical-validator never tunes the model to hit a target** — it audits; fixing the math is the implementer's job, and a failing check is information, not an obstacle. - Mark unverified claims as unverified. NO emojis in any output, plots-text, or UI. Commits under the user's own name only (Skryx-L-A) — never add Claude as a co-author. Never commit secrets / API keys (e.g. for data or compute services).