Spatial profiles - progenax — differentiable initial conditions for N-body simulations

Spatial profiles — 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.

Plummer sphere¶

✅ verified · 5 equations · 2 sources · API: PlummerProfile

Cored, infinitely extended spherical density profile with an analytic inverse-CDF: the classic smooth model for young and idealized clusters and the standard N-body test problem.

Use it for	Not for
✓ idealized/controlled N-body experiments (fully analytic chain: rho, M(<r), Phi, f(E))	✗ tidally truncated clusters (no finite edge — use King/LIMEPY)
✓ smooth cored systems without tidal truncation	✗ steep young-cluster outer slopes gamma < 5 (use EFF)
✓ differentiable pipelines needing a closed-form position sampler

Parameters¶

Name	Meaning	Units	Typical range	Code
`r_h`	3-D half-mass radius; sets the scale radius a = r_h*sqrt(2^(2/3)-1)	pc	0.1–10	`PlummerProfile(r_h=...)`

Equations¶

\rho(r) \;=\; \frac{3\,M}{4\pi\,a^3}\,\biggl[1 + \biggl(\frac{r}{a}\biggr)^{\!2}\,\biggr]^{-5/2}

(1)

Symbols: $\rho$ : mass density [Msun / pc^3]; $M$ : total mass [Msun]; $a$ : Plummer scale radius [pc]. Assumes: spherical symmetry; isotropic (for the paired DF). Derivation: theory page.

M(<r) \;=\; M\,\frac{r^3}{(r^2 + a^2)^{3/2}}

(2)

Symbols: $M(<r)$ : enclosed mass [Msun]. Assumes: spherical symmetry. Derivation: theory page.

a \;=\; r_h\,\sqrt{2^{2/3} - 1}\;\approx\;0.7664\,r_h

(3)

Symbols: $r_h$ : 3-D half-mass radius [pc]. Derivation: theory page.

\sigma_r^2(r) \;=\; \frac{G\,M}{6\,\sqrt{r^2 + a^2}}

(4)

Symbols: $\sigma_r$ : 1-D radial velocity dispersion [pc / Myr]; $G$ : gravitational constant (explicit, units-carried) [pc^3 / (Msun Myr^2)]. Assumes: isotropic Plummer DF. Derivation: theory page.

f(E) \;=\; \frac{24\sqrt{2}}{7\pi^3}\,\frac{a^2}{G^5\,M^4}\,(-E)^{7/2}, \qquad E < 0

(5)

Symbols: $E$ : specific energy (bound: E < 0) [pc^2 / Myr^2]. Assumes: ergodic f(E); isotropic. Derivation: theory page.

Sources¶

Plummer (1911) — the space-density law (Schuster n=5 polytrope fit to globular clusters) (Eqs. 11-12 (space density, in scale-radius units))
Aarseth et al. (1974) — the Plummer model as the standard N-body test problem + IC recipe (inverse-CDF positions; Beta(3/2,9/2) speed draw) (Eq. 1, p. 183)

Code & validation¶

code: PlummerProfile (src/progenax/profiles/plummer.py)
validation: tests/validation/test_plummer_physics.py::TestPlummerScaleRadius::test_scale_radius_formula_exact
validation: tests/validation/test_plummer_physics.py::TestPlummerDensityProfile::test_cdf_formula_accuracy
validation: tests/validation/test_plummer_physics.py::TestPlummerVirialEquilibrium::test_virial_ratio

King (1966) lowered isothermal¶

✅ verified · 4 equations · 1 source · API: KingProfile

Single-mass lowered-isothermal sphere: an isothermal core with a finite tidal cutoff, parameterised by the dimensionless central concentration W0. The standard model for old, dynamically relaxed globular clusters.

Use it for	Not for
✓ old, dynamically relaxed globular clusters	✗ young/expanding clusters with power-law halos (use EFF)
✓ tidally truncated systems needing a finite edge r_t	✗ radially anisotropic systems (use Michie)
	✗ generalized truncation g != 1 or multi-mass (use LIMEPY / Engine A)

Parameters¶

Name	Meaning	Units	Typical range	Code
`W0`	dimensionless central potential Psi(0)/sigma_0^2; sets the concentration c = log10(r_t/r_c)	dimensionless	3–12 (supported to ~15)	`KingProfile.from_W0_rc(W0=...)`
`r_c`	King core radius r_c^2 = 9 sigma_0^2 / (4 pi G rho_0)	pc	0.1–5	`KingProfile.from_W0_rc(r_c=...)`

Equations¶

f(E) \;=\; \begin{cases} \rho_1\,(2\pi\sigma_0^2)^{-3/2}\,\bigl[\,e^{(\Phi(r_t)-E)/\sigma_0^2} - 1\,\bigr], & E < \Phi(r_t) \\ 0, & E \ge \Phi(r_t) \end{cases}

(6)

Symbols: $E$ : specific energy [pc^2 / Myr^2]; $\sigma_0$ : central velocity-scale parameter [pc / Myr]; $\rho_1$ : density normalization [Msun / pc^3]. Assumes: isotropic; single-mass; lowered Maxwellian. Derivation: theory page.

\rho(W) \;=\; \rho_1 \cdot \bigl[\,e^W\,\mathrm{erf}(\sqrt{W}) - \sqrt{4W/\pi}\,(1 + \tfrac{2}{3}W)\,\bigr]

(7)

Symbols: $W$ : dimensionless potential Psi/sigma_0^2 [dimensionless]. Assumes: follows from integrating the lowered-Maxwellian DF over velocities. Derivation: theory page.

r_c^2 \;=\; \frac{9\,\sigma_0^2}{4\pi G\,\rho_0}

(8)

Symbols: $\rho_0$ : central density [Msun / pc^3]. Derivation: theory page.

c \;\equiv\; \log_{10}\!\left(\frac{r_t}{r_c}\right) \;=\; \log_{10}(\xi_t)

(9)

Symbols: $r_t$ : tidal (truncation) radius, the psi -> 0 crossing [pc]; $\xi_t$ : dimensionless tidal radius r_t/r_c [dimensionless]. Derivation: theory page.

Sources¶

King (1966) — lowered-Maxwellian f(E), rho(W) with erf, the factor-9 Poisson ODE, Table II c(W0) (Eq. 3 (DF); Eq. 15 (r_c normalization); Eq. 16 (Poisson ODE); Eq. 17 (rho(W)); Table II p. 73 (c(W0)))

Code & validation¶

code: KingProfile (src/progenax/profiles/king.py)
code: king_lowered_maxwellian_density (src/progenax/profiles/king.py)
validation: tests/validation/test_king_physics.py::test_concentration_matches_king1966_table_ii
validation: tests/validation/test_king_physics.py::TestKingODESolution::test_boundary_conditions
validation: tests/validation/test_king_physics.py::TestKingLoweredMaxwellianDensity::test_density_shape_matches_direct_velocity_integral

EFF (1987) power-law halo¶

✅ verified · 3 equations · 1 source · API: EFFProfile

Cored profile with a power-law outer halo of 3-D slope gamma: the empirical fit to young LMC clusters. gamma = 5 recovers the Plummer sphere exactly; gamma <= 3 has divergent total mass, so a finite truncation radius r_t is carried in practice.

Use it for	Not for
✓ young massive clusters with shallow power-law halos (LMC-style)	✗ relaxed, tidally truncated globulars (use King)
✓ systems needing a tunable outer slope between Plummer and isothermal	✗ gamma <= 3 without an explicit r_t (untruncated mass diverges)

Parameters¶

Name	Meaning	Units	Typical range	Code
`a`	core scale radius	pc	0.1–10	`EFFProfile(a=...)`
`gamma`	3-D density power-law slope (EFF87 fit the PROJECTED surface slope; 3-D ~ projected + 1)	dimensionless	3.2–7 (EFF87 surface slopes 2.2–3.2 map to 3-D ~3.2–4.2; gamma = 5 is Plummer)	`EFFProfile(gamma=...)`
`r_t`	truncation radius (required for gamma <= 3; finite in practice)	pc	5–100	`EFFProfile(r_t=...)`

Equations¶

\rho(r) \;=\; \rho_0\,\biggl[1 + \biggl(\frac{r}{a}\biggr)^{\!2}\,\biggr]^{-\gamma/2}

(10)

Symbols: $\rho_0$ : central density [Msun / pc^3]; $\gamma$ : 3-D power-law slope [dimensionless]. Assumes: spherical symmetry; 3-D (deprojected) slope convention. Derivation: theory page.

M(<r) \;=\; \frac{4\pi}{3}\,\rho_0\,r^3\; {}_2F_1\!\left(\tfrac{3}{2},\,\tfrac{\gamma}{2};\,\tfrac{5}{2};\,-\frac{r^2}{a^2}\right)

(11)

Symbols: $M(<r)$ : enclosed mass (Gauss hypergeometric closed form) [Msun]. Assumes: spherical symmetry. Derivation: theory page.

M_{\mathrm{total}} \;=\; 4\pi\,\rho_0\,a^3\,\frac{\sqrt{\pi}}{4}\, \frac{\Gamma\!\big(\tfrac{\gamma-3}{2}\big)}{\Gamma\!\big(\tfrac{\gamma}{2}\big)}

(12)

Symbols: $\Gamma$ : Euler gamma function [dimensionless]. Assumes: gamma > 3 (else the untruncated mass diverges). Derivation: theory page.

Sources¶

Elson et al. (1987) — the EFF surface-brightness law and the young-LMC-cluster fits (Eq. 1 (projected surface-brightness law); Eq. 2 (enclosed projected luminosity); Table 1 (surface slopes 2.2-3.2, median 2.6))

Code & validation¶

code: EFFProfile (src/progenax/profiles/eff.py)
validation: tests/validation/test_eff_physics.py::TestEFFDensityFormula::test_central_density_unity
validation: tests/validation/test_eff_physics.py::TestEFFDensityFormula::test_power_law_slope_asymptotic
validation: tests/validation/test_eff_physics.py::TestEFFTidalTruncation::test_all_particles_within_tidal_radius

Michie (1963) anisotropic lowered isothermal¶

✅ verified · 1 equation · 2 sources · API: MichieProfile

The spatial side of the self-consistent Michie–King model: the density generated by the radially anisotropic Michie DF through its own radius-dependent Poisson equation. More extended than King at the same W0 (radial orbits push mass outward); r_a -> inf recovers King exactly.

Use it for	Not for
✓ self-consistent radially anisotropic globular-cluster models	✗ holding a fixed observed density (use the OM overlay on Plummer/EFF)
✓ systems where anisotropy should RESHAPE the density (not just the velocities)	✗ r_a below the W0-dependent radial-orbit bound (1/r^2 tail, never truncates — construction raises)

Parameters¶

Name	Meaning	Units	Typical range	Code
`W0`	dimensionless central potential (as King)	dimensionless	3–12	`MichieProfile(W0=...) / solve_michie_profile(W0=...)`
`r_c`	core radius (King Eq. 15 normalization)	pc	0.1–5	`MichieProfile(r_c=...)`
`r_a`	anisotropy radius; smaller = more radial = more extended (larger r_t)	pc	>~ 3-4 r_c at W0=7 (below: raises ValueError)	`MichieProfile(r_a=...)`

Equations¶

\frac{1}{\xi^2}\frac{d}{d\xi}\!\left(\xi^2\frac{d\psi}{d\xi}\right) = -9\,\frac{\hat\rho(\psi,\ \xi/\hat r_a)}{\hat\rho(W_0,0)}, \qquad \psi(0)=W_0,\ \psi^\prime(0)=0

(13)

Symbols: $\xi$ : dimensionless radius r/r_c [dimensionless]; $\psi$ : dimensionless relative potential [dimensionless]. Assumes: the anisotropy-weighted density makes the RHS explicitly radius-dependent (unlike King). Derivation: theory page.

Sources¶

Michie (1963) — the anisotropic DF and the radius-dependent Poisson equation (Eq. 5.0 (DF); Eq. 5.8 (Poisson, p. 138 — scanned source, visually verified 2026-07-11))
King (1966) — the lowering, the factor-9 nondimensionalization, and the r_c normalization (Eqs. 15-16)

Code & validation¶

code: MichieProfile (src/progenax/profiles/michie.py)
code: solve_michie_profile (src/progenax/profiles/michie.py)
validation: tests/validation/test_michie_physics.py::TestMichieIsotropicLimit::test_density_matches_king_at_large_ra
validation: tests/validation/test_michie_physics.py::TestMichieAnisotropyProfile::test_beta_below_osipkov_merritt_ceiling
validation: tests/validation/test_michie_physics.py::TestMichieAnisotropyStructure::test_more_anisotropic_more_extended

References¶

Plummer, H. C. (1911). On the problem of distribution in globular star clusters. Monthly Notices of the Royal Astronomical Society, 71, 460–470. 10.1093/mnras/71.5.460
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.
King, I. R. (1966). The structure of star clusters. III. Some simple dynamical models. The Astronomical Journal, 71, 64–75. 10.1086/109857
Elson, R. A. W., Fall, S. M., & Freeman, K. C. (1987). The structure of young star clusters in the Large Magellanic Cloud. The Astrophysical Journal, 323, 54–78. 10.1086/165807
Michie, R. W. (1963). On the distribution of high energy stars in spherical stellar systems. Monthly Notices of the Royal Astronomical Society, 125, 127–139. 10.1093/mnras/125.2.127