Phenom precession: provisional component ledger

Scope and status

This research ledger, anchored to foundation commit 5bc907d, covers IMRPhenomP/Pv2, XP, XPHM, and the repository's XPHM-SpinTaylor and XPNR routes. It does not create a WaveformDefinition, certify full models, or cover SEOBNR. Aligned-spin carriers are D for P/Pv2 and XAS for XP. XPHM and its angle variants use the unresolved XHM mode ledger. Each row below is research-only until the exact gates in the final section pass.

Primary mathematics: Schmidt, Hannam & Husa (2012) and Hannam et al. (2014) for PhenomP twisting; Pratten et al. (2021), arXiv:2004.06503v2 for XP/XPHM (Secs. III–IV, Apps. A–G); Hamilton et al. (2025), arXiv:2507.02604v1 and Thompson et al. (2024), arXiv:2312.10025v1 for XPNR/XO4a; and Colleoni et al. (2025), arXiv:2412.16721 for XPHM-SpinTaylor (Sec. II.2). Version-specific LAL behavior is a reference implementation rather than an independent paper equation.

Inputs, conventions, and options

All precessing routes take two 3-vector dimensionless spins in addition to mass, distance, inclination and extrinsic phase/time inputs. A complete option tuple must pin frequency grid, f_ref, phi0/observer azimuth, phic, tc, phasing convention, spin and mass ordering, L/J/N source frames, Euler offsets, carrier calibration, selected modes, and final-spin rule. In Pratten et al., h=h_+−ih_× (Eq. 1), the Fourier transform uses exp(−2πift) (Eq. 3), gamma obeys dgamma/dt=−cos(beta)dalpha/dt (Eq. 7), and inertial/coprecessing modes rotate through Wigner D matrices (Eqs. 8–10). Those signs and frame choices matter to complex comparisons.

Route	Native option surface	Important discrepancy or boundary
P/Pv2	The Torch P class exports IMRPhenomPv2 as a class alias, but public Torch waveform dispatch calls a separate clean Pv2 function for the Pv2 key. JAX P and the separate JAX Pv2 class/functions are likewise distinct.	The P primitive defaults f_ref=20 Hz; clean JAX Pv2 defaults to the first positive sample when f_ref is absent and accepts convention 0 or 1. Class alias, dispatcher key, and LAL named variant must not be treated as equivalent without explicit tuple comparison.
XP	Both Torch XP and JAX XP default to MSA prec_version 223, convention 1, and final_spin_mod 3 for that route; NNLO selects 102.	Both frontends use scoped clean zero-nutation continuations. Both frontends use a clean distinct-root two-spin projection at unequal mass, zero or nonzero phi0, conventions 0/1/6, and final_spin_mod=3. The nonzero-phi0 map is derived from published source-frame conventions and passes the declared strict public-binary fixture. Equal-mass or invalid-root generic rows retain NNLO angle fallback, but explicit remnant mode 3 raises instead of silently becoming mode 0; the opposed-J guard remains.
XPHM	Both accept NNLO, MSA, SpinTaylor and PNR branches through Torch and JAX. Supported coprecessing positive-m modes: 22, 21, 33, 32, 44.	Both class defaults are MSA version 223, convention 1, and final-spin option 3. An explicit version controls the family even if the convenience method label conflicts. SpinTaylor and XPNR public names dispatch to XPHM with method selection, rather than selecting a separately calibrated carrier.
Angle/offset labels	Native version resolver accepts NNLO 101–104, MSA 220–224, SpinTaylor 310/311/320/321 and PNR 300/330 (300 resolves to 330). Native convention accepts 0, 1, 5, 6, 7 and final_spin_mod accepts 0, 2, 3 or automatic choice for XPHM.	Pratten App. F Tables 3–5 defines published 101–104, 220–224, offset conventions and final-spin rules. SpinTaylor/PNR labels are later native extensions and need separate source/compatibility tests. Native XP supports final_spin_mod 0 or 3, not XPHM's 2.

The paper's Table 4 distinguishes conventions 0, 1, 5, 6 and 7 through alpha/epsilon offsets and where phiRef enters the carrier. Convention 1 uses the Pv2 alpha initial angle and zero carrier phiRef. Table 5 and Eqs. 39–42 distinguish chi_p, a single transverse spin, vectorial transverse spin, and MSA averaged remnant choices. The native final_spin_mod=2 and 3 routes must not be silently interchanged; the reference also permits an option 1 which native XP/XPHM do not expose. XPHM's negative-m contributions are generated by symmetry when twisting the selected positive-m coprecessing modes (Pratten App. F).

Mathematics and components

IDs are proposed stable research identifiers. “Pending” means an independently evaluable source calculation, full branch evidence or reference comparison is still missing; “conditional” marks a specifically qualified implemented branch.

Provisional ID / status	Mathematics and source anchor	Torch/JAX mapping and dependencies	Open gate
P-EFFSPIN / pending	P/Pv2 map two spins to effective aligned and in-plane spin at a reference frequency; Hannam 2014 and Pratten 2021 Sec. IV.4, Eqs. 34–42 discuss chi_p and remnant alternatives.	Torch P, JAX P, JAX Pv2; D 22.	Independent source-frame mapping, exchanged-body, zero-in-plane and unequal-spin equal-mass cases.
P-NNLO / pending	NNLO alpha and epsilon with precession-cone beta; Pratten App. G.1 Eqs. 120–121 and subsequent coefficients, and Sec. III Eqs. 7–10. Native comments use section-style G7–G9 labels that differ from the pinned HTML v2 numbering.	P angle functions in both frontends and clean Pv2 adapters.	Paper-derived angle values/derivatives and offsets at f_ref, including singular/aligned limits.
P-TWIST / pending	Wigner rotation and polarization projection of D 22, Pratten Eqs. 1–10 and App. E SPA mapping.	P/Pv2 source-frame geometry, Torch/JAX dispatchers.	Complex h_+, h_× at multiple inclinations, phic/phi0 and time shifts against same named LAL variant.
XP-ANG-NNLO / pending	XPHM paper Sec. IV.1, App. G.1 and App. F Table 3 versions 101–104; PN L choices alter beta and offsets.	Torch MSA/NNLO engine, JAX engine; XAS 22.	Independent version-specific equations, angular momentum order and fallback boundary checks.
XP-ANG-MSA / conditional	XPHM paper Sec. IV.2, App. F Table 3 versions 220–224; MSA analytic two-spin angles, with defined failure behavior.	Torch clean v223 chart, JAX MSA engine, and separate scalar/JAX zero-nutation references.	Scoped zero-nutation and unequal-mass generic v223 components have independent checks; equal-mass \(q=1\) (\(\delta=0\)) division-by-zero resolved and turning-root coalescence regularized in Torch/JAX (tests/test_precession_boundaries.py); other versions, non-v223 charts and difficult fallback boundaries remain open; the declared nonzero-phi0 generic fixture passes the mapped binary gate.
XP-TWIST / pending	XAS co-precessing 22 rotated by Pratten Eqs. 7–10 and SPA in App. E; final-spin Eq. 39 or 42 according to option.	Torch XP, JAX XP.	LAL complex polarizations for every version/offset tuple, aligned boundary and XAS carrier gauge.
XPHM-MULTIMODE / pending	XHM 22/21/33/32/44 coprecessing modes rotated with full l=2,3,4 Wigner matrices, Pratten Sec. III, Eqs. 8–10 and App. E.	Torch XPHM, JAX XPHM; XHM component IDs in companion ledger.	Mode mixing/negative-m signs and phase gauges by mode, plus all unresolved XHM calibration gates.
XPHM-ST / pending	Orbit-averaged SpinTaylorT4 spin/L evolution, fixed-grid RK4 in v=(πMf)^(1/3), Euler extraction and minimal rotation. Colleoni et al. 2025 Sec. II.2, Eqs. 18–25 gives spin/L evolution, J-frame angles and post-inspiral continuation; Eq. 26 gives vectorial remnant spin. PN sources also include Kidder 1995 and Racine 2008.	Torch SpinTaylor, JAX SpinTaylor, XPHM/XHM carrier. Versions 310/311/320/321; typical LAL comparison uses 320 and final_spin_mod=2.	Equation-by-equation PN order and integration gauge, grid convergence, gradient validation, post-inspiral exponential \(\beta\) damping option (damp_beta=True) verified in tests/test_precession_boundaries.py, and LAL same-option complex comparison.
XPHM-PNR / component-conditional	XPNR Eqs. (3)–(8), (15)–(24) and XO4a Eqs. (25)–(35), (44), (50)–(52): transition-spin map, NR-tuned angle surfaces, attachments/continuations, carrier deformation/effective ringdown/asymmetry, and higher-mode map.	Dedicated XPNR ledger, independent scalar reference, Torch/JAX PNR engines and inherited coefficient tables; public route currently uses the native symmetric XHM carrier. Version 330.	Scoped equation tests pass after correcting B3; transition state, attachments, full carrier/asymmetry, coefficient provenance, external complex waveforms and NR validation remain open.

The complete published XPNR waveform is not identical to this repository's composition: the native name pairs a provisional subset of the NR-tuned angles with the native symmetric XHM carrier. The missing XHM-CP deformation, effective ringdown and dominant-mode asymmetry are carrier components, not angle options. The dedicated ledger records the exact scope and failed gates; an optimized plus-polarization match cannot certify those pieces. Likewise, the optional XPHM ODE method is experimental native functionality and has no paper-option equivalence established here.

Implementation mapping

Native call graph: public Torch or JAX dispatcher → named P/Pv2, XP or XPHM implementation → D, XAS or XHM carrier → chosen angle engine → Wigner rotation/projection. XPHM-SpinTaylor and XPNR aliases set the method before calling XPHM. The XPNR coefficient arrays live in Torch and JAX; a coefficient file existing in two frontends is not an independent calibration.

The Pv2 source-frame checks, XP aligned-boundary checks, SpinTaylor checks, and PNR checks identify implementation branches. The last two include optional LAL/PyCBC optimized-over-time/phase match tests, which measure a different property from complex waveform error.

Evidence and limitations

The frozen case manifest and provenance report Pv2 1/1 catalog plus 1/1 holdout, and XP 1/1 plus 1/1, passing the declared complex relative L2 ≤ 10^-6 and mismatch ≤ 10^-8 thresholds for those configurations. They do not certify arbitrary P/Pv2 or XP variants. XPHM has 0/1 in each strict full-waveform set. SpinTaylor and XPNR are outside the frozen counts: optional tests define minimum plus-polarization matches of 0.98 over 20–300 Hz for three SpinTaylor cases and 0.99 over 20–400 Hz for four XPNR cases. These are acceptance thresholds, not a reported domain-wide result and not complex mode accuracy.

Known comparability gaps: Colleoni et al. also introduce an updated coprecessing amplitude, whereas this native SpinTaylor route uses the current XHM carrier. Pv2 class aliases and public routes differ; XP's physical zero-nutation continuation has a scoped dispatch; LAL App. F has options and multibanding not represented by native arguments; SpinTaylor and PNR are additional angle routes; and all XPHM routes inherit XHM's failed strict whole-waveform gate and calibration uncertainty. Differentiability of an implementation is not an independently checked derivative of the published model. The XPHM closure ledger records the shared default, scalar rotation reference, exact native reductions, and current failed full-waveform diagnostics.

XP v223 endpoint audit (2026-09-24)

The paragraphs in this audit record the earlier public dispatch and its failures. The subsequent physical zero-nutation continuation supersedes those dispatch statements for the supported Torch XP branch; the explicit v223 helper and pinned LAL diagnostics retain the historical compatibility contract.

For XP conventions 0 and 1, a Table 4 carrier-phase offset is not by itself a strain-phase offset. Pratten et al., Appendix C Eqs. (67), (75), (79), and (81) also fix the observer direction, initial Euler angles, and output basis. At the aligned endpoint, the spin-2 projection depends on the combined angle exp[2i(alpha0 + gamma0)], which equals exp[2i(3*pi/2 + phic)] in the tested source frame even though the raw exact-aligned alpha0 chart differs from its tiny-transverse-spin chart by pi. The new endpoint test checks this combined identity at phic = 0, 0.3, 0.7 and transverse spin 0 or 1e-9. A separate test checks each generic convention's complete Torch clean waveform against public LAL over 20–511.75 Hz. The generic clean convention-0/1 strains have a relative sign in that fixture; treating only the Table 4 carrier shift as their full relative phase gave a stale assertion.

An earlier aligned observer-azimuth diagnostic found that the inherited Torch and JAX routes agreed to about 1.3e-14 relative L2, while a Torch-only nonzero-phi0 rotation of the clean zero-phi0 waveform would break that agreement. Passing the MSA final-spin override into the inherited XAS carrier was insufficient: clean convention 1 differed by 0.070509 relative L2 at 25, 40, and 80 Hz. At those frequencies, the clean/XAS complex plus-polarization ratios were approximately 0.997302-0.073561i, 0.999993-0.000022i, and 0.987079+0.160141i. Their frequency dependence ruled out a constant phase correction. The later scoped physical zero-nutation continuations and generic source-chart transport in both frontends supersede the dispatch description in this historical diagnostic.

The paper's Eq. (17) has the strict aligned limit cos(beta)=1 when transverse spin vanishes; an equation-level test preserves that source claim. Native XP v223 instead evaluates the exact-aligned auxiliary-root endpoint with a finite regularization. In the fixture below, its default near/exact strains differ by 3.61e-5 (plus) and 4.89e-5 (cross) in relative L2 at azimuth -2, even for transverse spin 1e-9. Public LAL v223 reproduces this numerical jump, while the default clean exact and near strains separately agree with public LAL. The default-waveform test therefore bounds this version-specific jump rather than claiming fixed-basis waveform continuity; its convention-0 check bounds the same numerical effect at 2.55e-5/3.45e-5. The XPHM assertions remain unchanged. Public LAL convention 0 has an additional near-aligned phase threshold around transverse spin 1e-9, distinct from the default auxiliary-root effect. Neither numerical behavior changes the paper's strict beta limit.

Two XP tests remain open in the combined precession suite: the convention-6 cross-route assertion (1.73e-2 relative at one sample) and the nonzero-phi0 exact-aligned phase relation (7.05e-2 relative L2). These remain failing gates.

The reference-closure follow-up separates the published Appendix C Eq. (79) vector identity from the v223 composed-strain behavior. It records the distinct provenance of the 259/72, 427/72, and compatibility-derived 259/75 coefficients and checks the measured XP/XAS reference-frequency ratio against public LAL directly. The equation-level identity remains a strict gate.

The v223 azimuth-boundary diagnostic separates two incompatible contracts at convention 1. Pratten et al., Eqs. (8)--(13) and Appendix C Eqs. (67)--(81) fix the finite-rotation projection and observer frame; the aligned spin-2 exp(-2i phi0) action and fixed-basis near-aligned continuity follow from those equations, rather than being a separately printed waveform prescription. The exact-zero Euler chart and the split-root finite-beta floor are v223 compatibility choices, not published identities. For (40,20) Msun, phic=0.3, f_ref=40 Hz, and a 1e-9 transverse spin at azimuth -2, both native clean and public LAL v223 convention 1 retain a 4.24e-5 relative complex-strain difference between near and exact alignment at 25, 40, and 80 Hz, despite agreeing with each other to 5.4e-10 on the near case. At azimuth 0.4, the shared residual is 1.00e-5; the finite opening angle stays near 3.7e-5 radians as transverse spin vanishes. In a diagnostic composition, transporting the near-aligned alpha by -phi_J and gamma by +phi_J reduces the near/exact difference to about 3.4e-10 at the first azimuth, but then differs from LAL by 4.24e-5. At that audit snapshot, the public observer-azimuth gate was red at its exact-phase assertion because Torch selected different routes at zero and nonzero phi0; its subsequent near-continuity assertion concerned a separate v223 chart incompatibility. Neither gate should be made green by silently replacing the LAL-compatible near chart or the physical exact endpoint. The later physical continuation and frame-map record documents the public adapter choice and its scoped Torch/JAX and LAL checks; the historical compatibility diagnostics above remain distinct.

The audit ran on len with Torch 2.14.0+cu130, JAX 0.11.2, LAL 7.7.1, and LALSimulation 6.2.1; the LALSimulation extension SHA-256 was e816879d23e652e8b3928496d6fd261de0832b5c3781c50e33a458042495b42e. The diagnostic fixture used (m1,m2)=(40,20) Msun, (chi1,chi2)=((0,0,0.4),(0,0,-0.2)), distance=500 Mpc, inclination=0.7, phic=0.3, f_ref=40 Hz, prec_version=223, and final_spin_mod=3. The dense generic oracle fixture is specified in test_xp_aligned_boundary_clean.py. Standalone backend diagnostics must set PYTHONPATH=src to import this checkout rather than an installed package.

The nonpublic JAX generic-angle diagnostic implements the intrinsic spin cubic, nutation phase, secular and oscillatory angles from Chatziioannou et al., Eqs. (21), (24), (51), (65), and Apps. B, D, F, with the opening angle and remnant identity from Pratten et al., Sec. IV and App. G. It names the native-v223 compatibility choices separately: reference spin flux contractions, q² nutation coefficient, pole continuation, nonconserved-spin 3PN opening angular momentum, and total-mass-squared remnant normalization. The focused test compares intermediate values, final angles, remnant, and six spin derivatives against the Torch clean kernel for the generic (40,20) fixture and independent (48,17) holdout. On len with the versions above, all five checks pass; the angle differences for the first fixture are at most 4e-15. This establishes intrinsic Torch/JAX agreement at two nondegenerate unequal-mass points. Observer-frame transport, endpoint integration, public dispatch, and LAL complex strain remain separate gates.

Nonpublic JAX v223 aligned projection (2026-09-24)

The JAX aligned projection composes the nonpublic intrinsic endpoint with the observer geometry of Pratten et al., Appendix C and the finite-beta quadrupole projection of Eqs. (8)--(13) and Appendix A. Its split-root opening angle, inferred v223-compatible 259/75 source-frame coefficient, and exact-aligned Euler chart are compatibility prescriptions, not paper identities. phic is the clean carrier/source-frame phase; observer_azimuth is the separate public-XP-like phi0. For exact alignment the helper imposes the spin-2 exp(-2i phi0) SO(2) action after finite-beta projection as a physical endpoint identity; this does not assert that the current public nonzero-phi0 route or LAL uses that prescription.

The focused tests compare geometry, Euler angles, remnant, finite-beta polarizations, and phic derivatives with Torch clean; they check JIT and observer-azimuth derivatives separately. On len with the latest-package environment, the endpoint and projection tests passed 21/21 (PYTHONPATH=src python -m pytest -q tests/test_jax_clean_v223_projection.py tests/test_jax_clean_v223_endpoint.py). Dense exact-aligned convention-0/1 waveforms at phi0=0 differ from the pinned public LAL v223 option tuple by about 2.1e-10 relative L2. At that diagnostic snapshot, with fixed phic=0.3, phi0=0.4, and 25/40/80 Hz, the imposed physical endpoint differed from the then-public Torch route by 1.99876278 (convention 0) and 0.0705129942 (convention 1) relative combined-polarization L2. That diagnostic did not change public dispatch. The later physical continuation and frame-map record supersedes this public-route status, while retaining the separate v223 binary-boundary failures.

The JAX generic projection adds two-spin source-frame geometry and composes the intrinsic MSA angles with the XAS carrier and quadrupole projection at public observer phi0=0. Its frame construction follows Pratten et al., Appendix C Eqs. (67)--(85), including the polarization-basis angle in Eq. (85), and the rotation follows Eqs. (8)--(13) and Appendix A; the source-frame 259/75 term and convention transport remain explicitly compatibility-derived. The 17 focused checks cover geometry, complex strain, six-spin derivatives, batching/JIT, label exchange, and two generic dense-grid LAL fixtures for conventions 0/1. On len (Torch 2.14.0+cu130, JAX 0.11.2, LAL 7.7.1, LALSimulation 6.2.1), all pass; the largest dense complex-polarization relative L2 is 4.21e-13 over 20--511.75 Hz. As a separate diagnostic, public LAL convention 6 equals exp(2i phic) times convention 1 to 2.34e-15 relative L2 at phic=0.3 for both fixtures. Public JAX XP now uses this composition for unequal-mass generic rows at zero or nonzero phi0, prec_version=223, final_spin_mod=3, and conventions 0/1/6. The clean kernel masks nonpositive frequency bins after positive-frequency evaluation. Exactly equal-mass generic rows retain the inherited angle route; explicit remnant mode 3 is rejected when that MSA root is unsupported. The mapped nonzero-phi0 source chart passes the declared public-binary fixture for conventions 0/1/6; this does not certify equal mass, near alignment, or XPHM dispatch.

XP physical zero-nutation continuation (2026-09-24)

The reference-closure page now gives the paper equation, independent scalar/JAX opening-angle kernels, Torch public dispatch conditions, and measured difference from the explicit v223/LAL diagnostic. The scalar Eq. (7) minimal-rotation check and exact XP/XAS waveform collapse now cover the zero-nutation endpoint, including an omitted carrier f_ref. The later boundary and frame-map closure records strict passing internal continuity checks for the generic two-spin up-down fixture in both tested bands, at the unchanged 1e-6 threshold. Invalid coalescing-root rows use the declared NNLO angle fallback; this is not a sourced generic MSA continuation. The pinned-LAL full-complex boundary gate remains failed. The reference-closure page keeps the cubic conditioning, root ordering and physical-instability boundaries separate. The public JAX waveform uses the physical one-spin continuation only for its guarded option tuple. Valid unequal-mass generic two-spin rows use the clean source chart at nonzero phi0; the declared full-waveform mapped-binary fixture passes, while equal-mass MSA-remnant and near-aligned v223 binary boundaries remain open. The aligned convention-6 LAL residual is about 0.118 relative L2, while the separate binary-compatibility helper retains its strict gate.

Reproduce the checks

Inspect the cited source, dispatchers, companion XHM ledger and historical manifest. Local smoke checks can use the four named test files above with the repository pytest setup; optional LAL/PyCBC comparisons require those dependencies. This ledger did not rerun the frozen reference suite.

A six-section executable specification requires one explicitly named option tuple per branch, with: (1) pinned source versions and independently computed effective-spin, angle, Wigner, carrier and remnant equations; (2) exact frames, spin/mass ordering, reference and Fourier conventions; (3) branch-specific Torch/JAX values and derivatives, RK convergence for SpinTaylor, fit-hash/derivative checks for PNR, and aligned/transitional limits; (4) same-option LAL complex mode and polarization catalog/holdout checks with recorded L2 and mismatch tolerances, while reporting optimized matches separately; (5) separate NR physical validation for physical-accuracy claims; and (6) reproducible commands, dependency and fixture hashes, option arguments and observed numerical outcomes. XPHM cannot be promoted until the relevant XHM components pass their own gates. No unqualified P, Pv2, XP, XPHM, SpinTaylor or XPNR catalog record follows from the evidence above.