Course contents · Methods · Quickstart
| Layer | Files | Responsibility |
|---|---|---|
| Initial conditions | systems.py | Construct two-body, hierarchy, and cluster states; orient systems |
| State/model contract | core.py | Validate state/model inputs and define cost/model interfaces |
| Force helpers | forces.py | Direct acceleration and jerk kernels |
| Integrator formulas | integrators/ | Explicit, geometric, predictor/corrector, extrapolation, and splitting steps |
| Time driver | simulate.py | Advance states and handle adaptive trials and samples |
| Kepler machinery | universal_kepler.py, kepler.py | Kepler propagation and analytic reference support |
| Restricted model | restricted.py, restricted_integrators.py | Moving primaries, indirect acceleration, tracer diagnostics, and restricted splitting |
| Diagnostics | diagnostics.py | Energy, angular momentum, and other state diagnostics |
| External references | references.py | REBOUND adapter, agreement window, and pointwise comparison |
| Experiment design | experiments/ | Initial state, methods/settings, observations, saving, and plotting |
| Batch execution | Part 1, Part 2, Part 3, Part 4 | Command interfaces and lesson ordering |
Read run_experiment() first in a lesson. Follow only the helper needed for the current concept. Part 1 shares utilities in common.py; Part 2/3 deliberately include their own helpers so their scripts can run independently.
Start at the course README, choose a lesson, then open code or data only as needed. Each numbered lesson contains its own comparison rules, interpretation of saved fields, measured figures, evidence links, and direct links to the functions it uses.
docs/ holds methods, glossary, sources, this design map, the Part 4 overview, and reproducibility guidance. Its evidence/ subfolder provides readable numerical records. Method selection lives in Lesson 3F and the course conclusions live in lessons/conclusion.md. Introductory evidence pages do not add unsupported inputs to the final aggregator.
The results guide explains the saved outputs, and the experiment guide maps each script to its lesson. results/ holds measured outputs alongside that reading guide. Part 1/2 lesson runs and Part 3 batch runs keep their existing names because experiment discovery depends on them. Running examples/efficiency.py writes two illustration files, efficiency.png and efficiency_costs.csv, to the results root; they are not part of the bundled evidence.
.gitignore tells Git which untracked local files to leave out, such as Python caches and virtual environments. It does not delete files and is itself a tracked text file. The existing ignore rules are retained.
pyproject.toml declares installation metadata and dependency extras. It remains required. The experiments' source_manifest.json files record the source or measurements used by a saved run. These describe provenance; they do not freeze current code.
- The nine course solvers are educational implementations; IAS15/external BS are dependency calls.
- Hermite4 has a shared fixed step; RK45/BS have a shared adaptive step. No individual/block stepping is implemented.
- GL4 uses dense numerical Jacobians and linear solves; 3B limits it by budget at larger N.
- Current planetary WH is not a hybrid encounter or softened-cluster solver.
- Cluster initialization is Plummer-shaped positions plus scaled Gaussian velocities, not an equilibrium Plummer distribution function.
- The final aggregator consumes a recognized subset of lesson schemas. Twenty lessons do not imply twenty sources in 3F: thirteen contain supported summary inputs.
- The largest planetary experiment uses N=100; the short cluster experiment uses N up to 20 and the ensemble uses N=10.
These limits make the course interpretable and reproducible. They also identify precise questions for future extensions.
Processed WH2 uses a dedicated fixed-grid loop. It retains a live mapping state and evaluates physical output on copies. Common helpers, dynamics and secular diagnostics separate serialization, physical measurements and reference checks.
External methods are installed REBOUND implementations. Configuration adapters support the available REBOUND 4/5 interfaces, and output synchronization selects the public method exposed by the installed release. Numerical settings, output times and unavailable counters remain explicit.
4D reads a completed 3F data snapshot and verifies the measurement inputs declared by that snapshot. It adds margins without changing the old map's feasibility policy. New Part 4 families have a separate table. This data-input check does not prevent editing source code.
The root runner executes all five lessons and the required 4E output-sampling validator. Optional project checks inspect current links and syntax; --results also recomputes saved numerical quantities. No historical source baseline or edit-authorization file is required. See Verification.
A full Part 4 invocation keeps A–E under one new batch. The supplied course evidence is collected in one batch, with its original measurement identities retained. The runner streams child output while writing each lesson log.
4E writes a stage record and saves reference figures before candidates start. Finished candidates are checkpointed in the numerical tables. Its separate sampling validator updates reference floors and final figures. The saved-data plotting entry point can rebuild available views without running a solver or declaring missing validation complete.
The final postprocessor routes derived files into the relevant lesson folders. Shared analysis settings, input hashes and source provenance remain at batch level. The existing stage order and method scans are unchanged. The 4E plotter reads sampled reference arrays for its peak-resolution panel, using the refined grid once available and labelling the coarser grid before validation.