Binaries

class gwGenealogy.binaries.bbh.BBHs(m1=None, m2=None, M=None, q=None, small_q=None, a1=0.0, a2=0.0, theta1=0.0, theta2=0.0, phi1=0.0, phi2=0.0, z=None)

Bases: object

Container for binary black hole parameters.

Parameters:

• m1 (float or array, optional) – Primary mass (m1 >= m2). Provide with m2, OR provide M with q/small_q.

• m2 (float or array, optional) – Secondary mass.

• M (float or array, optional) – Total mass. Provide with q or small_q.

• q (float or array, optional) – Mass ratio m1/m2 >= 1.

• small_q (float or array, optional) – Mass ratio m2/m1 in (0, 1].

• a1 (float or array) – Primary dimensionless spin magnitude.

• a2 (float or array) – Secondary dimensionless spin magnitude.

• theta1 (float or array) – Primary spin tilt angle [rad].

• theta2 (float or array) – Secondary spin tilt angle [rad].

• phi1 (float or array) – Primary azimuthal spin angle [rad].

• phi2 (float or array) – Secondary azimuthal spin angle [rad].

• z (float or array, optional) – Redshift.

gwGenealogy.binaries.bbh_masses.sample_masses(n_samples, m_min=5.0, m_max=50.0, m1_distribution='uniform', pairing='random', alpha=-2.5, beta=6.7, seed=None)

Sample binary black hole masses with flexible m1 distribution and pairing.

Parameters:

• n_samples (int) – Number of binary systems to generate

• m_min (float) – Minimum mass in solar masses (default: 5.0)

• m_max (float) – Maximum mass in solar masses (default: 50.0)

• m1_distribution (str) – Distribution for primary mass (default: ‘uniform’): - ‘uniform’: uniform in [m_min, m_max] - ‘loguniform’: uniform in log-space - ‘powerlaw’: p(m1) ∝ m1^alpha

• pairing (str) – Pairing model for secondary mass (default: ‘random’): - ‘random’: m2 from same distribution as m1, then sort m1 > m2 - ‘secondary_mass_power_law’: p(m2|m1) ∝ m2^beta on [m_min, m1] - ‘total_mass_power_law’: p(m2|m1) ∝ (m1+m2)^4 on [m_min, m1]

• alpha (float) – Power-law index for m1 when m1_distribution=’powerlaw’ (default: -2.5)

• beta (float) – Power-law index for secondary_mass_power_law pairing (default: 6.7)

• seed (int or None) – Random seed for reproducibility (default: None)

Returns:

• m1 (array) – Primary masses in solar masses (m1 >= m2)

• m2 (array) – Secondary masses in solar masses

References

Flat/log/powerlaw models: Abbott et al. (2017), https://arxiv.org/abs/1703.06223 secondary_mass_power_law: Fragione & Silk (2020), https://arxiv.org/abs/1906.05295 total_mass_power_law: O’Leary et al. (2016), https://arxiv.org/abs/1602.02809

gwGenealogy.binaries.bbh_spins.sample_spins(n_samples, chi_min=0, chi_max=1, spin_magnitude='uniform', spin_angles='isotropic', beta_a=1.4, beta_b=3.6, tilt_beta_a=None, tilt_beta_b=None, seed=None)

Sample spin vectors for binary black hole systems with flexible distributions.

Parameters:

n_samplesint

Number of spin pairs to generate

chi_minfloat

Minimum dimensionless spin magnitude (default: 0)

chi_maxfloat

Maximum dimensionless spin magnitude (default: 1)

spin_magnitudestr

Distribution for spin magnitudes. Options: - ‘uniform’: Uniform distribution between chi_min and chi_max - ‘beta’: Beta distribution with parameters beta_a and beta_b

spin_anglesstr

Distribution for spin orientations. Options: - ‘isotropic’: Uniform distribution on the sphere (physically motivated) - ‘uniform’: Uniform distribution in theta angle - ‘beta’: Beta(tilt_beta_a, tilt_beta_b) on [0, 1] radian

beta_afloat

Alpha parameter for spin magnitude Beta distribution (default: 1.4) Only used when spin_magnitude=’beta’

beta_bfloat

Beta parameter for spin magnitude Beta distribution (default: 3.6) Only used when spin_magnitude=’beta’ Default values are based on https://arxiv.org/abs/2111.03634

tilt_beta_afloat or None

Alpha parameter for tilt Beta distribution. Required when spin_angles=’beta’

tilt_beta_bfloat or None

Beta parameter for tilt Beta distribution. Required when spin_angles=’beta’

seedint or None

Random seed for reproducibility (default: None)

Returns:

chi1numpy array of shape (n_samples, 3)

3D spin vectors for the primary black hole

chi2numpy array of shape (n_samples, 3)

3D spin vectors for the secondary black hole

gwGenealogy.binaries.bbh_spins.sample_spin_magnitudes(n_samples, chi_min, chi_max, spin_magnitude, beta_a, beta_b, seed=None)

Sample spin magnitudes based on specified distribution.

Parameters:

n_samplesint

Number of samples to generate

chi_minfloat

Minimum spin magnitude

chi_maxfloat

Maximum spin magnitude

spin_magnitudestr

Distribution type: ‘uniform’ or ‘beta’

beta_afloat

Alpha parameter for Beta distribution

beta_bfloat

Beta parameter for Beta distribution

seedint or None

Random seed for reproducibility (default: None)

Returns:

a1numpy array of shape (n_samples,)

Spin magnitudes for primary black hole

a2numpy array of shape (n_samples,)

Spin magnitudes for secondary black hole

gwGenealogy.binaries.bbh_spins.sample_spin_angles(n_samples, spin_angles='isotropic', tilt_beta_a=None, tilt_beta_b=None, seed=None)

Sample spin orientation angles.

Parameters:

n_samplesint

Number of samples to generate

spin_anglesstr

Distribution type (default: ‘isotropic’): - ‘isotropic’: uniform on the sphere (uniform in cos theta) - ‘uniform’: uniform in theta on [0, pi] - ‘beta’: Beta(a, b) on [0, 1] radian (preferentially aligned)

tilt_beta_afloat or None

Alpha parameter for Beta tilt distribution (required when spin_angles=’beta’)

tilt_beta_bfloat or None

Beta parameter for Beta tilt distribution (required when spin_angles=’beta’)

seedint or None

Random seed for reproducibility (default: None)

Returns:

theta1, theta2numpy array of shape (n_samples,)

Polar (tilt) angles in radians

phi1, phi2numpy array of shape (n_samples,)

Azimuthal angles in radians

gwGenealogy.binaries.bbh_redshifts.E(z, Om0=0.315, OL0=0.685)

Dimensionless Hubble parameter E(z) = H(z)/H0

For flat ΛCDM: E(z) = sqrt(Ωm(1+z)^3 + ΩΛ)

Parameters: - z: Redshift - Om0: Matter density parameter (default: 0.315) - OL0: Dark energy density parameter (default: 0.685)

Returns: - E(z): Dimensionless Hubble parameter

gwGenealogy.binaries.bbh_redshifts.comoving_volume_element(z, H0=67.4, Om0=0.315, OL0=0.685)

Differential comoving volume element dV_c/dz

dV_c/dz = (4π c / H0) * (d_L(z) / (1+z))^2 / E(z)

where d_L(z) is the luminosity distance

Parameters: - z: Redshift - H0: Hubble constant in km/s/Mpc (default: 67.4) - Om0: Matter density parameter (default: 0.315) - OL0: Dark energy density parameter (default: 0.685)

Returns: - dV_c/dz: Comoving volume element in Gpc^3

gwGenealogy.binaries.bbh_redshifts.luminosity_distance(z, H0=67.4, Om0=0.315, OL0=0.685)

Luminosity distance as a function of redshift

d_L(z) = (1+z) * (c/H0) * ∫[0 to z] dz’/E(z’)

Parameters: - z: Redshift (can be array) - H0: Hubble constant in km/s/Mpc (default: 67.4) - Om0: Matter density parameter (default: 0.315) - OL0: Dark energy density parameter (default: 0.685)

Returns: - d_L: Luminosity distance in Mpc

gwGenealogy.binaries.bbh_redshifts.redshift_probability_density(z, z_max=10.0)

Probability density for redshift distribution

p(z) ∝ (dV_c/dz) / (1+z)

The (1+z) factor accounts for cosmological time dilation, converting source-frame time to observer-frame time.

Parameters: - z: Redshift (can be array) - z_max: Maximum redshift to consider (default: 10.0)

Returns: - p(z): Unnormalized probability density

gwGenealogy.binaries.bbh_redshifts.sample_redshift(n_samples, z_min=0.0, z_max=10.0, seed=None)

Sample redshifts from the uniform-rate distribution:

p(z) ∝ dVc/dz / (1+z)

i.e. R(z) = const (uniform in comoving volume and source-frame time).

Parameters: - n_samples: Number of redshift values to sample - z_min: Minimum redshift (default: 0.0) - z_max: Maximum redshift (default: 10.0) - seed: Random seed for reproducibility (default: None)

Returns: - z_samples: Array of sampled redshifts

gwGenealogy.binaries.bbh_redshifts.powerlaw_redshift_pdf(z, lamb, z_max=10.0)

Unnormalized probability density for the PowerLaw merger-rate model.

p(z) ∝ (1+z)^lambda * dVc/dz / (1+z)

Parameters: - z: Redshift (scalar or array) - lamb: Power-law index lambda (lamb > 0 = rate increases with z) - z_max: Maximum redshift (default: 10.0)

Returns: - p(z): Unnormalized probability density

gwGenealogy.binaries.bbh_redshifts.sample_redshift_powerlaw(n_samples, lamb, z_min=0.0, z_max=10.0, seed=None)

Sample redshifts from the PowerLaw merger-rate model:

p(z) ∝ (1+z)^lambda * dVc/dz / (1+z)

Parameters: - n_samples: Number of redshift values to sample - lamb: Power-law index lambda - z_min: Minimum redshift (default: 0.0) - z_max: Maximum redshift (default: 10.0) - seed: Random seed for reproducibility (default: None)

Returns: - z_samples: Array of sampled redshifts

gwGenealogy.binaries.bbh_redshifts.madau_dickinson_redshift_pdf(z, gamma, kappa, z_peak, z_max=10.0)

Unnormalized probability density for the Madau-Dickinson merger-rate model.

R(z) = (1+z)^gamma / [1 + ((1+z)/(1+z_peak))^kappa] p(z) ∝ R(z) * dVc/dz / (1+z)

Parameters: - z: Redshift (scalar or array) - gamma: Low-z power-law slope - kappa: High-z turnover steepness - z_peak: Peak redshift of the merger rate - z_max: Maximum redshift (default: 10.0)

Returns: - p(z): Unnormalized probability density

gwGenealogy.binaries.bbh_redshifts.sample_redshift_madau_dickinson(n_samples, gamma, kappa, z_peak, z_min=0.0, z_max=10.0, seed=None)

Sample redshifts from the Madau-Dickinson merger-rate model:

R(z) = (1+z)^gamma / [1 + ((1+z)/(1+z_peak))^kappa] p(z) ∝ R(z) * dVc/dz / (1+z)

Parameters: - n_samples: Number of redshift values to sample - gamma: Low-z power-law slope - kappa: High-z turnover steepness - z_peak: Peak redshift of the merger rate - z_min: Minimum redshift (default: 0.0) - z_max: Maximum redshift (default: 10.0) - seed: Random seed for reproducibility (default: None)

Returns: - z_samples: Array of sampled redshifts

gwGenealogy.binaries.bbh_remnant.preload_kick_model(kick_model)

Trigger any one-time lazy model loading for a kick model.

The IW2025 gwmodel flow is lazy-loaded on first use, and that load perturbs the global torch RNG state. Calling this once before seeding the legacy RNG keeps the seeded sampling path reproducible even on the first kick computation in a process. No-op for models without lazy state.

Parameters:

kick_model (str) – Kick model name, as passed to BBHRemnant.

class gwGenealogy.binaries.bbh_remnant.BBHRemnant(bbh=None, m1=None, m2=None, a1=None, a2=None, theta1=None, theta2=None, phi1=None, phi2=None, precessing=True, mass_spin_model=None, kick_model=None)

Bases: object

Compute remnant properties for BBH mergers.

Parameters:

• bbh (BBHs instance, optional) – A gwGenealogy.binaries.BBHs object. If provided, all binary parameters are taken from it.

• m1 (array, optional) – Component masses [Msun]. Required if bbh is not given.

• m2 (array, optional) – Component masses [Msun]. Required if bbh is not given.

• a1 (array, optional) – Spin magnitudes [0, 1].

• a2 (array, optional) – Spin magnitudes [0, 1].

• theta1 (array, optional) – Spin tilt angles [rad].

• theta2 (array, optional) – Spin tilt angles [rad].

• phi1 (array, optional) – Spin azimuthal angles [rad].

• phi2 (array, optional) – Spin azimuthal angles [rad].

• precessing (bool) – True (default) for precessing models, False for nonprecessing.

• mass_spin_model (str or None) – Model for remnant mass and spin. None uses the default. Precessing: ‘hbr’ (default), ‘sur7dq4remnant’, ‘sur7dq4emri’ Nonprecessing: ‘uib’ (default), ‘hbr’, ‘sur7dq4remnant’, ‘sur7dq4emri’

• kick_model (str or None) – Model for kick velocity. None uses the default. Precessing: ‘gwmodel’ (default), ‘hlz’ (-> CLZM2007), ‘sur7dq4remnant’ Nonprecessing: ‘gwmodel_kick_q200’ (default), ‘hlz’ (-> HLZ2014), ‘sur3dq8remnant’

• construction) (Attributes (after)

• ----------

• Mf (array) – Remnant mass [Msun]

• af (array) – Remnant spin magnitude

• vkick (array) – Kick velocity [km/s]

gwGenealogy.binaries.bbh_gwtc.download_gwtc_data(catalog=None, dest=None, quiet=False)

Download GWTC population data files from Google Drive.

These files are not shipped with the package (each is several hundred MB). They are fetched into the user data directory (~/.gwGenealogy/data, or $GWGENEALOGY_DATA, or dest) where the samplers look for them.

Parameters:

• catalog (str or None) – Download only the file for this catalog (e.g. ‘gwtc5’, ‘gwtc4’, ‘gwtc3’); None (default) downloads all catalogs.

• dest (str or Path or None) – Target directory. Defaults to the user data directory.

• quiet (bool) – Suppress gdown progress output.

Returns:

pathlib.Path

Return type:

the directory the files were downloaded into.

gwGenealogy.binaries.bbh_gwtc.sample_gwtc_population(n_samples, catalog='gwtc5', source='posterior', mode='ppd', data_dir=None, n_hyper_draws=1000, gwtc3_hyper_samples=None, seed=None)

Sample BBH parameters from GWTC default-family population models.

Parameters:

• n_samples (int) – Number of BBH systems to draw

• catalog (str) – Population catalog (default: ‘gwtc5’): - ‘gwtc3’: Power Law + Peak, Beta spin, tilt peak fixed at +1 - ‘gwtc4’: Broken PowerLaw + Two Peaks, Gaussian spin, free tilt peak - ‘gwtc5’: same model family as gwtc4, O3+O4 selection - ‘gwtc5_var4’: gwtc5 with looser selection-variance cut - ‘gwtc5_madau_dickinson’: gwtc5 mass/spin + Madau-Dickinson redshift

• source (str) – ‘prior’ or ‘posterior’ (default: ‘posterior’)

• mode (str or int) – Sampling mode (default: ‘ppd’): - ‘ppd’: posterior predictive (random hyper-draw per binary) - ‘mean’: hyper-posterior/prior-averaged distribution - int: single hyper-draw index

• data_dir (str or Path or None) – Directory containing popsummary HDF5 files. If None, searches the package data/ directory. Required for source=’posterior’ if files are not in the package data/ directory.

• n_hyper_draws (int) – Number of hyper-prior draws for source=’prior’, or number of hyper-posterior draws to subsample for gwtc3 (default: 1000)

• gwtc3_hyper_samples (dict or None) – Pre-loaded GWTC-3 hyper-posterior samples. If None and catalog=’gwtc3’ with source=’posterior’, loads from gwtc3_default.json.

• seed (int or None) – Random seed for reproducibility

Returns:

Dictionary with keys: mass_1, mass_2, q (=m1/m2 >= 1), small_q (=m2/m1), a1, a2, cos_theta1, cos_theta2, theta1, theta2, redshift, chi_eff, chi_p (and hyper_draw_index if mode != ‘mean’)

Return type:

dict

gwGenealogy.binaries.bbh_gwtc.available_catalogs()

Return list of available catalog keys.

gwGenealogy.binaries.smbbh.sample_smbbh(n_samples, accretion='hot', m_total_min=100000.0, m_total_max=100000000000.0, seed=None)

Sample supermassive BBH binary parameters for a given accretion model.

Parameters:

• n_samples (int) – Number of binary systems to generate

• accretion (str) – Accretion type (default: ‘hot’): - ‘agnostic’: uniform spins on [0,1], isotropic orientations - ‘hot’: hot wet accretion (high spins, preferentially aligned) - ‘cold’: cold wet accretion (very high spins, strongly aligned) - ‘dry’: dry merger (moderate spins, isotropic orientations)

• m_total_min (float) – Minimum total mass in Msun (default: 1e5)

• m_total_max (float) – Maximum total mass in Msun (default: 1e11)

• seed (int or None) – Random seed for reproducibility

Returns:

Dictionary with keys: - m_total: total mass in Msun - mass_1: primary mass in Msun (m1 >= m2) - mass_2: secondary mass in Msun - q: mass ratio m1/m2 >= 1 - small_q: mass ratio m2/m1 in (0, 1] - a1: primary spin magnitude - a2: secondary spin magnitude - theta1: primary spin tilt angle (rad) - theta2: secondary spin tilt angle (rad) - cos_theta1, cos_theta2: cosines of tilt angles - phi1: primary azimuthal angle (rad) - phi2: secondary azimuthal angle (rad)

Return type:

dict