tools

The RIFT.misc.tools module provides a suite of utilities for transforming gravitational wave source parameters between different coordinate systems. These transformations are critical for linearizing the likelihood surface and optimizing the sampling process.

Mass Parameter Conversions

The module provides standard conversions between different mass representations: - Component Masses ($mathbf{m_1, m_2}$): The individual masses of the binary components. - Chirp Mass ($mathbf{mathcal{M}_c}$): The leading-order parameter determining the frequency evolution of the signal. - Symmetric Mass Ratio ($mathbf{eta}$): A measure of the mass asymmetry of the binary. - Mass Ratio ($mathbf{q}$): Defined as $m_2 / m_1$.

Key functions include m1m2ToMc, qToeta, and McqTom1m2.

PN Phase and Mu-Parameters

A central feature of RIFT is the transformation of physical parameters into a more “linear” space based on Post-Newtonian (PN) phase coefficients.

1. PN Phase Coefficients: Functions like psi0, psi2, and psi3 calculate the phase coefficients at 0PN, 1PN, and 1.5PN orders, respectively.

2. The $mathbf{U}$ Matrix: RIFT uses a linear transformation matrix $mathbf{U}$ to map these phase coefficients to a set of parameters denoted as $mu_1, mu_2, mu_3$. This mapping is designed to decouple the parameters and make the likelihood surface more Gaussian, which significantly improves the efficiency of interpolators and samplers.

3. Inversion: Since the mapping from physical parameters to $mu$ parameters is non-linear, the module implements numerical inversion (e.g., using bisection search in mu1mu2etaToMc) to recover physical parameters from $mu$ values.

High-Level Converters

For ease of use, the module provides dictionary-based converters that can be integrated directly into the sampling pipeline: - convert_m1m2chi1chi2_to_Mcqmu1mu2: Transforms a set of component masses and spins into chirp mass, mass ratio, and $mu$ parameters. - convert_Mcqchi1chi2_to_mu1mu2: Specifically targets the $mu$-parameter mapping.

Sampling and Jacobians

When changing coordinate systems during sampling, the prior volume must be preserved. The function m1m2chi1chi2Tomu1mu2qchi2Jacobian computes the determinant of the transformation Jacobian, allowing the sampler to correctly weight the prior in the $mu$-coordinate space.

API Reference

RIFT.misc.tools.McqToMtot(Mc, q)

RIFT.misc.tools.McqTom1m2(Mc, q)

RIFT.misc.tools.Mcqchi1chi2Tomu1mu2mu3(mc, q, chi1, chi2)

chirpmass, q, chi1, chi2 to mu1, mu2, mu3

RIFT.misc.tools.convert_Mcqchi1chi2_to_mu1mu2(parameters)

Convert Mc, q, chi1, chi2 to mu1, mu2 and add them to parameters.

Parameters

parameters: dict

Returns

converted_parameters: dict

RIFT.misc.tools.convert_m1m2chi1chi2_to_Mcqmu1mu2(parameters)

Convert m1, m2, chi1, chi2 to Mc, q, mu1, mu2 and add them to parameters.

Parameters

parameters: dict

Returns

converted_parameters: dict

RIFT.misc.tools.convert_mu1mu2qchi2_to_Mcchi1(parameters)

Convert mu1, mu2, q, chi2 to Mc, chi1 and add them to parameters.

Parameters

parameters: dict

Returns

converted_parameters: dict

RIFT.misc.tools.etaToq(eta)

eta=m1*m2/(m1+m2)**2 to q=m2/m1

RIFT.misc.tools.m1m2(Mc, eta)

RIFT.misc.tools.m1m2ToMc(m1, m2)

RIFT.misc.tools.m1m2chi1chi2Tomu1mu2qchi2Jacobian(Mc, q)

Jacobian of the transformation from m1, m2, chi1, chi2 to mu1, mu2, q, chi2

RIFT.misc.tools.mu1mu2etaToMc(mu1, mu2, eta)

Convert mu1, mu2, eta=m1*m2/(m1+m2)**2 into chirpmass using bisection search.

RIFT.misc.tools.mu1mu2qchi2ToMcqchi1chi2(mu1, mu2, q, chi2)

mu1, mu2, q=m2/m1, chi2 to chirpmass, q, chi1, chi2

RIFT.misc.tools.mu2Mcetachi2Tochi1(mu2, Mc, eta, chi2)

mu2, chirpmass, eta=m1*m2/(m1+m2)**2, chi2 to chi1

RIFT.misc.tools.psi0(Mc)

chirpmass to the 0PN phase coefficient

RIFT.misc.tools.psi2(Mc, eta)

chirpmass and eta=m1*m2/(m1+m2)**2 to the 1PN phase coefficient

RIFT.misc.tools.psi3(Mc, q, a1z, a2z)

RIFT.misc.tools.qToeta(q)

q=m2/m1 to eta=m1*m2/(m1+m2)**2

RIFT.misc.tools.qa1za2zTobeta(q, a1z, a2z)

RIFT.misc.tools.transform_m1m2s1zs2z_mu1mu2qs2z(m1, m2, s1z, s2z)

component masses: m1, m2 and z-components of spins: s1z, s2z to mu1, mu2, q=m2/m1, s2z

RIFT.misc.tools.transform_mu1mu2qs2z_m1m2s1zs2z(mu1, mu2, q, s2z)

mu1, mu2, q=m2/m1, z-component of secondary spin to component masses: m1, m2 and z-components of spins: s1z, s2z