Utils
- gwGenealogy.utils.distributions.seed_legacy_rng(rng_or_seed)[source]
Seed the global (legacy) RNG backends reproducibly.
Some kick models draw from the global RNG rather than from a passed-in Generator: the precessing CLZM2007 formula uses
np.random.uniformfor its azimuthal angle, and the IW2025gwmodelflow samples via torch. To keep results reproducible from our controlled RNG chain, this seeds bothnp.randomand torch (if installed).- Parameters:
rng_or_seed (numpy.random.Generator or int) – If a Generator, one integer seed is drawn from it (advancing its state). If an int, it is used directly — useful to apply the same legacy seed to several calls (e.g. evaluating multiple kick models on an identical realization).
- Returns:
int
- Return type:
the seed applied to the legacy backends.
- gwGenealogy.utils.distributions.sample_uniform_1d(n_samples, low=0.0, high=1.0, seed=None, plot=False, bins=50)[source]
Sample using NumPy’s recommended random generator
Parameters: - n_samples: Number of samples to generate - low: Lower bound of the uniform distribution (default: 0.0) - high: Upper bound of the uniform distribution (default: 1.0) - seed: Random seed for reproducibility (default: None) - plot: Whether to plot the distribution (default: False) - bins: Number of histogram bins for plotting (default: 50)
Returns: - Array of sampled points
samples = sample_uniform_rng(1000, seed=42)
- gwGenealogy.utils.distributions.sample_loguniform_1d(n_samples, low=1.0, high=10.0, seed=None, plot=False, bins=50, base=10)[source]
Sample uniformly in log-space (log-uniform distribution)
Parameters: - n_samples: Number of samples to generate - low: Lower bound of the distribution (default: 1.0, must be > 0) - high: Upper bound of the distribution (default: 10.0) - seed: Random seed for reproducibility (default: None) - plot: Whether to plot the distribution (default: False) - bins: Number of histogram bins for plotting (default: 50) - base: Logarithm base (default: 10)
Returns: - Array of sampled points
Note: low must be > 0 for log-uniform sampling
Example: samples = sample_loguniform_1d(1000, low=1, high=100, seed=42)
- gwGenealogy.utils.distributions.sample_gaussian_1d(n_samples, mean=0.0, std=1.0, seed=None, plot=False, bins=50)[source]
Sample from a Gaussian (normal) distribution
Parameters: - n_samples: Number of samples to generate - mean: Mean of the Gaussian distribution (default: 0.0) - std: Standard deviation of the Gaussian distribution (default: 1.0) - seed: Random seed for reproducibility (default: None) - plot: Whether to plot the distribution (default: False) - bins: Number of histogram bins for plotting (default: 50)
Returns: - Array of sampled points
- gwGenealogy.utils.distributions.sample_lognormal_1d(n_samples, mean=0.0, sigma=1.0, seed=None, plot=False, bins=50)[source]
Sample from a log-normal distribution
Parameters: - n_samples: Number of samples to generate - mean: Mean of the underlying normal distribution (default: 0.0) - sigma: Standard deviation of the underlying normal distribution (default: 1.0) - seed: Random seed for reproducibility (default: None) - plot: Whether to plot the distribution (default: False) - bins: Number of histogram bins for plotting (default: 50)
Returns: - Array of sampled points
- gwGenealogy.utils.distributions.sample_powerlaw_1d(n_samples, beta, xmin=1.0, xmax=10.0, seed=None, plot=False, bins=50)[source]
Sample from a power-law distribution with PDF ∝ x^β
Parameters: - n_samples: Number of samples to generate - beta: Power-law exponent (β in x^β) - xmin: Minimum value of the distribution (default: 1.0) - xmax: Maximum value of the distribution (default: 10.0) - seed: Random seed for reproducibility (default: None) - plot: Whether to plot the distribution (default: False) - bins: Number of histogram bins for plotting (default: 50)
Returns: - Array of sampled points
- gwGenealogy.utils.distributions.sample_maxwellian_1d(n_samples, sigma=1.0, seed=None, plot=False, bins=50)[source]
Sample from a Maxwell (speed) distribution.
The Maxwell distribution describes the magnitude of a 3D isotropic Gaussian velocity vector with per-component dispersion sigma:
f(v) = sqrt(2/pi) * (v^2 / sigma^3) * exp(-v^2 / (2*sigma^2))
Mean: sigma * sqrt(8/pi).
Parameters: - n_samples: Number of samples to generate - sigma: 1D velocity dispersion (default: 1.0) - seed: Random seed for reproducibility (default: None) - plot: Whether to plot the distribution (default: False) - bins: Number of histogram bins for plotting (default: 50)
Returns: - Array of sampled speeds (>= 0)
- gwGenealogy.utils.distributions.sample_beta_1d(n_samples, a=1.4, b=3.6, seed=None, plot=False, bins=50)[source]
Sample from a Beta distribution
For spin magnitudes (https://arxiv.org/abs/2111.03634)
Parameters: - n_samples: Number of samples to generate - a: Alpha parameter of the Beta distribution (default: 1.4) - b: Beta parameter of the Beta distribution (default: 3.6) - seed: Random seed for reproducibility (default: None) - plot: Whether to plot the distribution (default: False) - bins: Number of histogram bins for plotting (default: 50)
Returns: - Array of sampled points (values between 0 and 1)
- gwGenealogy.utils.conversions.m1_m2_to_q(m1, m2)[source]
Mass ratio q = m1/m2 >= 1.
If m1 < m2 for any element, the masses are swapped so that q >= 1.
- gwGenealogy.utils.conversions.m1_m2_to_eta(m1, m2)[source]
Symmetric mass ratio eta = m1*m2 / (m1+m2)^2.
- gwGenealogy.utils.conversions.source_frame_to_detector_frame_mass(m_source, z)[source]
Convert source-frame mass to detector-frame mass.
m_detector = (1 + z) * m_source
- gwGenealogy.utils.conversions.detector_frame_to_source_frame_mass(m_detector, z)[source]
Convert detector-frame mass to source-frame mass.
m_source = m_detector / (1 + z)
- gwGenealogy.utils.conversions.chi_eff(q, chi1z, chi2z)[source]
Effective inspiral spin parameter.
chi_eff = (q * chi1z + chi2z) / (1 + q)
- gwGenealogy.utils.conversions.chi_p(q, chi1_perp, chi2_perp)[source]
Effective precession spin parameter.
chi_p = max(chi1_perp, (4 + 3q) / (q(4q + 3)) * chi2_perp)
- gwGenealogy.utils.conversions.delta_parallel(q, chi1, chi2, theta1, theta2)[source]
Parallel component of the asymmetric spin combination Delta.
Delta_parallel = |q * chi1 * cos(theta1) - chi2 * cos(theta2)| / (1 + q)
- gwGenealogy.utils.conversions.delta_perp(q, chi1, chi2, theta1, theta2, delta_phi)[source]
Perpendicular component of the asymmetric spin combination Delta.
- Parameters:
q (float or array) – Mass ratio q = m1/m2 >= 1
chi1 (float or array) – Dimensionless spin magnitudes
chi2 (float or array) – Dimensionless spin magnitudes
theta1 (float or array) – Tilt angles in radians
theta2 (float or array) – Tilt angles in radians
delta_phi (float or array) – Azimuthal angle difference phi1 - phi2 in radians
- Return type:
float or array
- gwGenealogy.utils.conversions.chi_tilde_parallel(q, chi1, chi2, theta1, theta2)[source]
Parallel component of the symmetric spin combination chi-tilde.
chi_tilde_parallel = (q^2 * chi1 * cos(theta1) + chi2 * cos(theta2)) / (1 + q)^2
- gwGenealogy.utils.conversions.chi_tilde_perp(q, chi1, chi2, theta1, theta2, delta_phi)[source]
Perpendicular component of the symmetric spin combination chi-tilde.
- Parameters:
q (float or array) – Mass ratio q = m1/m2 >= 1
chi1 (float or array) – Dimensionless spin magnitudes
chi2 (float or array) – Dimensionless spin magnitudes
theta1 (float or array) – Tilt angles in radians
theta2 (float or array) – Tilt angles in radians
delta_phi (float or array) – Azimuthal angle difference phi1 - phi2 in radians
- Return type:
float or array
- gwGenealogy.utils.coordinates.polar_to_cartesian(r, theta, phi)[source]
Convert spherical polar coordinates to Cartesian.
- gwGenealogy.utils.coordinates.cartesian_to_polar(x, y, z)[source]
Convert Cartesian coordinates to spherical polar.
- Parameters:
- Returns:
r (float or array) – Radial coordinate (>= 0)
theta (float or array) – Polar angle in radians [0, pi]
phi (float or array) – Azimuthal angle in radians [0, 2*pi)
- gwGenealogy.utils.coordinates.spins_polar_to_cartesian_vectors(a1, a2, theta1, theta2, phi1, phi2)[source]
Convert spin magnitudes and angles to 3D Cartesian spin vectors.
- Parameters:
a1 (array) – Dimensionless spin magnitudes
a2 (array) – Dimensionless spin magnitudes
theta1 (array) – Polar (tilt) angles in radians
theta2 (array) – Polar (tilt) angles in radians
phi1 (array) – Azimuthal angles in radians
phi2 (array) – Azimuthal angles in radians
- Returns:
chi1 (array of shape (n_samples, 3)) – 3D spin vectors for the primary black hole
chi2 (array of shape (n_samples, 3)) – 3D spin vectors for the secondary black hole
- gwGenealogy.utils.coordinates.spins_cartesian_vectors_to_polar(chi1_vec, chi2_vec)[source]
Convert 3D Cartesian spin vectors to magnitudes and angles.
- Parameters:
chi1_vec (array of shape (n_samples, 3) or (3,)) – 3D spin vectors for the primary black hole
chi2_vec (array of shape (n_samples, 3) or (3,)) – 3D spin vectors for the secondary black hole
- Returns:
a1, a2 (array) – Dimensionless spin magnitudes
theta1, theta2 (array) – Polar (tilt) angles in radians
phi1, phi2 (array) – Azimuthal angles in radians
- gwGenealogy.utils.statistics.compute_kullback_leibler_divergence(samples_a, samples_b, n_bins=100)[source]
Compute the Kullback-Leibler divergence KL(P || Q) from two sets of samples.
Note: KL divergence is asymmetric — KL(P||Q) != KL(Q||P).
Parameters:
- samples_aarray
Samples from distribution P
- samples_barray
Samples from distribution Q
- n_binsint
Number of histogram bins (default: 100)
Returns:
- klfloat
KL divergence (>= 0; 0 iff P == Q)
- gwGenealogy.utils.statistics.compute_jensen_shannon_divergence(samples_a, samples_b, n_bins=100)[source]
Compute the Jensen-Shannon divergence between two sets of samples.
JSD is a symmetric, bounded measure of the similarity between two probability distributions, based on the KL divergence.
Parameters:
- samples_aarray
First set of samples
- samples_barray
Second set of samples
- n_binsint
Number of histogram bins (default: 100)
Returns:
- jsdfloat
Jensen-Shannon divergence (0 = identical, ln(2) = maximally different)