gwpopulation.models.spin

Implemented spin models

Classes

GaussianChiEffChiP	A covariant Gaussian in effective aligned and precessing spins.
SplineSpinMagnitudeIdentical	Interpolated spline model for spin magnitudes.
SplineSpinTiltIdentical	Interpolated spline model for spin orientations.

Functions

iid_spin(dataset, xi_spin, sigma_spin, amax, ...)	Independently and identically distributed spins.
ln_iid_spin(dataset, xi_spin, sigma_spin, amax, ...)	Log of iid_spin(), computed without leaving log space so that it
iid_spin_magnitude_beta(dataset[, amax, alpha_chi, ...])	Independent and identically distributed beta distributions for both spin magnitudes.
ln_iid_spin_magnitude_beta(dataset[, amax, alpha_chi, ...])	Log of iid_spin_magnitude_beta().
independent_spin_magnitude_beta(dataset, alpha_chi_1, ...)	Independent beta distributions for both spin magnitudes.
ln_independent_spin_magnitude_beta(dataset, ...)	Log of independent_spin_magnitude_beta().
iid_spin_orientation_gaussian_isotropic(dataset, ...)	A mixture model of spin orientations with isotropic and normally
ln_iid_spin_orientation_gaussian_isotropic(dataset, ...)	Log of iid_spin_orientation_gaussian_isotropic().
independent_spin_orientation_gaussian_isotropic(...[, ...])	A mixture model of spin orientations with isotropic and normally
ln_independent_spin_orientation_gaussian_isotropic(...)	Log of independent_spin_orientation_gaussian_isotropic(), computed
gaussian_chi_eff(dataset, mu_chi_eff, sigma_chi_eff)	A Gaussian in chi effective distribution
ln_gaussian_chi_eff(dataset, mu_chi_eff, sigma_chi_eff)	Log of gaussian_chi_eff(), which does not underflow far from the
gaussian_chi_p(dataset, mu_chi_p, sigma_chi_p)	A Gaussian distribution in precessing effective spin (chi p)
ln_gaussian_chi_p(dataset, mu_chi_p, sigma_chi_p)	Log of gaussian_chi_p(), which does not underflow far from the

Module Contents

gwpopulation.models.spin.iid_spin(dataset, xi_spin, sigma_spin, amax, alpha_chi, beta_chi)

Independently and identically distributed spins. The magnitudes are assumed to follow a Beta distribution and the orientations are assumed to follow an isotropic + truncated half Gaussian mixture model.

Parameters:

dataset: dict

Dictionary of numpy arrays containing ‘a_1’ and ‘a_2’.

xi_spin: float

Fraction of black holes in preferentially aligned component.

sigma_spin: float

Width of preferentially aligned component.

alpha_chi, beta_chi: float

Parameters of Beta distribution for both black holes.

amax: float

Maximum black hole spin.

gwpopulation.models.spin.ln_iid_spin(dataset, xi_spin, sigma_spin, amax, alpha_chi, beta_chi)

Log of iid_spin(), computed without leaving log space so that it does not underflow, e.g., in single precision.

Parameters:

dataset: dict

Dictionary of numpy arrays containing ‘a_1’, ‘a_2’, ‘cos_tilt_1’, and ‘cos_tilt_2’.

xi_spin: float

Fraction of black holes in preferentially aligned component.

sigma_spin: float

Width of preferentially aligned component.

alpha_chi, beta_chi: float

Parameters of Beta distribution for both black holes.

amax: float

Maximum black hole spin.

gwpopulation.models.spin.iid_spin_magnitude_beta(dataset, amax=1, alpha_chi=1, beta_chi=1)

Independent and identically distributed beta distributions for both spin magnitudes.

See Wysocki+ <https://arxiv.org/abs/1805.06442> Eq. (10)

Parameters:

dataset: dict

Dictionary of numpy arrays containing ‘a_1’ and ‘a_2’.

alpha_chi, beta_chi: float

Parameters of Beta distribution for both black holes.

amax: float

Maximum black hole spin.

gwpopulation.models.spin.ln_iid_spin_magnitude_beta(dataset, amax=1, alpha_chi=1, beta_chi=1)

Log of iid_spin_magnitude_beta().

Parameters:

dataset: dict

Dictionary of numpy arrays containing ‘a_1’ and ‘a_2’.

alpha_chi, beta_chi: float

Parameters of Beta distribution for both black holes.

amax: float

Maximum black hole spin.

gwpopulation.models.spin.independent_spin_magnitude_beta(dataset, alpha_chi_1, alpha_chi_2, beta_chi_1, beta_chi_2, amax_1, amax_2)

Independent beta distributions for both spin magnitudes.

See Wysocki+ <https://arxiv.org/abs/1805.06442> Eq. (10)

Parameters:

dataset: dict

Dictionary of numpy arrays containing ‘a_1’ and ‘a_2’.

alpha_chi_1, beta_chi_1: float

Parameters of Beta distribution for more massive black hole.

alpha_chi_2, beta_chi_2: float

Parameters of Beta distribution for less massive black hole.

amax_1, amax_2: float

Maximum spin of the more/less massive black hole.

gwpopulation.models.spin.ln_independent_spin_magnitude_beta(dataset, alpha_chi_1, alpha_chi_2, beta_chi_1, beta_chi_2, amax_1, amax_2)

Log of independent_spin_magnitude_beta().

Parameters:

dataset: dict

Dictionary of numpy arrays containing ‘a_1’ and ‘a_2’.

alpha_chi_1, beta_chi_1: float

Parameters of Beta distribution for more massive black hole.

alpha_chi_2, beta_chi_2: float

Parameters of Beta distribution for less massive black hole.

amax_1, amax_2: float

Maximum spin of the more/less massive black hole.

gwpopulation.models.spin.iid_spin_orientation_gaussian_isotropic(dataset, xi_spin, sigma_spin, mu_spin=1)

A mixture model of spin orientations with isotropic and normally distributed components. The distribution of primary and secondary spin orientations are expected to be identical and independent.

See Talbot and Thrane Eq. (4)

\[p(z_1, z_2 | \xi, \sigma) = \frac{(1 - \xi)^2}{4} + \xi \prod_{i\in\{1, 2\}} \mathcal{N}_{[-1, 1]}(z_i; \mu=1, \sigma=\sigma)\]

Where \(\mathcal{N}_{[a, b]}\) is the truncated normal distribution over \([a, b]\).

Parameters:

dataset: dict

Dictionary of numpy arrays for ‘cos_tilt_1’ and ‘cos_tilt_2’.

xi_spin: float

Fraction of black holes in gaussian component (\(\xi\)).

sigma_spin: float

Width of gaussian component.

mu_spin: float

Mean of the gaussian component (default: cos_tilt = 1).

gwpopulation.models.spin.ln_iid_spin_orientation_gaussian_isotropic(dataset, xi_spin, sigma_spin, mu_spin=1)

Log of iid_spin_orientation_gaussian_isotropic().

Parameters:

dataset: dict

Dictionary of numpy arrays for ‘cos_tilt_1’ and ‘cos_tilt_2’.

xi_spin: float

Fraction of black holes in gaussian component (\(\xi\)).

sigma_spin: float

Width of gaussian component.

mu_spin: float

Mean of the gaussian component (default: cos_tilt = 1).

gwpopulation.models.spin.independent_spin_orientation_gaussian_isotropic(dataset, xi_spin, sigma_1, sigma_2, mu_1=1, mu_2=1)

A mixture model of spin orientations with isotropic and normally distributed components.

See Talbot and Thrane Eq. (4)

\[p(z_1, z_2 | \xi, \sigma) = \frac{(1 - \xi)^2}{4} + \xi \prod_{i\in\{1, 2\}} \mathcal{N}_{[-1, 1]}(z_i; \mu=1, \sigma=\sigma_{i})\]

Where \(\mathcal{N}_{[a, b]}\) is the truncated normal distribution over \([a, b]\).

Parameters:

dataset: dict

Dictionary of numpy arrays for ‘cos_tilt_1’ and ‘cos_tilt_2’.

xi_spin: float

Fraction of black holes in gaussian component (\(\xi\)).

mu_1: float

Mean of the gaussian component for the more massive black hole (\(\mu_1\)).

mu_2: float

Mean of the gaussian component for the less massive black hole (\(\mu_2\)).

sigma_1: float

Width of the gaussian component for the more massive black hole (\(\sigma_1\)).

sigma_2: float

Width of the gaussian component for the less massive black hole (\(\sigma_2\)).

gwpopulation.models.spin.ln_independent_spin_orientation_gaussian_isotropic(dataset, xi_spin, sigma_1, sigma_2, mu_1=1, mu_2=1)

Log of independent_spin_orientation_gaussian_isotropic(), computed without leaving log space so that the Gaussian component does not underflow far from its mean, e.g., in single precision.

Parameters:

dataset: dict

Dictionary of numpy arrays for ‘cos_tilt_1’ and ‘cos_tilt_2’.

xi_spin: float

Fraction of black holes in gaussian component (\(\xi\)).

mu_1: float

Mean of the gaussian component for the more massive black hole (\(\mu_1\)).

mu_2: float

Mean of the gaussian component for the less massive black hole (\(\mu_2\)).

sigma_1: float

Width of the gaussian component for the more massive black hole (\(\sigma_1\)).

sigma_2: float

Width of the gaussian component for the less massive black hole (\(\sigma_2\)).

gwpopulation.models.spin.gaussian_chi_eff(dataset, mu_chi_eff, sigma_chi_eff)

A Gaussian in chi effective distribution

\[p(\chi_{\text{eff}} | \mu_\chi, \sigma_\chi) = \mathcal{N}_{[-1, 1]}(\chi_{\text{eff}}; \mu=\mu_\chi, \sigma=\sigma_\chi)\]

Where \(\mathcal{N}_{[a, b]}\) is the truncated normal distribution over \([a, b]\).

See Miller+ and Callister+.

Parameters:

dataset: dict

Input data, must contain chi_eff (\(\chi_{\text{eff}}\))

mu_chi_eff: float

Mean of the distribution (\(\mu_\chi\))

sigma_chi_eff: float

Standard deviation of the distribution (\(\sigma_\chi\))

Returns:

array-like: The probability

gwpopulation.models.spin.ln_gaussian_chi_eff(dataset, mu_chi_eff, sigma_chi_eff)

Log of gaussian_chi_eff(), which does not underflow far from the mean, e.g., in single precision.

Parameters:

dataset: dict

Input data, must contain chi_eff (\(\chi_{\text{eff}}\))

mu_chi_eff: float

Mean of the distribution (\(\mu_\chi\))

sigma_chi_eff: float

Standard deviation of the distribution (\(\sigma_\chi\))

Returns:

array-like: The log probability, -inf outside \([-1, 1]\)

gwpopulation.models.spin.gaussian_chi_p(dataset, mu_chi_p, sigma_chi_p)

A Gaussian distribution in precessing effective spin (chi p)

\[p(\chi_p) = \mathcal{N}_{[0, 1]}(\chi_p; \mu=\mu_\chi, \sigma=\sigma_\chi)\]

Where \(\mathcal{N}_{[a, b]}\) is the truncated normal distribution over \([a, b]\).

See Miller+ and Callister+.

Parameters:

dataset: dict

Input data, must contain chi_eff (\(\chi_p\))

mu_chi_p: float

Mean of the distribution (\(\mu_\chi\))

sigma_chi_p: float

Standard deviation of the distribution (\(\sigma_\chi\))

Returns:

array-like: The probability

gwpopulation.models.spin.ln_gaussian_chi_p(dataset, mu_chi_p, sigma_chi_p)

Log of gaussian_chi_p(), which does not underflow far from the mean, e.g., in single precision.

Parameters:

dataset: dict

Input data, must contain chi_p (\(\chi_p\))

mu_chi_p: float

Mean of the distribution (\(\mu_\chi\))

sigma_chi_p: float

Standard deviation of the distribution (\(\sigma_\chi\))

Returns:

array-like: The log probability, -inf outside \([0, 1]\)

class gwpopulation.models.spin.GaussianChiEffChiP

Bases: object

A covariant Gaussian in effective aligned and precessing spins.

\[p(\chi_{\rm eff}, \chi_p | \Lambda) = \mathcal{N}_{[-1, 1], [0, 1]}(\chi_{\rm eff}, \chi_p; [\mu_{\rm eff}, \mu_{p}], \Sigma)\]

Where \(\mathcal{N}_{[a, b], [c, d]}\) is the two-dimensional truncated normal distribution over \([a, b]\) and \([c, d]\).

The covariance matrix is given by:

\[\begin{split}\Sigma = \begin{bmatrix} \sigma^2_{\text{eff}} & \rho \sigma_{\text{eff}} \sigma_{p} \\ \rho \sigma_{\text{eff}} \sigma_{p} & \sigma^2_{p} \end{bmatrix}\end{split}\]

Note

The implementation divides the quadratic form by \(1 - \rho\) rather than \(1 - \rho^2\), so, before truncation, the covariance matrix is \(\Sigma / (1 + \rho)\). The correlation coefficient is \(\rho\), but the standard deviations are \(\sigma_{\text{eff}} / \sqrt{1 + \rho}\) and \(\sigma_{p} / \sqrt{1 + \rho}\), which equal \(\sigma_{\text{eff}}\) and \(\sigma_{p}\) only for \(\rho = 0\); e.g., they are twice as large for \(\rho = -0.75\). See gwpopulation.utils.unnormalized_2d_gaussian().

See Miller+ and Callister+.

Parameters:

dataset: dict

Dictionary of numpy arrays for chi_eff and chi_p.

mu_chi_eff: float

Mean of the chi effective distribution (\(\mu_{\text{eff}}\))

mu_chi_p: float

Mean of the chi p distribution (\(\mu_{p}\))

sigma_chi_eff: float

Standard deviation of the chi effective distribution (\(\sigma_{\text{eff}}\))

sigma_chi_p: float

Standard deviation of the chi p distribution (\(\sigma_{p}\))

spin_covariance: float

Covariance between the two parameters (\(\rho\))

chi_eff

chi_p

__call__(dataset, mu_chi_eff, sigma_chi_eff, mu_chi_p, sigma_chi_p, spin_covariance)

ln_prob(dataset, mu_chi_eff, sigma_chi_eff, mu_chi_p, sigma_chi_p, spin_covariance)

The log of __call__(): the quadratic form of the Gaussian minus the log of its normalization, which does not underflow far from the mean, e.g., in single precision.

Parameters:

dataset: dict

Dictionary of numpy arrays for chi_eff and chi_p.

mu_chi_eff, sigma_chi_eff, mu_chi_p, sigma_chi_p, spin_covariance: float

As for __call__().

Returns:

array-like

The log probability, -inf outside the support.

_normalization(mu_chi_eff, sigma_chi_eff, mu_chi_p, sigma_chi_p, spin_covariance)

Numerically calculate the normalization over a two-dimensional grid with trapezoidal integration

Parameters:

mu_chi_eff: float

Mean of the chi effective distribution (\(\mu_{\text{eff}}\))

mu_chi_p: float

Mean of the chi p distribution (\(\mu_{p}\))

sigma_chi_eff: float

Standard deviation of the chi effective distribution (\(\sigma_{\text{eff}}\))

sigma_chi_p: float

Standard deviation of the chi p distribution (\(\sigma_{p}\))

spin_covariance: float

Covariance between the two parameters (\(\rho\))

Returns:

float

The normalizing constant

class gwpopulation.models.spin.SplineSpinMagnitudeIdentical(minimum=0, maximum=1, nodes=5, kind='cubic', regularize=False)

Bases: gwpopulation.models.interped.InterpolatedNoBaseModelIdentical

Interpolated spline model for spin magnitudes.

See Golomb and Talbot

Parameters:

minimum: float

Minimum value to normalize the spline over, default=0.

maximum: float

Maximum value to normalize the spline over, default=1.

nodes: int

Number of nodes to use in the spline, default=5.

kind: str

The interpolation order of the spline, default=”cubic”.

regularize: bool

Whether to regularize the spline node values to have root-mean-square value rms{name}, default=False.

class gwpopulation.models.spin.SplineSpinTiltIdentical(minimum=-1, maximum=1, nodes=5, kind='cubic', regularize=False)

Bases: gwpopulation.models.interped.InterpolatedNoBaseModelIdentical

Interpolated spline model for spin orientations.

See Golomb and Talbot

Parameters:

minimum: float

Minimum value to normalize the spline over, default=-1.

maximum: float

Maximum value to normalize the spline over, default=1.

nodes: int

Number of nodes to use in the spline, default=5.

kind: str

The interpolation order of the spline, default=”cubic”.

regularize: bool

Whether to regularize the spline node values to have root-mean-square value rms{name}, default=False.