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, 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: FloatLike) -> 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 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 ComplexScalar

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: 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 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 FloatScalar

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