Skip to content

likelihood

HeterodynedTransientLikelihoodFD ¤

Bases: SingleEventLikelihood

Frequency-domain likelihood using the relative-binning (heterodyne) scheme.

Optionally marginalizes over coalescence phase when phase_marginalization is provided.

Parameters:

Name Type Description Default
detectors Sequence[Detector]

List of detector objects containing data and metadata.

required
waveform Waveform

Waveform model to evaluate.

required
fixed_parameters Optional[FixedParameters]

Dictionary of fixed parameter values. Each value may be a constant Float, a callable returning a scalar, or a callable returning a dict (e.g. transform.backward). See TransientLikelihoodFD for a detailed description and example.

None
f_min Optional[float | dict[str, float]]

Minimum frequency for likelihood evaluation. Can be a single float or a per-detector dictionary. Must be positive and not below the minimum frequency of the data. Defaults to that minimum frequency.

None
f_max Optional[float | dict[str, float]]

Maximum frequency for likelihood evaluation. Can be a single float or a per-detector dictionary. Must not exceed the maximum frequency of the data or the Nyquist frequency. Defaults to the smaller of the two.

None
n_bins Optional[int]

Number of frequency bins for relative binning. Mutually exclusive with epsilon; raises ValueError if both are set. When neither is set, epsilon=0.5 is used as the default.

None
epsilon Optional[float]

Maximum allowed phase change per bin (rad). The bin count is set to max(1, int(total_phase / epsilon)). Mutually exclusive with n_bins; raises ValueError if both are set. When neither is set, epsilon=0.5 is used as the default.

None
optimizer_popsize int

Population size for the CMA-ES optimizer used when finding reference parameters automatically. Defaults to 500.

500
optimizer_n_steps int

Maximum number of CMA-ES generations. Defaults to 1000.

1000
optimizer_target Optional[float]

Optional log-likelihood value at which the CMA-ES search stops early, before optimizer_n_steps is reached. Defaults to None, which runs up to the full optimizer_n_steps generations; the search may still stop earlier if CMA-ES's convergence/stall criterion fires.

None
reference_parameters Optional[dict]

Pre-computed reference parameters (dict). If supplied, the optimizer is skipped entirely.

None
reference_waveform Optional[Waveform]

Optional waveform instance used to compute the reference waveform. Defaults to waveform when not provided.

None
prior Optional[Prior]

Prior distribution from which the initial CMA-ES mean is drawn. Required when reference_parameters is not provided.

None
likelihood_transforms Optional[list[NtoMTransform]]

Transforms mapping sampling parameters to likelihood parameters (e.g. mass-ratio → symmetric mass-ratio).

None
phase_marginalization Optional[Union[PhaseMargConfig, dict, bool]]

If provided, marginalize over coalescence phase phase_c. Pass a PhaseMargConfig object, a plain dict {}, or True (shorthand for PhaseMargConfig()). None or False (default) disables phase marginalization.

None

Methods:

Name Description
maximize_likelihood

Find the maximum-likelihood parameters using CMA-ES.

Attributes:

Name Type Description
bin_widths Float[Array, ' n_valid']

Widths derived from the shared bin-edge grid.

freq_grid_high Float[Array, ' n_valid']

Upper frequency edge of each relative-binning interval.

freq_grid_low Float[Array, ' n_valid']

Lower frequency edge of each relative-binning interval.

bin_widths: Float[Array, ' n_valid'] property ¤

Widths derived from the shared bin-edge grid.

freq_grid_high: Float[Array, ' n_valid'] property ¤

Upper frequency edge of each relative-binning interval.

freq_grid_low: Float[Array, ' n_valid'] property ¤

Lower frequency edge of each relative-binning interval.

maximize_likelihood(prior: Prior, likelihood_transforms: list[NtoMTransform], optimizer_popsize: int = 500, optimizer_n_steps: int = 1000, optimizer_target: Optional[float] = None) ¤

Find the maximum-likelihood parameters using CMA-ES.

Uses evosax.CMA_ES (Covariance Matrix Adaptation Evolution Strategy) to search the full parameter space. The initial mean is drawn from the prior and the entire ask/tell loop is compiled with jax.lax.while_loop for speed, stopping once optimizer_n_steps generations have run, optimizer_target has been reached, or evosax's own CMA-ES convergence/stall criterion (cma_cond, using its built-in default tolerances) detects that the search has converged or numerically degenerated — whichever comes first. The population is evaluated in batches that fit in device memory.

Parameters:

Name Type Description Default
prior Prior

Prior used to seed the initial CMA-ES mean.

required
likelihood_transforms list[NtoMTransform]

Transforms mapping sampling parameters to likelihood parameters.

required
optimizer_popsize int

Population size for CMA-ES. Defaults to 500.

500
optimizer_n_steps int

Maximum number of CMA-ES generations. Defaults to 1000.

1000
optimizer_target Optional[float]

Optional log-likelihood value (same scale as evaluate) at which to stop early, before optimizer_n_steps is reached. Defaults to None, which runs up to the full optimizer_n_steps generations (the search may still stop earlier if CMA-ES's own convergence/stall criterion fires).

None

MultibandedTransientLikelihoodFD ¤

Bases: SingleEventLikelihood

Multi-banded likelihood for gravitational wave transient events.

This implements the multi-banding method described in S. Morisaki, 2021, arXiv:2104.07813. The method divides the frequency range into bands with different resolutions, using coarser grids at higher frequencies to speed up likelihood evaluation.

Attributes:

Name Type Description
reference_chirp_mass Float

Reference chirp mass for determining frequency bands.

reference_chirp_mass_in_second Float

Geometrised reference chirp mass in time unit [second].

highest_mode int

Maximum magnetic number of GW moments (fixed to 2 for 22-mode).

accuracy_factor Float

Parameter L controlling approximation accuracy.

time_offset Float

Time offset for band construction.

delta_f_end Float

Frequency scale for high-frequency tapering.

durations Array

Durations of each band.

fb_dfb Array

Starting frequencies and taper widths for each band.

linear_coeffs dict

Pre-computed coefficients for (d|h) inner product.

quadratic_coeffs dict

Pre-computed coefficients for (h|h) inner product.

Parameters:

Name Type Description Default
detectors Sequence[Detector]

List of detector objects.

required
waveform Waveform

Waveform model to evaluate.

required
fixed_parameters Optional[dict]

Fixed parameters for the likelihood.

None
f_min Optional[Float | dict[str, Float]]

Minimum frequency for likelihood evaluation, or a dict mapping detector name to a per-detector Float. Must be positive and not below the minimum frequency of the data. Defaults to that minimum frequency.

None
f_max Optional[Float | dict[str, Float]]

Maximum frequency for likelihood evaluation, or a dict mapping detector name to a per-detector Float. Must not exceed the maximum frequency of the data or the Nyquist frequency. Defaults to the smaller of the two.

None
highest_mode int

Maximum magnetic number (default 2, for 22-mode only).

2
accuracy_factor Float

Accuracy parameter L (default 5.0).

5.0
prior Optional[Prior]

Combined prior object. Needed when reference_chirp_mass, time_offset, or delta_f_end are None so they can be inferred automatically from the prior bounds.

None
reference_chirp_mass Optional[Float]

Reference chirp mass in solar masses. Use the minimum of your chirp-mass prior for maximum speedup. When None, the value is inferred from the M_c component of prior.

None
time_offset Optional[Float]

Time offset in seconds. When None, inferred from the t_c (or t_{ifo}) prior range; falls back to 2.12 s with a warning when the prior is unavailable and the data end 2 s after the trigger time (otherwise it is an error).

None
delta_f_end Optional[Float]

End frequency taper scale in Hz. When None, inferred from the t_c prior range; falls back to 53.0 Hz.

None
max_banding_frequency Optional[Float]

Upper limit on band starting frequency.

None
min_banding_duration Float

Minimum duration for bands.

0.0

maximum_frequency: float property ¤

Highest f_max of the likelihood across the detectors.

minimum_frequency: float property ¤

Lowest f_min of the likelihood across the detectors.

n_bands: int property ¤

Number of frequency bands.

SingleEventLikelihood ¤

Bases: LikelihoodBase

Methods:

Name Description
__init__

Args:

evaluate

Prepare parameters and evaluate the likelihood.

evaluate_from_waveform

Evaluate this likelihood from a waveform cache.

generate_waveform

Generate a reusable waveform cache.

Attributes:

Name Type Description
detector_frequencies list[Float[Array, ' n_freq']]

Frequencies in the frequency range of the likelihood, one array per detector.

detector_names list[str]

Names of the detectors used in this likelihood.

df FloatLike

Shared frequency spacing of the frozen detector data.

duration FloatLike

Duration of the data segment in seconds (taken from the first detector).

trigger_time float

Shared trigger time of the frozen detector data.

waveform_caches_distance bool

Whether a waveform cache can be reused across d_L changes.

detector_frequencies: list[Float[Array, ' n_freq']] property ¤

Frequencies in the frequency range of the likelihood, one array per detector.

detector_names: list[str] property ¤

Names of the detectors used in this likelihood.

df: FloatLike property ¤

Shared frequency spacing of the frozen detector data.

duration: FloatLike property ¤

Duration of the data segment in seconds (taken from the first detector).

trigger_time: float property ¤

Shared trigger time of the frozen detector data.

waveform_caches_distance: bool property ¤

Whether a waveform cache can be reused across d_L changes.

Derived from the waveform's type by default, so subclasses may override it to control the behavior directly. Consumed by the waveform-cache block-dependency inference (see jimgw.core.single_event.blocked_likelihood): when True, d_L is excluded from the cache's dependency set, so a d_L-only proposal block reuses the cache instead of rebuilding it.

__init__(detectors: Sequence[Detector], waveform: Waveform, *, fixed_parameters: Optional[FixedParameters] = None, f_min: Optional[float | dict[str, float]] = None, f_max: Optional[float | dict[str, float]] = None) -> None ¤

Parameters:

Name Type Description Default
detectors Sequence[Detector]

Detectors with initialized data and PSD. The detectors will be frozen to prevent accidental changes after the likelihood is constructed.

required
waveform Waveform

Waveform model to evaluate.

required
fixed_parameters Optional[dict]

Parameters held constant during sampling. Values may be scalars or callables f(params) -> Float | dict; callables are applied in insertion order. Defaults to None (no fixed parameters).

None
f_min Optional[float | dict[str, float]]

Minimum frequency for likelihood evaluation.

None
f_max Optional[float | dict[str, float]]

Maximum frequency for likelihood evaluation.

None

Raises:

Type Description
ValueError

If the waveform is a time-domain model, if any detector has uninitialized data or PSD, if the data of the detectors do not carry one trigger time inside them, or if the frequency range of the likelihood is invalid.

evaluate(params: Mapping[str, FloatLike]) -> FloatScalar ¤

Prepare parameters and evaluate the likelihood.

Constants are injected directly; callables receive the current params dict and may return a scalar or a dict (the matching key is extracted). Callables are applied in insertion order.

evaluate_from_waveform(params: Mapping[str, FloatLike], waveform_cache: Any) -> FloatScalar ¤

Evaluate this likelihood from a waveform cache.

generate_waveform(params: Mapping[str, FloatLike]) -> Any ¤

Generate a reusable waveform cache.

Evaluated at unit distance when waveform_caches_distance is True, so d_L is not a cache dependency; otherwise d_L is a dependency like any other waveform parameter. Every other effective waveform input is always a dependency, regardless of distance support.

Parameters:

Name Type Description Default
params dict[str, Float]

Source parameters to build the cache from.

required

Returns:

Name Type Description
Any Any

An opaque cache understood by this likelihood's evaluate_from_waveform.

TransientLikelihoodFD ¤

Bases: SingleEventLikelihood

Frequency-domain transient gravitational wave likelihood.

Supports optional marginalization over coalescence time, phase, and/or luminosity distance.

Parameters:

Name Type Description Default
detectors Sequence[Detector]

List of detector objects containing data and metadata.

required
waveform Waveform

Waveform model to evaluate.

required
fixed_parameters Optional[FixedParameters]

Parameters held constant during sampling. Values may be constants or callables f(params) -> Float | dict; callables are applied in insertion order. See the likelihood tutorial for details and examples.

None
f_min Optional[float | dict[str, float]]

Minimum frequency for likelihood evaluation. Can be a single float or a per-detector dictionary. Must be positive and not below the minimum frequency of the data. Defaults to that minimum frequency.

None
f_max Optional[float | dict[str, float]]

Maximum frequency for likelihood evaluation. Can be a single float or a per-detector dictionary. Must not exceed the maximum frequency of the data or the Nyquist frequency. Defaults to the smaller of the two.

None
time_marginalization Optional[Union[TimeMargConfig, dict, bool]]

If provided, marginalize over coalescence time t_c. Pass a TimeMargConfig object, a plain dict (e.g. {"tc_range": (-0.1, 0.1)}), or True (shorthand for TimeMargConfig()). False or the default None disables time marginalization.

None
phase_marginalization Optional[Union[PhaseMargConfig, dict, bool]]

If provided, marginalize over coalescence phase phase_c. Pass a PhaseMargConfig object, a plain dict {}, or True (shorthand for PhaseMargConfig()). False or the default None disables phase marginalization.

None
distance_marginalization Optional[Union[DistanceMargConfig, dict, bool]]

If provided, marginalize over luminosity distance d_L. Pass a DistanceMargConfig object or a plain dict (e.g. {"distance_prior": prior, "n_dist_points": 10000}). False or the default None disables distance marginalization. True is not supported — distance_prior has no default; pass a dict or DistanceMargConfig instead.

None
Example

likelihood = TransientLikelihoodFD( ... detectors, waveform, ... f_min=20, f_max=1024, ... phase_marginalization=True, ... time_marginalization={"tc_range": (-0.1, 0.1)}, ... ) logL = likelihood.evaluate(params)

ZeroLikelihood ¤

Bases: LikelihoodBase

Trivial likelihood that always returns zero.

Useful for prior-only sampling or debugging.

Methods:

Name Description
evaluate

Return zero regardless of the parameters.

evaluate(params: Mapping[str, FloatLike]) -> FloatScalar ¤

Return zero regardless of the parameters.

Parameters:

Name Type Description Default
params dict[str, Float]

Ignored.

required

Returns:

Name Type Description
FloatScalar FloatScalar

Always 0.0.