Aligned-spin TaylorF2 mathematical specification
| Definition field | Catalog value |
|---|---|
| Model ID | taylorf2-aligned-bh-spin-3.5pn/v1 |
| Reference composition | taylorf2-aligned-bh-spin-3.5pn/v1 |
| Scope | Aligned black-hole spin phase corrections through 3.5PN conservative dynamics and flux to infinity with restricted quadrupole amplitude. |
| Domain and modes | frequency; (2, 2) |
| Native backends | torch, jax |
| Scoped verification claims | 0 |
| Option | Default | Native choices | Reference-only choices |
|---|---|---|---|
spin_order |
7 |
-1, 0, 1, 2, 3, 4, 5, 6, 7, 8 |
None |
phasing_convention |
coalescence |
coalescence, reference_frequency |
None |
phenom_d_calibration |
false |
false, true |
None |
Scope and status
Specification: taylorf2-aligned-bh-spin-3.5pn/v1.
This extension composes the unchanged
taylorf2-nonspinning-3.5pn/v1 reference with separately sourced
aligned black-hole spin corrections. It retains the baseline's Newtonian
amplitude, Fourier convention, phase origins, positive-frequency domain, and
unwindowed waveform. Its spin phasing covers the conservative dynamics and
flux to infinity; horizon absorption, which starts at 2.5PN for spinning black
holes, is excluded. The old equations, component IDs, API, and fixtures remain
the baseline; a zero-spin reduction checks the composition without serving as an
independent derivation of that baseline. Its bounded
direct source review is separate evidence.
Inputs, conventions, and options
Parameters and composition
In addition to the baseline total mass \(M\) and distance \(D\) in seconds, frequency \(f\) in Hz, inclination \(\iota\), time \(t_c\), and orbital phase parameter \(\phi_c\), use
Here \(-1<\delta<1\) and \(-1\leq\chi_i\leq1\); each spin is the signed component along the orbital angular momentum. Both signs of \(\delta\) are allowed, so exchanging body labels maps \((\delta,\chi_1,\chi_2)\) to \((-\delta,\chi_2,\chi_1)\). Spin-induced multipoles take their black-hole values; general compact-object quadrupoles, tides, precession, eccentricity, amplitude spin corrections, absorption, merger, cutoffs, and tapers are outside this scope. These analytic bounds do not establish physical accuracy at arbitrary frequency.
Frontend option contract
frontend_terms() in the separate traceability module translates existing
frontend options into explicit reference terms. spin_order is a legacy recipe,
so its integer value is not a uniform PN cutoff. The coefficient and numerical
tests check the option boundaries directly. No spin recipe is changed to make
the names look like physical orders.
spin_order |
Terms | With phenom_d_calibration=True |
|---|---|---|
| 0, 1, 2 | None | None |
| 3 | SO3 |
SO3 |
| 4 | SO3, SS4 |
SO3, SS4 |
| 5 | SO3, SS4, SO5, SO6, SO7 |
SO3, SS4, SO5, SO6, SO7 |
| 6, 7 | SO3, SS4, SO5, SO6, SS6, SO7 |
SO3, SS4, SO5, SO6, SO7 |
| 8 or greater | SO3, SS4, SO5, SO6, SS6, SO7, SS7, SSS7 |
SO3, SS4, SO5, SO6, SO7 |
| negative | SO3, SS4, SO5, SO6, SS6, SO7 |
SO3, SS4, SO5, SO6, SO7 |
The public waveform default is spin_order=7; the low-level phase default is
spin_order=5. Negative values share the public default's listed terms and do
not enable the final SS7 and SSS7 terms. An explicit spin_order=8 selects all
terms in this reference. phenom_d_calibration=True suppresses SS6, SS7, and
SSS7 at any selector; it is available for coefficients and low-level phase,
but is not exposed by the public waveform call. This checks that compatibility
recipe, not an IMRPhenomD calibration or complete IMRPhenomD waveform.
Mathematics and components
Spin phase composition
Let \(I_{\rm NS}(v,\eta)\) be the unchanged nonspinning intrinsic phase and \(v=(\pi M f)^{1/3}\). The extension uses
SO, SS, and SSS identify terms linear, quadratic, and cubic in spin; the number
is the power of \(v\) inside the PN bracket. An explicit terms subset includes
only the named contributions. SO5_log is the derived coefficient
\(3P_{\rm SO5}\), selected together with SO5. The kernel's default is its complete
listed term set. This explicit mathematical selection is independent of the
frontends' integer options described below.
The combined phase replaces \(I\) in the baseline's two waveform phase conventions. The logarithm scale is the same \(\ln v\) convention. Changing the 2.5PN scale changes a parameter-dependent phase constant; finite-reference subtraction cancels that constant. Comparisons hold the declared phase convention fixed.
Sources and transformations
The spin equations are entered independently in
taylorf2_aligned_spin.py.
Its exact expressions import the baseline reference, never production helpers
or frontend coefficients. Component evidence pins a paper version and equation;
generated expressions and fixtures do not supply an independent source audit.
The lower-order terms use Wade et al., arXiv:1306.3901v2, Eq. (4) and the accompanying definitions of \(\beta\), \(\sigma\), and \(\gamma\). Set the quadrupole parameters to their black-hole values and specialize all spin products to the aligned case. In that notation the bracket corrections are \(4\beta\), \(-10\sigma\), and \(-\gamma\), with the 2.5PN logarithm expanded in the declared gauge.
Mishra et al., arXiv:1601.05588v1, Eqs. (6a), (6b), and (7), supply the higher-order polynomial contributions in \(\chi_s,\chi_a,\delta,\eta\). The reference retains the baseline second-harmonic \(3/(128\eta v^5)\) normalization. Mishra's Eq. (4) is not used to replace that normalization: the first-harmonic phase convention in Eq. (1) and the printed prefactor require care. Wade's orbital-phase prefactor becomes the baseline factor when multiplied by the harmonic number two.
The 3.5PN spin–spin tail
SS7 includes the quadratic part of
Pratten et al., arXiv:2001.11412v1, Eq. (A19)
and the additional tail contribution in its
Eq. (A24). Eq. (A19) alone is
incomplete for this scope. Mishra Eq. (6b) does not supply this quadratic term.
The reference includes neither Pratten's additional 4PN terms nor its
phenomenological fits and IMR joins.
An independent balance-law calculation checks this source combination. Define \(X_{1,2}=(1\pm\delta)/2\) and \(a_i=X_i\chi_i\). With black-hole multipoles, Bohé et al., arXiv:1501.01529v1, Eqs. (3.33), (4.14) give the leading quadratic coefficients in the normalized energy and flux:
The orbital tail coefficient is \(f_3=4\pi\) from Buonanno et al., arXiv:0907.0700v1, Eq. (3.2). Messina and Nagar, arXiv:1703.08107v4, Eq. (26) gives the explicit additional flux coefficient
In \(dt/dv=-E'(v)/\mathcal F(v)\), its normalized quadratic coefficient at \(v^7\) is \(q_7=-f_7^{\rm SS}+4\pi(2f_4-3e_4)\). Integrating the second-harmonic stationary phase gives \(P_{\rm SS7}=-20q_7\), hence
Setting \(f_7^{\rm SS}=0\) in that derivation reproduces the quadratic part of
Pratten Eq. (A19): \(-\pi[570(a_1^2+a_2^2)+1100a_1a_2]\). Restoring the flux
adds \(20f_7^{\rm SS}\) to the phase coefficient, exactly Eq. (A24). This source
review used the pinned printed equations and a separate symbolic reduction;
it did not infer the correction from production outputs or generated fixtures.
The backend correction therefore affects selectors spin_order >= 8 with
calibration disabled. The public default 7, phase default 5, negative
selectors, and calibration profiles omit SS7 and retain their term sets.
The exact correction table is generated from the independent expressions;
SO5_log multiplies \(v^5\ln v\), and all coefficients exclude the common
\(3/(128\eta v^5)\) prefactor.
| Spin term | Exact correction |
|---|---|
SO3 |
\(4 \cdot \chi_{1} \cdot \left(- \frac{25 \cdot \delta^{2}}{16} + \frac{113 \cdot \left(\frac{\delta}{2} + \frac{1}{2}\right)^{2}}{12} + \frac{25}{16}\right) + 4 \cdot \chi_{2} \cdot \left(- \frac{25 \cdot \delta^{2}}{16} + \frac{113 \cdot \left(\frac{1}{2} - \frac{\delta}{2}\right)^{2}}{12} + \frac{25}{16}\right)\) |
SS4 |
\(- \frac{405 \cdot \chi_{1}^{2} \cdot \left(\frac{\delta}{2} + \frac{1}{2}\right)^{2}}{8} - 10 \cdot \chi_{1} \cdot \chi_{2} \cdot \left(\frac{79}{32} - \frac{79 \cdot \delta^{2}}{32}\right) - \frac{405 \cdot \chi_{2}^{2} \cdot \left(\frac{1}{2} - \frac{\delta}{2}\right)^{2}}{8}\) |
SO5 |
\(- \chi_{1} \cdot \left(\left(\frac{1}{4} - \frac{\delta^{2}}{4}\right) \cdot \left(\frac{5 \cdot \delta^{2}}{6} + \frac{4615}{28}\right) + \left(\frac{741805}{2268} - \frac{35 \cdot \delta^{2}}{9}\right) \cdot \left(\frac{\delta}{2} + \frac{1}{2}\right)^{2}\right) - \chi_{2} \cdot \left(\left(\frac{1}{4} - \frac{\delta^{2}}{4}\right) \cdot \left(\frac{5 \cdot \delta^{2}}{6} + \frac{4615}{28}\right) + \left(\frac{1}{2} - \frac{\delta}{2}\right)^{2} \cdot \left(\frac{741805}{2268} - \frac{35 \cdot \delta^{2}}{9}\right)\right)\) |
SO6 |
\(\pi \cdot \left(\frac{2270 \cdot \delta \cdot \left(\frac{\chi_{1}}{2} - \frac{\chi_{2}}{2}\right)}{3} + \left(\frac{\chi_{1}}{2} + \frac{\chi_{2}}{2}\right) \cdot \left(130 \cdot \delta^{2} + \frac{1880}{3}\right)\right)\) |
SS6 |
\(\delta \cdot \left(\frac{\chi_{1}}{2} - \frac{\chi_{2}}{2}\right) \cdot \left(\frac{\chi_{1}}{2} + \frac{\chi_{2}}{2}\right) \cdot \left(\frac{8225 \cdot \delta^{2}}{72} + \frac{59065}{144}\right) + \left(\frac{\chi_{1}}{2} - \frac{\chi_{2}}{2}\right)^{2} \cdot \left(\frac{263245 \cdot \delta^{2}}{1008} - 480 \cdot \left(\frac{1}{4} - \frac{\delta^{2}}{4}\right)^{2} + \frac{235}{224}\right) + \left(\frac{\chi_{1}}{2} + \frac{\chi_{2}}{2}\right)^{2} \cdot \left(\frac{232415 \cdot \delta^{2}}{2016} + \frac{1255 \cdot \left(\frac{1}{4} - \frac{\delta^{2}}{4}\right)^{2}}{9} + \frac{16455}{112}\right)\) |
SO7 |
\(\delta \cdot \left(\frac{\chi_{1}}{2} - \frac{\chi_{2}}{2}\right) \cdot \left(- \frac{26804935 \cdot \delta^{2}}{24192} - \frac{1985 \cdot \left(\frac{1}{4} - \frac{\delta^{2}}{4}\right)^{2}}{48} - \frac{21772661965}{3048192}\right) + \left(\frac{\chi_{1}}{2} + \frac{\chi_{2}}{2}\right) \cdot \left(- \frac{10566655595 \cdot \delta^{2}}{3048192} + \frac{5345 \cdot \left(\frac{1}{4} - \frac{\delta^{2}}{4}\right)^{3}}{36} - \frac{1042165 \cdot \left(\frac{1}{4} - \frac{\delta^{2}}{4}\right)^{2}}{3024} - \frac{3645857045}{762048}\right)\) |
SS7 |
\(- \pi \cdot \left(\frac{815 \cdot \chi_{1}^{2} \cdot \left(\frac{\delta}{2} + \frac{1}{2}\right)^{2}}{2} + 785 \cdot \chi_{1} \cdot \chi_{2} \cdot \left(\frac{1}{2} - \frac{\delta}{2}\right) \cdot \left(\frac{\delta}{2} + \frac{1}{2}\right) + \frac{815 \cdot \chi_{2}^{2} \cdot \left(\frac{1}{2} - \frac{\delta}{2}\right)^{2}}{2}\right)\) |
SSS7 |
\(\delta \cdot \left(\frac{\chi_{1}}{2} - \frac{\chi_{2}}{2}\right)^{3} \cdot \left(595 \cdot \delta^{2} + \frac{305}{24}\right) + \delta \cdot \left(\frac{\chi_{1}}{2} - \frac{\chi_{2}}{2}\right) \cdot \left(\frac{\chi_{1}}{2} + \frac{\chi_{2}}{2}\right)^{2} \cdot \left(\frac{215 \cdot \delta^{2}}{8} + \frac{7185}{4}\right) + \left(\frac{\chi_{1}}{2} - \frac{\chi_{2}}{2}\right)^{2} \cdot \left(\frac{\chi_{1}}{2} + \frac{\chi_{2}}{2}\right) \cdot \left(\frac{3635 \cdot \delta^{2}}{2} + 80 \cdot \left(\frac{1}{4} - \frac{\delta^{2}}{4}\right)^{2} + \frac{45}{8}\right) + \left(\frac{\chi_{1}}{2} + \frac{\chi_{2}}{2}\right)^{3} \cdot \left(\frac{475 \cdot \delta^{2}}{24} + \frac{100 \cdot \left(\frac{1}{4} - \frac{\delta^{2}}{4}\right)^{2}}{3} + \frac{7055}{12}\right)\) |
SO5_log |
\(- 3 \cdot \chi_{1} \cdot \left(\left(\frac{1}{4} - \frac{\delta^{2}}{4}\right) \cdot \left(\frac{5 \cdot \delta^{2}}{6} + \frac{4615}{28}\right) + \left(\frac{741805}{2268} - \frac{35 \cdot \delta^{2}}{9}\right) \cdot \left(\frac{\delta}{2} + \frac{1}{2}\right)^{2}\right) - 3 \cdot \chi_{2} \cdot \left(\left(\frac{1}{4} - \frac{\delta^{2}}{4}\right) \cdot \left(\frac{5 \cdot \delta^{2}}{6} + \frac{4615}{28}\right) + \left(\frac{1}{2} - \frac{\delta}{2}\right)^{2} \cdot \left(\frac{741805}{2268} - \frac{35 \cdot \delta^{2}}{9}\right)\right)\) |
Implementation mapping
Component traceability
The generated map records each new component and every unchanged inherited component version, with links to its evidence, reference expression, both frontends, and maintained checks. For a spin correction, a coefficient tuple position identifies the containing coefficient; the frontend does not expose each physical spin term as a separate return value. Tests compare selected combinations and their differences. The inherited base map remains authoritative for its original component definitions, including its reference-only paper gauge.
New components: taylorf2-aligned-bh-spin-3.5pn/v1.
Unchanged inherited components: taylorf2-nonspinning-3.5pn/v1.
Additional independent derivation:
| Component | Sources | Reference expression | Checks |
|---|---|---|---|
tf2.bhspin.SS7.v1 |
bohe2015, Eq. 3.33, 4.14; messina2017, Eq. 23, 26; buonanno2009-balance, Eq. 3.2, 3.3a, 3.3b, 3.14 | ss7_balance_terms |
S31 |
Check labels are local to this table; function names identify maintained tests.
Metadata tests resolve the links and detect stale tables. They establish structural coverage, not transcription correctness or numerical agreement.
Evidence and limitations
Numerical checks and limitations
The maintained FP64 checks compare both frontends with scalar reference
values at 80 decimal digits. They cover all coefficient tuple slots, selectors
0, 2, 3, 4, 5, 6, 7, 8, -1, the calibration exception, spin-degree isolation,
and public waveform profiles 5, 7, 8, -1 in both phase conventions. They also
check exact zero-spin reduction, body-label exchange, spin boundaries \(\pm1\),
and first mass/spin Jacobians at zero and nonzero spins. Frequency derivatives
compare Torch's analytic derivative and JAX autodiff with symbolic differentiation.
Unit conversion uses the separate SI/IAU constants audit.
A reproducible sweep (seed 20260923, 12 systems) draws total mass logarithmically
from \([2.7,100]M_\odot\), mass ratio logarithmically from \([1,20]\), component spins
from \([-0.95,0.95]\), distance logarithmically from \([10,2000]\) Mpc, inclination
from \([0,\pi]\), \(t_c\) from \([-0.1,0.1]\) seconds, and \(\phi_c\) from \([-\pi,\pi]\).
Both \(v\) and \(v_{\rm ref}\) lie in \([0.12,0.30]\). Fixed cases add equal masses,
asymmetric masses, aligned/opposed spins, and reference-frequency cancellation.
These are sampled engineering checks, not a calibrated validity region.
Forward checks require relative amplitude error at most \(5\times10^{-14}\), unwrapped phase agreement with relative tolerance \(5\times10^{-14}\) and absolute tolerance \(2\times10^{-10}\) radians, and polarization error \(|h-h_{\rm ref}|/A<3\times10^{-10}\). Mass/spin Jacobians normalize polarization rows by the reference amplitude and use relative and absolute tolerances \(2\times10^{-9}\). Frequency derivative tolerances are relative \(2\times10^{-13}\) and absolute \(2\times10^{-12}\). Coefficient and spin-degree checks have their own stricter intermediate tolerances in the maintained tests.
Shared one-dimensional frequency grids and explicit per-binary \((B,1)\) grids
with vector reference frequencies are checked in eager and compiled execution.
JAX JIT and Torch torch.compile(backend="aot_eager", fullgraph=True) are covered;
the latter checks Dynamo/AOT graph capture, not Inductor code generation. This
extension adds no FP32 spin qualification.
Committed reference fixtures are generated at 100 and 160 decimal digits, checked for precision convergence, and store 65 digits with inputs, sources, term selection, conventions, and derivatives. A separate near-reference test at \(f=f_{\rm ref}+10^{-22}\) Hz also compares 100 and 160 digits, requiring 65-digit agreement. This working precision accounts for the digits lost in phase subtraction and a nearly edge-on cross polarization. Increasing precision checks arithmetic stability; it cannot detect the same incorrect expression evaluated twice.
This qualification concerns the declared reference equations and sampled cases. It supplies neither a uniform floating-point error proof nor physical validation against numerical relativity. No new LAL comparison, Lean proof, or Mathematica cross-check is implied. Accelerator qualification is explicit and separate from the maintained CPU job.
Recorded CPU qualification
On 2026-09-22, the combined required gate passed all 408 tests with no skips, expected failures, or deselections: 222 aligned-spin numerical/symbolic checks, 68 aligned-spin traceability checks, and 118 inherited reference/gate checks. The environment was macOS arm64, Python 3.13.7, SymPy 1.14.0, mpmath 1.3.0, Torch 2.14.0, and JAX 0.11.2, with JAX x64 enabled and both frontends on CPU. Generated artifacts and both traceability maps were current; the four frozen nonspinning kernel/table/fixture/test files retained their pre-extension hashes. Related TaylorF2 and IMRPhenomD regressions passed 25 tests; one optional external comparison was skipped because LALSuite/PyCBC was unavailable. The strict docs build and Ruff checks passed. These results qualify the scope above, including the corrected optional SS7 term, without adding an external-reference claim.
Reproduce the checks
Reproduce and review changes
Install the reference and both frontends, then run the complete qualification gate so inherited and new coverage execute together:
python -m pip install -e '.[reference,torch,jax,dev]'
python -m diffgw_reference.artifacts --check
python -m diffgw_reference.aligned_spin_artifacts --check
python -m diffgw_reference.aligned_spin_traceability --check
JAX_ENABLE_X64=1 JAX_PLATFORMS=cpu python -m pytest \
tests/test_waveform_definitions.py tests/test_*math_reference*.py \
tests/test_nsbh_*reference.py tests/test_emri_*reference.py \
tests/test_xp_msa_remnant_boundary_policy.py \
tests/test_xphm_rotation_reference.py tests/test_xphm_nnlo_clean_room.py \
tests/test_spintaylor_reference_angle.py \
--require-math-reference --reference-device=cpu -ra
The required mode fails on missing dependencies, missing or deselected test modules, skips, expected failures, and unexecuted tests. The workflow's presence does not by itself make it a required merge check.
Change mathematical component versions when their numerical meaning changes;
give a composed specification a new version when its included terms or
conventions change. Keep explicit inherited versions and the baseline artifacts.
Changes to coverage or a qualified function name need no mathematical version
bump. Regenerate the component map with
python -m diffgw_reference.aligned_spin_traceability and review the resulting
diff alongside source evidence. Resolve disagreements against the publications
and documented conventions, without choosing formulas to fit backend outputs.