Transform utils
Low-level transform utilities for compact-binary parameter spaces.
Three sections, each self-contained:
-
Mass — conversions between component masses (m1, m2) and derived parameterisations: total mass M, chirp mass Mc, mass ratio q, symmetric mass ratio eta.
-
Spin — J-frame spin-angle ↔ Cartesian-spin component conversions, plus the internal orbital-angular-momentum helper they depend on.
-
Sky / detector coordinate — sky-position transforms between the equatorial (RA/Dec) and detector-frame (zenith/azimuth) representations, including Euler rotation matrix construction.
Functions:
| Name | Description |
|---|---|
M_eta_to_m1_m2 |
Transforms the total mass M and symmetric mass ratio eta to the primary mass m1 |
M_q_to_m1_m2 |
Transforms the total mass M and mass ratio q to the primary mass m1 and |
Mc_eta_to_m1_m2 |
Transforming the chirp mass M_c and symmetric mass ratio eta to the primary mass m1 |
Mc_q_to_m1_m2 |
Transforms the chirp mass M_c and mass ratio q to the primary mass m1 and |
angle_rotation |
Transforming the azimuthal angle and zenith angle in Earth frame |
cartesian_spin_to_spin_angles |
Transforming the cartesian spin parameters to the spin angles. |
eta_to_q |
Transforming the symmetric mass ratio eta to the mass ratio q. |
euler_rotation |
Calculate the rotation matrix mapping the vector (0, 0, 1) to delta_x |
m1_m2_to_M_eta |
Transforms the primary mass m1 and secondary mass m2 to the total mass M |
m1_m2_to_M_q |
Transforms the primary mass m1 and secondary mass m2 to the total mass M |
m1_m2_to_Mc_eta |
Transforms the primary mass m1 and secondary mass m2 to the chirp mass M_c |
m1_m2_to_Mc_q |
Transforms the primary mass m1 and secondary mass m2 to the chirp mass M_c |
q_to_eta |
Transforming the chirp mass M_c and mass ratio q to the symmetric mass ratio eta. |
ra_dec_to_zenith_azimuth |
Transforming the right ascension and declination to the zenith angle and azimuthal angle. |
spin_angles_to_cartesian_spin |
Transforming the spin parameters. |
zenith_azimuth_to_ra_dec |
Transforming the azimuthal angle and zenith angle in Earth frame to right ascension and declination. |
M_eta_to_m1_m2(M_tot: FloatScalar, eta: FloatScalar) -> tuple[FloatScalar, FloatScalar]
¤
Transforms the total mass M and symmetric mass ratio eta to the primary mass m1 and secondary mass m2.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
M_tot
|
Float
|
Total mass. |
required |
eta
|
Float
|
Symmetric mass ratio. |
required |
Returns:
| Type | Description |
|---|---|
tuple[FloatScalar, FloatScalar]
|
tuple[Float, Float]: Primary mass (m1) and secondary mass (m2). |
M_q_to_m1_m2(M_tot: FloatScalar, q: FloatScalar) -> tuple[FloatScalar, FloatScalar]
¤
Transforms the total mass M and mass ratio q to the primary mass m1 and secondary mass m2.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
M_tot
|
Float
|
Total mass. |
required |
q
|
Float
|
Mass ratio. |
required |
Returns:
| Type | Description |
|---|---|
tuple[FloatScalar, FloatScalar]
|
tuple[Float, Float]: Primary mass (m1) and secondary mass (m2). |
Mc_eta_to_m1_m2(M_c: FloatScalar, eta: FloatScalar) -> tuple[FloatScalar, FloatScalar]
¤
Transforming the chirp mass M_c and symmetric mass ratio eta to the primary mass m1 and secondary mass m2.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
M_c
|
Float
|
Chirp mass. |
required |
eta
|
Float
|
Symmetric mass ratio. |
required |
Returns:
| Type | Description |
|---|---|
tuple[FloatScalar, FloatScalar]
|
tuple[Float, Float]: Primary mass (m1) and secondary mass (m2). |
Mc_q_to_m1_m2(M_c: FloatScalar, q: FloatScalar) -> tuple[FloatScalar, FloatScalar]
¤
Transforms the chirp mass M_c and mass ratio q to the primary mass m1 and secondary mass m2.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
M_c
|
Float
|
Chirp mass. |
required |
q
|
Float
|
Mass ratio. |
required |
Returns:
| Type | Description |
|---|---|
tuple[FloatScalar, FloatScalar]
|
tuple[Float, Float]: Primary mass (m1) and secondary mass (m2). |
angle_rotation(zenith: FloatScalar, azimuth: FloatScalar, rotation: Float[Array, '3 3']) -> tuple[FloatScalar, FloatScalar]
¤
Transforming the azimuthal angle and zenith angle in Earth frame to the polar angle and azimuthal angle in sky frame.
Modified from bilby-cython/geometry.pyx.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
zenith
|
Float
|
Zenith angle. |
required |
azimuth
|
Float
|
Azimuthal angle. |
required |
rotation
|
Float[Array, '3 3']
|
The rotation matrix. |
required |
Returns:
| Type | Description |
|---|---|
tuple[FloatScalar, FloatScalar]
|
tuple[Float, Float]: Polar angle (theta) and azimuthal angle (phi). |
cartesian_spin_to_spin_angles(iota: FloatScalar, S1x: FloatScalar, S1y: FloatScalar, S1z: FloatScalar, S2x: FloatScalar, S2y: FloatScalar, S2z: FloatScalar, M_c: FloatScalar, q: FloatScalar, fRef: FloatLike, phiRef: FloatLike) -> tuple[FloatScalar, FloatScalar, FloatScalar, FloatScalar, FloatScalar, FloatScalar, FloatScalar]
¤
Transforming the cartesian spin parameters to the spin angles.
The code is based on the approach used in LALsimulation: https://lscsoft.docs.ligo.org/lalsuite/lalsimulation/group__lalsimulation__inference.html
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
iota
|
Float
|
Zenith angle between the orbital angular momentum and the line of sight. |
required |
S1x
|
Float
|
The x-component of the primary spin. |
required |
S1y
|
Float
|
The y-component of the primary spin. |
required |
S1z
|
Float
|
The z-component of the primary spin. |
required |
S2x
|
Float
|
The x-component of the secondary spin. |
required |
S2y
|
Float
|
The y-component of the secondary spin. |
required |
S2z
|
Float
|
The z-component of the secondary spin. |
required |
M_c
|
Float
|
The chirp mass. |
required |
q
|
Float
|
The mass ratio. |
required |
fRef
|
Float
|
The reference frequency. |
required |
phiRef
|
Float
|
The binary phase at the reference frequency. |
required |
Returns:
| Type | Description |
|---|---|
tuple[FloatScalar, FloatScalar, FloatScalar, FloatScalar, FloatScalar, FloatScalar, FloatScalar]
|
tuple[Float, ...]: Tuple of (theta_jn, phi_jl, tilt_1, tilt_2, phi_12, chi_1, chi_2):
|
eta_to_q(eta: FloatScalar) -> FloatScalar
¤
Transforming the symmetric mass ratio eta to the mass ratio q.
Copied and modified from bilby/gw/conversion.py
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
eta
|
Float
|
Symmetric mass ratio. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Float |
FloatScalar
|
Mass ratio (q). |
euler_rotation(delta_x: Float[Array, 3]) -> Float[Array, '3 3']
¤
Calculate the rotation matrix mapping the vector (0, 0, 1) to delta_x while preserving the origin of the azimuthal angle.
This is decomposed into three Euler angles, alpha, beta, gamma, which rotate about the z-, y-, and z- axes respectively.
Copied and modified from bilby-cython/geometry.pyx
m1_m2_to_M_eta(m1: FloatScalar, m2: FloatScalar) -> tuple[FloatScalar, FloatScalar]
¤
Transforms the primary mass m1 and secondary mass m2 to the total mass M and symmetric mass ratio eta.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
m1
|
Float
|
Primary mass. |
required |
m2
|
Float
|
Secondary mass. |
required |
Returns:
| Type | Description |
|---|---|
tuple[FloatScalar, FloatScalar]
|
tuple[Float, Float]: Total mass (M) and symmetric mass ratio (eta). |
m1_m2_to_M_q(m1: FloatScalar, m2: FloatScalar) -> tuple[FloatScalar, FloatScalar]
¤
Transforms the primary mass m1 and secondary mass m2 to the total mass M and mass ratio q.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
m1
|
Float
|
Primary mass. |
required |
m2
|
Float
|
Secondary mass. |
required |
Returns:
| Type | Description |
|---|---|
tuple[FloatScalar, FloatScalar]
|
tuple[Float, Float]: Total mass (M_tot) and mass ratio (q). |
m1_m2_to_Mc_eta(m1: FloatScalar, m2: FloatScalar) -> tuple[FloatScalar, FloatScalar]
¤
Transforms the primary mass m1 and secondary mass m2 to the chirp mass M_c and symmetric mass ratio eta.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
m1
|
Float
|
Primary mass. |
required |
m2
|
Float
|
Secondary mass. |
required |
Returns:
| Type | Description |
|---|---|
tuple[FloatScalar, FloatScalar]
|
tuple[Float, Float]: Chirp mass (M_c) and symmetric mass ratio (eta). |
m1_m2_to_Mc_q(m1: FloatScalar, m2: FloatScalar) -> tuple[FloatScalar, FloatScalar]
¤
Transforms the primary mass m1 and secondary mass m2 to the chirp mass M_c and mass ratio q.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
m1
|
Float
|
Primary mass. |
required |
m2
|
Float
|
Secondary mass. |
required |
Returns:
| Type | Description |
|---|---|
tuple[FloatScalar, FloatScalar]
|
tuple[Float, Float]: Chirp mass (M_c) and mass ratio (q). |
q_to_eta(q: FloatScalar) -> FloatScalar
¤
Transforming the chirp mass M_c and mass ratio q to the symmetric mass ratio eta.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
q
|
Float
|
Mass ratio. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Float |
FloatScalar
|
Symmetric mass ratio (eta). |
ra_dec_to_zenith_azimuth(ra: FloatScalar, dec: FloatScalar, gmst: FloatScalar, rotation: Float[Array, '3 3']) -> tuple[FloatScalar, FloatScalar]
¤
Transforming the right ascension and declination to the zenith angle and azimuthal angle.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ra
|
Float
|
Right ascension. |
required |
dec
|
Float
|
Declination. |
required |
gmst
|
Float
|
Greenwich mean sidereal time. |
required |
rotation
|
Float[Array, '3 3']
|
The rotation matrix. |
required |
Returns:
| Type | Description |
|---|---|
tuple[FloatScalar, FloatScalar]
|
tuple[Float, Float]: Zenith angle and azimuthal angle. |
spin_angles_to_cartesian_spin(theta_jn: FloatScalar, phi_jl: FloatScalar, tilt_1: FloatScalar, tilt_2: FloatScalar, phi_12: FloatScalar, chi_1: FloatScalar, chi_2: FloatScalar, M_c: FloatScalar, q: FloatScalar, fRef: FloatLike, phiRef: FloatLike) -> tuple[FloatScalar, FloatScalar, FloatScalar, FloatScalar, FloatScalar, FloatScalar, FloatScalar]
¤
Transforming the spin parameters.
The code is based on the approach used in LALsimulation: https://lscsoft.docs.ligo.org/lalsuite/lalsimulation/group__lalsimulation__inference.html
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
theta_jn
|
Float
|
Zenith angle between the total angular momentum and the line of sight. |
required |
phi_jl
|
Float
|
Difference between total and orbital angular momentum azimuthal angles. |
required |
tilt_1
|
Float
|
Zenith angle between the spin and orbital angular momenta for the primary object. |
required |
tilt_2
|
Float
|
Zenith angle between the spin and orbital angular momenta for the secondary object. |
required |
phi_12
|
Float
|
Difference between the azimuthal angles of the individual spin vector projections onto the orbital plane. |
required |
chi_1
|
Float
|
Primary object aligned spin. |
required |
chi_2
|
Float
|
Secondary object aligned spin. |
required |
M_c
|
Float
|
The chirp mass. |
required |
q
|
Float
|
The mass ratio. |
required |
fRef
|
Float
|
The reference frequency. |
required |
phiRef
|
Float
|
Binary phase at a reference frequency. |
required |
Returns:
| Type | Description |
|---|---|
tuple[FloatScalar, FloatScalar, FloatScalar, FloatScalar, FloatScalar, FloatScalar, FloatScalar]
|
tuple[Float, Float, Float, Float, Float, Float, Float]: Tuple of (iota, S1x, S1y, S1z, S2x, S2y, S2z):
|
zenith_azimuth_to_ra_dec(zenith: FloatScalar, azimuth: FloatScalar, gmst: FloatScalar, rotation: Float[Array, '3 3']) -> tuple[FloatScalar, FloatScalar]
¤
Transforming the azimuthal angle and zenith angle in Earth frame to right ascension and declination.
Copied and modified from bilby/gw/utils.py
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
zenith
|
Float
|
Zenith angle. |
required |
azimuth
|
Float
|
Azimuthal angle. |
required |
gmst
|
Float
|
Greenwich mean sidereal time. |
required |
rotation
|
Float[Array, '3 3']
|
The rotation matrix. |
required |
Returns:
| Type | Description |
|---|---|
tuple[FloatScalar, FloatScalar]
|
tuple[Float, Float]: Right ascension (ra) and declination (dec). |