Skip to content

utils

General single-event likelihood utilities.

Contains the noise-weighted inner product functions used by the likelihood and the fixed-parameter application helper.

  • For mass, spin, and sky/detector coordinate transforms, see jimgw.core.single_event.transform_utils.

Functions:

Name Description
apply_fixed_parameters

Merge fixed_parameters into params, resolving callables in-place.

complex_inner_product

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

inner_product

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

apply_fixed_parameters(params: dict[str, FloatLike], fixed_parameters: FixedParameters) -> dict[str, FloatLike] ¤

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, FloatLike]

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: Inexact[Array, ' n_freq'], h2: Inexact[Array, ' n_freq'], psd: Float[Array, ' n_freq'], df: FloatLike) -> FloatScalar | ComplexScalar ¤

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

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

\[ \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 Inexact[Array, ' n_freq']

First waveform (real or complex array).

required
h2 Inexact[Array, ' n_freq']

Second waveform (real or 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:

Type Description
FloatScalar | ComplexScalar

FloatScalar | ComplexScalar: Noise-weighted inner product, real when both inputs are real. When h2 is the detector data, this is the complex match-filtered SNR.

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

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

Returns the real part of complex_inner_product:

\[ (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 Inexact[Array, ' n_freq']

First waveform (real or complex array).

required
h2 Inexact[Array, ' n_freq']

Second waveform (real or 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 FloatScalar

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