Skip to content

Utils

jimgw.core.single_event.utils ¤

apply_fixed_parameters(params: dict[str, Float], fixed_parameters: dict[str, Float | Callable[[dict[str, Float]], Float | dict[str, Float]]]) -> dict[str, Float] ¤

Merge fixed_parameters into params, resolving callables in-place.

For each entry in fixed_parameters:

  • If the value is callable, it is called with the current params dict. If the result is a dict, the value stored under the matching key is used; otherwise the scalar result is used directly.
  • If the value is not callable, it is inserted as-is.

Parameters:

Name Type Description Default
params dict[str, Float]

Parameter dictionary to update in-place. Callers that need to preserve the original should pass a copy.

 required
fixed_parameters dict

Fixed overrides. Values may be scalar constants or callables f(params) -> Float | dict[str, Float] applied in insertion order.

 required

Returns:

Type Description
dict[str, Float]

dict[str, Float]: The same params dict, mutated in-place with the fixed parameters applied.

Raises:

Type Description
KeyError

If a callable returns a dict that does not contain the expected key.

complex_inner_product(h1: Float[Array, ' n_freq'], h2: Float[Array, ' n_freq'], psd: Float[Array, ' n_freq'], df: Float) -> Complex ¤

Compute the complex noise-weighted inner product of two frequency-domain waveforms.

The first waveform h1 is complex-conjugated. The result is:

.. math::

\langle h_1, h_2 \rangle = 4 \Delta f \sum_k \frac{h_1^*(f_k)\, h_2(f_k)}{S_n(f_k)}

Parameters:

Name Type Description Default
h1 Float[Array, ' n_freq']

First waveform (complex array).

 required
h2 Float[Array, ' n_freq']

Second waveform (complex array).

 required
psd Float[Array, ' n_freq']

One-sided power spectral density at each frequency bin.

 required
df Float

Frequency bin spacing in Hz.

 required

Returns:

Name Type Description
Complex Complex

Complex noise-weighted inner product. When h2 is the detector data, this is the complex match-filtered SNR.

inner_product(h1: Float[Array, ' n_freq'], h2: Float[Array, ' n_freq'], psd: Float[Array, ' n_freq'], df: Float) -> Float ¤

Compute the real noise-weighted inner product of two frequency-domain waveforms.

Returns the real part of :func:complex_inner_product:

.. math::

(h_1 | h_2) = \operatorname{Re}\langle h_1, h_2 \rangle
    = 4 \Delta f \sum_k \operatorname{Re}\!\left[
      \frac{h_1^*(f_k)\, h_2(f_k)}{S_n(f_k)} \right]

Parameters:

Name Type Description Default
h1 Float[Array, ' n_freq']

First waveform (complex array).

 required
h2 Float[Array, ' n_freq']

Second waveform (complex array).

 required
psd Float[Array, ' n_freq']

One-sided power spectral density at each frequency bin.

 required
df Float

Frequency bin spacing in Hz.

 required

Returns:

Name Type Description
Float Float

Real noise-weighted inner product. When both waveforms are equal, this equals the optimal SNR squared.

m1_m2_to_M_q(m1: Float, m2: Float) -> tuple[Float, Float] ¤

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[Float, Float]

tuple[Float, Float]: Total mass (M_tot) and mass ratio (q).

M_q_to_m1_m2(M_tot: Float, q: Float) -> tuple[Float, Float] ¤

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[Float, Float]

tuple[Float, Float]: Primary mass (m1) and secondary mass (m2).

m1_m2_to_Mc_q(m1: Float, m2: Float) -> tuple[Float, Float] ¤

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[Float, Float]

tuple[Float, Float]: Chirp mass (M_c) and mass ratio (q).

Mc_q_to_m1_m2(M_c: Float, q: Float) -> tuple[Float, Float] ¤

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[Float, Float]

tuple[Float, Float]: Primary mass (m1) and secondary mass (m2).

m1_m2_to_M_eta(m1: Float, m2: Float) -> tuple[Float, Float] ¤

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[Float, Float]

tuple[Float, Float]: Total mass (M) and symmetric mass ratio (eta).

M_eta_to_m1_m2(M_tot: Float, eta: Float) -> tuple[Float, Float] ¤

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[Float, Float]

tuple[Float, Float]: Primary mass (m1) and secondary mass (m2).

m1_m2_to_Mc_eta(m1: Float, m2: Float) -> tuple[Float, Float] ¤

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[Float, Float]

tuple[Float, Float]: Chirp mass (M_c) and symmetric mass ratio (eta).

Mc_eta_to_m1_m2(M_c: Float, eta: Float) -> tuple[Float, Float] ¤

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[Float, Float]

tuple[Float, Float]: Primary mass (m1) and secondary mass (m2).

q_to_eta(q: Float) -> Float ¤

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 Float

Symmetric mass ratio (eta).

eta_to_q(eta: Float) -> Float ¤

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 Float

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

angle_rotation(zenith: Float, azimuth: Float, rotation: Float[Array, '3 3']) -> tuple[Float, Float] ¤

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[Float, Float]

tuple[Float, Float]: Polar angle (theta) and azimuthal angle (phi).

_theta_phi_to_ra_dec(theta: Float, phi: Float, gmst: Float) -> tuple[Float, Float] ¤

Transforming the polar angle and azimuthal angle to right ascension and declination.

Parameters:

Name Type Description Default
theta Float

Polar angle.

 required
phi Float

Azimuthal angle.

 required
gmst Float

Greenwich mean sidereal time.

 required

Returns:

Type Description
tuple[Float, Float]

tuple[Float, Float]: Right ascension (ra) and declination (dec).

zenith_azimuth_to_ra_dec(zenith: Float, azimuth: Float, gmst: Float, rotation: Float[Array, '3 3']) -> tuple[Float, Float] ¤

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[Float, Float]

tuple[Float, Float]: Right ascension (ra) and declination (dec).

_ra_dec_to_theta_phi(ra: Float, dec: Float, gmst: Float) -> tuple[Float, Float] ¤

Transforming the right ascension ra and declination dec to the polar angle theta and azimuthal angle phi.

Parameters:

Name Type Description Default
ra Float

Right ascension.

 required
dec Float

Declination.

 required
gmst Float

Greenwich mean sidereal time.

 required

Returns:

Type Description
tuple[Float, Float]

tuple[Float, Float]: Polar angle (theta) and azimuthal angle (phi).

ra_dec_to_zenith_azimuth(ra: Float, dec: Float, gmst: Float, rotation: Float[Array, '3 3']) -> tuple[Float, Float] ¤

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[Float, Float]

tuple[Float, Float]: Zenith angle and azimuthal angle.

_rotate_y(angle: Float) -> Float[Array, '3 3'] ¤

Return the 3x3 rotation matrix for a rotation about the y-axis.

Parameters:

Name Type Description Default
angle Float

Rotation angle in radians.

 required

Returns:

Type Description
Float[Array, '3 3']

Float[Array, "3 3"]: Rotation matrix Ry(angle).

_rotate_z(angle: Float) -> Float[Array, '3 3'] ¤

Return the 3x3 rotation matrix for a rotation about the z-axis.

Parameters:

Name Type Description Default
angle Float

Rotation angle in radians.

 required

Returns:

Type Description
Float[Array, '3 3']

Float[Array, "3 3"]: Rotation matrix Rz(angle).

_Lmag_2PN(m1: Float, m2: Float, v0: Float) -> Float ¤

Compute the magnitude of the orbital angular momentum to 2 post-Newtonian orders.

Parameters:

Name Type Description Default
m1 Float

Primary mass.

 required
m2 Float

Secondary mass.

 required
v0 Float

Relative velocity at the reference frequency.

 required

Returns:

Name Type Description
Float Float

Magnitude of the orbital angular momentum.

spin_angles_to_cartesian_spin(theta_jn: Float, phi_jl: Float, tilt_1: Float, tilt_2: Float, phi_12: Float, chi_1: Float, chi_2: Float, M_c: Float, q: Float, fRef: Float, phiRef: Float) -> tuple[Float, Float, Float, Float, Float, Float, Float] ¤

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[Float, Float, Float, Float, Float, Float, Float]

tuple[Float, Float, Float, Float, Float, Float, Float]: Tuple of (iota, S1x, S1y, S1z, S2x, S2y, S2z):

  • iota: Zenith angle between the orbital angular momentum and the line of sight.
  • S1x: The x-component of the primary spin.
  • S1y: The y-component of the primary spin.
  • S1z: The z-component of the primary spin.
  • S2x: The x-component of the secondary spin.
  • S2y: The y-component of the secondary spin.
  • S2z: The z-component of the secondary spin.

cartesian_spin_to_spin_angles(iota: Float, S1x: Float, S1y: Float, S1z: Float, S2x: Float, S2y: Float, S2z: Float, M_c: Float, q: Float, fRef: Float, phiRef: Float) -> tuple[Float, Float, Float, Float, Float, Float, Float] ¤

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[Float, Float, Float, Float, Float, Float, Float]

tuple[Float, ...]: Tuple of (theta_jn, phi_jl, tilt_1, tilt_2, phi_12, chi_1, chi_2):

  • theta_jn: Zenith angle between the total angular momentum and the line of sight.
  • phi_jl: Difference between total and orbital angular momentum azimuthal angles.
  • tilt_1: Zenith angle between the spin and orbital angular momenta for the primary object.
  • tilt_2: Zenith angle between the spin and orbital angular momenta for the secondary object.
  • phi_12: Difference between the azimuthal angles of the individual spin vector projections onto the orbital plane.
  • chi_1: Primary object aligned spin.
  • chi_2: Secondary object aligned spin.