ler.gw_source_population.cbc_source_parameter_distribution

Module for sampling compact binary coalescence (CBC) source parameters.

This module provides the CBCSourceParameterDistribution class for generating complete sets of intrinsic and extrinsic gravitational wave parameters for compact binary sources (BBH, BNS, NSBH). It includes mass distributions, spin parameters, sky positions, and other parameters needed for GW analysis.

Inheritance hierarchy:

• CBCSourceRedshiftDistribution

Usage:

Basic workflow example:

>>> from ler.gw_source_population import CBCSourceParameterDistribution
>>> cbc = CBCSourceParameterDistribution(event_type='BBH')
>>> params = cbc.sample_gw_parameters(size=1000)
>>> print(list(params.keys()))

Module Contents

Classes

CBCSourceParameterDistribution

Class for sampling compact binary coalescence source parameters.

Attributes

chunk_size

ler.gw_source_population.cbc_source_parameter_distribution.chunk_size = '10000'

class ler.gw_source_population.cbc_source_parameter_distribution.CBCSourceParameterDistribution(z_min=0.0, z_max=10.0, event_type='BBH', source_priors=None, source_priors_params=None, cosmology=None, spin_zero=False, spin_precession=False, directory='./interpolator_json', create_new_interpolator=False)

Bases: ler.gw_source_population.cbc_source_redshift_distribution.CBCSourceRedshiftDistribution

Class for sampling compact binary coalescence source parameters.

This class generates complete sets of intrinsic and extrinsic gravitational wave parameters for compact binary sources including masses, spins, sky positions, and orbital parameters. It supports BBH, BNS, NSBH, and primordial black hole populations with configurable prior distributions.

Key Features:

• Multiple mass distribution models (PowerLaw+Gaussian, lognormal, bimodal)

• Configurable spin priors (zero, aligned, precessing)

• Isotropic sky position and orientation sampling

• Built-in support for population III and primordial black holes

Parameters:

z_minfloat

Minimum redshift of the source population.

default: 0.0

z_maxfloat

Maximum redshift of the source population.

default: 10.0

event_typestr

Type of compact binary event to generate.

Options:

• ‘BBH’: Binary black hole (Population I/II)

• ‘BNS’: Binary neutron star

• ‘NSBH’: Neutron star-black hole

• ‘BBH_popIII’: Population III binary black hole

• ‘BBH_primordial’: Primordial binary black hole

default: ‘BBH’

source_priorsdict or None

Dictionary of prior sampler functions for each parameter.

If None, uses default priors based on event_type.

default: None

source_priors_paramsdict or None

Dictionary of parameters for each prior sampler function.

If None, uses default parameters based on event_type.

default: None

cosmologyastropy.cosmology or None

Cosmology to use for distance calculations.

default: LambdaCDM(H0=70, Om0=0.3, Ode0=0.7, Tcmb0=0.0, Neff=3.04, m_nu=None, Ob0=0.0)

spin_zerobool

If True, spin parameters are set to zero (no spin sampling).

default: False

spin_precessionbool

If True (and spin_zero=False), sample precessing spin parameters.

If False (and spin_zero=False), sample aligned/anti-aligned spins.

default: False

directorystr

Directory to store interpolator JSON files.

default: ‘./interpolator_json’

create_new_interpolatordict or bool

Configuration for creating new interpolators.

If bool, applies to all interpolators.

default: False

Examples

>>> from ler.gw_source_population import CBCSourceParameterDistribution
>>> cbc = CBCSourceParameterDistribution(event_type='BBH')
>>> params = cbc.sample_gw_parameters(size=1000)
>>> print(list(params.keys()))

Instance Methods

CBCSourceParameterDistribution has the following methods:

Instance Attributes

CBCSourceParameterDistribution has the following attributes:

Attribute	Type	Unit	Description
z_min	float		Minimum redshift of source population
z_max	float		Maximum redshift of source population
cosmo	astropy.cosmology		Cosmology for distance calculations
spin_zero	bool		Whether to ignore spin parameters
spin_precession	bool		Whether to use precessing spins
directory	str		Directory for interpolator files
gw_param_samplers	dict		Dictionary of parameter sampler functions
gw_param_samplers_params	dict		Dictionary of sampler function parameters
available_gw_prior	dict		Available prior distributions
source_frame_masses	callable		Sampler for source frame masses
zs	callable		Sampler for source redshift
geocent_time	callable		Sampler for geocentric time
ra	callable		Sampler for right ascension
dec	callable		Sampler for declination
phase	callable		Sampler for coalescence phase
psi	callable		Sampler for polarization angle
theta_jn	callable		Sampler for inclination angle
a_1	callable		Sampler for spin1 magnitude
a_2	callable		Sampler for spin2 magnitude
tilt_1	callable		Sampler for tilt1 angle
tilt_2	callable		Sampler for tilt2 angle
phi_12	callable		Sampler for phi_12 angle
phi_jl	callable		Sampler for phi_jl angle

property zs

Class object (of FunctionConditioning) for source redshift, with rvs/sampler as callback. Can also be a user defined callable sampler.

The class object contains the following attribute methods:

• rvs: returns random samples from the redshift distribution

• pdf: returns the probability density function of the redshift distribution

• function: returns the redshift distribution function.

Returns:

zsnumpy.ndarray

Array of redshift values.

property source_frame_masses

Class object (of FunctionConditioning) for source frame masses, with rvs/sampler as callback. Can also be a user defined callable sampler.

The class object contains the following attribute methods:

• rvs: returns random samples from the density profile slope distribution

Returns:

mass_1_sourcenumpy.ndarray

Array of mass_1_source values in solar masses.

mass_2_sourcenumpy.ndarray

Array of mass_2_source values in solar masses.

Examples

>>> from ler.gw_source_population import CBCSourceParameterDistribution
>>> cbc_source_param_dist = CBCSourceParameterDistribution()
>>> cbc_source_param_dist.source_frame_masses(size=10)

property geocent_time

Class object (of FunctionConditioning) for geocentric time, with rvs/sampler as callback. Can also be a user defined callable sampler.

The class object contains the following attribute methods:

• rvs: returns random samples from the geocentric time distribution

• pdf: returns the probability density function of the geocentric time distribution

• function: returns the geocentric time distribution function.

Returns:

geocent_timenumpy.ndarray

Array of geocentric time values.

property ra

Class object (of FunctionConditioning) for right ascension, with rvs/sampler as callback. Can also be a user defined callable sampler.

The class object contains the following attribute methods:

• rvs: returns random samples from the right ascension distribution

• pdf: returns the probability density function of the right ascension distribution

• function: returns the right ascension distribution function.

Returns:

ranumpy.ndarray

Array of right ascension values.

property dec

Class object (of FunctionConditioning) for declination, with rvs/sampler as callback. Can also be a user defined callable sampler.

The class object contains the following attribute methods:

• rvs: returns random samples from the declination distribution

• pdf: returns the probability density function of the declination distribution

• function: returns the declination distribution function.

Returns:

decnumpy.ndarray

Array of declination values.

property phase

Class object (of FunctionConditioning) for coalescence phase, with rvs/sampler as callback. Can also be a user defined callable sampler.

The class object contains the following attribute methods:

• rvs: returns random samples from the coalescence phase distribution

• pdf: returns the probability density function of the coalescence phase distribution

• function: returns the coalescence phase distribution function.

Returns:

phasenumpy.ndarray

Array of coalescence phase values.

property psi

Class object (of FunctionConditioning) for polarization angle, with rvs/sampler as callback. Can also be a user defined callable sampler.

The class object contains the following attribute methods:

• rvs: returns random samples from the polarization angle distribution

• pdf: returns the probability density function of the polarization angle distribution

• function: returns the polarization angle distribution function.

Returns:

geocent_timenumpy.ndarray

Array of polarization angle values.

property theta_jn

Class object (of FunctionConditioning) for inclination angle, with rvs/sampler as callback. Can also be a user defined callable sampler.

The class object contains the following attribute methods:

• rvs: returns random samples from the inclination angle distribution

• pdf: returns the probability density function of the inclination angle distribution

• function: returns the inclination angle distribution function.

Returns:

theta_jnnumpy.ndarray

Array of inclination angle values, i.e. the angle between the line of sight and the orbital angular momentum (rad).

property a_1

Class object (of FunctionConditioning) for spin1 magnitude, with rvs/sampler as callback. Can also be a user defined callable sampler.

The class object contains the following attribute methods:

• rvs: returns random samples from the spin1 magnitude distribution

• pdf: returns the probability density function of the spin1 magnitude distribution

• function: returns the spin1 magnitude distribution function.

Returns:

a_1numpy.ndarray

Array of spin magnitude values for the primary body.

property a_2

Class object (of FunctionConditioning) for spin2 magnitude, with rvs/sampler as callback. Can also be a user defined callable sampler.

The class object contains the following attribute methods:

• rvs: returns random samples from the spin2 magnitude distribution

• pdf: returns the probability density function of the spin2 magnitude distribution

• function: returns the spin2 magnitude distribution function.

Returns:

a_2numpy.ndarray

Array of spin magnitude values for the secondary body.

property tilt_1

Class object (of FunctionConditioning) for tilt1 angle, with rvs/sampler as callback. Can also be a user defined callable sampler.

The class object contains the following attribute methods:

• rvs: returns random samples from the tilt1 angle distribution

• pdf: returns the probability density function of the tilt1 angle distribution

• function: returns the tilt1 angle distribution function.

Returns:

tilt_1numpy.ndarray

Array of the spin tilt angle of the primary body, i.e. the angle between the spin vector and the orbital angular momentum for the primary body (rad).

property tilt_2

Class object (of FunctionConditioning) for tilt2 angle, with rvs/sampler as callback. Can also be a user defined callable sampler.

The class object contains the following attribute methods:

• rvs: returns random samples from the tilt2 angle distribution

• pdf: returns the probability density function of the tilt2 angle distribution

• function: returns the tilt2 angle distribution function.

Returns:

tilt_2numpy.ndarray

Array of the spin tilt angle of the secondary body, i.e. the angle between the spin vector and the orbital angular momentum for the secondary body (rad).

property phi_12

Class object (of FunctionConditioning) for phi_12 angle, with rvs/sampler as callback. Can also be a user defined callable sampler.

The class object contains the following attribute methods:

• rvs: returns random samples from the phi_12 angle distribution

• pdf: returns the probability density function of the phi_12 angle distribution

• function: returns the phi_12 angle distribution function.

Returns:

phi_12numpy.ndarray

Array of the spin tilt angle between the two spins, i.e., angle between the projections of the two spins onto the orbital plane (rad).

property phi_jl

Class object (of FunctionConditioning) for phi_jl angle, with rvs/sampler as callback. Can also be a user defined callable sampler.

The class object contains the following attribute methods:

• rvs: returns random samples from the phi_jl angle distribution

• pdf: returns the probability density function of the phi_jl angle distribution

• function: returns the phi_jl angle distribution function.

Returns:

phi_jlnumpy.ndarray

Array of the angle values between the orientation of the total angular momentum around the orbital angular momentum (rad).

property available_gw_prior

Dictionary of all available prior distributions and their parameters.

This is a dynamically generated dictionary containing available samplers for each GW parameter type and their default parameter values.

Returns:

available_gw_priordict

Nested dictionary organized by parameter type (e.g., ‘source_frame_masses’,

‘geocent_time’, etc.) with sampler names and default parameters.

z_min = 'None'

float

Minimum redshift of the source population

z_max = 'None'

float

Maximum redshift of the source population

event_type = 'None'

str

Type of event to generate.

e.g. ‘BBH’, ‘BNS’, ‘NSBH’

source_priors = 'None'

dict

Dictionary of prior sampler functions.

source_priors_params = 'None'

dict

Dictionary of prior sampler functions’ input parameters.

cosmo

astropy.cosmology

Cosmology to use.

spin_zero = 'None'

bool

If True, spin prior is set to zero.

spin_precession = 'False'

directory = "'./interpolator_json'"

Directory path for storing interpolator JSON files.

Returns:

directorystr

Path to the interpolator storage directory.

default: ‘./interpolator_json’

sample_gw_parameters(size=1000, param=None)

Sample all gravitational wave parameters for compact binaries.

Generates a complete set of intrinsic and extrinsic parameters including masses, redshift, luminosity distance, sky position, orientation, and optionally spin parameters.

Parameters:

sizeint

Number of samples to draw.

default: 1000

paramdict or None

Dictionary of fixed parameter values.

Parameters in this dict will not be sampled.

default: None

Returns:

gw_parametersdict

Dictionary of sampled GW parameters. The included parameters and their units are as follows (for default settings):

Parameter	Units	Description
zs		redshift of the source
geocent_time	s	GPS time of coalescence
ra	rad	right ascension
dec	rad	declination
phase	rad	phase of GW at reference frequency
psi	rad	polarization angle
theta_jn	rad	inclination angle
a_1		spin_1 of the compact binary
a_2		spin_2 of the compact binary
luminosity_distance	Mpc	luminosity distance
mass_1_source	Msun	mass_1 of the compact binary (source frame)
mass_2_source	Msun	mass_2 of the compact binary (source frame)
mass_1	Msun	mass_1 of the compact binary (detector frame)
mass_2	Msun	mass_2 of the compact binary (detector frame)

Examples

>>> from ler.gw_source_population import CBCSourceParameterDistribution
>>> cbc = CBCSourceParameterDistribution()
>>> params = cbc.sample_gw_parameters(size=1000)
>>> print(list(params.keys()))

binary_masses_BBH_powerlaw_gaussian(size, get_attribute=False, **kwargs)

Sample source masses with PowerLaw+PEAK model for Population I/II BBH.

Implements the mass distribution model from LIGO-Virgo population analyses combining a power-law with a Gaussian peak component.

Parameters:

sizeint

Number of samples to draw.

get_attributebool

If True, return the sampler object instead of samples.

default: False

**kwargsdict

Model parameters:

• mminbh: Minimum BH mass (Msun), default: 4.98

• mmaxbh: Maximum BH mass (Msun), default: 112.5

• alpha: Power-law spectral index, default: 3.78

• mu_g: Gaussian peak mean (Msun), default: 32.27

• sigma_g: Gaussian peak width (Msun), default: 3.88

• lambda_peak: Fraction in Gaussian component, default: 0.03

• delta_m: Low-mass tapering range (Msun), default: 4.8

• beta: Mass ratio power-law index, default: 0.81

Returns:

mass_1_sourcenumpy.ndarray

Array of primary masses in source frame (Msun).

mass_2_sourcenumpy.ndarray

Array of secondary masses in source frame (Msun).

Examples

>>> from ler.gw_source_population import CBCSourceParameterDistribution
>>> cbc = CBCSourceParameterDistribution()
>>> m1_src, m2_src = cbc.binary_masses_BBH_powerlaw_gaussian(size=1000)

binary_masses_BBH_popIII_lognormal(size, get_attribute=False, **kwargs)

Sample source masses for Population III BBH from lognormal distribution.

Based on Eqn. 1 and 4 of Ng et al. 2022 for Population III black holes.

Parameters:

sizeint

Number of samples to draw.

get_attributebool

If True, return the sampler object instead of samples.

default: False

**kwargsdict

Model parameters:

• m_min: Minimum BH mass (Msun), default: 5.0

• m_max: Maximum BH mass (Msun), default: 150.0

• Mc: Central mass scale (Msun), default: 30.0

• sigma: Distribution width, default: 0.3

Returns:

mass_1_sourcenumpy.ndarray

Array of primary masses in source frame (Msun).

mass_2_sourcenumpy.ndarray

Array of secondary masses in source frame (Msun).

Examples

>>> from ler.gw_source_population import CBCSourceParameterDistribution
>>> cbc = CBCSourceParameterDistribution(event_type='BBH_popIII')
>>> m1_src, m2_src = cbc.binary_masses_BBH_popIII_lognormal(size=1000)

binary_masses_BBH_primordial_lognormal(size, get_attribute=False, **kwargs)

Sample source masses for primordial BBH from lognormal distribution.

Based on Eqn. 1 and 4 of Ng et al. 2022 for primordial black holes.

Parameters:

sizeint

Number of samples to draw.

get_attributebool

If True, return the sampler object instead of samples.

default: False

**kwargsdict

Model parameters:

• m_min: Minimum BH mass (Msun), default: 1.0

• m_max: Maximum BH mass (Msun), default: 100.0

• Mc: Central mass scale (Msun), default: 20.0

• sigma: Distribution width, default: 0.3

Returns:

mass_1_sourcenumpy.ndarray

Array of primary masses in source frame (Msun).

mass_2_sourcenumpy.ndarray

Array of secondary masses in source frame (Msun).

binary_masses_NSBH_broken_powerlaw(size, get_attribute=False, **kwargs)

Sample source masses for NSBH from broken power-law distribution.

Uses gwcosmo-style broken power-law for black hole mass and power-law for neutron star mass.

Parameters:

sizeint

Number of samples to draw.

get_attributebool

If True, return the sampler object instead of samples.

default: False

**kwargsdict

Model parameters:

• mminbh: Minimum BH mass (Msun), default: 26

• mmaxbh: Maximum BH mass (Msun), default: 125

• alpha_1: Primary power-law index, default: 6.75

• alpha_2: Secondary power-law index, default: 6.75

• b: Break point, default: 0.5

• delta_m: Tapering range (Msun), default: 5

• mminns: Minimum NS mass (Msun), default: 1.0

• mmaxns: Maximum NS mass (Msun), default: 3.0

• alphans: NS mass power-law index, default: 0.0

Returns:

mass_1_sourcenumpy.ndarray

Array of BH masses in source frame (Msun).

mass_2_sourcenumpy.ndarray

Array of NS masses in source frame (Msun).

Examples

>>> from ler.gw_source_population import CBCSourceParameterDistribution
>>> cbc = CBCSourceParameterDistribution(event_type='NSBH')
>>> m1_src, m2_src = cbc.binary_masses_NSBH_broken_powerlaw(size=1000)

binary_masses_uniform(size, get_attribute=False, **kwargs)

Sample source masses from uniform distribution.

Parameters:

sizeint

Number of samples to draw.

get_attributebool

If True, return the sampler object instead of samples.

default: False

**kwargsdict

Model parameters:

• m_min: Minimum mass (Msun), default: 1.0

• m_max: Maximum mass (Msun), default: 3.0

Returns:

mass_1_sourcenumpy.ndarray

Array of primary masses in source frame (Msun).

mass_2_sourcenumpy.ndarray

Array of secondary masses in source frame (Msun).

Examples

>>> from ler.gw_source_population import CBCSourceParameterDistribution
>>> cbc = CBCSourceParameterDistribution()
>>> m1_src, m2_src = cbc.binary_masses_uniform(size=1000)

binary_masses_BNS_bimodal(size, get_attribute=False, **kwargs)

Sample BNS masses from bimodal Gaussian distribution.

Based on Will M. Farr et al. 2020 Eqn. 6 for neutron star mass distribution combining two Gaussian peaks.

Parameters:

sizeint

Number of samples to draw.

get_attributebool

If True, return the sampler object instead of samples.

default: False

**kwargsdict

Model parameters:

• w: Weight of left peak, default: 0.643

• muL: Mean of left peak (Msun), default: 1.352

• sigmaL: Width of left peak (Msun), default: 0.08

• muR: Mean of right peak (Msun), default: 1.88

• sigmaR: Width of right peak (Msun), default: 0.3

• mmin: Minimum mass (Msun), default: 1.0

• mmax: Maximum mass (Msun), default: 2.3

Returns:

mass_1_sourcenumpy.ndarray

Array of primary masses in source frame (Msun).

mass_2_sourcenumpy.ndarray

Array of secondary masses in source frame (Msun).

Examples

>>> from ler.gw_source_population import CBCSourceParameterDistribution
>>> cbc = CBCSourceParameterDistribution(event_type='BNS')
>>> m1_src, m2_src = cbc.binary_masses_BNS_bimodal(size=1000)

constant_values_n_size(size=100, get_attribute=False, **kwargs)

Return array of constant values.

Parameters:

sizeint

Number of values to return.

default: 100

get_attributebool

If True, return the sampler object instead of samples.

default: False

**kwargsdict

Model parameters:

• value: Constant value to return, default: 0.0

Returns:

valuesnumpy.ndarray

Array of constant values.

sampler_uniform(size, get_attribute=False, **kwargs)

Sample values from uniform distribution.

Parameters:

sizeint

Number of samples to draw.

get_attributebool

If True, return the sampler object instead of samples.

default: False

**kwargsdict

Model parameters:

• xmin: Minimum value, default: 0.0

• xmax: Maximum value, default: 1.0

Returns:

valuesnumpy.ndarray

Array of uniformly distributed values in range [xmin, xmax].

sampler_cosine(size, get_attribute=False, **kwargs)

Sample from cosine distribution for declination.

Samples values in range [-pi/2, pi/2] following a cosine distribution, appropriate for isotropic sky position declination.

Parameters:

sizeint

Number of samples to draw.

get_attributebool

If True, return the sampler object instead of samples.

default: False

Returns:

valuesnumpy.ndarray

Array of values in range [-pi/2, pi/2] (rad).

sampler_sine(size, get_attribute=False, **kwargs)

Sample from sine distribution for inclination angles.

Samples values in range [0, pi] following a sine distribution, appropriate for isotropic orientation angles.

Parameters:

sizeint

Number of samples to draw.

get_attributebool

If True, return the sampler object instead of samples.

default: False

Returns:

valuesnumpy.ndarray

Array of values in range [0, pi] (rad).