dingo.gw.inference package

Submodules

dingo.gw.inference.gw_samplers module

class dingo.gw.inference.gw_samplers.GWSampler(**kwargs)

Bases: GWSamplerMixin, Sampler

Sampler for gravitational-wave inference using neural posterior estimation. Augments the base class by defining transform_pre and transform_post to prepare data for the inference network.

transform_pre :

Decimates data (if necessary and using MultibandedFrequencyDomain).
Whitens strain.
Repackages strain data and the inverse ASDs (suitably scaled) into a torch tensor.

transform_post :

Extract the desired inference parameters from the network output ( array-like), de-standardize them, and repackage as a dict.

Also mixes in GW functionality for building the domain and correcting the reference time.

Allows for conditional and unconditional models, and draws samples from the model based on (optional) context data.

This is intended for use either as a standalone sampler, or as a sampler producing initial sample points for a GNPE sampler.

Parameters:: kwargs – Keyword arguments that are forwarded to the superclass.

class dingo.gw.inference.gw_samplers.GWSamplerGNPE(**kwargs)

Bases: GWSamplerMixin, GNPESampler

Gravitational-wave GNPE sampler. It wraps a PosteriorModel and a standard Sampler for initialization. The former is used to generate initial samples for Gibbs sampling.

Compared to the base class, this class implements the required transforms for preparing data and parameters for the network. This includes GNPE transforms, data processing transforms, and standardization/de-standardization of parameters.

A GNPE network is conditioned on additional “proxy” context theta^, i.e.,

p(theta | theta^, d)

The theta^ depend on theta via a fixed kernel p(theta^ | theta). Combining these known distributions, this class uses Gibbs sampling to draw samples from the joint distribution,

p(theta, theta^ | d)

The advantage of this approach is that we are allowed to perform any transformation of d that depends on theta^. In particular, we can use this freedom to simplify the data, e.g., by aligning data to have merger times = 0 in each detector. The merger times are unknown quantities that must be inferred jointly with all other parameters, and GNPE provides a means to do this iteratively. See https://arxiv.org/abs/2111.13139 for additional details.

Gibbs sampling breaks access to the probability density, so this must be recovered through other means. One way is to train an unconditional flow to represent p(theta^ | d) for fixed d based on the samples produced through the GNPE Gibbs sampling. Starting from these, a single Gibbs iteration gives theta from the GNPE network, along with the probability density in the joint space. This is implemented in GNPESampler provided the init_sampler provides proxies directly and num_iterations = 1.

Attributes (beyond those of Sampler)

init_samplerSampler: Used for providing initial samples for Gibbs sampling.
num_iterationsint: Number of Gibbs iterations to perform.
iteration_trackerIterationTracker: not set up
remove_init_outliersfloat: not set up

param kwargs:: Keyword arguments that are forwarded to the superclass.

property maximum_frequency: float | dict[str, float]

property minimum_frequency: float | dict[str, float]

class dingo.gw.inference.gw_samplers.GWSamplerMixin(**kwargs)

Bases: object

Mixin class designed to add gravitational wave functionality to Sampler classes:

builder for data domain
correction for fixed detector locations during training (t_ref)

Parameters:: kwargs – Keyword arguments that are forwarded to the superclass.

property detectors

property event_metadata

property frequency_updates: bool

property maximum_frequency: float | dict[str, float]

property minimum_frequency: float | dict[str, float]

property random_strain_cropping

class dingo.gw.inference.gw_samplers.SamplerProtocol(*args, **kwargs)

Bases: Protocol

base_model_metadata: dict

dingo.gw.inference.gw_samplers.check_frequency_updates(model_metadata: dict, f_min: dict[str, float] | float | None = None, f_max: dict[str, float] | float | None = None)

Validate and apply optional minimum and maximum frequency constraints for a model’s frequency domain.

This function checks that any provided per-detector minimum (f_min) or maximum (f_max) frequencies—either as a single float applied to all detectors or as a dict mapping each detector to its own value—:

Match exactly the set of detectors in the model metadata.

Respect the hard bounds defined by the domain (domain.f_min / domain.f_max).

Comply with optional random-strain-cropping settings (probability, independent vs. joint detectors, and per-detector caps/floors).

Parameters:

model_metadata (dict) –
Dictionary containing the model’s training settings and data. Must include:
- [“train_settings”][“data”][“detectors”]: list of detector names.
- [“train_settings”][“data”][“random_strain_cropping”]: optional dict of cropping parameters.
f_min (dict[str, float], float, or None, optional) – Single float or per-detector dict of minimum frequencies to enforce. If a float is provided, it is applied to all detectors. Each value must be ≥ domain.f_min. If None, no minimum-frequency validation is performed.
f_max (dict[str, float], float, or None, optional) – Single float or per-detector dict of maximum frequencies to enforce. If a float is provided, it is applied to all detectors. Each value must be ≤ domain.f_max. If None, no maximum-frequency validation is performed.

Raises:

ValueError –

If model_metadata does not describe a UniformFrequencyDomain or MultibandedFrequencyDomain. - If f_min/f_max keys don’t exactly match the detector list. - If any requested frequency lies outside the hard domain bounds. - If cropping is disabled but a change in frequency is requested. - If per-detector constraints (independent vs. joint) or cropping caps/floors are violated.

Return type:

None

dingo.gw.inference.inference_utils module

dingo.gw.inference.inference_utils.prepare_log_prob(sampler, num_samples: int, nde_settings: dict, batch_size: int | None = None, threshold_std: float | None = inf, remove_init_outliers: float | None = 0.0, low_latency_label: str | None = None, outdir: str | None = None)

Prepare gnpe sampling with log_prob. This is required, since in its vanilla form gnpe does not provide the density for its samples.

Specifically, we train an unconditional neural density estimator (nde) for the gnpe proxies. This requires running the gnpe sampler till convergence, and extracting the gnpe proxies after the final gnpe iteration. The nde is trained to match the distribution over gnpe proxies, which provides a way of rapidly sampling (converged!) gnpe proxies and evaluating the log_prob.

After this preparation step, self.run_sampler can leverage self.gnpe_proxy_sampler (which is based on the aforementioned trained nde) to sample gnpe proxies, such that one gnpe iteration is sufficient. The log_prob of the samples in the joint space (inference parameters + gnpe proxies) is then simply given by the sum of the corresponding log_probs (from self.model and self.gnpe_proxy_sampler.model).