API Reference

regular_precession

Regular Precession: When L moves in a cone around J with an opening angle theta_tilde that changes on a radiation reaction timescale, with frequency omega_tilde (also changing on the same timescale) and a phase gamma_P.

Model presented in following paper : arXiv:2509.10628 [gr-qc]

class regular_precession.Regular_precession(params)[source]

Bases: object

get_total_mass()[source]

Calculate the total mass of the binary system from the chirp mass and symmetric mass ratio [s], M = M_c / eta**(3/5).

Parameters:

mczfloat: Chirp mass [s].
etafloat: Symmetric mass ratio [dimensionless].

Returns:

total_massfloat: Total mass of the binary system.

get_f_cut()[source]

Compute the cut-off frequency where the binary coalesces, equation 13 in the paper (https://arxiv.org/pdf/2509.10628), f_cut = 1/(6**(3/2)*pi*M), where M is the total mass of the binary.

Parameters:

get_total_massfunction call: Computes the total mass of the binary system given the chirp mass and symmetric mass ratio, M = M_c / eta**(3/5).

Returns:

f_cutfloat: Cut-off frequency.

get_theta_LJ(f)[source]

Angle between L and J at a given frequency [rad] in the L-J plane, equation 18a in the paper (https://arxiv.org/pdf/2509.10628), theta_LJ = 0.1/(4*eta) * theta_tilde * (f/f_cut)**(1/3), where f_cut is the cut-off frequency, theta_tilde is the dimensionless precession amplitude.

Parameters:

ffloat or array_like: Frequency where the angle is to be calculated [Hz].
etafloat: Symmetric mass ratio.
theta_tildefloat: Dimensionless precession amplitude parameter.
get_f_cutfunction call: Computes the cut-off frequency, f_cut = 1/(6**(3/2)*pi*M), where M is the total mass of the binary.

Returns:

theta_LJfloat or array_like: Angle between L and J at a given frequency.

get_phi_LJ(f)[source]

Angle between projection of L in the x-y plane and x axis in source frame at a given frequency [rad], equation 19 in the paper (https://arxiv.org/pdf/2509.10628), phi_LJ = gamma_P + int_{f_min}^f (Omega_LJ (df’/dt)**(-1)) df’, where Omega_LJ is the precession frequency.

Parameters:

ffloat or array_like: Frequency where the angle is to be calculated [Hz].
omega_tildefloat: Dimensionless precession frequency parameter [Dimensionless].
mczfloat: Chirp mass [s].
gamma_Pfloat: Precession phase at reference frequency [rad].
get_total_massfunction call: Computes the total mass of the binary system, M = M_c / eta**(3/5), given the chirp mass M_c and symmetric mass ratio eta [s].
get_f_cutfunction call: Computes the cut-off frequency, f_cut = 1/(6**(3/2)*pi*M), where M is the total mass of the binary [Hz].

Returns:

phi_LJfloat or array_like: Angle between projection of L in the x-y plane and x axis in source frame at a given frequency.

amp_prefactor()[source]

Amplitude prefactor calculated using chirp mass and distance, equation 6 in the paper (https://arxiv.org/pdf/2509.10628), A = sqrt(5/96) * (pi**(-2/3)) * (M_c**(5/6)) / D_L, where M_c is the chirp mass and D_L is the luminosity distance.

Parameters:

mczfloat: Chirp mass [s].
distfloat: Luminosity distance [s].

Returns:

amp_prefactorfloat: Amplitude prefactor.

Return type:

float

precession_angles()[source]

Compute angles important for the precession model, specifically the angle between J and N, and the angle between the x-axis of the source frame and H in the sky frame. Equations A4, A6a, A6b in the paper (https://arxiv.org/abs/2006.10290).

Parameters:

theta_Jfloat: Binary plane inclination - polar angle for J in detector frame [rad].
phi_Jfloat: Binary plane azimuthal angle for J in detector frame [rad].
theta_Sfloat: Sky inclination - polar angle for line of sight in detector frame [rad].
phi_Sfloat: Sky azimuthal angle for line of sight in detector frame [rad].

Returns:

cos_i_JNfloat: Cosine of the angle between the total angular momentum and the line of sight.
sin_i_JNfloat: Sine of the angle between the total angular momentum and the line of sight.
cos_o_XHfloat: Cosine of the angle between the x-axis of the source frame and H in the detector frame.
sin_o_XHfloat: Sine of the angle between the x-axis of the source frame and H in the detector frame.

LdotN(f)[source]

Cosine of the angle between L and N, equation A10 in the paper (https://arxiv.org/pdf/2509.10628).

Parameters:

ffloat or array_like: Frequency at which to calculate the dot product [Hz].
get_theta_LJfunction call: Computes the angle between L and J, equation 18a.
get_phi_LJfunction call: Computes the azimuthal angle of L in source frame, equation 18b.
precession_anglesfunction call: Computes orientation angles, equations A4, A6a, A6b.

Returns:

LdotNfloat or array_like: Dot product of L and N (cosine of angle between L and N).

beam_pattern_amplitude_and_phase(f)[source]

Beam pattern functions for + and x polarizations, equations 3, 4a, 4b in the paper (https://arxiv.org/pdf/2509.10628).

Parameters:

ffloat or array_like: Frequency at which to calculate the beam pattern [Hz].
theta_Sfloat: Sky inclination angle [rad].
phi_Sfloat: Sky azimuthal angle [rad].
get_theta_LJfunction call: Computes the angle between L and J, equation 18a.
get_phi_LJfunction call: Computes the azimuthal angle of L in source frame, equation 18b.
precession_anglesfunction call: Computes orientation angles, equations A4, A6a, A6b.

Returns:

C_ampfloat or array_like: Amplitude of the beam pattern functions for + and x polarizations.
sin_2pafloat or array_like: Sine of 2 times the polarization angle + alpha (for x polarization).
cos_2pafloat or array_like: Cosine of 2 times the polarization angle + alpha (for + polarization).

amplitude(f)[source]

GW amplitude, equation 10 in the paper (https://arxiv.org/pdf/2509.10628) - also in Apostolatos+ 1994 as equation 7a.

Parameters:

ffloat or array_like: Frequency at which the amplitude is to be calculated [Hz].
LdotNfunction call: Computes the dot product between L and N, equation A10.
beam_pattern_amplitude_and_phasefunction call: Computes beam pattern functions, equations 3, 4a, 4b.
amp_prefactorfunction call: Computes amplitude prefactor, equation 6.

Returns:

ampfloat or array_like: Amplitude of the GW signal.

Return type:

array

phase_phi_P(f)[source]

Polarization phase of the GW signal, equation 11 in the paper (https://arxiv.org/pdf/2509.10628).

Parameters:

ffloat or array_like: Frequency at which the phase is to be calculated [Hz].
LdotNfunction call: Computes the dot product between L and N, equation A10.
beam_pattern_amplitude_and_phasefunction call: Computes beam pattern functions, equations 3, 4a, 4b.

Returns:

phi_pfloat or array_like: Polarization phase of the GW signal.

f_dot(f)[source]

df/dt from Cutler & Flanagan 1994, equation 20 in the paper (https://arxiv.org/pdf/2509.10628).

Parameters:

ffloat or array_like: Frequency at which the derivative is to be calculated [Hz].
mczfloat: Chirp mass [s].

Returns:

f_dotfloat or array_like: df/dt at a given frequency [Hz/s].

integrand_delta_phi(y, f)[source]

Integrand for delta phi p, equation 12 and A19 in the paper (https://arxiv.org/pdf/2509.10628).

Parameters:

yfloat: Variable for the integral (typically 0 for initial condition).
ffloat or array_like: Frequency at which the integrand is to be calculated [Hz].
omega_tildefloat: Dimensionless precession frequency parameter.
LdotNfunction call: Computes the dot product between L and N, equation A10.
precession_anglesfunction call: Computes orientation angles, equations A11, A12, A13.
f_dotfunction call: Computes frequency derivative, equation 20.
get_theta_LJfunction call: Computes the angle between L and J, equation A14.
get_phi_LJfunction call: Computes the azimuthal angle of L in source frame, equation A15.
get_f_cutfunction call: Computes the cut-off frequency, equation A16.
get_total_massfunction call: Computes the total mass of the binary, equation A17.

Returns:

integrand_delta_phifloat or array_like: Integrand for the delta phi p.

phase_delta_phi(f)[source]

Integrates the delta_phi integrand from 0 to f to get the phase correction to precession phase, integrating equation 12/A19 in the paper (https://arxiv.org/pdf/2509.10628).

Parameters:

ffloat or array_like: Frequency at which the phase is to be calculated [Hz].
integrand_delta_phifunction call: Computes the integrand for phase correction, equation 12/A19.

Returns:

integralfloat or array_like: Integral of the integrand_delta_phi.

Psi(f)[source]

GW phase up to 2 PN order, equation 7 in https://arxiv.org/pdf/2509.10628.

Parameters:

ffloat or array_like: Frequency at which the phase is to be calculated [Hz].
mczfloat: Chirp mass [s].
etafloat: Symmetric mass ratio.
t_cfloat: Coalescence time [s].
phi_cfloat: Coalescence phase [rad].
get_total_massfunction call: Computes the total mass of the binary.

Returns:

Psifloat or array_like: GW phase of the GW signal.

precessing_strain(f, delta_f=0.25, frequencySeries=True)[source]

GW signal with regular precession, equation 9 in https://arxiv.org/pdf/2509.10628.

Parameters:

ffloat or array_like: Frequency at which the strain is to be calculated [Hz].
delta_ffloat, optional: Frequency resolution [Hz]. Default is 0.25.
frequencySeriesbool, optional: Whether to return a FrequencySeries object. Default is True.
amplitudefunction call: Computes the GW amplitude, equation 10.
Psifunction call: Computes the GW phase, equation 7.
phase_phi_Pfunction call: Computes the polarization phase, equation 11.
phase_delta_phifunction call: Computes the precession phase correction, equation A19.

Returns:

precessing_strainarray or FrequencySeries: GW signal with regular precession.

cos_theta_L(f)[source]

Evolution of the orbital angular momentum vector in the detector frame (cosine of polar angle).

Parameters:

ffloat or array_like: Frequency at which the angle is to be calculated [Hz].
theta_Sfloat: Sky inclination angle [rad].
get_theta_LJfunction call: Computes the angle between L and J.
get_phi_LJfunction call: Computes the azimuthal angle of L in source frame.
precession_anglesfunction call: Computes orientation angles, equations A4, A6a, A6b.

Returns:

L_zfloat or array_like: Cosine of the polar angle for the orbital angular momentum vector.

phi_L(f)[source]

Evolution of the orbital angular momentum vector in the detector frame (azimuthal angle).

Parameters:

ffloat or array_like: Frequency at which the angle is to be calculated [Hz].
theta_Sfloat: Sky inclination angle [rad].
phi_Sfloat: Sky azimuthal angle [rad].
get_theta_LJfunction call: Computes the angle between L and J, equation 18a.
get_phi_LJfunction call: Computes the azimuthal angle of L in source frame, equation 19.
precession_anglesfunction call: Computes orientation angles, equations A4, A6a, A6b.

Returns:

Phi_Lfloat or array_like: Azimuthal angle of the orbital angular momentum vector.

systems_lib

Precessing & Non-precessing systems library.

This module defines system parameters and constants for use in regular precession waveform modeling.

mismatch_n_SNR

Mismatch and SNR calculations for regular precession waveforms.

This module provides functions to compute mismatches, SNRs, and related quantities for precessing and non-precessing systems.

mismatch_n_SNR.Sn(f, delta_f=0.25, frequencySeries=True)[source]

Compute the ALIGO noise curve from arXiv:0903.0338.

Parameters:

farray_like: Frequency array.
delta_ffloat, optional: Frequency step (default 0.25).
frequencySeriesbool, optional: If True, return a FrequencySeries object (default True).

Returns:

Sn_valFrequencySeries or array_like: Noise curve values as FrequencySeries if frequencySeries is True, else as array.

mismatch_n_SNR.get_mismatch_rp(source, template, update_tc_phic=True)[source]

Calculate the mismatch between a source and template waveform.

Parameters:

sourcedict: Source system parameters.
templatedict: Template system parameters.
update_tc_phicbool, optional: Whether to update template’s t_c and phi_c (default True).

Returns:

dict: Dictionary with keys ‘mismatch’, ‘phase’, and ‘ind’.

mismatch_n_SNR.opt_mismatch_gammaP(rp_params, np_params, size_of_gammaP_arr)[source]

Compute mismatch as a function of gamma_P.

Parameters:

rp_paramsdict: Regular precession parameters.
np_paramsdict: Non-precessing parameters.
size_of_gammaP_arrint: Number of gamma_P values to scan.

Returns:

gammaP_arrarray_like: Array of gamma_P values.
mismatch_arrarray_like: Array of mismatch values.
ind_arrarray_like: Array of indices of best match.
phase_m_arrarray_like: Array of phase values at best match.

mismatch_n_SNR.ideal_params(rp_params, min_gammaP)[source]

Return ideal parameters for a given minimum gamma_P.

Parameters:

rp_paramsdict: Regular precession parameters.
min_gammaPfloat: Value of gamma_P for which to return ideal params.

Returns:

dict: Updated rp_params.

mismatch_n_SNR.opt_mismatch_extremas_gammaP(rp_params, np_params, size_of_gammaP_arr, return_tc_phic)[source]

Find the minimum and maximum mismatch for an array of gamma_P values.

Parameters:

rp_paramsdict: Regular precession parameters.
np_paramsdict: Non-precessing parameters.
size_of_gammaP_arrint: Size of gamma_P array.
return_tc_phicbool: Whether to return t_c and phi_c.

Returns:

min_mismatchfloat: Minimum mismatch.
max_mismatchfloat: Maximum mismatch.
min_gammaPfloat: Gamma_P value at minimum mismatch.
max_gammaPfloat: Gamma_P value at maximum mismatch.
min_indint, optional: Index of minimum mismatch (if return_tc_phic is True).
min_phasefloat, optional: Phase at minimum mismatch (if return_tc_phic is True).

mismatch_n_SNR.get_SNRs(rp_params, np_params, redshift=100)[source]

Get SNRs for regular precession (RP) and non-precessing (NP) signals, and cross terms.

Parameters:

rp_paramsdict: Regular precession parameters.
np_paramsdict: Non-precessing parameters.
redshiftfloat, optional: Redshift (default 100, which means no redshift correction).

Returns:

SNR_dictdict: Dictionary with SNR values for RP, NP, and cross terms.

Return type:

dict

mismatch_n_SNR.lindblom_inequality(rp_params, np_params, size_of_gammaP_arr, rp_SNR_term=True, np_SNR_term=False)[source]

Compute the Lindblom inequality for waveform distinguishability.

Parameters:

rp_paramsdict: Regular precession parameters.
np_paramsdict: Non-precessing parameters.
size_of_gammaP_arrint: Size of gamma_P array.
rp_SNR_termbool, optional: Use RP SNR term (default True).
np_SNR_termbool, optional: Use NP SNR term (default False).

Returns:

lindblomfloat or None: Value of the Lindblom inequality, or None if no term selected.

mismatch_n_SNR.same_total_mass_diff_chirp(q, mcz, rp_params, np_params)[source]

Vary q while keeping total mass constant. Returns new parameter dicts and chirp mass.

Parameters:

qfloat: Mass ratio.
mczfloat: Chirp mass.
rp_paramsdict: Regular precession parameters.
np_paramsdict: Non-precessing parameters.

Returns:

rp_paramsdict: Updated regular precession parameters.
np_paramsdict: Updated non-precessing parameters.
mcz_newfloat: New chirp mass.
etafloat: Symmetric mass ratio.

mismatch_n_SNR.redshift_to_luminosity_distance(z)[source]

Convert redshift to luminosity distance in standard Lambda CDM cosmology.

Parameters:

zfloat: Redshift.

Returns:

luminosity_distancefloat: Luminosity distance in Gpc.

Return type:

float

mismatch_n_SNR.redshifted_new_params(z, rp_params)[source]

Get redshifted parameters for a system.

Parameters:

zfloat: Redshift.
rp_paramsdict: Regular precession parameters.

Returns:

rp_paramsdict: Updated regular precession parameters with redshifted mass and distance.

Return type:

dict