Validation - progenax — differentiable initial conditions for N-body simulations

This section documents what progenax’s test suite proves about the physics. Where the API reference says “this function exists and has this signature,” validation says “this function reproduces ζ(1.67) = 1.789 from Kainulainen et al. (2014) to within 0.02.” Validation is where the package’s scientific credibility lives.

The validation suite is physics-anchored: every test asserts a quantitative match between progenax output and an analytical or published-observational ground truth, with explicit pass/fail tolerances.

See the validation audit report for trustworthiness tiers, limits, recommendations, and the remaining/incomplete roadmap (point-in-time, 2026-06-08).

Where this section proves each model reproduces its ground truth, the science demos run the models backwards — recovering cluster parameters from mock observations by differentiable MLE / NUTS. That inference rests on gradient integrity: the differentiability gradient audit measures every public entry point’s autodiff gradient against finite differences (gradient integrity = Fisher integrity), and reports the two hazards it found and fixed.

Live status¶

Map of the section¶

Page	Scope
Validation methodology	The three-tier test architecture (unit / integration / validation), tolerance conventions, the anchor-on-defining-condition lesson, how to add new validation tests
Testing architecture	The validation backbone: the four frozen-literal registries (API-coverage, physics, provenance, differentiability), the generated dashboard, and the four-part release gate
Differentiability gradient audit	The per-entry-point autodiff-vs-finite-difference gradient registry (gradient integrity = Fisher integrity); the two found-and-fixed silent-zero hazards
Plummer equilibrium	Virial Q recovery, density-profile sampling, velocity-dispersion radial profile, energy conservation
King profile validation	ODE integration vs King (1966) Table II concentrations, tidal-truncation behaviour, $W_0$ sweep
EFF profile validation	Density-profile sampling, asymptotic-slope verification
Michie-King anisotropy validation	Anisotropy β(r) vs the DF oracle, isotropic King limit, anisotropic dispersions
Rotation & anisotropy validation	Solid-body & differential rotation; Osipkov-Merritt β(r) for Plummer/EFF
IMF statistics validation	Salpeter / Kroupa / Chabrier / Maschberger sampling: KS-test goodness-of-fit and recovered $\alpha$ vs truth
Environment-dependent IMF validation	Environment-dependent IMF: Marks (2012) Fundamental Plane $\alpha_3$ and Jeřábková (2018) low-mass slopes vs published tables
ZAMS relations validation	Tout (1996) ZAMS $L(M)$ / $R(M)$ fits vs the published coefficients and stellar anchors
Binary-aware IMF validation	End-to-end forward-model + likelihood: reproduces “confidently wrong” regime at $N \gtrsim 10^4$
Substructure (CW04 Q) validation	CW04 Q substructure diagnostic: (s̄,m̄) plane, Table 1, differentiable q_approx
Mass segregation validation	$\Lambda_{\mathrm{MSR}}$ diagnostic (analytic), energy-ranked generator, and the differentiable segregation observables (soft $\Lambda_{\mathrm{MSR}}$ / radial / $\Sigma$ – $m$ )
Gravoturbulent + PP20 validation	PP20 ζ(p) regression suite + BM19 forward chain (now in the experimental `gravoturb` package; historical record of the 2026-04-28 transcription-bug fix)
Multi-mass LIMEPY equilibrium (Engine A)	Engine A: coupled multi-mass LIMEPY equilibrium — per-component σ(r) vs the DF moment, Q_j across δ, anisotropic β(r) vs the DF, DF-table budgets
Multi-component Eddington equilibria (Engine B)	Engine B: prescribed-density shared-potential Eddington equilibria — King A-vs-B cross-engine anchor, analytic Plummer DF oracles, OM anisotropy, realizability
Two-component populations (superseded)	Superseded API (deleted 2026-06); pointer to the MultiComponentCluster engines + the surviving two-population check
Cluster-builder validation	The `build_cluster` convenience layer — virial Q across all 5 aliases, density recovery, tidal cut, rotation $L_z$ , OM anisotropy; bit-identical-to-`build_spatial_ic` sugar
Performance & memory	DF-table acceleration and memory budgets: speed-CDF-table routing vs the exact quadrature oracle, construction/sampling speedups
Tidal truncation validation	Jacobi-radius computation and truncation behaviour
Analytical test cases validation	Two-body Kepler, three-body figure-eight, harmonic oscillator — exact-solution sanity tests
Cross-cutting physics tests	Cross-cutting physics validations not specific to one module
Validation plot gallery	Rendered figures from `validation/plots/`

What “validated” means¶

A progenax module is “validated” when it has at least one test in each of three tiers — unit (per-function mechanical correctness), integration (end-to-end builder/pipeline behaviour), and validation (quantitative match to analytic or published physics). A module without all three tiers is treated as experimental — it can be used, but its results are not signed off for production research.

The tier definitions, the pass/fail tolerance conventions (closed-form 10^-12, finite- $N$ statistical $5\times10^{-3}$ , approximation $5\times10^{-2}$ , observational anchor 10^-2), and the single most important methodology lesson — anchor on the defining condition, not the derived constant (test $M(<r_h)=M/2$ , not $a = 0.7664\,r_h$ ) — all live in one place: Validation methodology. The backbone that enforces coverage (the three-tier suite, the four registries, the generated dashboard, and the release gate) is documented at Testing architecture.

References¶

The three-tier methodology, tolerance conventions, and anchor lesson are documented in detail at Validation methodology. The PP20 ζ(p) regression suite is the largest single validation contribution and is documented at Gravoturbulent + PP20 validation.

References¶

Kainulainen, J., Federrath, C., & Henning, T. (2014). Unfolding the laws of star formation: The density distribution of molecular clouds. Science, 344, 183–185. 10.1126/science.1248724