Tidal physics & diagnostics - progenax — differentiable initial conditions for N-body simulations

Tidal physics & diagnostics — 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.

Jacobi radius & tidal truncation¶

✅ verified · 2 equations · 2 sources · API: jacobi_radius

The tidal (Jacobi) radius of a cluster on a circular galactic orbit — the generalized cube-root law covering the point-mass (Keplerian) and flat-rotation-curve (isothermal) hosts — and the post-sampling truncation operator that removes stars beyond it.

Use it for	Not for
✓ setting a physically motivated outer edge from the host potential	✗ eccentric orbits (the circular-orbit r_J over-estimates the effective edge at perigalacticon)
✓ fill-factor studies (r_h/r_J as the tidal-filling knob)	✗ self-consistent tidally truncated DFs (that is what King/LIMEPY are for)

Parameters¶

Name	Meaning	Units	Typical range	Code
`M_cl`	cluster mass	Msun	1e2–1e6	`jacobi_radius(M_cl=...)`
`M_gal`	host mass enclosed within the orbital radius	Msun	1e10–1e12	`jacobi_radius(M_gal=...)`
`R`	galactocentric orbital radius	pc (or kpc via units)	1–30 kpc	`jacobi_radius(R=...)`

Equations¶

r_J \;=\; R\,\biggl[\frac{M_{\mathrm{cl}}}{(3 - \mathrm{d}\ln M_{\mathrm{gal}}/\mathrm{d}\ln R)\,M_{\mathrm{gal}}(<R)}\biggr]^{1/3}

(1)

Symbols: $r_J$ : Jacobi (tidal) radius; the L1 Lagrange distance [pc]. Assumes: circular orbit; point-mass host: denominator 3 (King 1962); isothermal host (dlnM/dlnR = 1): denominator 2 (Baumgardt & Makino 2003). Derivation: theory page.

\mathcal{F} \;\equiv\; \frac{r_h}{r_J}

(2)

Symbols: $\mathcal{F}$ : tidal fill factor (underfilling << 1; Roche-filling ~ 0.5) [dimensionless]. Derivation: theory page.

Sources¶

King (1962) — the tidal-radius concept and the (m/3M)^(1/3) cube-root law (DOI verified live) (Section II (the empirical tidal cutoff))
Baumgardt & Makino (2003) — the isothermal-host form r_t = (G m / 2 V^2)^(1/3) R^(2/3) used for flat rotation curves (Eq. 5)

Code & validation¶

code: jacobi_radius (src/progenax/tidal.py)
code: apply_tidal_truncation (src/progenax/tidal.py)
validation: tests/validation/test_tidal_physics.py::TestJacobiTidalBalance::test_self_gravity_equals_tidal_plus_centrifugal
validation: tests/validation/test_tidal_physics.py::TestJacobiL1Lagrange::test_matches_l1_for_realistic_cluster
validation: tests/validation/test_tidal_physics.py::TestKeplerianVsIsothermal::test_isothermal_keplerian_ratio

Cartwright & Whitworth (2004) Q diagnostic¶

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

The MST-based substructure statistic Q = mbar / sbar (normalized mean MST edge length over normalized correlation length): Q < 0.8 flags substructure, Q > 0.8 central concentration. Exact estimator (compute_q_parameter) plus the differentiable kNN surrogate (q_approx, recalibrated in audit S3).

Use it for	Not for
✓ quantifying substructure/smoothness of sampled or observed positions	✗ distinguishing substructure TYPES (fractal vs radial gradients can share a Q)
✓ differentiable pipelines: q_approx as a Fisher-able summary (grad-audited)	✗ small N (CW04 calibrated at 100 <= N <= 300; anchors carry realization scatter)

Parameters¶

Name	Meaning	Units	Typical range	Code
`positions`	2-D projected positions (the CW04 convention; A = pi R^2 normalization)	pc	N >= ~100	`compute_q_parameter(positions_2d) / q_approx(positions)`

Equations¶

Q \;\equiv\; \frac{\bar m}{\bar s}, \qquad \bar m = \frac{\langle \ell_{\rm MST} \rangle}{\sqrt{A/N}}, \quad \bar s = \frac{\langle r_{ij} \rangle}{R}, \quad A = \pi R^2

(3)

Symbols: $\bar m$ : mean MST edge length normalized by sqrt(A/N) [dimensionless]; $\bar s$ : mean pairwise separation normalized by the cluster radius R [dimensionless]. Assumes: 2-D projected positions; A = pi R^2 (the CW04 area convention — NOT the convex hull); uniform-sphere anchor Q = 0.79 +/- 0.02 reproduced to < 0.01.

Sources¶

Cartwright & Whitworth (2004) — the Q = mbar/sbar statistic, the A = pi R^2 normalization convention, and the Table-1 fractal/radial anchors (ledger-verified p. 590) (Section 4 (definition); Table 1, p. 590 (Q = 0.45/0.61/0.73/0.80 at D = 1.5/2.0/2.5/3.0))

Code & validation¶

code: compute_q_parameter (src/progenax/diagnostics/substructure.py)
code: q_approx (src/progenax/diagnostics/q_approx.py)
validation: tests/unit/substructure/test_q_baselines.py::TestUniformSphereBaseline::test_q_matches_cw04_range
validation: tests/unit/substructure/test_q_approx.py::TestQApproxCalibrationAccuracy::test_calibrated_q_approx_matches_exact

Primordial mass segregation & Lambda_MSR¶

✅ verified · 2 equations · 2 sources · API: energy_sorted_segregation

The energy-sorted primordial-segregation generator (most-massive stars on the most-bound orbits, no orbit reuse) and the Allison et al. (2009) Lambda_MSR MST diagnostic that measures it — plus the differentiable soft surrogate lambda_msr_approx.

Use it for	Not for
✓ non-equilibrium primordial segregation ICs (energy-sorted assignment)	✗ dynamical (evolved) segregation — this is the IC-time operator
✓ measuring segregation: Lambda_MSR > 1 = massive stars more concentrated
✓ EQUILIBRIUM segregation belongs to Engine A’s from_mass_segregation (see that card)

Parameters¶

Name	Meaning	Units	Typical range	Code
`n_massive`	size of the massive subset compared against random subsets in Lambda_MSR	count	5–20	`lambda_msr(..., n_massive=...)`

Equations¶

E_i \;=\; \tfrac{1}{2}|\mathbf{v}_i|^2 \;+\; \Phi(\mathbf{r}_i)

(4)

Symbols: $E_i$ : specific orbital energy used for the energy-sorted assignment (most massive -> most bound) [pc^2 / Myr^2]. Assumes: assignment permutes orbits, never reuses one (masses preserved exactly). Derivation: theory page.

\Lambda_{\mathrm{MSR}} \;=\; \frac{\langle\, \ell_{\mathrm{random}}\,\rangle}{\ell_{\mathrm{massive}}} \;\pm\;\frac{\sigma_{\mathrm{random}}}{\ell_{\mathrm{massive}}}

(5)

Symbols: $\ell_{\mathrm{massive}}$ : MST length of the n_massive most massive stars [pc]; $\langle \ell_{\mathrm{random}} \rangle$ : mean MST length of same-size random subsets [pc]. Assumes: Lambda_MSR ~ 1: no segregation; > 1: massive stars more concentrated (Allison 2009). Derivation: theory page.

Sources¶

Allison et al. (2009) — the Lambda_MSR MST-ratio diagnostic (Eq. 1 + Section 2 (per-paper material, ledger-verified))
Baumgardt et al. (2008) — the primordial-segregation IC context (segregated initial models) (Section 2)

Code & validation¶

code: energy_sorted_segregation (src/progenax/cluster/mass_segregation.py)
code: lambda_msr_approx (src/progenax/diagnostics/segregation_approx.py)
validation: tests/unit/cluster/test_mass_segregation.py::TestEnergySortedSegregation::test_assigned_energy_is_monotonic_in_mass
validation: tests/unit/cluster/test_mass_segregation.py::TestEnergySortedSegregation::test_most_massive_star_is_the_most_bound

References¶

King, I. R. (1962). The structure of star clusters. I. An empirical density law. The Astronomical Journal, 67, 471. 10.1086/108756
Baumgardt, H., & Makino, J. (2003). Dynamical evolution of star clusters in tidal fields. Monthly Notices of the Royal Astronomical Society, 340, 227–246. 10.1046/j.1365-8711.2003.06286.x
Cartwright, A., & Whitworth, A. P. (2004). The statistical analysis of star clusters. Monthly Notices of the Royal Astronomical Society, 348, 589–598. 10.1111/j.1365-2966.2004.07360.x
Allison, R. J., Goodwin, S. P., Parker, R. J., Portegies Zwart, S. F., de Grijs, R., & Kouwenhoven, M. B. N. (2009). Using the minimum spanning tree to trace mass segregation. Monthly Notices of the Royal Astronomical Society, 395, 1449–1454. 10.1111/j.1365-2966.2009.14508.x
Baumgardt, H., De Marchi, G., & Kroupa, P. (2008). Evidence for primordial mass segregation in globular clusters. The Astrophysical Journal, 685, 247–253. 10.1086/590488