Add opt-in Offner et al. 2023 multiplicity model (Table 1, including BDs)

[jluastro]

Adds an opt-in multiplicity model based on Offner et al. 2023, Protostars and Planets VII, ASPC 534, 275 (arXiv:2203.10066; ADS 2023ASPC..534..275O; Table 1 on Zenodo 10.5281/zenodo.6628915).

The SPISEA v2.5 MultiplicityUnresolved / MultiplicityResolvedDK objects remain the default. Frozen FITS in tests/test_data/ are unchanged.

Documentation

docs/multiplicity.rst fully describes the Offner models (formulas, coefficients, BD policy, Table 1 companion-assignment note) and includes the five comparison figures vs SPISEA v2.5. Changelog and docs/imf.rst point at the opt-in. Figures are generated from the multiplicity object methods (python docs/figures/plot_mf_offner_vs_spisea2.5.py and plot_q_sep_offner_vs_spisea2.5.py).

New and modified callables in spisea/imf/multiplicity.py have numpy-style Parameters/Returns with types and units (Msun, AU, dex of log10(a/AU), dimensionless MF/CSF/q/γ). Private model helpers (_logistic_in_logm, etc.) are at the bottom of the file so Sphinx/source order documents the public classes first. Primary mass must be positive; massless (M≤0) primaries are not supported.

MF vs primary mass

Offner 2023 vs SPISEA v2.5: multiplicity fraction vs primary mass

Left: brown-dwarf zoom. Right: BD through early B. Solid: Offner logistic in log-mass. Dashed: SPISEA v2.5 (0.44 M^{0.51}). Dotted: SPISEA v2.5 scalar BD staircase.

q and separations vs mass

Offner 2023 vs SPISEA v2.5: mass-ratio index vs primary mass

Offner γ is an error-weighted logistic in log M fitted to Table 1 γ_trunc (not interpolation):

γ(M) = A + (B - A) / (1 + (M / M0)**(-k))
A=6.6, B=-1.77, M0=0.0651, k=0.629

The fit undershoots Fontanive 4.8±2.2 (~3.3 at 0.033 Msun). Offner BD companions are more equal-mass than the SPISEA v2.5 stellar q_pow (6.1 / −0.4 step). Mean-q companion panel: docs/figures/meanq_offner_vs_spisea2.5.png.

Offner 2023 vs SPISEA v2.5: characteristic separation vs primary mass

Offner μ(a) is a smooth broken power law in log10(a) vs log10(M), s=0.1 dex, FGK-pulled (C∞ via stable logcosh):

v = log10(M / Mp);  yp = log10(μp)
log10(a) = yp + 0.5*(αL+αR)*v + 0.5*(αR-αL)*s * logcosh(v/s)
μp=44.46 AU, Mp=0.819 Msun, αL=1.005, αR=-0.308, s=0.10

Offner BD a peaks at a few AU (μ(0.033)≈2 AU); SPISEA v2.5 DK is a Duchêne–Kraus broken power law with a BD blend and is not meant for that range.

Offner 2023 vs SPISEA v2.5: sigma of log10 a vs primary mass

Offner σ(log10 a) is a 2-parameter logistic pinned at 0.7 / 1.5:

σ(M) = 0.7 + 0.8 / (1 + (M / 0.354)**(-6.05))

Resolved draws use loc = log_a_mean(mass), scale = sigma_log_a(mass) in a truncated lognormal (0.01–2000 AU).

How to use

from spisea.imf import imf, multiplicity
from spisea import synthetic

multi = multiplicity.MultiplicityUnresolvedOffner2023()
# alias: multiplicity.MultiplicityOffner2023()
# resolved: multiplicity.MultiplicityResolvedOffner2023()

imf_obj = imf.Kroupa_2001(multiplicity=multi)
cluster = synthetic.ResolvedCluster(iso, imf_obj, Mcl)

Logistic in log-mass MF/CSF

MF(M)  = A + (B - A) / (1 + (M / M0)**(-k))
CSF(M) = same form, different coefficients

MF:  A=0.14, B=0.99, M0=1.41, k=1.25
CSF: A=0.12, B=2.35, M0=3.57, k=0.96

C-infinity smooth, saturates at B ~ 1. RMS vs Table 1 geom-mean MF ~0.026 vs ~0.049 for the old 3-segment law. Fontanive (8 ± 6%) remains ~0.07 below the curve (~15%). MF clipped to [0, 1]; CSF = MF below 0.08 Msun.

Architecture

Companion masses and “is this a multiple?” are drawn in IMF.generate_cluster / IMF.calc_multi, not in synthetic.py.

1. Mass-aware random_q(x, mass=None) — Offner uses the error-weighted γ logistic.
2. Companion-count policy — BD cap of 1 companion lives on the multiplicity object.
3. Duck-typed resolved orbits — Offner resolved does not subclass DK.
4. log_a_mean / sigma_log_a — public; resolved log_semimajoraxis draws from those.

Tests

pytest -q on this cloud VM cannot collect the full suite: missing synphot, stsynphot, and pandas (no spisea-synphot conda env). With --continue-on-collection-errors: 27 passed, 1 failed (test_resolvedmult → missing stsynphot), 1 skipped (no pysynphot/stsynphot), 5 collection errors, 0 deselected. All Offner unit tests that ran passed, including test_xi2. The test_resolvedmult failure is missing photometry backends, not Offner math.

pytest spisea/tests/test_multiplicity.py spisea/tests/test_imf.py -k "not test_resolvedmult and not test_xi2": 26 passed, 2 deselected.

_{To show artifacts inline, enable in settings.}