Binary populations & orbits - progenax — differentiable initial conditions for N-body simulations

Binary populations & orbits — 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.

Moe & Di Stefano (2017) P–q–e statistics¶

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

The faithful non-separable multiplicity statistics: mass-ratio power laws with a twin excess, all conditioned on primary mass AND period (Table 13 grids), plus the period- and mass-dependent eccentricity slope. The companion-composition engine behind MoeCompanions / MoeDiStefano2017Full.

Use it for	Not for
✓ observationally faithful binary populations across 0.8-40+ Msun primaries	✗ separable q-only toys (use FlatMassRatio / PowerLawMassRatio)
✓ massive-star population synthesis where the q-P coupling matters (twin excess at short P)	✗ sub-solar primaries below the MD17 calibration range

Parameters¶

Name	Meaning	Units	Typical range	Code
`primary_mass`	primary mass M1 conditioning every grid lookup	Msun	0.8–40 (Table 13 bins, interpolated)	`MoeCompanions()/MoeDiStefano2017Full() consume M1 arrays at sample time`

Equations¶

g(q \mid M_1) \;=\; (1 - f_{\mathrm{twin}})\,\frac{q^{\gamma(M_1)}}{Z_{\mathrm{pl}}} \;+\; f_{\mathrm{twin}}\,\mathcal{N}(q \mid 1,\,\sigma_{\mathrm{twin}})

(1)

Symbols: $q$ : mass ratio m2/m1 (twin excess = fraction with q > 0.95, defined over q > 0.3) [dimensionless]; $\gamma(M_1)$ : broken power-law slope (gamma_largeq above q = 0.3, gamma_smallq below) [dimensionless]. Assumes: Table-13 grid interpolation in (M1, log P); twin convention: excess fraction over 0.3 < q < 1.0. Derivation: theory page.

\eta(M_1, P) = \begin{cases} 0.6 - \dfrac{0.7}{\log_{10} P - 0.5}, & 0.8 < M_1 < 3\,M_\odot\ \text{(Eq. 17)} \\ 0.9 - \dfrac{0.2}{\log_{10} P - 0.5}, & M_1 > 7\,M_\odot\ \text{(Eq. 18)} \end{cases}

(2)

Symbols: $\eta$ : eccentricity power-law slope p(e) proportional to e^eta (0 = uniform, 1 = thermal) [dimensionless]. Assumes: linear interpolation in M1 across 3-7 Msun; eta <= -1 (very short P) returns e ~ 0. Derivation: theory page.

e_{\max}(P) \;=\; 1 - \Bigl(\frac{P}{2\,\mathrm{d}}\Bigr)^{-2/3} \quad (P > 2\ \mathrm{d})

(3)

Symbols: $e_{\max}$ : period-dependent Roche-lobe eccentricity ceiling; P <= 2 d circularizes [dimensionless]. Assumes: components must not overflow Roche lobes at periapsis (MD17 Eq. 3). Derivation: theory page.

Sources¶

Moe & Di Stefano (2017) — Table 13 multiplicity grids (gamma_largeq, gamma_smallq, F_twin, f_logP) — ledger-verified cell-by-cell; eccentricity slopes and the Roche ceiling (Table 13, p. 52; Eqs. 17-18 (eta fits); Eq. 3, p. 38 (e_max Roche ceiling))

Code & validation¶

code: MoeDiStefano2017Full (src/progenax/imf/binary/moe_di_stefano.py)
code: MoeCompanions (src/progenax/binaries/companions.py)
code: MoeEccentricity (src/progenax/binaries/eccentricity.py)
validation: tests/unit/imf/test_moe_full.py::TestTable13Interpolation::test_gamma_largeq_cells
validation: tests/unit/imf/test_moe_full.py::TestTable13Interpolation::test_ftwin_cells
validation: tests/unit/imf/test_moe_full.py::TestFTwinPaperConvention::test_f_twin_excess_over_q_gt_03

Period distributions (Öpik / DM91 / Sana+2012)¶

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

The three direct period samplers: log-uniform (Öpik baseline), the Duquennoy & Mayor (1991) solar-type log-normal, and the Sana+2012 short-period-biased OB power law — plus mass-dependent routing between them.

Use it for	Not for
✓ solar-type primaries: LogNormalPeriod (DM91 sec 7.3 defaults)	✗ compact binaries / post-interaction periods (IC-time statistics only)
✓ O/B primaries: SanaOBPeriod (pi = -0.55 in log10 P)	✗ a generic low-mass field population sampled with the Sana OB law
✓ mixed populations via MassDependentBinaryConfig routing at m_break

Parameters¶

Name	Meaning	Units	Typical range	Code
`mu_log_P`	log-normal mean of log10(P/day) (DM91: 4.8, median ~180 yr)	dex(day)	4.8	`LogNormalPeriod(mu_log_P=...)`
`sigma_log_P`	log-normal width (DM91: 2.3)	dex	2.3	`LogNormalPeriod(sigma_log_P=...)`
`power`	Sana OB slope pi of f(log10 P) proportional to (log10 P)^pi	dimensionless	-0.55 (+/- 0.2, Sana 2012)	`SanaOBPeriod(power=-0.55)`

Equations¶

f(\log P) \;=\; C\,\exp\!\left[-\frac{(\log P - \overline{\log P})^2}{2\,\sigma_{\log P}^2}\right], \qquad \overline{\log P} = 4.8,\ \sigma_{\log P} = 2.3

(4)

Symbols: $P$ : orbital period in days [day]. Assumes: solar-type primaries (DM91 sample).

f(\log_{10} P) \;\propto\; (\log_{10} P)^{\pi}, \qquad \pi = -0.55,\ \ 0.15 \le \log_{10} P \le 3.5

(5)

Symbols: $\pi$ : Sana 2012 period exponent (short-period biased) [dimensionless]. Assumes: O/B primaries; intrinsic (bias-corrected) distribution.

Sources¶

Duquennoy & Mayor (1991) — the solar-type Gaussian in log P (mean 4.8, sigma 2.3, P in days) (Section 7.3 (per-paper note, PDF-verified; scanned source))
Sana et al. (2012) — the OB-star intrinsic period power law pi = -0.55 +/- 0.2 (Table S3 exponents (per-paper note))

Code & validation¶

code: LogUniformPeriod (src/progenax/binaries/period.py)
code: LogNormalPeriod (src/progenax/binaries/period.py)
code: SanaOBPeriod (src/progenax/binaries/period.py)
validation: tests/unit/binaries/test_population.py::TestLogNormalPeriod::test_mean_log_period
validation: tests/unit/binaries/test_population.py::TestLogNormalPeriod::test_std_log_period

Eccentricity distributions (thermal / uniform / Moe)¶

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

The three eccentricity samplers: Heggie’s thermal f(e) = 2e (dynamical equilibrium), the uniform baseline, and the Moe & Di Stefano period-and-mass-dependent power law with the Roche ceiling.

Use it for	Not for
✓ dynamically processed populations: ThermalEccentricity (f = 2e, = 2/3)	✗ post-tidal-circularization populations at short P without the Moe ceiling
✓ observationally faithful primordial e: MoeEccentricity (couples to P, M1)

Parameters¶

Name	Meaning	Units	Typical range	Code
`e_max`	optional hard ceiling on ThermalEccentricity/UniformEccentricity draws	dimensionless	0.9–1.0	`ThermalEccentricity(e_max=...)`

Equations¶

f(e) \;=\; 2e,\qquad e \in [0, 1]

(6)

Symbols: $e$ : orbital eccentricity [dimensionless]. Assumes: dynamical (thermal) equilibrium; = 2/3; sampled as e = sqrt(u). Derivation: theory page.

f(e) \;=\; 1,\qquad e \in [0, 1]

(7)

Symbols: $e$ : orbital eccentricity [dimensionless]. Assumes: agnostic baseline; = 1/2. Derivation: theory page.

Sources¶

Heggie (1975) — the thermal/equilibrium f(e) = 2e from energy equipartition (with = 2/3; CDF e^2, PPF sqrt(u)) (per-paper note (heggie-1975.md), thermal-distribution discussion)
Moe & Di Stefano (2017) — the period/mass-dependent eta slope and the Roche e_max ceiling (see the moe_pqe card) (Eqs. 17-18; Eq. 3, p. 38)

Code & validation¶

code: ThermalEccentricity (src/progenax/binaries/eccentricity.py)
code: UniformEccentricity (src/progenax/binaries/eccentricity.py)
code: MoeEccentricity (src/progenax/binaries/eccentricity.py)
validation: tests/unit/binaries/test_population.py::TestThermalEccentricity::test_thermal_mean
validation: tests/unit/binaries/test_population.py::TestThermalEccentricity::test_canonical_moments_emax1

Kepler orbital elements¶

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

The two-body orbital-element chain: Kepler III (P <-> a), the Kepler equation solved by fixed-iteration Newton, true anomaly, orbit-plane state, and the 3-1-3 Euler rotation to inertial components — the machinery that turns (P, e, angles) into positions and velocities.

Use it for	Not for
✓ resolving sampled binaries into component positions/velocities (the binary -> spatial connector)	✗ N >= 3 hierarchical dynamics (no secular evolution here)
✓ machine-precision two-body ICs (energy/L conserved to ~1e-16)	✗ relativistic or tidally evolving orbits

Parameters¶

Name	Meaning	Units	Typical range	Code
`elements`	KeplerElements(a, e, i, omega, Omega, M0): semi-major axis, eccentricity, inclination, argument of periapsis, longitude of ascending node, mean anomaly	pc / dimensionless / rad	e in [0, 1); angles in [0, 2 pi)	`KeplerElements(a=..., e=..., i=..., omega=..., Omega=..., M0=...)`

Equations¶

P^2 \;=\; \frac{4\pi^2\,a^3}{G\,(m_1 + m_2)}

(8)

Symbols: $P$ : orbital period [Myr (or day via unit conversion)]; $a$ : semi-major axis of the RELATIVE orbit [pc]. Assumes: two-body; G explicit and units-carried. Derivation: theory page.

E - e\,\sin E \;=\; M(t), \qquad M(t) = M_0 + n\,t,\quad n = 2\pi/P

(9)

Symbols: $E$ : eccentric anomaly (fixed-iteration Newton solve — differentiable, JIT-safe) [rad]; $M$ : mean anomaly [rad]. Assumes: fixed iteration count (no while_loop): converged to float64 for e < 0.99. Derivation: theory page.

\mathbf{r}_1 = -\frac{m_2}{m_1 + m_2}\,\mathbf{r}_{\mathrm{rel}}, \qquad \mathbf{r}_2 = +\frac{m_1}{m_1 + m_2}\,\mathbf{r}_{\mathrm{rel}}

(10)

Symbols: $\mathbf{r}_{\mathrm{rel}}$ : relative separation vector after the 3-1-3 Euler rotation [pc]. Assumes: center-of-mass frame: momentum exactly zero per binary. Derivation: theory page.

Sources¶

Murray & Dermott (2000) — the standard celestial-mechanics chain (Kepler equation, anomalies, orbit-plane state, Euler rotations) (Ch. 2 (the two-body problem))

Code & validation¶

code: KeplerElements (src/progenax/binaries/kepler.py)
code: compute_period (src/progenax/binaries/kepler_period.py)
code: period_to_semimajor_axis (src/progenax/binaries/kepler_period.py)
validation: tests/validation/test_binary_physics.py::TestKeplerThirdLaw::test_period_semimajor_axis_roundtrip
validation: tests/validation/test_binary_physics.py::TestKeplerEquation::test_eccentric_orbit_periapsis
validation: tests/validation/test_binary_physics.py::TestBinaryMomentumConservation::test_momentum_zero

Binary-cluster assembly (build_binary_cluster)¶

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

The composition operator: primary IMF x companion model x population target -> a cluster whose binaries are resolved into components (resolve_binary_components) with per-binary COM preservation and full primordial-pair bookkeeping. A semantics card — the physics lives in the composed model cards.

Use it for	Not for
✓ one-call binary-population ICs (Systems / Stars / TotalMass targets)	✗ hierarchical triples+ (pairs only at IC time)
✓ energy-budget-aware binary populations (binary_energy_budget diagnostics)

Parameters¶

Name	Meaning	Units	Typical range	Code
`primary_imf`	any IMF card’s model (house default: the SMOOTH Maschberger)	—	—	`build_binary_cluster(primary_imf=...)`
`companion_model`	IndependentCompanions (separable) or MoeCompanions (faithful P-q-e)	—	—	`build_binary_cluster(companions=...)`
`target`	population size specification: Systems(n) / Stars(n) / TotalMass(M)	count or Msun	—	`build_binary_cluster(target=...)`

Equations¶

\sum_{\mathrm{pair}} m_j \mathbf{v}_j \;=\; \mathbf{0} \quad \text{and} \quad \frac{\sum_{\mathrm{pair}} m_j \mathbf{r}_j}{\sum_{\mathrm{pair}} m_j} \;=\; \mathbf{r}_{\mathrm{sys}}

(11)

Symbols: $\mathbf{r}_{\mathrm{sys}}$ : the system (center-of-mass) position drawn from the spatial profile [pc]. Assumes: each binary’s internal orbit is superposed on its system’s cluster orbit; COM and momentum exact per pair.

Sources¶

Moe & Di Stefano (2017) — the faithful companion statistics option (see moe_pqe) (Table 13)
Murray & Dermott (2000) — the orbital resolution (see kepler_elements) (Ch. 2)

Code & validation¶

code: build_binary_cluster (src/progenax/builders.py)
code: resolve_binary_components (src/progenax/binaries/assembly.py)
validation: tests/integration/test_binary_cluster.py::TestBuildBinaryCluster::test_units_kepler_third_law_roundtrip
validation: tests/integration/test_binary_cluster.py::TestBuildBinaryCluster::test_com_preserved
validation: tests/integration/test_binary_cluster.py::TestBuildBinaryCluster::test_count_and_provenance

References¶

Moe, M., & Di Stefano, R. (2017). Mind your Ps and Qs: The interrelation between period (P) and mass-ratio (Q) distributions of binary stars. The Astrophysical Journal Supplement Series, 230, 15. 10.3847/1538-4365/aa6fb6
Duquennoy, A., & Mayor, M. (1991). Multiplicity among solar-type stars in the solar neighbourhood. II. Distribution of the orbital elements in an unbiased sample. Astronomy & Astrophysics, 248, 485–524.
Sana, H., de Mink, S. E., de Koter, A., Langer, N., Evans, C. J., Gieles, M., Gosset, E., Izzard, R. G., Le Bouquin, J.-B., & Schneider, F. R. N. (2012). Binary interaction dominates the evolution of massive stars. Science, 337, 444–446. 10.1126/science.1223344
Heggie, D. C. (1975). Binary evolution in stellar dynamics. Monthly Notices of the Royal Astronomical Society, 173, 729–787. 10.1093/mnras/173.3.729
Murray, C. D., & Dermott, S. F. (2000). Solar System Dynamics. Cambridge University Press. 10.1017/CBO9781139174817