Cluster builders & stellar relations - progenax — differentiable initial conditions for N-body simulations

Cluster builders & stellar relations — model cards¶

Machine-generated from the provenance registry (ADR-0034): every model’s sources (with public DOI/arXiv/ADS pointers), governing equations, parameter meanings, code entry points, and the validation tests that pin them. The hand-authored theory pages hold the derivations; these cards are the citable single source of truth.

Cluster builders (build_cluster + named wrappers)¶

✅ verified · 1 equation · 1 source · API: build_cluster

The one-call IC convenience layer: build_cluster and the six named wrappers (Plummer/King/EFF/Michie/LIMEPY + from_params) are pure sugar over build_spatial_ic — bit-identical outputs — pairing each profile with its matched equilibrium DF (matched_velocity_df kills the mismatched-r_h footgun). A semantics card: the physics lives in the composed model cards.

Use it for	Not for
✓ the recommended one-call entry point for standard cluster ICs	✗ custom profile/DF cross-pairings (compose build_spatial_ic directly)
✓ Q=None (default) = faithful UNSCALED equilibrium from the matched DF	✗ tidal_radius on non-Plummer profiles (they carry a native r_t; the kwarg is Plummer-only by design)

Parameters¶

Name	Meaning	Units	Typical range	Code
`profile`	which model family to build (see that family’s card for its physics)	—	—	`build_cluster(profile=...) / build_king_cluster(...) etc.`
`Q`	optional virial rescale target; None = no rescale (the DF’s own equilibrium)	dimensionless	None (or 0.5 to force-rescale, e.g. after rotation overlays)	`build_cluster(Q=...)`

Equations¶

Q \;\equiv\; \frac{T}{|V|}, \qquad Q = \tfrac12 \iff 2T + V = 0

(1)

Symbols: $Q$ : virial ratio (0.5 = equilibrium; < 0.5 subvirial/cold; > 0.5 supervirial) [dimensionless]. Assumes: matched profile+DF pairs land at Q = 0.5 WITHOUT rescale (finite-N fluctuation only).

Sources¶

Aarseth et al. (1974) — the Q = T/|V| convention the builders report (Eq. 1 context)

Code & validation¶

code: build_cluster (src/progenax/builders_cluster.py)
code: build_plummer_cluster (src/progenax/builders_cluster.py)
code: build_king_cluster (src/progenax/builders_cluster.py)
code: build_eff_cluster (src/progenax/builders_cluster.py)
code: build_michie_cluster (src/progenax/builders_cluster.py)
code: build_limepy_cluster (src/progenax/builders_cluster.py)
code: build_cluster_from_params (src/progenax/builders_cluster.py)
code: matched_velocity_df (src/progenax/builders_cluster.py)
validation: tests/unit/builders/test_cluster_builders.py::test_build_cluster_is_bit_identical_to_manual_base_case
validation: tests/unit/builders/test_cluster_builders.py::test_plummer_alias_identical
validation: tests/unit/builders/test_cluster_builders.py::test_limepy_alias_identical
validation: tests/unit/builders/test_cluster_builders.py::test_cluster_params_wrapper_identical_to_build_cluster

Tout+1996 ZAMS stellar relations¶

✅ verified · 1 equation · 1 source

Zero-age-main-sequence L(M, Z) and R(M, Z) from the Tout et al. (1996) rational-polynomial fits (75/75 coefficients ledger-verified cell-by-cell against the PDF), with derived T_eff and log g. Internalized into progenax.stellar as the startrax placeholder.

Use it for	Not for
✓ ZAMS photometric/structural labels for sampled masses (0.1-100 Msun, Z in [1e-4, 0.03])	✗ evolved stars (ZAMS only; evolution is startrax’s future scope)
✓ differentiable M <-> L inversion (inverse_zams_luminosity, grad-audited)

Parameters¶

Name	Meaning	Units	Typical range	Code
`M`	stellar mass	Msun	0.1–100 (fit range)	`zams_luminosity(M) / zams_radius(M) / ...`
`Z`	metallicity (solar 0.02)	dimensionless	1e-4–0.03	`zams_luminosity(M, Z=...)`

Equations¶

L(1\,M_\odot) = 0.6977\,L_\odot,\quad R(1\,M_\odot) = 0.8882\,R_\odot,\quad T_{\rm eff} \approx 5600\,{\rm K},\quad \log g \approx 4.54

(2)

Symbols: $L$ : ZAMS luminosity (the ZAMS Sun is FAINTER than today’s Sun — do not ‘fix’ to 1.0) [Lsun]. Assumes: Z = 0.02; anchors computed from the verified coefficients and pinned by test_zams_physics.

Sources¶

Tout et al. (1996) — the L(M,Z) and R(M,Z) rational-polynomial fits; 75/75 coefficients verified exactly (Tables 1-2) (Eq. 3 + Table 1 (luminosity, 35 coefficients); Eq. 4 + Table 2 (radius, 40 coefficients; nu fixed at the Z = 0.02 optimum, p. 258))

Code & validation¶

code: zams_luminosity (src/progenax/stellar.py)
code: zams_radius (src/progenax/stellar.py)
code: zams_effective_temperature (src/progenax/stellar.py)
code: inverse_zams_luminosity (src/progenax/stellar.py)
validation: tests/validation/test_zams_physics.py::TestSolarAnchors::test_luminosity_solar_anchor
validation: tests/validation/test_zams_physics.py::TestSolarAnchors::test_radius_solar_anchor
validation: tests/validation/test_zams_physics.py::TestStefanBoltzmannClosure::test_teff_matches_stefan_boltzmann

References¶

Aarseth, S. J., Henon, M., & Wielen, R. (1974). A comparison of numerical methods for the study of star cluster dynamics. Astronomy and Astrophysics, 37, 183–187.
Tout, C. A., Pols, O. R., Eggleton, P. P., & Han, Z. (1996). Zero-age main-sequence radii and luminosities as analytic functions of mass and metallicity. Monthly Notices of the Royal Astronomical Society, 281, 257. 10.1093/mnras/281.1.257