sage.data.waveform.approximants.IMRPhenomXAS_NRTidalv3

Filename : IMRPhenomXAS_NRTidalv3.py Description : GPU-native batched IMRPhenomXAS_NRTidalv3 aligned-spin BNS/NSBH

frequency-domain waveform model.

Implements the NRTidalv3 tidal corrections on top of the IMRPhenomXAS BBH backbone (García-Quirós et al. 2020, arXiv:2001.10914), following Abac et al. 2023 (arXiv:2311.07456) and the LALSim C reference implementation in LALSimNRTunedTides.c and LALSimIMRPhenomX_internals.c.

Tidal contributions:

• NRTidalv3 tidal phase (per-star Padé approximant with dynamic effective Love number, Eqs. 27-33 of 2311.07456)

• Smooth post-merger transition to 7.5PN tidal phase (Planck taper in [1.15, 1.35] × f_merger, Eq. 45)

• Minimum-clamping of tidal phase after merger

• NRTidalv2 tidal amplitude correction (Eq. 24 of arXiv:1905.06011, same formula reused in NRTidalv3)

• Planck-window tapering of amplitude at/beyond f_merger

Spin-induced quadrupole/octupole moment (SIQM) tidal PN terms at 2PN, 3PN, and 3.5PN order in the tidal phase, following LALSimIMRPhenomX_internals.c IMRPhenomXGetTidalPhaseCoefficients and IMRPhenomX_TidalPhase (lines 2893-3085). Quadrupole parameters are derived from lambda via the universal relation XLALSimInspiralEOSQfromLambda (LALSimInspiralEOS.c line 104), octupole parameters from XLALSimUniversalRelationSpinInduced- OctupoleVSSpinInducedQuadrupole (LALSimUniversalRelations.c).

0 : m1 (solar masses, m1 >= m2) 1 : m2 (solar masses) 2 : chi1z (dimensionless aligned spin, body 1) 3 : chi2z (dimensionless aligned spin, body 2) 4 : distance (Mpc) 5 : tc (s, time of coalescence) 6 : phic (rad, reference orbital phase) 7 : inclination (rad) 8 : lambda1 (dimensionless tidal deformability Lambda_1 >= 0) 9 : lambda2 (dimensionless tidal deformability Lambda_2 >= 0)

Created on 2026-05-28

__author__ = Narenraju Nagarajan __copyright__ = Copyright 2026, Sage __license__ = MIT Licence __version__ = 0.0.1 __maintainer__ = Narenraju Nagarajan __email__ = N/A __status__ = inProgress

References

NRTidalv3 : Abac et al. (2023), arXiv:2311.07456 Merger freq fit: Gonzalez et al. (2022), arXiv:2210.16366 7.5PN tidal : Vines et al. (2011); Henry et al. (2020) kappa2T : Dietrich et al. (2017), arXiv:1706.02969 NRTidalv2 amp : Dietrich et al. (2019), arXiv:1905.06011 BBH backbone : Garcia-Quiros et al. (2020), arXiv:2001.10914

Classes

IMRPhenomXAS_NRTidalv3

GPU-native batched IMRPhenomXAS with NRTidalv3 tidal corrections.

Module Contents

class IMRPhenomXAS_NRTidalv3(param_sampler=None, waveform_project=None, augment=None, multiband_mode='none', m1_worst=None, m2_worst=None)

Bases: sage.data.waveform.approximants.IMRPhenomXAS.IMRPhenomXAS, torch.nn.Module

GPU-native batched IMRPhenomXAS with NRTidalv3 tidal corrections.

Inherits the full BBH backbone (amplitude, three-region phase, QNM tables, connection coefficients, time-alignment fit) from IMRPhenomXAS and adds per-star NRTidalv3 tidal phase/amplitude on top.

When constructed with a param_sampler this class also acts as a signal-sampler torch.nn.Module (same pattern as IMRPhenomPv2). Call forward() to obtain a batch of detector-frame strain tensors and normalised parameter targets ready for network training.

Parameters (waveform math only)

ftorch.Tensor, shape (B, F)

Frequency grid in Hz.

f_reftorch.Tensor, shape (B, 1)

Reference frequency in Hz.

Parameters (signal-sampler mode)

param_samplerDistributionSampler or None

BNS parameter sampler built from runs/bns/gwconfig.yaml. When None the instance can still be used as pure waveform math.

waveform_projectConstantProjection or None

Multi-detector projection module.

augmentcallable or None

Optional SNR-rescaling augmentation.

param param_sampler:

type param_sampler:

DistributionSampler or None

param waveform_project:

type waveform_project:

ConstantProjection or None

param augment:

type augment:

callable or None

param multiband_mode:

‘none’ — full uniform FD grid, behaviour unchanged (default). ‘worst_case’ — waveforms generated directly at the worst-case

coarse grid; self.selector is available for noise.

‘per_signal’ — per-signal LAL grid (not yet implemented).

type multiband_mode:

str

param m1_worst:

Component masses (M_sun) used to build the worst-case grid. When both are None (default) the worst-case pair is found automatically by scanning param_sampler.bounds at startup — no hardcoded values. Provide explicit masses only to skip the scan (e.g. for reproducibility in tests). Only used when multiband_mode=’worst_case’.

type m1_worst:

float or None

param m2_worst:

Component masses (M_sun) used to build the worst-case grid. When both are None (default) the worst-case pair is found automatically by scanning param_sampler.bounds at startup — no hardcoded values. Provide explicit masses only to skip the scan (e.g. for reproducibility in tests). Only used when multiband_mode=’worst_case’.

type m2_worst:

float or None

GRAPH_READY = True

MULTIBAND_NONE = 'none'

MULTIBAND_WORST_CASE = 'worst_case'

MULTIBAND_PER_SIGNAL = 'per_signal'

property output_state: sage.core.pipeline.ProcessingState

Processing state of the waveform batch returned by forward().

Used by SageVanillaTraining to automatically configure GWBatch tracking and noise multibanding.

Returns:

Grid.FD_COARSE when multiband_mode='worst_case'; Grid.FD_UNIFORM otherwise.

Return type:

ProcessingState

WAVEFORM_PARAM_NAMES = ['mass1', 'mass2', 'chi1z', 'chi2z', 'distance', 'tc', 'coa_phase', 'inclination', 'lambda1',...

cfg = None

data_cfg = None

multiband_mode = 'none'

selector = None

signal_batch_size

f_ref

B

hp_buffer

hc_buffer

param_sampler = None

waveform_project = None

augment = None

forward(return_theta=False)

Sample a batch of BNS waveforms and return detector-frame strain.

Returns:

• hf (torch.Tensor, shape (B, D, F)) – Detector-frame strain for each detector.

• targets (torch.Tensor, shape (B, n_params + 1)) – Standardised parameter targets with a trailing signal-label column of ones.

• all_theta (torch.Tensor, shape (B, total_params)) – Full raw parameter batch (only when return_theta=True).

apply_tc(hp, hc, tc)

Apply tc phase shift using the analysis-window convention.

tc is measured from the START of the analysis window (same convention as IMRPhenomPv2). Adding padding_length_in_s converts it to the padded-segment frame before computing the FD phase ramp, so gwconfig tc values are directly interpretable as “seconds into the analysis window.”

get_hphc(theta, reproduce_lal=False)

Compute FD plus and cross polarisations for a BNS parameter batch.

Parameters:

• theta (torch.Tensor, shape (B, 10+)) –

  Columns: [m1, m2, chi1z, chi2z, distance, tc, phic,

  inclination, lambda1, lambda2]

  Masses in solar masses, distance in Mpc, angles in radians, tidal deformabilities dimensionless (>= 0).

• reproduce_lal (bool) – If True, skip FD tapering, tc shift, and df normalisation so the output can be compared directly with raw LALSim output.

Returns:

hp, hc

Return type:

torch.Tensor, shape (B, n_pad + F), complex128