ml4gw.distributions

Module containing callables classes for generating samples from specified distributions. Each callable should map from an integer N to a 1D torch Tensor containing N samples from the corresponding distribution.

Classes

Cosine([low, high, validate_args])	Cosine distribution based on torch.distributions.TransformedDistribution (see documentation).
DeltaFunction([peak, validate_args])
LogNormal(mean, std[, low, validate_args])
LogUniform(low, high[, validate_args])	Sample from a log uniform distribution
PowerLaw(minimum, maximum, index[, ...])	Sample from a power law distribution,
RateEvolution(rate_function, *args, **kwargs)	Wrapper around UniformComovingVolume() to allow for arbitrary rate evolution functions.
Sine([low, high, validate_args])	Sine distribution based on torch.distributions.TransformedDistribution.
UniformChirpDistance(chirp_mass, minimum, ...)	Joint distribution over chirp mass and luminosity distance that is uniform in chirp distance.
UniformComovingVolume(minimum, maximum[, ...])	Sample either redshift, comoving distance, or luminosity distance such that they are uniform in comoving volume, assuming a flat lambda-CDM cosmology.

class ml4gw.distributions.Cosine(low=-1.5707963267948966, high=1.5707963267948966, validate_args=None)

Bases: Distribution

Cosine distribution based on torch.distributions.TransformedDistribution (see documentation).

Parameters:

• low (float)

• high (float)

arg_constraints = {}

log_prob(value)

Return type:

Float[Tensor, '']

Parameters:

value (float)

rsample(sample_shape=None)

Return type:

Tensor

Parameters:

sample_shape (Size)

class ml4gw.distributions.DeltaFunction(peak=0.0, validate_args=None)

Bases: Distribution

Parameters:

peak (float)

arg_constraints = {}

rsample(sample_shape=None)

Return type:

Tensor

Parameters:

sample_shape (Size)

class ml4gw.distributions.LogNormal(mean, std, low=None, validate_args=None)

Bases: LogNormal

Parameters:

• mean (float)

• std (float)

• low (float | None)

support()

class ml4gw.distributions.LogUniform(low, high, validate_args=None)

Bases: TransformedDistribution

Sample from a log uniform distribution

Parameters:

• low (float)

• high (float)

class ml4gw.distributions.PowerLaw(minimum, maximum, index, validate_args=None)

Bases: TransformedDistribution

Sample from a power law distribution,

\[p(x) \approx x^{\alpha}.\]

Index alpha cannot be 0, since it is equivalent to a Uniform distribution. This could be used, for example, as a universal distribution of signal-to-noise ratios (SNRs) from uniformly volume distributed sources

\[p(\rho) = 3\rho_0^3 / \rho^4\]

where \(\rho_0\) is a representative minimum SNR considered for detection. See, for example, Schutz (2011). Or, for example, index=2 for uniform in Euclidean volume.

Parameters:

• minimum (float)

• maximum (float)

• index (float)

support = GreaterThanEq(lower_bound=0.0)

class ml4gw.distributions.RateEvolution(rate_function, *args, **kwargs)

Bases: UniformComovingVolume

Wrapper around UniformComovingVolume() to allow for arbitrary rate evolution functions. E.g., if rate_function = lambda z: 1 / (1 + z), then the distribution will sample values such that they occur uniform in source frame time.

Parameters:

• rate_function (Callable) -- Callable that takes redshift as input and returns the rate evolution factor.

• *args -- Arguments passed to UniformComovingVolume() constructor.

• **kwargs -- Keyword arguments passed to UniformComovingVolume() constructor.

class ml4gw.distributions.Sine(low=0.0, high=3.141592653589793, validate_args=None)

Bases: TransformedDistribution

Sine distribution based on torch.distributions.TransformedDistribution.

Parameters:

• low (float)

• high (float)

class ml4gw.distributions.UniformChirpDistance(chirp_mass, minimum, maximum, reference_chirp_mass=1.4, validate_args=None)

Bases: Distribution

Joint distribution over chirp mass and luminosity distance that is uniform in chirp distance.

Chirp distance is defined as

\[d_c = d_L (M_{ref} / M_c)^{5 / 6}\]

where \(d_L\) is the luminosity distance, \(M_c\) is the chirp mass, and \(M_{ref}\) is a fixed chirp mass used for reference in the scaling.

Samples are generated by drawing \(M_c\) from chirp_mass and, independently, \(d_c\) uniformly between minimum and maximum, then setting \(d_L = d_c (M_c / M_{ref})^{5 / 6}\). The joint density is

\[\log p(M_c, d_L) = \log p(M_c) - \log(d_{max} - d_{min}) - \frac{5}{6} \log(M_c / M_{ref})\]

for \(d_{min} \leq d_c \leq d_{max}\), and \(-\infty\) otherwise.

Each sample is a pair along the last dimension, with the chirp mass at index 0 and the luminosity distance at index 1. The same layout is expected by log_prob().

Parameters:

• chirp_mass (Distribution) -- Distribution of chirp masses

• minimum (float) -- Minimum chirp distance

• maximum (float) -- Maximum chirp distance

• reference_chirp_mass (float) -- Chirp mass value to use for reference

arg_constraints = {}

log_prob(value)

Return type:

Tensor

Parameters:

value (Tensor)

sample(sample_shape=None)

Return type:

Tensor

Parameters:

sample_shape (Size)

class ml4gw.distributions.UniformComovingVolume(minimum, maximum, distance_type='redshift', h0=67.66, omega_m=0.30966, z_grid_max=5, grid_size=10000, validate_args=None)

Bases: Distribution

Sample either redshift, comoving distance, or luminosity distance such that they are uniform in comoving volume, assuming a flat lambda-CDM cosmology. Default H0 and Omega_M values match Planck18 parameters in Astropy.

Parameters:

• minimum (float) -- Minimum distance in the specified distance type

• maximum (float) -- Maximum distance in the specified distance type

• distance_type (str) -- Type of distance to sample from. Can be redshift, comoving_distance, or luminosity_distance

• h0 (float) -- Hubble constant in km/s/Mpc

• omega_m (float) -- Matter density parameter

• z_max -- Maximum redshift for the grid

• grid_size (int) -- Number of points in the grid for interpolation

• validate_args (bool) -- Whether to validate arguments

• z_grid_max (float)

arg_constraints = {}

log_prob(value)

Return type:

Tensor

Parameters:

value (Tensor)

rsample(sample_shape=None)

Return type:

Tensor

Parameters:

sample_shape (Size)

support = GreaterThanEq(lower_bound=0.0)