Higher-mode, eccentric, and tidal waveform family: research ledger

This family research ledger began at foundation 5bc907d. It follows the six-section specification template. TaylorF2_HM has a versioned leading-carrier specification, and TaylorF2_Eccentric has a versioned nonspinning amplitude-off slice. The remaining three rows remain provisional. The component IDs below are historical research identifiers, not registered catalog IDs.

Scope and status

Native approximant	Implemented mathematical scope	Research status
TaylorF2_HM	Frequency-domain, aligned-spin SPA inspiral, leading amplitudes for (2,2), (2,1), (3,1), (3,2), (3,3), (4,2), (4,3), (4,4)	Independent leading-carrier reference covers all eight modes; exact external eight-mode waveform comparison remains unavailable.
TaylorF2_Eccentric	Frequency-domain (2,2) quasi-circular TaylorF2 plus an order-e0² eccentric phase through relative 3PN; optional project amplitude factor	The nonspinning amplitude-off composition has an independent scalar reference and two strict LAL holdouts in Torch/JAX; spins and optional amplitude remain provisional.
IMRPhenomD_NRTidal	Frequency-domain aligned-spin (2,2) IMRPhenomD plus 2017 NRTidal phase and BNS merger taper	The nonspinning tidal-phase component passes independent scalar and pinned-binary quotient gates. The nonspinning merger/taper composition also has scoped scalar/Torch/JAX factor checks and premerger carrier agreement; nonzero-tide binary taper gates fail. Spins and broader whole-waveform qualification remain provisional.
IMRPhenomD_NRTidalv2	Same BBH carrier plus 2019 phase, historical default tidal amplitude, EOS-dependent self-spin, and merger taper	Nonspinning phase, amplitude/taper, spinning paper-D composition through taper, and the positive-22 projection have scoped independent references. The paper gate follows Eqs. (28)–(29) despite their Fig. 7 conflict; the historical default amplitude and high-frequency pinned-binary taper retain provenance and binary gaps. Spinning whole-waveform qualification remains pending.
IMRPhenomNSBH	Frequency-domain aligned-spin (2,2) PhenomD-like phase with NRTidalv2 term and a disruption-dependent PhenomC-like amplitude	Compactness/disruption-root, torus/ISCO, branch classification, branch amplitude factors, joining frequencies, conditional amplitude windows and sum, and explicit-gauge phase composition have scoped independent scalar gates. The joining-frequency gate is conditional: the low/no-torus \(\widetilde f_0\) has an extra native factor absent from Table I. The amplitude variant audit records Eq. (26)/(29) variants; the \(C^1\) smooth polynomial continuation \(g(\Lambda) = 1 + 0.5\Lambda - 0.25\Lambda^2\) (\(\Lambda \le 1\)) resolves the printed jump discontinuity at \(\Lambda=1\), and the \(+0.81248\omega^+\) plus window preserves the BBH limit, verified in tests/test_differentiable_solvers_and_nsbh.py. Remaining amplitude, legacy phase gauge, and whole waveform remain provisional.

Torch and JAX expose all five through their respective get_fd_waveform dispatchers. TaylorF2_HM and the narrow TaylorF2_Eccentric slice are registered in src/diffgw_core/waveform_definitions/catalog.py; the other three are not. The historical model_manifest.json statuses describe declared CPU FP64 waveform comparisons, not independently executable scalar expressions for the remaining provisional models or a parameter-domain certificate. This ledger's foundation audit did not rerun comparisons; the HM specification links its subsequent maintained checks.

Inputs, conventions, and options

All five native frontends accept gravitational-wave frequency grids in Hz (including a possible DC bin), component masses in solar masses, distance in Mpc, aligned dimensionless spins, inclination, orbital coalescence phase, and coalescence time. They return complex h_plus, h_cross; nonpositive-frequency bins are zeroed by the assembled models. The phase is placed in an exp(-i Ψ) factor. Existing TaylorF2 and IMRPhenomD documents define the carrier conventions: TaylorF2 and IMRPhenomD. The exact sign of a composed mode and projection must be included in each eventual standalone spec.

Model	Additional native inputs/defaults and convention requiring a reference case
HM	modes defaults to all eight; return_modes returns per-mode polarizations; phi0=0; f_isco_cutoff=True, Schwarzschild or Kerr isco_type, optional smooth rolloff of width roll_off_delta=0.1; spin_order=7; f_ref, lambda1/2 pass through to TaylorF2. Frequency and cutoff for mode m are rescaled by m/2.
Eccentric	e0/eccentricity aliases (manifest quotes [0,0.4)); f0_ecc takes precedence over f_lower, then positive f_ref, then the lowest positive grid sample (20 Hz if none). Eccentricity is defined at that frequency; an explicitly supplied positive f_ref independently anchors the waveform phase, including the eccentric correction. ecc_order=6 means 3PN phase, not order e0^6; include_amplitude_correction=False. Spin aliases and phasing_convention/reference_frame are forwarded to TaylorF2.
NRTidal v1/v2	lambda1/2 default to zero; apply_merger_taper=True applies a Planck window from f_merger to 1.2 f_merger. f_ref, phasing_convention, and reference_frame pass to PhenomD. For v2 reference-frequency phasing, the native code subtracts the 2PN+3PN self-spin term at f_ref but retains the 3.5PN term. This is a carrier choice needing its own comparison.
NSBH	mass1 is BH, mass2 is NS, lambda2 is the NS deformability; source calibration assumes negligible NS spin. Paper scope is 1≤q≤15, |chi_BH|≤0.5, 0≤Lambda_NS≤5000 (Thompson et al., abstract), narrower than some accepted native inputs. f_ref defaults to 30 Hz; explicit zero selects the lowest positive sample. Default/legacy phase has inherited affine offsets, including an upper-grid-frequency anchor unless f_final/fhigh is supplied. Explicit coalescence or reference_frequency selects the PhenomD phase gauge.

The HM and eccentric models are inspiral-only approximants with cutoff adapters; the NSBH and NRTidal models inherit calibrated IMR carrier data. There is no separately packaged training asset for this family; fit decimals are embedded in the cited Python modules. Those decimal rows and all branch boundaries require versioned provenance in canonical specs. This ledger has not established derivative behavior at the hard HM cutoff, NSBH classification boundaries, or a failed NSBH disruption-root iteration.

Mathematics and components

Let B_TF2 and B_D denote the existing TaylorF2 and IMRPhenomD carriers, x=(πMf)^(2/3), η=m1 m2/M², and κ_eff=(3/16) Λ̃. The native compositions are:

• HM: h_{l,-m}(f) = sqrt(16π/5) A_TF2(f) R_lm(f) exp[-i{(m/2) Ψ_TF2(2f/m) + 3π(1-m/2)/4}], followed by the implemented spin-weighted-harmonic projection and per-mode cutoff.
• Eccentric: Ψ = Ψ_TF2 + ΔΨ_ecc(f;f0) - ΔΨ_ecc(f_ref;f0), with ΔΨ_ecc = -(2355/1462)[3/(128ηv⁵)] e0²(v0/v)^(19/3) P_3PN(v,v0,η). The optional amplitude multiplier is 1-(743/9216)e0²(f/f0)^(-19/9); its source attribution is unresolved here.
• NRTidal v1/v2: h = B_D exp(-i Ψ_T) W_merger for v1, with Ψ_T=-κ_eff[39/(16η)]x^(5/2)P_v1(x). V2 replaces P_v1 by P_v2, adds 2PN/3PN/3.5PN EOS self-spin phasing, and applies an additive tidal amplitude before the window. The native v2 implementation converts that face-on amplitude into a common polarization multiplier.
• NSBH: A_NSBH = A_PN W_ins + A_PM W_pm + A_RD W_rd with branch-dependent joins; Ψ_NSBH = Ψ_PhD + Ψ_NRTidalv2. Native synthesis applies the quadrupolar inclination factors and its chosen affine phase gauge.

pending means that a paper-literal independent scalar expression and its specified conventions are still needed. conditional means a reusable reference exists but additional source or carrier inputs must be qualified. diagnostic denotes a check, never production mathematics. Native functions in the table already execute; status here describes the library reference work, not native availability or verification.

Research component ID/version	Pinned source and variant	Status	Independent scalar / native mapping and blocker
hm.mode-phase/v0	García-Quirós et al. 2020, Eqs. (4.8)–(4.10), inspiral harmonic rescaling; Mezzasoma & Yunes 2022, Eqs. (2.24)–(2.30), SPA phase and offset	superseded in scope	The v1 carrier checks aligned-spin phase and both phase origins for all eight modes. Tidal terms remain outside that HM slice.
hm.leading-amplitudes/v0	Kidder 2008, García-Quirós 2020, Mezzasoma & Yunes 2022, Eqs. (2.20)–(2.21i), especially (4,2) Eq. (2.21g); leading PN only	superseded in scope	The v1 carrier derives all eight leading ratios and compares complex projected modes with Torch/JAX. Higher-PN and spin-amplitude terms remain outside scope.
hm.projection-cutoff/v0	García-Quirós Eqs. (2.1)–(2.12) for mode and polarization conventions; project harmonic ISCO adapter	superseded in scope	The v1 carrier checks negative-m projection, azimuth derivatives, and Schwarzschild hard-cutoff thresholds; Kerr and smooth cutoff options remain unchecked.
ecc.phase-3pn-e2/v1	Moore et al. 2016, Eq. (6.26), TaylorF2 SPA phase at order e0²	scoped executable	Independent SymPy rational polynomial and 80-digit scalar evaluation check all six native truncations in Torch/JAX CPU float64; distinct f_ref subtraction is the separately specified project gauge. See component specification.
ecc.amplitude-adapter/v0	Moore et al. Sec. VI.E uses 0PN amplitude at order e0⁰; native 743/9216 factor is a project option	pending	Torch/JAX eccentric_amplitude_factor; identify a primary derivation or mark explicitly project-only; default is off.
nrt1.phase-pade/v0	Dietrich, Bernuzzi & Tichy 2017, Eq. (7), 2017 rational phase	superseded in scope	The versioned nonspinning phase independently evaluates the printed Padé relation and the carrier-rounded coefficient, with scoped Torch/JAX and pinned-binary quotient checks. Spins and the whole waveform remain outside that component gate.
nrt2.phase-pade/v0	Dietrich et al. 2019, Eqs. (17)–(21), frequency-domain phase, constrained coefficients	superseded in scope	The versioned nonspinning phase checks the published Padé form and Torch/JAX below merger; the NSBH composition and self-spin remain outside that gate.
nrt2.tidal-amplitude/v0	Dietrich 2019, Eqs. (23)–(25), fitted d=13477.8	superseded in scope	The Eq. (24) amplitude component is independently checked, but Table II excludes it from the paper's D option. The historical default's extra 1/2 normalization remains without paper provenance; see the audit.
nrt2.self-spin-eos/v1	Dietrich 2019, Eqs. (26)–(29), Table II	conditional	Printed-equation D spec, scalar reference, Torch/JAX gates and receipt cover positive-Lambda 2PN+3PN. Fig. 7 conflicts with Eqs. (28)–(29); the historical fit, Lambda clamps, anchoring and spinning binary gate are separate.
nrt2.paper-d-composition/v1	Dietrich 2019, Eqs. (17)–(21), (25)–(29), Table II; Dietrich 2018, Eq. (11)	conditional	Spinning complex-composition gate and receipt join the independent phase, self-spin and taper references through the merger boundary for Torch/JAX. Paper Fig. 7 and pinned-LAL amplitude/merger conflicts prevent a stronger binary or physical claim.
nrt.merger-taper/v0	Dietrich et al. 2018, Eq. (11) BNS frequency; McKechan et al. 2010 taper; published 1.2 f_merger endpoint	superseded in scope	The scalar taper component and v1 nonspinning composition check printed equations and backend behavior. Nonzero-tide high-frequency binary quotients exceed their frozen gates; source audit narrows the unresolved boundary.
nsbh.compactness-disruption/v0	Thompson et al. 2020, Appendix A Eqs. (8)–(10), Appendix B Eq. (32)	superseded in scope	The v1 independent scalar gate checks Eq. (32) and Eqs. (8)–(10), including largest-positive-root selection and normalized residuals, on a frozen grid. Branch use and whole-waveform behavior remain pending.
nsbh.torus-isco/v1	Thompson et al. 2020, Appendix A Eqs. (11)–(12)	scoped executable	The independent scalar gate checks the raw baryonic torus fit, the Kerr ISCO radius, and the native nonnegative clip on 105 frozen cases in Torch/JAX CPU FP64. This does not qualify merger-classification branches or waveform composition.
nsbh.branch-classification/v1	Thompson et al. 2020, Table I and Sec. II.A step 6	scoped executable	The independent scalar gate checks all four classes and exact/adjacent FP64 boundaries through the production predicates in Torch/JAX. The remnant-derived ringdown input and downstream amplitude functions are separate gates.
nsbh.branch-amplitude-fits/v1	Thompson et al. 2020, Appendix A Eqs. (20)–(24), (30), Table I	scoped executable	The scalar gate checks the adjusted ringdown frequency, four fit coordinates and three class-dependent factors on 210 controlled/composed cases against the native production helper. Joining frequencies, Eq. (26)/(29) corrections and assembled amplitude remain separate.
nsbh.joining-frequencies/v1	Thompson et al. 2020, Table I	conditional	The paper-literal scalar gate checks all printed joins. Three native branch rows agree in Torch/JAX; the low/no-torus \(\widetilde f_0\) applies an additional carrier factor and remains unqualified. Low-branch \(\widetilde f_2\) is a paper dash. The remnant/QNM input is supplied.
nsbh.amplitude-variants/v1	Thompson et al. 2020 v2, Table I and Eqs. (26), (29); Pannarale et al. 2015, Eqs. (20), (26)	scoped regularized	The frozen provenance diagnostic distinguishes printed and native-compatible variants. The project-correction \(C^1\) smooth continuation \(g(\Lambda) = 1 + 0.5\Lambda - 0.25\Lambda^2\) (\(\Lambda \le 1\)) resolves the printed Eq. (26) jump at \(\Lambda=1\), and the \(+0.81248\omega^+\) plus window preserves the non-disruptive BBH limit, verified in tests/test_differentiable_solvers_and_nsbh.py. Full amplitude assembly and paper-literal options remain separate.
nsbh.amplitude.window-sum/v1	Thompson et al. 2020 v2, Eqs. (4), (30); Pannarale et al. 2015, Eq. (13)	conditional	The independent scalar gate checks the production-called Torch/JAX three-window sum with supplied positive centers, width, mass, and carriers, including selected derivatives and pre-refactor public amplitude samples; see the receipt. Upstream amplitude fits and full composition remain unqualified.
nsbh.qnm.london-220/v1	London and Fauchon-Jones 2019, Eq. (22); Thompson 2020, Appendix A Eqs. (16)–(19)	scoped executable	The paper-coefficient scalar gate checks native Torch/JAX london_ringdown_properties frequency and quality factor at 18 supplied remnant states; see the receipt. The final mass and spin provider is separate.
nsbh.remnant.rounding_interval/v1	Zappa et al. 2019, Supplementary Table I and Eqs. (4)–(6); Jiménez-Forteza et al. 2017, Eqs. (7)–(28), Tables 1–4 and 7–10	scoped executable	The source-defined rounding-interval gate and len receipt check printed coefficient consistency and final mass/spin from the native BBH and NSBH remnant providers on five guard-inactive calibrated cases in Torch/JAX. Extrapolation guards, NR accuracy, inherited extra coefficient provenance and whole-waveform assembly remain separate.
nsbh.remnant.guards/v0	Zappa et al. 2019, Supplementary §I; Jiménez-Forteza et al. 2017, Eq. (20)	blocked	The source-boundary audit identifies native factor clipping and fallback predicates absent from the published prescription. Printed-coefficient intervals show factors above one with physical total remnant quantities. No scalar/native paper-alignment gate is claimed.
nsbh.remnant/v0	Zappa et al. 2019 and Jiménez-Forteza et al. 2017	superseded in scope	The rounded-coefficient v1 interval gate above qualifies a selected component domain; it does not recover the unprinted coefficients or qualify extrapolation guards.
nsbh.amplitude-branches/v0	Pannarale et al. 2015 and Thompson Eq. (4), Table I, Appendix A Eqs. (20)–(30)	superseded in scope	The v1 branch-factor gate covers Eq. (20)–(24), (30) and three Table I factors. The conditional joining-frequency gate isolates one native/paper mismatch. The window-and-sum gate checks Eq. (4)/(30) given supplied inputs. The variant audit records why Eq. (26)/(29) and full assembly remain blocked.
nsbh.phase.explicit-composition.v1	Thompson Sec. II.2 PhenomD + NRTidalv2 phase; Khan 2016; Dietrich 2019 Eqs. (17)–(21)	conditional	The frozen scalar gate and receipt compose independent PhenomD and NRTidalv2 references and check the Torch/JAX NSBH unit phase in both explicit gauges. Remnant/QNM inputs and extra PhenomD fit digits are supplied; the default legacy affine gauge and amplitude are outside this gate.
nsbh.phase-gauge/v0	Thompson Sec. II.B PhenomD + NRTidalv2 phase; project legacy affine gauge	superseded in scope	The explicit-gauge composition has a v1 gate above. Default grid-dependent legacy offsets and remnant-provider provenance remain separate.
family.historical-comparison/v0	Frozen manifest/provenance-ledger LAL comparisons, declared samples only	diagnostic	No production reference component; case IDs and recorded metrics in docs/model_manifest.json. Rerun only after an independent component reference is ready.

Implementation mapping

The table names the native entry points. The independent diffgw_reference.taylorf2_hm module covers the declared leading HM carrier; diffgw_reference.taylorf2_eccentric composes the bounded nonspinning amplitude-off eccentric slice. No complete scalar reference exists yet for the remaining three models. Existing scalar TaylorF2 nonspinning, aligned-spin, tidal, spin-quadrupole and IMRPhenomD amplitude/phase/remnant/intrinsic modules can be reused as qualified carrier components, but they cannot be treated as references for the remaining added terms. Native Torch/JAX evaluators do not call these scalar modules.

Family	Torch location	JAX location	Carrier/reference reuse and specific divergence to resolve
HM	src/torchwave/approximants/taylorf2_hm.py (_swsh_projection_coefficients, TaylorF2_HM.forward)	src/jaxwave/approximants/taylorf2_hm.py (same projection, evaluate)	TaylorF2.evaluate_phase/amplitude; stored h_{l,-m} and harmonic-specific cutoff are project composition choices. (4,1) and (5,5) remain absent because TD amplitudes alone do not fix native SPA/projection conventions.
Eccentric	src/torchwave/approximants/taylorf2_eccentric.py (eccentric_phase_correction, eccentric_amplitude_factor, forward)	src/jaxwave/approximants/taylorf2_eccentric.py (same components, evaluate)	TaylorF2 carrier and options reused. The native f0 fallback samples the positive frequency grid; the phase is anchored at a distinct positive explicit f_ref, or at f0 when no positive f_ref is supplied.
NRTidal v1/v2	src/torchwave/approximants/imrphenomd_nrtidal.py	src/jaxwave/approximants/imrphenomd_nrtidal.py	IMRPhenomD carrier reused. Shared published coefficient values in src/diffgw_core/nrtidal_fits.py; Torch reexports them through nrtidal_published_fits.py. V1 has phase only, v2 also amplitude and self-spin.
NSBH	src/torchwave/approximants/imrphenom_nsbh.py, nsbh_clean_phase.py, nsbh_clean_amplitude.py, nsbh_phase_baseline.py	src/jaxwave/approximants/imrphenom_nsbh.py, nsbh_phase_baseline.py	Uses PhenomD phase structure but a distinct PhenomC-like amplitude; do not reuse PhenomD amplitude. JAX embeds the NRTidalv2 expression and local amplitude helpers; Torch separates them. Default affine gauge is an inherited compatibility adapter, not a published Thompson equation.

The source audit corrected the manifest, provenance ledger, and native headers: the eccentric SPA phase points to Moore et al. Eq. (6.26), the NSBH amplitude model to Pannarale et al., PRD 92, 084050, and the HM model to Mezzasoma & Yunes, arXiv:2203.15934. The optional eccentric amplitude factor remains a project option without an established primary derivation. These source mappings do not establish coefficient-level or waveform-level equivalence.

Evidence and limitations

The foundation source inspection recorded model composition and paper locations; by itself it does not confirm coefficient-by-coefficient equivalence. The later HM leading-carrier reference adds an executable eight-mode comparison within its declared scope. docs/model_manifest.json records one dominant-only HM LAL diagnostic; two historical eccentric catalog cases plus two separately frozen nonspinning eccentric holdouts; and one catalog plus one holdout for each tidal/NSBH model. The latter declared cases passed their historical CPU FP64 gates, but the suite did not establish independent scalar reference behavior, full domain accuracy, or physical validity. The HM (2,2) external diagnostic says nothing about the seven additional modes; the scalar eight-mode checks are a different kind of evidence. The NSBH 22-case expansion cited by the manifest remains external-comparison evidence, and its inherited PhenomD/remnant calibration provenance remains open.

Remaining independent-reference blockers are concrete: (1) HM tidal terms, Kerr and smooth cutoff options, and an exact same-model external eight-mode waveform comparison; (2) eccentric aligned-spin cross terms and provenance for the optional amplitude factor beyond the scoped nonspinning amplitude-off version; (3) tidal scope beyond the v1 nonspinning phase/taper and v2 printed-equation spinning D composition, including independent whole-carrier composition, historical D-amplitude normalization, and the high-frequency binary taper discrepancy; (4) NSBH low/no-torus joining-factor provenance, Eq. (26)/(29) variants, supplementary remnant coefficients, upstream amplitude carriers and full composition, and intrinsic/affine phase split. The published validity regions must be separated from permissive native input acceptance. This ledger makes no whole-model verification claim.

To promote the remaining models, create three docs/math/<model>.md pages, each with these same six headings, exact option/front-end inventory, composition equation, links to versioned component pages, and distinct source, independent-reference, backend, external-comparison and physics evidence. Implement paper-literal scalar components under diffgw_reference, then compose complete scalar polarizations with fixed conventions. Test those components separately from native Torch/JAX, add representative holdouts and branch-boundary/derivative cases, reconcile source pins and carrier precision, and only then consider their catalog entries, generated tables and qualification.

Reproduce the checks

This page's static scope can be checked without LAL or waveform fixtures:

python -m json.tool docs/model_manifest.json >/dev/null
git diff --check
rg 'TaylorF2_HM|TaylorF2_Eccentric|IMRPhenomD_NRTidal|IMRPhenomNSBH' \
  src/torchwave/waveforms.py src/jaxwave/waveforms.py

Maintained native checks, when the relevant Torch/JAX dependencies are installed, include pytest -q tests/test_taylorf2_hm_math_reference.py tests/test_taylorf2_hm.py tests/test_taylorf2_hm_mode_inventory.py tests/test_eccentric.py tests/parity/test_eccentric_parity.py tests/test_nrtidal.py tests/test_nrtidal_reconstruction.py tests/test_clean_room_nsbh.py tests/test_nsbh_phase_mass_regression.py. The LAL-dependent test in test_nrtidal.py may skip when LAL is absent; such a skip conveys no independent-reference evidence. Refresh any frozen external fixtures only through their separate provenance workflow. An equation, coefficient, branch, phase convention, or asset change requires a new component version, its source pin and tests, plus review of the generated model documentation once catalog registration is justified.