`ler.rates.gwrates`

Module for calculating detection rates of gravitational wave events.

This module contains the main GWRATES class for calculating the rates of detectable gravitational wave events. The class inherits from CBCSourceParameterDistribution for source parameters sampling and utilizes the gwsnr package for detection probability calculation.

Inheritance hierarchy:

CBCSourceParameterDistribution
- CBCSourceRedshiftDistribution
Uses the gwsnr package for pdet calculation.

Usage:

Basic workflow for rate calculation:

>>> from ler.rates import GWRATES
>>> gwrates = GWRATES()
>>> gw_params = gwrates.gw_cbc_statistics()
>>> gwrates.gw_rate()

Module Contents

Classes

GWRATES

Class to sample GW events and calculate their detection rates.

class ler.rates.gwrates.GWRATES(npool=int(4), z_min=0.0, z_max=10.0, event_type='BBH', cosmology=None, pdet_finder=None, json_file_names=None, interpolator_directory='./interpolator_json', create_new_interpolator=False, ler_directory='./ler_data', verbose=True, **kwargs)[source]

Bases: ler.gw_source_population.CBCSourceParameterDistribution

Class to sample GW events and calculate their detection rates.

This class provides functionality for sampling gravitational wave source parameters, detection probabilities, and computing detection rates for compact binary coalescence events. Parameters of simulated events are stored in JSON files (not as class attributes) to conserve RAM memory.

Key Features:

Sampling of GW event parameters
Detection probability calculation using gwsnr package or custom functions
Rate calculation for detectable events
Batch processing for memory efficiency
JSON-based parameter storage for reproducibility

Parameters:

npoolint

Number of cores to use for parallel processing.

default: 4

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 event to generate.

Options:

‘BBH’: Binary Black Hole
‘BNS’: Binary Neutron Star
‘NSBH’: Neutron Star-Black Hole

default: ‘BBH’

cosmologyastropy.cosmology or None

Cosmology to use for the calculation.

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

pdet_findercallable or None

Custom detection probability finder function.

If None, uses gwsnr’s pdet calculator.

The function should follow the signature:

def pdet_finder(gw_param_dict): return pdet_net_dict

where pdet_net_dict.keys = [‘pdet_net’].

default: None

json_file_namesdict or None

Names of the JSON files to store the necessary parameters.

default: dict(gwrates_params=”gwrates_params.json”, gw_param=”gw_param.json”, gw_param_detectable=”gw_param_detectable.json”)

interpolator_directorystr

Directory to store the interpolators.

default: ‘./interpolator_json’

create_new_interpolatorbool or dict

Whether to create new interpolators.

default: False

ler_directorystr

Directory to store the output parameters.

default: ‘./ler_data’

verbosebool

If True, print all chosen parameters during initialization.

default: True

**kwargsdict

Additional keyword arguments passed to parent classes:

CBCSourceParameterDistribution and

GWSNR (if pdet_finder is not provided).

Notes

GWRATES class inherits from CBCSourceParameterDistribution.

Refer to that class for additional inherited attributes and methods.
Parameters are stored in JSON files for memory efficiency and reproducibility.
For stable rate estimates, use size >= 1e6 samples.

Examples

Basic usage:

>>> from ler.rates import GWRATES
>>> gwrates = GWRATES()
>>> gw_params = gwrates.gw_cbc_statistics()
>>> gwrates.gw_rate()

Instance Methods

GWRATES class has the following methods:

Method	Description
`gw_cbc_statistics()`	Generate GW source parameters
`gw_rate()`	Calculate the GW detection rate
`selecting_n_gw_detectable_events()`	Select n GW detectable events

Instance Attributes

GWRATES class has the following attributes:

Attribute	Type	Description
`npool()`	`int`	Number of parallel processing cores
`z_min()`	`float`	Minimum source redshift
`z_max()`	`float`	Maximum source redshift
`event_type()`	`str`	Type of CBC event
`cosmo()`	`astropy.cosmology` \|	Cosmology for calculations
`json_file_names()`	`dict`	JSON file names for parameter storage
`interpolator_directory()`	`str`	Directory for interpolator files
`ler_directory()`	`str`	Directory for output parameter files
`list_of_detectors()`	`list`	List of detector names
`pdet_finder()`	`callable`	Detection probability finder function
`gwrates_args()`	`dict`	All GWRATES initialization arguments

property npool[source]

Number of parallel processing cores.

Returns:

npoolint

Number of logical cores to use for multiprocessing.

default: 4

property z_min[source]

Minimum redshift of the source population.

Returns:

z_minfloat

Minimum source redshift for sampling.

default: 0.0

property z_max[source]

Maximum redshift of the source population.

Returns:

z_maxfloat

Maximum source redshift for sampling.

default: 10.0

property event_type[source]

Type of compact binary coalescence event.

Returns:

event_typestr

Type of CBC event.

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 luminosity distance and comoving volume calculations.

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

property json_file_names[source]

Dictionary of JSON file names for parameter storage.

Returns:

json_file_namesdict

Dictionary with keys:

‘gwrates_params’: GWRATES initialization parameters
‘gw_param’: GW event parameters
‘gw_param_detectable’: Detectable GW events

property interpolator_directory[source]

Directory path for interpolator JSON files.

Returns:

interpolator_directorystr

Path to directory containing interpolator data files.

default: ‘./interpolator_json’

property ler_directory[source]

Directory path for LeR output files.

Returns:

ler_directorystr

Path to directory for storing output parameter files.

default: ‘./ler_data’

property create_new_interpolator[source]

Configuration dictionary for interpolator creation settings.

Returns:

create_new_interpolatordict

Dictionary specifying which interpolators to create.

Each key is an interpolator name, and values are dicts with:

‘create_new’: bool - Whether to create new interpolator
‘resolution’: int or list - Grid resolution for interpolation

Special key ‘gwsnr’ is a bool for GWSNR interpolator creation. Default: dict(

merger_rate_density = {‘create_new’: False, ‘resolution’: 500}, redshift_distribution = {‘create_new’: False, ‘resolution’: 500}, luminosity_distance = {‘create_new’: False, ‘resolution’: 500}, differential_comoving_volume = {‘create_new’: False, ‘resolution’: 500}, source_frame_masses = {‘create_new’: False, ‘resolution’: 500}, geocent_time = {‘create_new’: False, ‘resolution’: 500}, ra = {‘create_new’: False, ‘resolution’: 500}, dec = {‘create_new’: False, ‘resolution’: 500}, phase = {‘create_new’: False, ‘resolution’: 500}, psi = {‘create_new’: False, ‘resolution’: 500}, theta_jn = {‘create_new’: False, ‘resolution’: 500}, a_1 = {‘create_new’: False, ‘resolution’: 500}, a_2 = {‘create_new’: False, ‘resolution’: 500}, tilt_1 = {‘create_new’: False, ‘resolution’: 500}, tilt_2 = {‘create_new’: False, ‘resolution’: 500}, phi_12 = {‘create_new’: False, ‘resolution’: 500}, phi_jl = {‘create_new’: False, ‘resolution’: 500},

)

property list_of_detectors[source]

List of gravitational wave detector names.

Returns:

list_of_detectorslist

List of detector identifiers used for pdet calculations.

Typically set from gwsnr.detector_list during initialization.

property pdet_finder[source]

Detection probability finder function.

Returns:

pdet_findercallable

Function that calculates detection probability for GW events.

The function signature should be:

pdet_finder(gw_param_dict) -> dict with key ‘pdet_net’.

property gwrates_args[source]

Dictionary of all GWRATES initialization arguments.

Returns:

gwrates_argsdict

Dictionary containing all parameters used to initialize GWRATES and

its parent classes, useful for reproducibility.

gw_cbc_statistics(size=100000, batch_size=50000, resume=True, save_batch=False, output_jsonfile=None)[source]

Generate GW source parameters with detection probabilities.

This function calls the _gw_sampling_routine function to generate the parameters in batches. The generated parameters are stored in a JSON file; if save_batch=True, it updates the file after each batch.

Parameters:

sizeint

Number of samples to generate.

default: 100000

batch_sizeint

Batch size for sampling.

default: 50000

resumebool

If True, resume from the last batch.

default: True

save_batchbool

If True, save parameters after each batch.

If False, save all parameters at the end (faster).

default: False

output_jsonfilestr or None

JSON file name for storing the parameters.

default: ‘gw_param.json’ (stored in ler_directory)

Returns:

gw_paramdict: dictionary of GW source parameters. The included parameters and their units are as follows (for default settings):

Examples

>>> from ler.rates import GWRATES
>>> gwrates = GWRATES()
>>> param = gwrates.gw_cbc_statistics()

gw_rate(gw_param=None, pdet_threshold=0.5, pdet_type='boolean', output_jsonfile=None)[source]

Calculate the GW detection rate.

This function calculates the detection rate and stores the parameters of detectable events in a JSON file.

Parameters:

gw_paramdict or str or None

Dictionary of GW source parameters or JSON file name.

default: None (uses self.json_file_names[“gw_param”])

pdet_thresholdfloat

Threshold for detection probability.

default: 0.5

pdet_typestr

Detectability condition type.

Options:

‘boolean’: Binary detection based on pdet_threshold
‘probability_distribution’: Uses pdet values directly

default: ‘boolean’

output_jsonfilestr or None

JSON file name for storing detectable event parameters.

default: ‘gw_param_detectable.json’

Returns:

total_ratefloat: Total GW detection rate (yr^-1).
gw_paramdict: dictionary of GW source parameters of the detectable events. The included parameters and their units are as follows (for default settings):

Examples

>>> from ler.rates import GWRATES
>>> gwrates = GWRATES()
>>> gwrates.gw_cbc_statistics()
>>> total_rate, gw_param = gwrates.gw_rate()

rate_function(detectable_size, total_size, verbose=True)[source]

Helper function to calculate the detection rate via Monte Carlo integration.

Parameters:

detectable_sizeint or float

Number of detectable events.

total_sizeint

Total number of simulated events.

verbosebool

If True, print rate information.

default: True

Returns:

ratefloat: Detection rate (yr^-1).

selecting_n_gw_detectable_events(size=100, batch_size=50000, stopping_criteria=dict(relative_diff_percentage=0.5, number_of_last_batches_to_check=4), pdet_threshold=0.5, resume=True, output_jsonfile='gw_params_n_detectable.json', meta_data_file='meta_gw.json', pdet_type='boolean', trim_to_size=False)[source]

Generate a target number of detectable GW events by iterative batch sampling.

This function samples GW parameters in batches and saves only the detectable events to a JSON file. It optionally stops when the cumulative rate has stabilized based on the stopping criteria.

Parameters:

sizeint

Target number of detectable samples to collect.

default: 100

batch_sizeint

Batch size for sampling.

default: 50000

stopping_criteriadict or None

Criteria for stopping sample collection (but will not stop until n>size).

Keys:

‘relative_diff_percentage’: Maximum relative difference in rate (float)
‘number_of_last_batches_to_check’: Number of batches for comparison (int)

If None, stops when detectable events exceed size.

default: dict(relative_diff_percentage=0.5, number_of_last_batches_to_check=4)

pdet_thresholdfloat

Threshold for detection probability.

default: 0.5

resumebool

If True, resume from the last batch.

default: True

output_jsonfilestr

JSON file name for storing detectable event parameters.

default: ‘gw_params_n_detectable.json’

meta_data_filestr

JSON file name for storing metadata.

default: ‘meta_gw.json’

pdet_typestr

Detectability condition type.

Options:

‘boolean’: Binary detection based on pdet_threshold
‘probability_distribution’: Uses pdet values directly

default: ‘boolean’

trim_to_sizebool

If True, trim final result to exactly the specified size.

default: False

Returns:

param_finaldict

dictionary of GW source parameters of the detectable events. 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 of the primary compact binary
a_2		spin of the secondary compact binary
luminosity_distance	Mpc	luminosity distance
mass_1_source	Msun	mass of the primary compact binary (source frame)
mass_2_source	Msun	mass of the secondary 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)
pdet_L1		pdet of L1
pdet_H1		pdet of H1
pdet_V1		pdet of V1
pdet_net		pdet of the network

Examples

>>> from ler.rates import GWRATES
>>> gwrates = GWRATES()
>>> gw_param = gwrates.selecting_n_gw_detectable_events(size=100)

ler.rates.gwrates

Module Contents

Classes

Instance Methods

Instance Attributes

`ler.rates.gwrates`