`ler.gw_source_population.cbc_source_redshift_distribution`

Module for compact binary coalescence (CBC) source redshift distribution.

This module provides the CBCSourceRedshiftDistribution class for generating redshift distributions of compact binary sources (BBH, BNS, NSBH) based on various merger rate density models. It supports multiple astrophysical merger rate density prescriptions including PopI/II, PopIII, and primordial black hole models.

Usage:

Basic workflow example:

>>> from ler.gw_source_population import CBCSourceRedshiftDistribution
>>> cbc = CBCSourceRedshiftDistribution(z_min=0.001, z_max=10)
>>> zs_samples = cbc.merger_rate_density_based_source_redshift(size=1000)

Module Contents

Classes

CBCSourceRedshiftDistribution

Class for generating compact binary coalescence source redshift distributions.

class ler.gw_source_population.cbc_source_redshift_distribution.CBCSourceRedshiftDistribution(npool=4, z_min=0.001, z_max=10.0, event_type='BBH', merger_rate_density=None, merger_rate_density_param=None, cosmology=None, directory='./interpolator_json', create_new_interpolator=False)[source]

Bases: object

Class for generating compact binary coalescence source redshift distributions.

This class generates source redshift distributions for compact binary coalescence events (BBH, BNS, NSBH) using various astrophysical merger rate density models. It provides interpolated functions for efficient sampling of source redshifts weighted by the merger rate density in the detector frame.

Key Features:

Multiple merger rate density models (PopI/II, PopIII, Primordial)
Configurable cosmology for distance calculations
Cached interpolators for computational efficiency
Support for user-defined merger rate density functions

Parameters:

npoolint

Number of processors to use for multiprocessing.

default: 4

z_minfloat

Minimum redshift of the source population.

default: 0.001

z_maxfloat

Maximum redshift of the source population.

default: 10.0

event_typestr

Type of compact binary event.

Options:

‘BBH’: Binary black hole
‘BNS’: Binary neutron star
‘NSBH’: Neutron star-black hole

default: ‘BBH’

merger_rate_densitystr or callable or None

Merger rate density model to use.

Options:

‘merger_rate_density_bbh_oguri2018’: PopI/II BBH (Oguri 2018)
‘merger_rate_density_bbh_popIII_ken2022’: PopIII BBH (Ng 2022)
‘merger_rate_density_bbh_primordial_ken2022’: Primordial BBH (Ng 2022)
callable: User-defined function f(z) -> rate density

default: None (uses ‘merger_rate_density_bbh_oguri2018’)

merger_rate_density_paramdict or None

Parameters for the merger rate density function.

default: None (uses dict(R0=19 * 1e-9, b2=1.6, b3=2.1, b4=30))

cosmologyastropy.cosmology or None

Cosmology for distance calculations.

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

directorystr

Directory to store interpolator JSON files.

default: ‘./interpolator_json’

create_new_interpolatordict or bool

Control interpolator creation.

If bool: Apply to all interpolators.

If dict: Per-quantity settings with keys ‘create_new’ and ‘resolution’.

default: False

Examples

Basic usage:

>>> from ler.gw_source_population import CBCSourceRedshiftDistribution
>>> cbc = CBCSourceRedshiftDistribution(z_min=0.001, z_max=10)
>>> zs_samples = cbc.merger_rate_density_based_source_redshift(size=1000)
>>> rate = cbc.merger_rate_density(zs=0.5)

property npool[source]

Number of processors for multiprocessing.

Returns:

npoolint

Number of parallel processes to use.

default: 4

property z_min[source]

Minimum source redshift.

Returns:

z_minfloat

Lower bound of the redshift range.

default: 0.001

property z_max[source]

Maximum source redshift.

Returns:

z_maxfloat

Upper bound of the redshift range.

default: 10.0

property directory[source]

Directory path for storing interpolator JSON files.

Returns:

directorystr

Path to the interpolator storage directory.

default: ‘./interpolator_json’

property event_type[source]

Type of compact binary coalescence event.

Returns:

event_typestr

CBC event type.

Options:

‘BBH’: Binary black hole
‘BNS’: Binary neutron star
‘NSBH’: Neutron star-black hole

default: ‘BBH’

property cosmo[source]

Astropy cosmology object for distance calculations.

Returns:

cosmoastropy.cosmology

Cosmology used for redshift-distance conversions.

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

property luminosity_distance[source]

Class object (of FunctionConditioning) for the luminosity distance, with function as callback, which converts redshift to luminosity distance (in Mpc) for the selected cosmology.

The class object contains the following attribute methods:

function: returns the luminosity distance distribution function.
function_inverse: returns the inverse luminosity distance distribution function, which converts luminosity distance (in Mpc) to redshift.

Returns:

luminosity_distancenumpy.ndarray: Array of luminosity distances (in Mpc).

property differential_comoving_volume[source]

Class object (of FunctionConditioning) for the differential comoving volume function, with function as callback, which returns dVc/dz (in Mpc^3 sr^-1) for the selected cosmology.

The class object contains the following attribute methods:

function: returns the differential comoving volume distribution function.

Returns:

differential_comoving_volumenumpy.ndarray: Array of differential comoving volumes (in Mpc^3 sr^-1).

property merger_rate_density[source]

Source-frame merger rate density object.

Returns a FunctionConditioning object with methods:

function(zs): Get merger rate density in source frame
rvs(size): Sample source redshifts in source frame
pdf(zs): Get probability density

Returns:

merger_rate_densityFunctionConditioning: Callable that accepts redshift(s) and returns merger rate density in source frame (units: Mpc^-3 yr^-1).

property merger_rate_density_based_source_redshift[source]

FunctionConditioning object for source-redshift sampling.

Samples source redshifts from the normalized detector-frame density

\[p(z) = \frac{1}{\mathcal{N}} \frac{R(z)}{1+z}\frac{dV_c}{dz}, \qquad \mathcal{N} = \int_{z_{\min}}^{z_{\max}} \frac{R(z)}{1+z}\frac{dV_c}{dz}\,dz.\]

The class object contains the following methods:

rvs(size): returns random samples from the source redshift distribution.
pdf(z): returns the source redshift probability density function.
function(z): returns the source redshift distribution function.

Returns:

merger_rate_density_based_source_redshiftFunctionConditioning: FunctionConditioning object with redshift distribution methods

property normalization_pdf_z[source]

Normalization constant for the redshift probability distribution.

Returns:

normalization_pdf_zfloat: Integral of the unnormalized p(z) over [z_min, z_max].

property create_new_interpolator[source]

Dictionary controlling interpolator creation settings.

Returns:

create_new_interpolatordict: Dictionary that controls the creation of new interpolators. Default: {‘merger_rate_density’: {‘create_new’: False, ‘resolution’: 100}, ‘luminosity_distance’: {‘create_new’: False, ‘resolution’: 100}, ‘differential_comoving_volume’: {‘create_new’: False, ‘resolution’: 100}}

property merger_rate_density_param[source]

Parameters for the merger rate density function.

Returns:

merger_rate_density_paramdict: Dictionary of parameters for the selected merger rate density model.

property available_merger_rate_density_model[source]

Dictionary of available merger rate density models and default parameters.

Returns:

available_merger_rate_density_modeldict

Dictionary with model names as keys and parameter dicts as values.

Available models:

‘merger_rate_density_bbh_oguri2018’
‘merger_rate_density_madau_dickinson2014’
‘merger_rate_density_madau_dickinson_belczynski_ng’
‘sfr_with_time_delay’
‘merger_rate_density_bbh_popIII_ken2022’
‘merger_rate_density_bbh_primordial_ken2022’

merger_rate_density_detector_frame[source]

merger_rate_density_bbh_oguri2018(zs, get_attribute=False, **kwargs)[source]

Compute PopI/II BBH merger rate density (Oguri et al. 2018).

Returns the source-frame merger rate density following the Oguri et al. (2018) prescription for PopI/II stellar populations.

Parameters:

zs`numpy.ndarray: Source redshift(s) at which to evaluate.
get_attributebool: If True, return the FunctionConditioning object. default: False
**kwargsdict: Override default fitting parameters: R0=19e-9, b2=1.6, b3=2.1, b4=30.

Returns:

rate_density`numpy.ndarray or FunctionConditioning: Merger rate density in source frame (units: Mpc^-3 yr^-1).

Examples

>>> from ler.gw_source_population import CBCSourceRedshiftDistribution
>>> cbc = CBCSourceRedshiftDistribution(merger_rate_density="merger_rate_density_bbh_oguri2018")
>>> rate = cbc.merger_rate_density(zs=0.5)

sfr_with_time_delay(zs, get_attribute=False, **kwargs)[source]

Compute merger rate density with time delay convolution.

Convolves the star formation rate with a time delay distribution to compute the merger rate density. Uses multiprocessing for numerical integration (Borhanian & Sathyaprakash 2024).

Parameters:

zs`numpy.ndarray: Source redshift(s) at which to evaluate.
get_attributebool: If True, return the FunctionConditioning object. default: False
**kwargsdict: Override default SFR and time delay parameters.

Returns:

rate_density`numpy.ndarray or FunctionConditioning: Merger rate density (units: Mpc^-3 yr^-1).

merger_rate_density_madau_dickinson2014(zs, get_attribute=False, **kwargs)[source]

Compute merger rate density following Madau & Dickinson (2014).

Returns the binary merger rate density using the Madau-Dickinson functional form from Equation 15 of Madau & Dickinson (2014).

Parameters:

zs`numpy.ndarray: Source redshift(s) at which to evaluate.
get_attributebool: If True, return the FunctionConditioning object. default: False
**kwargsdict: Override default fitting parameters: R0=89 * 1e-9, a=0.015, b=2.7, c=2.9, d=5.6.

Returns:

rate_density`numpy.ndarray or FunctionConditioning: Binary merger rate density (units: Mpc^-3 yr^-1).

Examples

>>> from ler.gw_source_population import CBCSourceRedshiftDistribution
>>> cbc = CBCSourceRedshiftDistribution(merger_rate_density="merger_rate_density_madau_dickinson2014")
>>> sfr = cbc.merger_rate_density(zs=2.0)

merger_rate_density_madau_dickinson_belczynski_ng(zs, get_attribute=False, **kwargs)[source]

Compute BBH merger rate density following Ng et al. (2021).

This model uses a Madau-Dickinson-like functional form to fit the merger rate density of field BHs, accounting for time delays and metallicity effects.

density(zs) ∝ (1 + zs) ** alpha_F / (1 + ((1 + zs) / c_F) ** beta_F)

Parameters:

zs`numpy.ndarray: Source redshift(s) at which to evaluate.
get_attributebool: If True, return the FunctionConditioning object. default: False
**kwargsdict: Override default fitting parameters: R0, alpha_F, beta_F, c_F.

Returns:

rate_density`numpy.ndarray or FunctionConditioning: BBH merger rate density (units: Mpc^-3 yr^-1).

Examples

>>> from ler.gw_source_population import CBCSourceRedshiftDistribution
>>> cbc = CBCSourceRedshiftDistribution(merger_rate_density="merger_rate_density_madau_dickinson_belczynski_ng")
>>> rate = cbc.merger_rate_density(zs=2.0)

merger_rate_density_bbh_popIII_ken2022(zs, get_attribute=False, **kwargs)[source]

Compute PopIII BBH merger rate density (Ng et al. 2022).

Returns the merger rate density for Population III binary black holes following the Ng et al. (2022) prescription.

Parameters:

zs`numpy.ndarray: Source redshift(s) at which to evaluate.
get_attributebool: If True, return the FunctionConditioning object. default: False
**kwargsdict: Override default fitting parameters: R0=19.2e-9, aIII=0.66, bIII=0.3, zIII=11.6.

Returns:

rate_density`numpy.ndarray or FunctionConditioning: Merger rate density (units: Mpc^-3 yr^-1).

Examples

>>> from ler.gw_source_population import CBCSourceRedshiftDistribution
>>> cbc = CBCSourceRedshiftDistribution(
...     z_min=5, z_max=40,
...     merger_rate_density="merger_rate_density_bbh_popIII_ken2022"
... )
>>> rate = cbc.merger_rate_density(zs=10)

merger_rate_density_bbh_primordial_ken2022(zs, get_attribute=False, **kwargs)[source]

Compute primordial BBH merger rate density (Ng et al. 2022).

Returns the merger rate density for primordial binary black holes following the Ng et al. (2022) prescription.

Parameters:

zs`numpy.ndarray: Source redshift(s) at which to evaluate.
get_attributebool: If True, return the FunctionConditioning object. default: False
**kwargsdict: Override default fitting parameters: R0=0.044e-9, t0=13.786885302009708.

Returns:

rate_density`numpy.ndarray or FunctionConditioning: Merger rate density (units: Mpc^-3 yr^-1).

Examples

>>> from ler.gw_source_population import CBCSourceRedshiftDistribution
>>> cbc = CBCSourceRedshiftDistribution(
...     z_min=5, z_max=40,
...     merger_rate_density="merger_rate_density_bbh_primordial_ken2022"
... )
>>> rate = cbc.merger_rate_density(zs=10)

ler.gw_source_population.cbc_source_redshift_distribution

Module Contents

Classes

`ler.gw_source_population.cbc_source_redshift_distribution`