API Reference

Waveform Generation

Waveform

IMRPhenomTHM interface class for waveform generation.

class phentax.waveform.IMRPhenomTHM(higher_modes='all', include_negative_modes=True, coarse_grain=False, t_low_fit=True, atol=1e-12, rtol=1e-12, T=None)

Bases: object

Class for generating multi-polar, aligned-spin IMRPhenomTHM waveforms.

Parameters:

• higher_modes (Optional[Array | list | str], default "all") – Higher modes to include beyond (2,2). Can be: - None: only (2,2) mode. - “all”: include all allowed higher modes. - list or Array of integers: specific modes to include (e.g., [21, 33]). Only the positive m modes have to be specified.

• include_negative_modes (bool, default True) – Whether to include negative m modes by symmetry.

• coarse_grain (bool, default False) – Whether to use adaptive coarse-graining for time grid generation.

• t_low_fit (bool, default True) – Whether to use the default fit for t_low in t(f).

• atol (float, default 1e-12) – Absolute tolerance for the t(f) root finding.

• rtol (float, default 1e-12) – Relative tolerance for the t(f) root finding.

• T (float | None, default None) – Total observation time in seconds. If None, it will be set to 3 months.

combine_amp_phase(amplitudes, phases)

Combine amplitude and phase into complex strain \(h = A * e^{-i \phi}\).

Parameters:

• amplitudes (Array) – Amplitude arrays for all modes, shape (Nmodes, Ntimes).

• phases (Array) – Phase arrays for all modes, shape (Nmodes, Ntimes).

Returns:

h_modes – Complex strain arrays for all modes, shape (Nmodes, Ntimes).

Return type:

Array

compute_amp_phase(m1, m2, chi1z, chi2z, distance, phi_ref, f_ref, f_min, inclination, psi, delta_t=15.0, t_min=nan, t_ref=nan, T=None)

Generate amplitude and phase for all modes for a batch of binaries or a single input.

Parameters:

• m1 (float | Array) – Mass of the first black hole in solar masses.

• m2 (float | Array) – Mass of the second black hole in solar masses.

• chi1z (float | Array) – Dimensionless spin of the first black hole along the orbital angular momentum.

• chi2z (float | Array) – Dimensionless spin of the second black hole along the orbital angular momentum.

• distance (float | Array) – Luminosity distance to the binary in megaparsecs.

• phi_ref (float | Array) – Reference phase at frequency f_ref in radians.

• f_ref (float | Array) – Reference frequency in Hz.

• f_min (float | Array) – Minimum frequency in Hz.

• inclination (float) – Inclination angle of the binary in radians.

• psi (float | Array) – Polarization angle in radians.

• delta_t (float, default 15.0) – Time step for waveform generation in seconds.

• t_min (float, default jnp.nan) – Minimum time for waveform generation in seconds. If NaN, will be set by the minimum frequency.

• t_ref (float, default jnp.nan) – Reference time for waveform generation in seconds. If NaN, will be set by the reference frequency.

• T (float | None, default None) – Total observation time in seconds. If set, it overrides the default value.

Return type:

tuple[WaveformParams, Array, Array, Array, Array]

Returns:

• wf_params (WaveformParams) – Waveform parameters of the binary.

• times (Array) – Time array in seconds.

• mask (Array) – Boolean mask indicating valid time points.

• amplitudes (Array) – Amplitude arrays for all modes, shape (Nbinaries, Nmodes, Ntimes).

• phases (Array) – Phase arrays for all modes, shape (Nbinaries, Nmodes, Ntimes).

compute_hlms(m1, m2, chi1z, chi2z, distance, phi_ref, f_ref, f_min, inclination, psi, delta_t=15.0, t_min=nan, t_ref=nan, T=None)

Generate complex strain \(h_{lm}\) for all modes for a batch of binaries or a single input.

Parameters:

• m1 (float | Array) – Mass of the first black hole in solar masses.

• m2 (float | Array) – Mass of the second black hole in solar masses.

• chi1z (float | Array) – Dimensionless spin of the first black hole along the orbital angular momentum.

• chi2z (float | Array) – Dimensionless spin of the second black hole along the orbital angular momentum.

• distance (float | Array) – Luminosity distance to the binary in megaparsecs.

• phi_ref (float | Array) – Reference phase at frequency f_ref in radians.

• f_ref (float | Array) – Reference frequency in Hz.

• f_min (float | Array) – Minimum frequency in Hz.

• inclination (float) – Inclination angle of the binary in radians.

• psi (float | Array) – Polarization angle in radians.

• delta_t (float, default 15.0) – Time step for waveform generation in seconds.

• t_min (float, default jnp.nan) – Minimum time for waveform generation in seconds. If NaN, will be set by the minimum frequency.

• t_ref (float, default jnp.nan) – Reference time for waveform generation in seconds. If NaN, will be set by the reference frequency.

• T (float | None, default None) – Total observation time in seconds. If sets, it overrides the default value.

Return type:

tuple[Array, Array, Array]

Returns:

• times (Array) – Time array in seconds.

• mask (Array) – Boolean mask indicating valid time points.

• h_lms (Array) – Complex strain arrays for all modes, shape (Nbinaries, Nmodes, Ntimes).

compute_polarizations(m1, m2, chi1z, chi2z, distance, phi_ref, f_ref, f_min, inclination, psi, delta_t=15.0, t_min=nan, t_ref=nan, T=None)

Generate plus and cross polarizations from the computed modes.

Parameters:

• m1 (float | Array) – Mass of the first black hole in solar masses.

• m2 (float | Array) – Mass of the second black hole in solar masses.

• chi1z (float | Array) – Dimensionless spin of the first black hole along the orbital angular momentum.

• chi2z (float | Array) – Dimensionless spin of the second black hole along the orbital angular momentum.

• distance (float | Array) – Luminosity distance to the binary in megaparsecs.

• phi_ref (float | Array) – Reference phase at frequency f_ref in radians.

• f_ref (float | Array) – Reference frequency in Hz.

• f_min (float | Array) – Minimum frequency in Hz.

• inclination (float) – Inclination angle of the binary in radians.

• psi (float | Array) – Polarization angle in radians.

• delta_t (float, default 15.0) – Time step for waveform generation in seconds.

• t_min (float, default jnp.nan) – Minimum time for waveform generation in seconds. If NaN, will be set by the minimum frequency.

• t_ref (float, default jnp.nan) – Reference time for waveform generation in seconds. If NaN, will be set by the reference frequency.

• T (float | None, default None) – Total observation time in seconds. If sets, it overrides the default value.

Return type:

tuple[Array, Array, Array, Array]

Returns:

• times (Array) – Time array in seconds.

• mask (Array) – Boolean mask indicating valid time points.

• h_plus (Array) – Plus polarization strain.

• h_cross (Array) – Cross polarization strain.

compute_polarizations_at_once(m1, m2, chi1z, chi2z, distance, phi_ref, f_ref, f_min, inclination, psi, delta_t=15.0, t_min=nan, t_ref=nan, T=None)

Generate plus and cross polarizations, but computing the \(h_{lm}\) individually for each mode to save memory.

Parameters:

• m1 (float | Array) – Mass of the first black hole in solar masses.

• m2 (float | Array) – Mass of the second black hole in solar masses.

• chi1z (float | Array) – Dimensionless spin of the first black hole along the orbital angular momentum.

• chi2z (float | Array) – Dimensionless spin of the second black hole along the orbital angular momentum.

• distance (float | Array) – Luminosity distance to the binary in megaparsecs.

• phi_ref (float | Array) – Reference phase at frequency f_ref in radians.

• f_ref (float | Array) – Reference frequency in Hz.

• f_min (float | Array) – Minimum frequency in Hz.

• inclination (float) – Inclination angle of the binary in radians.

• psi (float | Array) – Polarization angle in radians.

• delta_t (float, default 15.0) – Time step for waveform generation in seconds.

• t_min (float, default jnp.nan) – Minimum time for waveform generation in seconds. If NaN, will be set by the minimum frequency.

• t_ref (float, default jnp.nan) – Reference time for waveform generation in seconds. If NaN, will be set by the reference frequency.

• T (float | None, default None) – Total observation time in seconds. If set, it overrides the default value.

Return type:

tuple[Array, Array, Array, Array]

Returns:

• times_out (Array) – Time array in seconds.

• mask_out (Array) – Boolean mask indicating valid time points.

• h_plus_out (Array) – Plus polarization strain.

• h_cross_out (Array) – Cross polarization strain.

compute_strain_components(m1, m2, chi1z, chi2z, distance, phi_ref, f_ref, f_min, inclination, psi, delta_t=15.0, t_min=nan, t_ref=nan, T=None)

Generate complex strain \(h_{lm}\) for all modes and then multiply them by the corresponding spin-weighted spherical harmonics to get the contribution to the strain from each mode.

Parameters:

• m1 (float | Array) – Mass of the first black hole in solar masses.

• m2 (float | Array) – Mass of the second black hole in solar masses.

• chi1z (float | Array) – Dimensionless spin of the first black hole along the orbital angular momentum.

• chi2z (float | Array) – Dimensionless spin of the second black hole along the orbital angular momentum.

• distance (float | Array) – Luminosity distance to the binary in megaparsecs.

• phi_ref (float | Array) – Reference phase at frequency f_ref in radians.

• f_ref (float | Array) – Reference frequency in Hz.

• f_min (float | Array) – Minimum frequency in Hz.

• inclination (float) – Inclination angle of the binary in radians.

• psi (float | Array) – Polarization angle in radians.

• delta_t (float, default 15.0) – Time step for waveform generation in seconds.

• t_min (float, default jnp.nan) – Minimum time for waveform generation in seconds. If NaN, will be set by the minimum frequency.

• t_ref (float, default jnp.nan) – Reference time for waveform generation in seconds. If NaN, will be set by the reference frequency.

• T (float | None, default None) – Total observation time in seconds. If sets, it overrides the default value.

Return type:

tuple[Array, Array, Array]

Returns:

• times (Array) – Time array in seconds.

• mask (Array) – Boolean mask indicating valid time points.

• h_lms (Array) – Complex strain arrays for all modes, shape (Nbinaries, Nmodes, Ntimes).

compute_strain_components_amp_phase(m1, m2, chi1z, chi2z, distance, phi_ref, f_ref, f_min, inclination, psi, delta_t=15.0, t_min=nan, t_ref=nan, T=None)

Generate complex strain \(h_{lm}\) for all modes, and multiply them by the corresponding spin-weighted spherical harmonics to get the contribution to the strain from each mode. Extract the amplitude and phase of each mode.

Parameters:

• m1 (float | Array) – Mass of the first black hole in solar masses.

• m2 (float | Array) – Mass of the second black hole in solar masses.

• chi1z (float | Array) – Dimensionless spin of the first black hole along the orbital angular momentum.

• chi2z (float | Array) – Dimensionless spin of the second black hole along the orbital angular momentum.

• distance (float | Array) – Luminosity distance to the binary in megaparsecs.

• phi_ref (float | Array) – Reference phase at frequency f_ref in radians.

• f_ref (float | Array) – Reference frequency in Hz.

• f_min (float | Array) – Minimum frequency in Hz.

• inclination (float) – Inclination angle of the binary in radians.

• psi (float | Array) – Polarization angle in radians.

• delta_t (float, default 15.0) – Time step for waveform generation in seconds.

• t_min (float, default jnp.nan) – Minimum time for waveform generation in seconds. If NaN, will be set by the minimum frequency.

• t_ref (float, default jnp.nan) – Reference time for waveform generation in seconds. If NaN, will be set by the reference frequency.

• T (float | None, default None) – Total observation time in seconds. If sets, it overrides the default value.

Return type:

tuple[Array, Array, Array, Array]

Returns:

• times (Array) – Time array in seconds.

• mask (Array) – Boolean mask indicating valid time points.

• amplitudes (Array) – Amplitude arrays for all modes, shape (Nbinaries, Nmodes, Ntimes).

• phases (Array) – Phase arrays for all modes, shape (Nbinaries, Nmodes, Ntimes).

get_coarse_grained_time_array()

Get the coarse-grained time array in seconds. This is useful for users who want to use the same time array for other computations.

Return type:

tuple[Array, Array]

Returns:

• times_sec (Array) – Coarse-grained time array in seconds.

• mask (Array) – Boolean mask indicating valid time points.

get_time_grids(wf_params, num_steps)

Generate the time grid for waveform generation based on waveform parameters.

Parameters:

• wf_params (WaveformParams) – Waveform parameters of the binary.

• num_steps (int) – Number of steps for the time grid. This is used to allocate memory for the time grid, and it ensures all the binaries in the batch have the same number of steps.

Return type:

tuple[Array, Array]

Returns:

• times (Array) – Time array in units of mass for waveform generation.

• mask (Array) – Boolean mask indicating valid time points.

initial_processing(m1, m2, chi1z, chi2z, distance, phi_ref, f_ref, f_min, inclination, psi, delta_t=15.0, t_min=nan, t_ref=nan, T=None)

Initial processing to compute waveform parameters and time grids.

Parameters:

• m1 (float | Array) – Mass of the first black hole in solar masses.

• m2 (float | Array) – Mass of the second black hole in solar masses.

• chi1z (float | Array) – Dimensionless spin of the first black hole along the orbital angular momentum.

• chi2z (float | Array) – Dimensionless spin of the second black hole along the orbital angular momentum.

• distance (float | Array) – Luminosity distance to the binary in megaparsecs.

• phi_ref (float | Array) – Reference phase at frequency f_ref in radians.

• f_ref (float | Array) – Reference frequency in Hz.

• f_min (float | Array) – Minimum frequency in Hz.

• inclination (float | Array) – Inclination angle of the binary in radians.

• psi (float | Array) – Polarization angle in radians.

• delta_t (float | Array, default 15.0) – Time step for waveform generation in seconds.

• t_min (float | Array, default jnp.nan) – Minimum time for waveform generation in seconds. If NaN, will be set by the minimum frequency.

• t_ref (float | Array, default jnp.nan) – Reference time for waveform generation in seconds. If NaN, will be set by the reference frequency.

• T (float | None, default None) – Total observation time in seconds. If sets, it overrides the default value.

Return type:

tuple[WaveformParams, Array, Array, AmplitudeCoeffs, PhaseCoeffs]

Returns:

• wf_params (WaveformParams) – Waveform parameters of the binary, including derived parameters like total mass, symmetric mass ratio, and time arrays.

• times (Array) – Time array in units of mass for waveform generation.

• mask (Array) – Boolean mask indicating valid time points.

• amplitude_coeffs_22 (AmplitudeCoeffs) – Amplitude coefficients for the (2,2) mode.

• phase_coeffs_22 (PhaseCoeffs) – Phase coefficients for the (2,2) mode.

property max_adaptive_steps: int | None

property num_modes: int

Total number of modes included in the waveform, including negative m modes if applicable.

rotate_by_polarization_angle(h_plus, h_cross, psi)

Rotate the plus and cross polarizations by the polarization angle \(\psi\).

Parameters:

• h_plus (Array) – Plus polarization strain.

• h_cross (Array) – Cross polarization strain.

• psi (float | Array) – Polarization angle in radians.

Return type:

tuple[Array, Array]

Returns:

• h_plus_rotated (Array) – Rotated plus polarization strain.

• h_cross_rotated (Array) – Rotated cross polarization strain.

Core Functionality

Internal components

Internals

Internal data structures and coefficient computation for IMRPhenomT(HM).

class phentax.core.internals.WaveformParams(m1, m2, M, mass1, mass2, total_mass, eta, delta, chi_eff, chi1, chi2, distance, inclination, phi_ref, psi, Mf, af, M_sec, amp_factor, Mf_min, Mf_ref, Mdelta_t, Mt_min, Mt_ref, delta_t, t_min, t_ref, t_low, atol, rtol, Mt_end=500, length=10000)

Bases: Module

Physical parameters and derived quantities. These are intermediate quantities used throughout the waveform computation.

While the waveform interface expects the input m1 and m2 to be solar masses, here m1 and m2 are the dimensionless masses to match the phenomxpy interface.

Notes

• Dimensionless quantities (m1, m2, M, Mf, etc.) are in geometric units where \(G = c = 1\).

• Physical quantities (mass1, mass2, total_mass) are in solar masses

• Time quantities are either dimensionless (Mt_*) or in seconds (t_*, delta_t)

• This class is compatible with JAX transformations (jit, vmap, grad)

Parameters:

• m1 (float | Array) – Primary mass (dimensionless).

• m2 (float | Array) – Secondary mass (dimensionless).

• M (float | Array) – Total mass (dimensionless).

• mass1 (float | Array) – Primary mass (M_sun).

• mass2 (float | Array) – Secondary mass (M_sun).

• total_mass (float | Array) – Total mass (M_sun).

• eta (float | Array) – Symmetric mass ratio.

• delta (float | Array) – Mass difference ratio (m1-m2)/M.

• chi_eff (float | Array) – Effective spin.

• chi1 (float | Array) – Spin 1 z-component.

• chi2 (float | Array) – Spin 2 z-component.

• distance (float | Array) – Luminosity distance (Mpc).

• inclination (float | Array) – Inclination angle (radians).

• phi_ref (float | Array) – Reference phase (radians).

• psi (float | Array) – Polarization angle (radians).

• Mf (float | Array) – Final mass (dimensionless).

• af (float | Array) – Final spin (dimensionless).

• M_sec (float | Array) – Total mass in seconds.

• amp_factor (float | Array) – Amplitude prefactor.

• Mf_min (float | Array) – Minimum frequency (dimensionless).

• Mf_ref (float | Array) – Reference frequency (dimensionless).

• Mdelta_t (float | Array) – Delta t in dimensionless units.

• Mt_min (float | Array) – Minimum time in dimensionless units.

• Mt_ref (float | Array) – Reference time in dimensionless units.

• delta_t (float | Array) – Time step in seconds.

• t_min (float | Array) – Start time (seconds), default None.

• t_ref (float | Array) – Reference time (seconds), default None.

• t_low (float | Array) – if 0, use fits for bisection edge. else use value.

M: float | Array

M_sec: float | Array

Mdelta_t: float | Array

Mf: float | Array

Mf_min: float | Array

Mf_ref: float | Array

Mt_end: float | Array = 500

Mt_min: float | Array

Mt_ref: float | Array

af: float | Array

amp_factor: float | Array

atol: float | Array

chi1: float | Array

chi2: float | Array

chi_eff: float | Array

delta: float | Array

delta_t: float | Array

distance: float | Array

eta: float | Array

inclination: float | Array

length: int | Array = 10000

m1: float | Array

m2: float | Array

mass1: float | Array

mass2: float | Array

phi_ref: float | Array

psi: float | Array

rtol: float | Array

t_low: float | Array

t_min: float | Array

t_ref: float | Array

total_mass: float | Array

phentax.core.internals.compute_waveform_params(m1, m2, s1z, s2z, distance, inclination, phi_ref, psi, f_ref, f_min, delta_t=5.0, t_min=nan, t_ref=nan, t_low=0.0, atol=1e-12, rtol=1e-12)

Wrapper to compute derived waveform parameters.

Parameters:

• m1 (float | Array) – Primary mass (M_sun).

• m2 (float | Array) – Secondary mass (M_sun).

• s1z (float | Array) – Primary spin z-component (dimensionless).

• s2z (float | Array) – Secondary spin z-component (dimensionless).

• distance (float | Array) – Luminosity distance (Mpc).

• inclination (float | Array) – Inclination angle (radians).

• phi_ref (float | Array) – Reference phase (radians).

• psi (float | Array) – Polarization angle (radians).

• f_ref (float | Array) – Reference frequency (Hz), or 0 for peak.

• f_min (float | Array) – Minimum frequency (Hz).

• delta_t (float | Array, default 5.0) – Time step (seconds).

• t_min (float | Array, default jnp.nan) – Start time (seconds).

• t_ref (float | Array, default jnp.nan) – Reference time (seconds).

• t_low (float | Array, default 0.0) – if 0, use fits for bisection edge. else use value.

• atol (float | Array, optional) – Absolute Bisection tolerance

• rtol (float | Array, optional) – Relative bisection tolerance

Returns:

Derived waveform parameters.

Return type:

WaveformParams

phentax.core.internals.compute_wf_length_params(params)

Compute waveform length parameters in dimensionless units.

Parameters:

params (WaveformParams) – Input physical parameters.

Returns:

Updated waveform parameters with length parameters.

Return type:

WaveformParams

PN Coefficients

Post-Newtonian (PN) coefficients for IMRPhenomT(HM).

Contains the TaylorT3 omega PN coefficients and amplitude PN coefficients for all supported modes. These are mode-dependent and spin-dependent.

References: - TaylorT3 omega: Eq. A5 in arXiv:2012.11923 (IMRPhenomT paper) - Amplitude PN: Eq. 9.4 Blanchet 2008, Eq. 43 Faye 2012, Eq. 4.17 Arun, Eq. 4.27 Buonanno

class phentax.core.pn_coeffs.AmpPNCoeffs(ampN, amp0halfPNreal, amp1PNreal, amp1halfPNreal, amp2PNreal, amp2halfPNreal, amp3PNreal, amp3halfPNreal, amplog, amp0halfPNimag, amp1PNimag, amp1halfPNimag, amp2PNimag, amp2halfPNimag, amp3PNimag, amp3halfPNimag, fac0)

Bases: Module

Amplitude PN coefficients for a specific mode.

amp0halfPNimag: float | Array

amp0halfPNreal: float | Array

amp1PNimag: float | Array

amp1PNreal: float | Array

amp1halfPNimag: float | Array

amp1halfPNreal: float | Array

amp2PNimag: float | Array

amp2PNreal: float | Array

amp2halfPNimag: float | Array

amp2halfPNreal: float | Array

amp3PNimag: float | Array

amp3PNreal: float | Array

amp3halfPNimag: float | Array

amp3halfPNreal: float | Array

ampN: float | Array

amplog: float | Array

fac0: float | Array

class phentax.core.pn_coeffs.OmegaPNCoeffs(omega1PN, omega1halfPN, omega2PN, omega2halfPN, omega3PN, omega3halfPN)

Bases: Module

TaylorT3 omega PN coefficients (up to 3.5PN).

omega1PN: float | Array

omega1halfPN: float | Array

omega2PN: float | Array

omega2halfPN: float | Array

omega3PN: float | Array

omega3halfPN: float | Array

phentax.core.pn_coeffs.compute_amp_pn_coeffs(eta, chi1, chi2, delta, m1, m2, mode)

Compute amplitude PN coefficients for a given mode.

Parameters:

• eta (Array) – Symmetric mass ratio.

• chi1 (Array) – Dimensionless spin z-components.

• chi2 (Array) – Dimensionless spin z-components.

• delta (Array) – Mass difference ratio (m1-m2)/M.

• m1 (Array) – Component masses as fractions of total mass.

• m2 (Array) – Component masses as fractions of total mass.

• mode (int) – Mode key (22, 21, 33, 44, 55).

Returns:

Amplitude PN coefficients for the mode.

Return type:

AmpPNCoeffs

phentax.core.pn_coeffs.compute_amp_pn_coeffs_21(eta, chi1, chi2, delta, m1, m2)

Compute amplitude PN coefficients for the (2,1) mode.

Return type:

AmpPNCoeffs

phentax.core.pn_coeffs.compute_amp_pn_coeffs_22(eta, chi1, chi2, delta, m1, m2)

Compute amplitude PN coefficients for the (2,2) mode.

3PN non-spinning from Eq 9.4 Blanchet 2008. 3.5PN non-spinning from Eq. 43 Faye 2012. 1.5PN spinning from Eq 4.17 Arun. 2PN spinning from Eq. 4.27 Buonanno.

Parameters:

• eta (Array) – Symmetric mass ratio.

• chi1 (Array) – Dimensionless spin z-components.

• chi2 (Array) – Dimensionless spin z-components.

• delta (Array) – Mass difference ratio (m1-m2)/M.

• m1 (Array) – Component masses as fractions of total mass (m1+m2=1).

• m2 (Array) – Component masses as fractions of total mass (m1+m2=1).

Returns:

Amplitude PN coefficients for the 22 mode.

Return type:

AmpPNCoeffs

phentax.core.pn_coeffs.compute_amp_pn_coeffs_33(eta, chi1, chi2, delta, m1, m2)

Compute amplitude PN coefficients for the (3,3) mode.

Return type:

AmpPNCoeffs

phentax.core.pn_coeffs.compute_amp_pn_coeffs_44(eta, chi1, chi2, delta, m1, m2)

Compute amplitude PN coefficients for the (4,4) mode.

Return type:

AmpPNCoeffs

phentax.core.pn_coeffs.compute_amp_pn_coeffs_55(eta, chi1, chi2, delta, m1, m2)

Compute amplitude PN coefficients for the (5,5) mode.

Return type:

AmpPNCoeffs

phentax.core.pn_coeffs.compute_omega_pn_coeffs(eta, chi1, chi2, delta, m1, m2)

Compute TaylorT3 omega PN coefficients.

Eq. A5 in arXiv:2012.11923. Paper misses the term eta^3 * 235925/1769472 at 3PN order.

Parameters:

• eta (Array) – Symmetric mass ratio.

• chi1 (Array) – Dimensionless spin z-components.

• chi2 (Array) – Dimensionless spin z-components.

• delta (Array) – Mass difference ratio (m1-m2)/M.

• m1 (Array) – Component masses as fractions of total mass (m1+m2=1).

• m2 (Array) – Component masses as fractions of total mass (m1+m2=1).

Returns:

PN coefficients for TaylorT3 omega.

Return type:

OmegaPNCoeffs

Phase Coefficients

Phase and omega coefficient computation for IMRPhenomTHM.

This module implements the pPhase class functionality from phenomxpy, computing all the coefficients needed for the IMR omega and phase ansatze.

class phentax.core.phase.PhaseCoeffs(mode, omega1PN, omega1halfPN, omega2PN, omega2halfPN, omega3PN, omega3halfPN, omegaInspC1, omegaInspC2, omegaInspC3, omegaInspC4, omegaInspC5, omegaInspC6, omegaRING, alpha1RD, omegaRING_prec, omegaPeak, c1, c2, c3, c4, c1_prec, omegaMergerC1, omegaMergerC2, omegaMergerC3, omegaCut, domegaCut, domegaPeak, inspiral_cut, ringdown_cut, tt0, tEarly, omegaCutPNAMP, phiCutPNAMP, phOffInsp, phOffMerger, phOffRD, phoff, phiref0, powers_of_5)

Bases: Module

All phase/omega coefficients for a given mode.

Contains PN coefficients, pseudo-PN coefficients, ringdown parameters, and intermediate region coefficients.

Parameters:

• mode (int | Array) – Mode number (e.g., 22, 33, 44, etc.).

• omega1PN (float | Array) – 1PN coefficient for omega inspiral.

• omega1halfPN (float | Array) – 1.5PN coefficient for omega inspiral.

• omega2PN (float | Array) – 2PN coefficient for omega inspiral.

• omega2halfPN (float | Array) – 2.5PN coefficient for omega inspiral.

• omega3PN (float | Array) – 3PN coefficient for omega inspiral.

• omega3halfPN (float | Array) – 3.5PN coefficient for omega inspiral.

• omegaInspC1 (float | Array) – 1st pseudo-PN coefficient for omega inspiral.

• omegaInspC2 (float | Array) – 2nd pseudo-PN coefficient for omega inspiral.

• omegaInspC3 (float | Array) – 3rd pseudo-PN coefficient for omega inspiral.

• omegaInspC4 (float | Array) – 4th pseudo-PN coefficient for omega inspiral.

• omegaInspC5 (float | Array) – 5th pseudo-PN coefficient for omega inspiral.

• omegaInspC6 (float | Array) – 6th pseudo-PN coefficient for omega inspiral.

• omegaRING (float | Array) – Ringdown frequency (2*pi*fring).

• alpha1RD (float | Array) – Ringdown damping rate (2*pi*fdamp).

• omegaRING_prec (float | Array) – Ringdown frequency for precessing case.

• omegaPeak (float | Array) – Peak frequency.

• c1 (float | Array) – 1st ringdown ansatz coefficient.

• c2 (float | Array) – 2nd ringdown ansatz coefficient.

• c3 (float | Array) – 3rd ringdown ansatz coefficient.

• c4 (float | Array) – 4th ringdown ansatz coefficient.

• c1_prec (float | Array) – 1st ringdown ansatz coefficient for precessing case.

• omegaMergerC1 (float | Array) – 1st intermediate region coefficient.

• omegaMergerC2 (float | Array) – 2nd intermediate region coefficient.

• omegaMergerC3 (float | Array) – 3rd intermediate region coefficient.

• omegaCut (float | Array) – Omega at inspiral cut.

• domegaCut (float | Array) – domega/dt at inspiral cut.

• domegaPeak (float | Array) – domega/dt at peak.

• inspiral_cut (float | Array) – Transition time inspiral -> intermediate.

• ringdown_cut (float | Array) – Transition time intermediate -> ringdown (= 0, peak time).

• tt0 (float | Array) – t0 from fit.

• tEarly (float | Array) – Early time for phase offset.

• omegaCutPNAMP (float | Array) – Omega contribution from complex amplitude at transtion time pAmp.inspiral_cut.

• phiCutPNAMP (float | Array) – Phase contribution from complex amplitude at transtion time pAmp.inspiral_cut.

• phOffInsp (float | Array) – Phase offset for inspiral.

• phOffMerger (float | Array) – Phase offset for intermediate region.

• phOffRD (float | Array) – Phase offset for ringdown.

• phoff (float | Array) – phase offset for different modes.

• phiref0 (float | Array) – reference phase of the 22 mode at t=tref.

• powers_of_5 (Array) – Powers of 5^(n/8) for n=0..7 for phase computation.

alpha1RD: float | Array

c1: float | Array

c1_prec: float | Array

c2: float | Array

c3: float | Array

c4: float | Array

domegaCut: float | Array

domegaPeak: float | Array

inspiral_cut: float | Array

mode: int | Array

omega1PN: float | Array

omega1halfPN: float | Array

omega2PN: float | Array

omega2halfPN: float | Array

omega3PN: float | Array

omega3halfPN: float | Array

omegaCut: float | Array

omegaCutPNAMP: float | Array

omegaInspC1: float | Array

omegaInspC2: float | Array

omegaInspC3: float | Array

omegaInspC4: float | Array

omegaInspC5: float | Array

omegaInspC6: float | Array

omegaMergerC1: float | Array

omegaMergerC2: float | Array

omegaMergerC3: float | Array

omegaPeak: float | Array

omegaRING: float | Array

omegaRING_prec: float | Array

phOffInsp: float | Array

phOffMerger: float | Array

phOffRD: float | Array

phiCutPNAMP: float | Array

phiref0: float | Array

phoff: float | Array

powers_of_5: Array

ringdown_cut: float | Array

tEarly: float | Array

tt0: float | Array

phentax.core.phase.compute_domega_cut(tCut, tCut_threshold, eta, phase_coeffs_22)

Compute domegaCut using JAX conditional.

Parameters:

• tCut (float | Array) – Transition time inspiral -> intermediate.

• tCut_threshold (float | Array) – Threshold time to switch between inspiral and merger branch.

• eta (float | Array) – Symmetric mass ratio.

• phase_coeffs_22 (PhaseCoeffs)

Return type:

float | Array

phentax.core.phase.compute_phase_coeffs_22(wf_params)

Compute all phase coefficients for the 22 mode.

Parameters:

wf_params (WaveformParams) – Waveform parameters for the waveform.

Returns:

Updated derived parameters and phase coefficients for mode 22.

Return type:

tuple[WaveformParams, PhaseCoeffs]

phentax.core.phase.compute_phase_coeffs_hm(wf_params, phase_coeffs_22, OmegaCutPNAMP, PhiCutPNAMP, mode)

Compute all phase/omega coefficients for HM modes.

Parameters:

• wf_params (WaveformParams) – Waveform parameters for the waveform.

• phase_coeffs_22 (PhaseCoeffs) – Phase coefficients for the 22 mode.

• OmegaCutPNAMP (Array) – Omega contribution from complex amplitude at transtion time pAmp.inspiral_cut for HM modes.

• PhiCutPNAMP (Array) – Phase contribution from complex amplitude at transtion time pAmp.inspiral_cut for HM modes.

• mode (int | Array) – Mode number (e.g., 33, 44, etc.).

Return type:

PhaseCoeffs

phentax.core.phase.get_time_of_frequency(freq, eta, phase_coeffs, t_low=0.0, t_high=500.0, atol=1e-12, rtol=1e-12)

Get time corresponding to a given frequency using root finding.

Parameters:

• freq (float | Array) – (Dimensionless) frequency at which to find the corresponding time.

• eta (float | Array) – Symmetric mass ratio.

• phase_coeffs (PhaseCoeffs) – Phase coefficients for the mode.

• t_low (float | Array, optional) – Lower bound for the time search (default is 0.0. In this case, it is adjusted based on the frequency).

• t_high (float | Array, optional) – Upper bound for the time search (default is 500.0).

• atol (float | Array, optional) – Absolute Bisection tolerance

• rtol (float | Array, optional) – Relative bisection tolerance

Return type:

float | Array

phentax.core.phase.imr_omega(time, eta, phase_coeffs)

Compute the frequency \(\omega(t) = 2\pi f(t)\) at given times for a given mode.

Parameters:

• time (float | Array) – Time(s) at which to compute the phase.

• eta (float | Array) – Symmetric mass ratio.

• phase_coeffs (PhaseCoeffs) – Phase coefficients for the mode.

Returns:

Phase value(s) at the given time(s).

Return type:

Array

phentax.core.phase.imr_omega_dot(time, eta, phase_coeffs)

Compute the frequency derivative \(\dot{\omega}(t)\) at given times for a given mode with JAX autodiff.

Parameters:

• time (float | Array) – Time(s) at which to compute the phase.

• eta (float | Array) – Symmetric mass ratio.

• phase_coeffs (PhaseCoeffs) – Phase coefficients for the mode.

Returns:

Phase derivative value(s) at the given time(s).

Return type:

Array

phentax.core.phase.imr_phase(time, eta, phase_coeffs, phase_22=0.0)

Compute the phase at given times for a given mode.

Parameters:

• time (float | Array) – Time(s) at which to compute the phase.

• eta (float | Array) – Symmetric mass ratio.

• phase_coeffs (PhaseCoeffs) – Phase coefficients for the mode.

• phase_22 (float | Array, optional) – Phase of the (2,2) mode at the same times (default is 0.0). This is used for the higher modes’ inspiral phase computation.

Returns:

Phase value(s) at the given time(s).

Return type:

Array

Amplitude Coefficients

Amplitude coefficient computation for IMRPhenomTHM.

This module implements the pAmp class functionality from phenomxpy, computing all the coefficients needed for the IMR amplitude ansatze.

class phentax.core.amplitude.AmplitudeCoeffs(mode, pn_real_coeffs, pn_imag_coeffs, inspC1, inspC2, inspC3, alpha1RD, alpha1RD_prec, ampPeak, c1_prec, c2_prec, c3, c4_prec, mergerC1, mergerC2, mergerC3, mergerC4, inspiral_cut, ringdown_cut, tshift, fac0, omegaCutPNAMP, phiCutPNAMP)

Bases: Module

All amplitude coefficients for a given mode.

alpha1RD: float | Array

alpha1RD_prec: float | Array

ampPeak: float | Array

c1_prec: float | Array

c2_prec: float | Array

c3: float | Array

c4_prec: float | Array

fac0: float | Array

inspC1: float | Array

inspC2: float | Array

inspC3: float | Array

inspiral_cut: float | Array

mergerC1: float | Array

mergerC2: float | Array

mergerC3: float | Array

mergerC4: float | Array

mode: int | Array

omegaCutPNAMP: float | Array

phiCutPNAMP: float | Array

pn_imag_coeffs: Array

pn_real_coeffs: Array

ringdown_cut: float | Array

tshift: float | Array

phentax.core.amplitude.compute_amplitude_coeffs_22(wf_pafams, phase_coeffs)

Compute all amplitude coefficients for the 22 mode.

Parameters:

• wf_pafams (WaveformParams) – Waveform parameters.

• phase_coeffs (PhaseCoeffs) – Phase coefficients for the 22 mode.

Returns:

All amplitude coefficients for the 22 mode.

Return type:

AmplitudeCoeffs

phentax.core.amplitude.compute_amplitude_coeffs_hm(wf_pafams, phase_coeffs_22, mode)

Compute all amplitude coefficients for a given higher mode.

Parameters:

• wf_pafams (WaveformParams) – Waveform parameters.

• phase_coeffs_22 (PhaseCoeffs) – Phase coefficients for the 22 mode.

• mode (int | Array) – The higher mode to compute (e.g., 21, 33, 44, 55).

Returns:

All amplitude coefficients for the specified higher mode.

Return type:

AmplitudeCoeffs

phentax.core.amplitude.imr_amplitude(time, eta, amp_coeffs, phase_coeffs_22)

Compute IMR amplitude at given times for a specific mode.

Parameters:

• time (Array) – Times at which to compute the amplitude.

• eta (Array) – Symmetric mass ratio.

• amp_coeffs (AmplitudeCoeffs) – Amplitude coefficients for the mode.

• phase_coeffs_22 (PhaseCoeffs) – Phase coefficients for the 22 mode.

Returns:

Computed amplitude at the given times.

Return type:

Array

phentax.core.amplitude.imr_amplitude_dot(time, eta, amp_coeffs, phase_coeffs_22, return_amplitude=False)

Compute the IMR amplitude time derivative \(\dot{A}(t)\) at given times for a specific mode, using JAX automatic differentiation.

Parameters:

• time (Array) – Times at which to compute the amplitude.

• eta (Array) – Symmetric mass ratio.

• amp_coeffs (AmplitudeCoeffs) – Amplitude coefficients for the mode.

• phase_coeffs_22 (PhaseCoeffs) – Phase coefficients for the 22 mode.

• return_amplitude (bool, default False) – Whether to return the amplitude as well.

Returns:

Computed amplitude time derivative at the given times. If return_amplitude is True, the function returns the amplitude value as well.

Return type:

Array | Tuple[Array, Array]

Fits

Parameter space fits for IMRPhenomT(HM).

Contains calibrated fits for collocation points, ringdown frequencies, final spin/mass, and other quantities. All functions are JAX-compatible.

phentax.core.fits.fdamp(af, mode)

Damping frequency for given mode (fundamental).

Parameters:

• af (float | Array) – Final dimensionless spin.

• mode (int) – Mode key (22, 21, 33, 44, 55, 20).

Returns:

Dimensionless damping frequency (Mf * gamma).

Return type:

float

phentax.core.fits.fdamp_20(af)

Damping frequency for 20 mode.

Return type:

float | Array

phentax.core.fits.fdamp_21(af)

Damping frequency for 21 mode.

Return type:

float | Array

phentax.core.fits.fdamp_22(af)

Damping frequency for 22 mode.

Return type:

float | Array

phentax.core.fits.fdamp_33(af)

Damping frequency for 33 mode.

Return type:

float | Array

phentax.core.fits.fdamp_44(af)

Damping frequency for 44 mode.

Return type:

float | Array

phentax.core.fits.fdamp_55(af)

Damping frequency for 55 mode.

Return type:

float | Array

phentax.core.fits.fdamp_n2(af, mode)

Second overtone damping frequency for given mode.

Parameters:

• af (float | Array) – Final dimensionless spin.

• mode (int) – Mode key (22, 21, 33, 44, 55, 20).

Returns:

Dimensionless second overtone damping frequency.

Return type:

float

phentax.core.fits.fdamp_n2_20(af)

Second overtone damping frequency for 20 mode.

Return type:

float | Array

phentax.core.fits.fdamp_n2_21(af)

Second overtone damping frequency for 21 mode.

Return type:

float | Array

phentax.core.fits.fdamp_n2_22(af)

Second overtone damping frequency for 22 mode.

Return type:

float | Array

phentax.core.fits.fdamp_n2_33(af)

Second overtone damping frequency for 33 mode.

Return type:

float | Array

phentax.core.fits.fdamp_n2_44(af)

Second overtone damping frequency for 44 mode.

Return type:

float | Array

phentax.core.fits.fdamp_n2_55(af)

Second overtone damping frequency for 55 mode.

Return type:

float | Array

phentax.core.fits.final_mass_2017(eta, s1z, s2z)

Compute final remnant mass using IMRPhenomX fits (2017).

Parameters:

• eta (float | Array) – Symmetric mass ratio.

• s1z (float | Array) – Dimensionless z-component spins.

• s2z (float | Array) – Dimensionless z-component spins.

Returns:

Final mass as fraction of total mass (Mf/M).

Return type:

float

phentax.core.fits.final_spin_2017(eta, s1z, s2z)

Compute final remnant spin using IMRPhenomX fits (2017).

Parameters:

• eta (float | Array) – Symmetric mass ratio.

• s1z (float | Array) – Dimensionless z-component spins.

• s2z (float | Array) – Dimensionless z-component spins.

Returns:

Final dimensionless spin.

Return type:

float

phentax.core.fits.fring(af, mode)

Ringdown frequency for given mode.

Parameters:

• af (float | Array) – Final dimensionless spin.

• mode (int) – Mode key (22, 21, 33, 44, 55, 20).

Returns:

Dimensionless ringdown frequency (Mf * omega_ring).

Return type:

float

phentax.core.fits.fring_20(af)

Ringdown frequency for 20 mode.

Return type:

float | Array

phentax.core.fits.fring_21(af)

Ringdown frequency for 21 mode.

Return type:

float | Array

phentax.core.fits.fring_22(af)

Ringdown frequency for 22 mode.

Return type:

float | Array

phentax.core.fits.fring_33(af)

Ringdown frequency for 33 mode.

Return type:

float | Array

phentax.core.fits.fring_44(af)

Ringdown frequency for 44 mode.

Return type:

float | Array

phentax.core.fits.fring_55(af)

Ringdown frequency for 55 mode.

Return type:

float | Array

phentax.core.fits.inspiral_amp_cp(eta, s1z, s2z, mode, idx)

Inspiral amplitude collocation point.

Matches phenomxpy._IMRPhenomT_Inspiral_Amp_CP.

Parameters:

• eta (float | Array) – Symmetric mass ratio.

• s1z (float | Array) – Dimensionless z-component spins.

• s2z (float | Array) – Dimensionless z-component spins.

• mode (int) – Mode (22, 21, 33, 44, 55).

• idx (int) – Collocation point index (1, 2, or 3).

Returns:

Inspiral amplitude collocation point value.

Return type:

float

phentax.core.fits.inspiral_freq_cp(eta, s1z, s2z, idx)

Inspiral frequency collocation point (mode-independent).

Matches phenomxpy._IMRPhenomT_Inspiral_Freq_CP.

Parameters:

• eta (float | Array) – Symmetric mass ratio.

• s1z (float | Array) – Dimensionless z-component spins.

• s2z (float | Array) – Dimensionless z-component spins.

• idx (int) – Collocation point index (1-5).

Returns:

Inspiral frequency collocation point value.

Return type:

float

phentax.core.fits.inspiral_freq_cp_20(eta, s1z, s2z, idx=1)

Inspiral frequency collocation point for 20 mode (mode-independent).

Return type:

float | Array

phentax.core.fits.inspiral_freq_cp_21(eta, s1z, s2z, idx=1)

Inspiral frequency collocation point for 21 mode (mode-independent).

Return type:

float | Array

phentax.core.fits.inspiral_freq_cp_22(eta, s1z, s2z, idx=1)

Inspiral frequency collocation point for 22 mode (mode-independent).

Return type:

float | Array

phentax.core.fits.inspiral_freq_cp_33(eta, s1z, s2z, idx=1)

Inspiral frequency collocation point for 33 mode (mode-independent).

Return type:

float | Array

phentax.core.fits.inspiral_freq_cp_44(eta, s1z, s2z, idx=1)

Inspiral frequency collocation point for 44 mode (mode-independent).

Return type:

float | Array

phentax.core.fits.inspiral_freq_cp_55(eta, s1z, s2z, idx=1)

Inspiral frequency collocation point for 55 mode (mode-independent).

Return type:

float | Array

phentax.core.fits.inspiral_t0(eta, s1z, s2z, mode)

Inspiral TaylorT3 t0 calibration (mode-independent).

The t0 calibration is the same for all modes in IMRPhenomT.

Parameters:

• eta (float | Array) – Symmetric mass ratio.

• s1z (float | Array) – Dimensionless z-component spins.

• s2z (float | Array) – Dimensionless z-component spins.

• mode (int) – Mode key (unused, kept for API consistency).

Returns:

t0 calibration factor.

Return type:

float

phentax.core.fits.inspiral_t0_20(eta, s1z, s2z)

Inspiral t0 calibration for 20 mode (same as 22, mode-independent).

Return type:

float | Array

phentax.core.fits.inspiral_t0_21(eta, s1z, s2z)

Inspiral TaylorT3 t0 calibration for 21 mode (same as 22, mode-independent).

Return type:

float | Array

phentax.core.fits.inspiral_t0_22(eta, s1z, s2z)

Inspiral TaylorT3 t0 calibration (mode-independent).

Matches phenomxpy._IMRPhenomT_Inspiral_TaylorT3_t0.

Return type:

float | Array

phentax.core.fits.inspiral_t0_33(eta, s1z, s2z)

Inspiral TaylorT3 t0 calibration for 33 mode (same as 22, mode-independent).

Return type:

float | Array

phentax.core.fits.inspiral_t0_44(eta, s1z, s2z)

Inspiral TaylorT3 t0 calibration for 44 mode (same as 22, mode-independent).

Return type:

float | Array

phentax.core.fits.inspiral_t0_55(eta, s1z, s2z)

Inspiral TaylorT3 t0 calibration for 55 mode (same as 22, mode-independent).

Return type:

float | Array

phentax.core.fits.intermediate_amp_cp1(eta, s1z, s2z, mode)

Intermediate amplitude collocation point 1 for all modes.

This is a unified function that computes the intermediate amplitude collocation point for any supported mode, using the exact phenomxpy formula.

Parameters:

• eta (float | Array) – Symmetric mass ratio

• s1z (float | Array) – Dimensionless spin of primary along z-axis

• s2z (float | Array) – Dimensionless spin of secondary along z-axis

• mode (int) – Mode identifier (22, 21, 33, 44, 55)

Returns:

Intermediate amplitude collocation point 1 value

Return type:

float

phentax.core.fits.intermediate_freq_cp1(eta, s1z, s2z, mode)

Intermediate frequency collocation point 1 for all modes.

This is a unified function that computes the intermediate frequency collocation point for any supported mode, using the exact phenomxpy formula.

Parameters:

• eta (float | Array) – Symmetric mass ratio

• s1z (float | Array) – Dimensionless spin of primary along z-axis

• s2z (float | Array) – Dimensionless spin of secondary along z-axis

• mode (int) – Mode identifier (22, 21, 33, 44, 55)

Returns:

Intermediate frequency collocation point 1 value

Return type:

float

phentax.core.fits.intermediate_freq_cp1_20(eta, s1z, s2z)

Intermediate frequency collocation point 1 for 20 mode (use same as 22).

Return type:

float | Array

phentax.core.fits.intermediate_freq_cp1_21(eta, s1z, s2z)

Intermediate frequency collocation point 1 for 21 mode (legacy wrapper).

Return type:

float | Array

phentax.core.fits.intermediate_freq_cp1_22(eta, s1z, s2z)

Intermediate frequency collocation point 1 for 22 mode (legacy wrapper).

Return type:

float | Array

phentax.core.fits.intermediate_freq_cp1_33(eta, s1z, s2z)

Intermediate frequency collocation point 1 for 33 mode (legacy wrapper).

Return type:

float | Array

phentax.core.fits.intermediate_freq_cp1_44(eta, s1z, s2z)

Intermediate frequency collocation point 1 for 44 mode (legacy wrapper).

Return type:

float | Array

phentax.core.fits.intermediate_freq_cp1_55(eta, s1z, s2z)

Intermediate frequency collocation point 1 for 55 mode (legacy wrapper).

Return type:

float | Array

phentax.core.fits.intermediate_freq_cp2_20(eta, s1z, s2z)

Intermediate frequency collocation point 2 for 20 mode (use same as 22).

Return type:

float | Array

phentax.core.fits.intermediate_freq_cp2_21(eta, s1z, s2z)

DEPRECATED: Intermediate frequency collocation point 2 for 21 mode.

Return type:

float | Array

phentax.core.fits.intermediate_freq_cp2_22(eta, s1z, s2z)

DEPRECATED: Intermediate frequency collocation point 2 for 22 mode.

Return type:

float | Array

phentax.core.fits.intermediate_freq_cp2_33(eta, s1z, s2z)

DEPRECATED: Intermediate frequency collocation point 2 for 33 mode.

Return type:

float | Array

phentax.core.fits.intermediate_freq_cp2_44(eta, s1z, s2z)

Intermediate frequency collocation point 2 for 44 mode.

Return type:

float | Array

phentax.core.fits.intermediate_freq_cp2_55(eta, s1z, s2z)

Intermediate frequency collocation point 2 for 55 mode.

Return type:

float | Array

phentax.core.fits.peak_amp(eta, s1z, s2z, mode)

Peak amplitude for given mode.

Return type:

float | Array

phentax.core.fits.peak_amp_20(eta, s1z, s2z)

Peak amplitude for 20 mode (use same as 22).

Return type:

float | Array

phentax.core.fits.peak_amp_21(eta, s1z, s2z)

Peak amplitude for 21 mode.

Return type:

float | Array

phentax.core.fits.peak_amp_22(eta, s1z, s2z)

Peak amplitude for 22 mode.

Return type:

float | Array

phentax.core.fits.peak_amp_33(eta, s1z, s2z)

Peak amplitude for 33 mode.

Return type:

float | Array

phentax.core.fits.peak_amp_44(eta, s1z, s2z)

Peak amplitude for 44 mode.

Return type:

float | Array

phentax.core.fits.peak_amp_55(eta, s1z, s2z)

Peak amplitude for 55 mode.

Return type:

float | Array

phentax.core.fits.peak_freq(eta, s1z, s2z, mode)

Peak frequency for given mode.

Return type:

float | Array

phentax.core.fits.peak_freq_20(eta, s1z, s2z)

Peak frequency for 20 mode (use same as 22).

Return type:

float | Array

phentax.core.fits.peak_freq_21(eta, s1z, s2z)

Peak frequency for 21 mode.

Return type:

float | Array

phentax.core.fits.peak_freq_22(eta, s1z, s2z)

Peak frequency for 22 mode in dimensionless units (Mf).

This is the omega22 peak frequency fit from phenomxpy.

Parameters:

• eta (float | Array) – Symmetric mass ratio.

• s1z (float | Array) – Dimensionless z-component spins.

• s2z (float | Array) – Dimensionless z-component spins.

Returns:

Peak angular frequency in geometric units (M*omega).

Return type:

float

phentax.core.fits.peak_freq_33(eta, s1z, s2z)

Peak frequency for 33 mode.

Return type:

float | Array

phentax.core.fits.peak_freq_44(eta, s1z, s2z)

Peak frequency for 44 mode.

Return type:

float | Array

phentax.core.fits.peak_freq_55(eta, s1z, s2z)

Peak frequency for 55 mode.

Return type:

float | Array

phentax.core.fits.rd_amp_c3(eta, s1z, s2z, mode)

Ringdown amplitude C3 for given mode.

Return type:

float | Array

phentax.core.fits.rd_amp_c3_20(eta, s1z, s2z)

Ringdown amplitude C3 for 20 mode (use same as 22).

Return type:

float | Array

phentax.core.fits.rd_amp_c3_21(eta, s1z, s2z)

Ringdown amplitude C3 for 21 mode.

Return type:

float | Array

phentax.core.fits.rd_amp_c3_22(eta, s1z, s2z)

Ringdown amplitude C3 for 22 mode.

Return type:

float | Array

phentax.core.fits.rd_amp_c3_33(eta, s1z, s2z)

Ringdown amplitude C3 for 33 mode.

Return type:

float | Array

phentax.core.fits.rd_amp_c3_44(eta, s1z, s2z)

Ringdown amplitude C3 for 44 mode.

Return type:

float | Array

phentax.core.fits.rd_amp_c3_55(eta, s1z, s2z)

Ringdown amplitude C3 for 55 mode.

Return type:

float | Array

phentax.core.fits.rd_freq_d2(eta, s1z, s2z, mode)

Ringdown frequency D2 for given mode.

Return type:

float | Array

phentax.core.fits.rd_freq_d2_20(eta, s1z, s2z)

Ringdown frequency D2 for 20 mode (use same as 22).

Return type:

float | Array

phentax.core.fits.rd_freq_d2_21(eta, s1z, s2z)

Ringdown frequency D2 for 21 mode.

Return type:

float | Array

phentax.core.fits.rd_freq_d2_22(eta, s1z, s2z)

Ringdown frequency D2 for 22 mode.

Return type:

float | Array

phentax.core.fits.rd_freq_d2_33(eta, s1z, s2z)

Ringdown frequency D2 for 33 mode.

Return type:

float | Array

phentax.core.fits.rd_freq_d2_44(eta, s1z, s2z)

Ringdown frequency D2 for 44 mode.

Return type:

float | Array

phentax.core.fits.rd_freq_d2_55(eta, s1z, s2z)

Ringdown frequency D2 for 55 mode.

Return type:

float | Array

phentax.core.fits.rd_freq_d3(eta, s1z, s2z, mode)

Ringdown frequency D3 for given mode.

Return type:

float | Array

phentax.core.fits.rd_freq_d3_20(eta, s1z, s2z)

Ringdown frequency D3 for 20 mode (use same as 22).

Return type:

float | Array

phentax.core.fits.rd_freq_d3_21(eta, s1z, s2z)

Ringdown frequency D3 for 21 mode.

Return type:

float | Array

phentax.core.fits.rd_freq_d3_22(eta, s1z, s2z)

Ringdown frequency D3 for 22 mode.

Return type:

float | Array

phentax.core.fits.rd_freq_d3_33(eta, s1z, s2z)

Ringdown frequency D3 for 33 mode.

Return type:

float | Array

phentax.core.fits.rd_freq_d3_44(eta, s1z, s2z)

Ringdown frequency D3 for 44 mode.

Return type:

float | Array

phentax.core.fits.rd_freq_d3_55(eta, s1z, s2z)

Ringdown frequency D3 for 55 mode.

Return type:

float | Array

phentax.core.fits.tshift(eta, s1z, s2z, mode)

Time shift for given mode.

Return type:

float | Array

phentax.core.fits.tshift_20(eta, s1z, s2z)

Time shift for 20 mode (same as 22, returns 0).

Return type:

float | Array

phentax.core.fits.tshift_21(eta, s1z, s2z)

Time shift for 21 mode relative to 22 mode.

Return type:

float | Array

phentax.core.fits.tshift_22(eta, s1z, s2z)

Time shift for 22 mode (reference mode, always 0).

Return type:

float | Array

phentax.core.fits.tshift_33(eta, s1z, s2z)

Time shift for 33 mode relative to 22 mode.

Return type:

float | Array

phentax.core.fits.tshift_44(eta, s1z, s2z)

Time shift for 44 mode relative to 22 mode.

Return type:

float | Array

phentax.core.fits.tshift_55(eta, s1z, s2z)

Time shift for 55 mode relative to 22 mode.

Return type:

float | Array

Collocation Points

Collocation

Collocation point methods for pseudo-PN coefficient computation.

This module implements the linear system solving to compute pseudo-PN coefficients that augment the Post-Newtonian expansion to match numerical relativity fits.

class phentax.core.collocation.AmpPseudoPNCoeffs(c1, c2, c3)

Pseudo-PN coefficients for amplitude inspiral ansatz (3 coefficients).

class phentax.core.collocation.OmegaPseudoPNCoeffs(c1, c2, c3, c4, c5, c6)

Pseudo-PN coefficients for omega inspiral ansatz (6 coefficients).

phentax.core.collocation.compute_amp_collocation_points(eta, chi1, chi2, mode)

Compute amplitude values at collocation points using fits.

Uses inspiral_amp_cp fits at three time points: [-2000, -250, -150]M.

Parameters:

• eta (float | Array) – Symmetric mass ratio.

• chi1 (float | Array) – Dimensionless spin z-components.

• chi2 (float | Array) – Dimensionless spin z-components.

• mode (int) – Mode identifier (22, 21, 33, 44, 55).

Returns:

Amplitude values at the 3 collocation points.

Return type:

jnp.ndarray

phentax.core.collocation.compute_omega_collocation_points(eta, chi1, chi2, omega_pn_coeffs)

Compute omega values at collocation points.

The first point uses the PN ansatz at thetaini, the remaining 5 use inspiral_freq_cp fits.

Parameters:

• eta (float | Array) – Symmetric mass ratio.

• chi1 (float | Array) – Dimensionless spin z-components.

• chi2 (float | Array) – Dimensionless spin z-components.

• omega_pn_coeffs (jnp.ndarray) – Array of 6 PN coefficients.

Returns:

(omega_values, tt0, tEarly) - omega values at 6 collocation points, t0 from fit, and tEarly value.

Return type:

tuple

phentax.core.collocation.compute_omega_pseudo_pn_coeffs(omega_pn_coeffs, omega_collocation_values)

Compute pseudo-PN coefficients for omega inspiral ansatz.

Solves the linear system from Eq. 15 in arXiv:2012.11923:

B[i] = 4/(theta[i]^3) * (omega_fit[i] - pn_omega[i]) A[i,j] = theta[i]^(8+j) A * c = B

Parameters:

• omega_pn_coeffs (jnp.ndarray) – Array of 6 PN coefficients.

• omega_collocation_values (jnp.ndarray) – Omega values at 6 collocation points (from fits or PN ansatz).

Returns:

The 6 pseudo-PN coefficients.

Return type:

OmegaPseudoPNCoeffs

phentax.core.collocation.pn_ansatz_omega(theta, omega_pn_coeffs)

TaylorT3 PN omega ansatz.

Evaluates Eq. 6b from arXiv:2012.11923.

Parameters:

• theta (float | Array) – Dimensionless frequency parameter theta = (-eta * t / 5)^(-1/8).

• omega_pn_coeffs (jnp.ndarray) – Array of 6 PN coefficients [omega1PN, omega1halfPN, omega2PN, omega2halfPN, omega3PN, omega3halfPN].

Returns:

TaylorT3 omega value.

Return type:

float | Array

Utilities

Spherical Harmonics

Spin-weighted spherical harmonics

Jax implementation of -2 spin-weighted spherical harmonics. Enables jitted, vmapped and differentiable computation of \(_{-2}Y_{\ell,m}\).

phentax.utils.ylm.spin_weighted_spherical_harmonic(theta, phi, ell=2, emm=2)

Compute spin-weighted spherical harmonic \(_{-2}Y_{\ell,m}(\theta, \phi)\).

Optimized for JAX using explicit half-angle formulas to avoid branching. Valid for s=-2 and specific modes used in gravitational waves.

Parameters:

• theta (float | Array) – Polar angle (inclination) in radians.

• phi (float | Array) – Azimuthal angle in radians.

• ell (int | Array, default 2) – Orbital angular momentum quantum number.

• emm (int | Array, default 2) – Azimuthal quantum number.

Returns:

Value of the spin-weighted spherical harmonic.

Return type:

jnp.ndarray

phentax.utils.ylm.spin_weighted_spherical_harmonic_all_modes(theta, phi, ells, emms)

Vectorized computation of multiple spin-weighted spherical harmonics.

Parameters:

• theta (float | Array) – Polar angle (inclination) in radians.

• phi (float | Array) – Azimuthal angle in radians.

• ells (Array) – Array of orbital angular momentum quantum numbers.

• emms (Array) – Array of azimuthal quantum numbers.

Returns:

Array of spin-weighted spherical harmonics for each (ell, emm).

Return type:

jnp.ndarray

Grid Generation

Coarse graining

Utility functions for the creation of time grids.

phentax.utils.coarse_graining.estimate_adaptive_steps(eta, tmin, tmax)

Estimate the number of adaptive grid steps needed across a batch of binaries.

Uses the analytical solution of the leading-order ODE to predict the total number of grid points, then returns a value rounded up to the nearest BUCKET_SIZE for JIT cache friendliness.

The estimate accounts for the three-region grid structure:

1. Post-merger (tmax → 0): coarse uniform with step C_post.

2. Fine uniform (0 → ≈ −1): step C.

3. Adaptive (≈ −1 → tmin): step C |t|^{3/8}.

Parameters:

• eta (float | Array) – Symmetric mass ratio(s).

• tmin (float | Array) – Minimum time(s) (start of the grid).

• tmax (float | Array) – Maximum time(s) (end of the grid).

Returns:

Estimated number of required steps (with safety margin), rounded up to the nearest BUCKET_SIZE.

Return type:

int

phentax.utils.coarse_graining.estimate_adaptive_steps_from_T(T, delta_t=15.0)

Estimate adaptive grid size from observation time and time step only.

Uses worst-case symmetric mass ratio (eta = 0.25, equal mass) to guarantee the grid is large enough for any binary. The result depends only on user-controlled quantities, so it can be computed once at init time without causing JIT recompilation.

Parameters:

• T (float) – Total observation time in seconds.

• delta_t (float, default 15.0) – Time step in seconds.

Returns:

Estimated number of required steps, rounded up to the nearest BUCKET_SIZE for JIT-cache friendliness.

Return type:

int

phentax.utils.coarse_graining.generate_adaptive_grid(etas, tmins, tmaxs, Mdelta_ts, max_steps=10000)

Batch version of generate_adaptive_grid.

Parameters:

• etas (float | Array) – Symmetric mass ratios.

• tmins (float | Array) – Minimum times (start of the valid region).

• tmaxs (float | Array) – Maximum times (end of the grid).

• Mdelta_ts (float | Array) – User-specified time steps in units of total mass M. Used to set the post-merger step size (see _generate_adaptive_grid).

• max_steps (int, optional) – Maximum number of steps in the grid.

Returns:

• grids: (batch, max_steps)

• masks: (batch, max_steps)

Return type:

tuple[jnp.ndarray, jnp.ndarray]

phentax.utils.coarse_graining.generate_uniform_grid(tmins, tmaxs, delta_ts, max_steps=10000)

Batch version of generate_uniform_grid.

Parameters:

• tmins (float | Array) – Minimum times (start of the valid region).

• tmaxs (float | Array) – Maximum times (end of the grid).

• delta_ts (float | Array) – Time step sizes.

• max_steps (int, optional) – Maximum number of steps in the grid.

Returns:

• grids: (batch, max_steps)

• masks: (batch, max_steps)

Return type:

tuple[jnp.ndarray, jnp.ndarray]

phentax.utils.coarse_graining.leading_order_delta_t(eta, t)

Compute adaptive time step at leading order in omega.

Parameters:

• eta (float | Array) – Symmetric mass ratio.

• t (float | Array) – Time in units of total mass M.

Returns:

Leading order time step delta_t = 1 / (10 * f_LO), where f_LO is the leading order GW frequency at time t.

Return type:

float | Array

phentax.utils.coarse_graining.leading_order_factor(eta)

Compute the leading-order (positive) factor C in the adaptive time step formula.

Parameters:

eta (float | Array) – Symmetric mass ratio.

Returns:

Leading-order factor C such that \(\Delta t = C \cdot |t|^{3/8}\) in the inspiral.

Return type:

float | Array

phentax.utils.coarse_graining.masked_evaluate(time_grid, mask, func, fill_value=0j)

Evaluate a function on a grid only where the mask is True.

This uses jax.lax.cond inside a vmap to avoid expensive computation on padded/invalid grid points. Since the grid is sorted (padded values are clustered), this is efficient on GPUs due to low warp divergence.

Parameters:

• time_grid (Array) – Time points.

• mask (Array) – Boolean mask (True indicates valid points).

• func (Callable[[Array], Array]) – Function to evaluate. Must accept a scalar time and return a scalar/array.

• fill_value (float | complex, optional) – Value to return where mask is False, by default 0.0j.

Returns:

Result of func(t) where mask is True, fill_value otherwise.

Return type:

Array

Conditioning

Waveform conditioning utilities for FFT preparation.

phentax.utils.conditioning.condition_polarizations(time, h_plus, h_cross, dt, mask=None, t_taper_start=1.0, t_taper_end=1.0, t_buffer=10.0, pad_to_next_pow2=True)

Conditions the waveform for FFT: 1. Tapers the start and end of the original signal. 2. Adds a zero-buffer at the start. 3. Optionally pads the end to the next power of 2.

Parameters:

• time (Time array.)

• h_plus (Plus polarization strain array.)

• h_cross (Cross polarization strain array.)

• dt (Time step.)

• mask (Optional boolean mask indicating valid data points.) – If provided, the end taper is applied relative to the valid length.

• t_taper_start (Duration of the start taper (on the signal).)

• t_taper_end (Duration of the end taper.)

• t_buffer (Duration of the zero-buffer to add at the start.)

• pad_to_next_pow2 (Whether to pad the total length to the next power of 2.)

Return type:

tuple[Array, Array, Array]

Returns:

time_cond: Conditioned time array. h_plus_cond: Conditioned plus polarization strain array. h_cross_cond: Conditioned cross polarization strain array.

phentax.utils.conditioning.pad_and_shift(time, strain, dt, t_buffer)

Pads the waveform with zeros at the start and extends the time array backwards.

Parameters:

• time (Time array of shape (N,).)

• strain (Strain array of shape (N,).)

• dt (Time step.)

• t_buffer (Duration of the buffer to add (in seconds).)

Return type:

tuple[Array, Array]

Returns:

time_padded: New time array. strain_padded: New strain array with zero-padding at the start.

phentax.utils.conditioning.planck_taper(N, n_left, n_right)

Generates a Planck window of length N.

Parameters:

• N (Total length of the window.)

• n_left (Number of points for the left taper (rise).)

• n_right (Number of points for the right taper (decay).)

Return type:

Array

Returns:

window: Array of shape (N,) with values between 0 and 1.

phentax.utils.conditioning.planck_taper_masked(N, n_valid, n_left, n_right)

Generates a Planck window of length N, tapering at the start and at n_valid.

Parameters:

• N (Total length of the array.)

• n_valid (Index of the last valid point (or number of valid points).) – The taper will end at index n_valid-1.

• n_left (Number of points for the left taper.)

• n_right (Number of points for the right taper.)

Return type:

Array

Returns:

window: Array of shape (N,) with values between 0 and 1.

Utilities

Utility

Utility functions for phentax.

Contains helper functions for mass ratios, spins, unit conversions, and spin-weighted spherical harmonics, all implemented in pure JAX.

phentax.utils.utility.amp_nr_to_si(h_nr, distance_mpc, total_mass)

Convert strain amplitude from NR units to SI units.

Parameters:

• h_nr (array) – Strain in NR units (dimensionless, at unit distance).

• distance_mpc (float | Array) – Luminosity distance in Megaparsecs.

• total_mass (float | Array) – Total mass in solar masses.

Returns:

Strain in SI units.

Return type:

array

phentax.utils.utility.check_equal_bhs(m1, m2, s1z, s2z)

Check if the binary black hole system is equal-mass and equal-spin.

Parameters:

• m1 (float | Array) – Masses of the two black holes.

• m2 (float | Array) – Masses of the two black holes.

• s1z (float | Array) – Dimensionless spin z-components of the two black holes.

• s2z (float | Array) – Dimensionless spin z-components of the two black holes.

Returns:

True if equal-mass and equal-spin, False otherwise.

Return type:

bool | Array

phentax.utils.utility.chi_eff(eta, s1z, s2z)

Compute effective spin parameter.

Parameters:

• eta (float | Array) – Symmetric mass ratio.

• s1z (float | Array) – Dimensionless spin of primary along orbital angular momentum.

• s2z (float | Array) – Dimensionless spin of secondary along orbital angular momentum.

Returns:

Effective spin chi_eff = (m1*s1z + m2*s2z) / (m1 + m2).

Return type:

float | Array

phentax.utils.utility.eta_from_q(q)

Compute symmetric mass ratio from mass ratio \(q = m_1/m_2 >= 1\).

Parameters:

q (float | Array) – Mass ratio q >= 1.

Returns:

Symmetric mass ratio eta.

Return type:

float | Array

phentax.utils.utility.hz_to_mass(f_hz, total_mass)

Convert frequency from Hz to dimensionless units (Mf).

Parameters:

• f_hz (float | Array) – Frequency in Hz.

• total_mass (float | Array) – Total mass in solar masses.

Returns:

Dimensionless frequency Mf.

Return type:

float | Array

phentax.utils.utility.m1ofeta(eta, total_mass=1.0)

Compute primary mass from symmetric mass ratio.

Parameters:

• eta (float) – Symmetric mass ratio in [0, 0.25].

• total_mass (float, default 1.0) – Total mass (m1 + m2). If 1.0, returns dimensionless mass fraction.

Returns:

Primary (larger) mass.

Return type:

float

phentax.utils.utility.m2ofeta(eta, total_mass=1.0)

Compute secondary mass from symmetric mass ratio.

Parameters:

• eta (float | Array) – Symmetric mass ratio in [0, 0.25].

• total_mass (float | Array, default 1.0) – Total mass (m1 + m2). If 1.0, returns dimensionless mass fraction.

Returns:

Secondary (smaller) mass.

Return type:

float | Array

phentax.utils.utility.mass_to_hz(mf, total_mass)

Convert frequency from dimensionless units (Mf) to Hz.

Parameters:

• mf (float | Array) – Dimensionless frequency Mf.

• total_mass (float | Array) – Total mass in solar masses.

Returns:

Frequency in Hz.

Return type:

float | Array

phentax.utils.utility.mass_to_second(t_m, total_mass)

Convert time from dimensionless units (t/M) to seconds.

Parameters:

• t_m (float | Array) – Dimensionless time t/M.

• total_mass (float | Array) – Total mass in solar masses.

Returns:

Time in seconds.

Return type:

float | Array

phentax.utils.utility.mode_to_int(ell, emm)

Convert \((\ell, m)\) mode indices to integer key.

Parameters:

• ell (int) – Orbital angular momentum quantum number.

• emm (int) – Azimuthal quantum number.

Returns:

Integer key: \(10*\ell + abs(m)\) for positive \(m\) modes.

Return type:

int

phentax.utils.utility.mode_to_lm(mode)

Convert integer mode key to \((\ell, m)\) mode indices. Assumes positive \(m\) modes.

Parameters:

mode (int | Array) – Integer key: \(10*\ell + abs(m)\) for positive \(m\) modes.

Returns:

\((\ell, m)\) mode indices.

Return type:

tuple of Array

phentax.utils.utility.qofeta(eta)

Compute mass ratio q = m1/m2 >= 1 from symmetric mass ratio.

Parameters:

eta (float | Array) – Symmetric mass ratio in [0, 0.25].

Returns:

Mass ratio q >= 1.

Return type:

float | Array

phentax.utils.utility.sTotR(eta, s1z, s2z)

Compute reduced total spin parameter S = (m1^2*s1z + m2^2*s2z) / (m1^2 + m2^2).

This is the spin combination used in PhenomT fits.

Parameters:

• eta (float | Array) – Symmetric mass ratio.

• s1z (float | Array) – Dimensionless spin of primary along orbital angular momentum.

• s2z (float | Array) – Dimensionless spin of secondary along orbital angular momentum.

Returns:

Reduced total spin S.

Return type:

float | Array

phentax.utils.utility.second_to_mass(t_sec, total_mass)

Convert time from seconds to dimensionless units (t/M).

Parameters:

• t_sec (float | Array) – Time in seconds.

• total_mass (float | Array) – Total mass in solar masses.

Returns:

Dimensionless time t/M.

Return type:

float | Array

phentax.utils.utility.solve_3x3_explicit(A, b)

Solves Ax = b for 3x3 matrix A using Cramer’s rule / explicit inverse. Much faster than jnp.linalg.solve for small matrices on GPU inside vmap.

Parameters:

• A (Array) – Coefficient matrix of shape (3, 3).

• b (Array) – Right-hand side vector of shape (3,).

Returns:

Solution vector x of shape (3,).

Return type:

Array