ler.rates.ler

Module for calculating detection rates of gravitational wave events.

This module contains the main LeR class for calculating the rates of detectable gravitational wave events, both lensed and unlensed. The class inherits from LensGalaxyParameterDistribution for source and lens parameters sampling, and utilizes image property calculations.

The inheritance hierarchy is as follows:

• LensGalaxyParameterDistribution

  • OpticalDepth

  • ImageProperties

  • CBCSourceParameterDistribution

  • CBCSourceRedshiftDistribution

• Uses the gwsnr package for pdet calculation.

Usage:

Basic workflow for rate calculation:

>>> from ler.rates import LeR
>>> ler = LeR()
>>> unlensed_params = ler.unlensed_cbc_statistics()
>>> ler.unlensed_rate()
>>> lensed_params = ler.lensed_cbc_statistics()
>>> ler.lensed_rate()
>>> ler.rate_ratio()

Copyright (C) 2026 Phurailatpam Hemantakumar. Distributed under MIT License.

Module Contents

Classes

LeR	Class to sample lensed and unlensed GW events and calculate their detection rates.

class ler.rates.ler.LeR(npool=int(4), z_min=0.0, z_max=10.0, event_type='BBH', lens_type='epl_shear_galaxy', cosmology=None, pdet_finder=None, json_file_names=None, interpolator_directory='./interpolator_json', create_new_interpolator=False, ler_directory='./ler_data', verbose=True, **kwargs)

Bases: ler.lens_galaxy_population.LensGalaxyParameterDistribution

Class to sample lensed and unlensed GW events and calculate their detection rates.

This class provides functionality for sampling gravitational wave source parameters, detection probabilities, and computing detection rates for both lensed and unlensed 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 unlensed and lensed CBC 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. gw_priors and gw_priors_params will be set accordingly.

Options:

• ‘BBH’: Binary Black Hole

• ‘BNS’: Binary Neutron Star

• ‘NSBH’: Neutron Star-Black Hole

default: ‘BBH’

lens_typestr

Type of lens model to use. lens_functions, lens_functions_params, lens_priors and lens_priors_params will be set accordingly.

Options:

• ‘epl_shear_galaxy’: Exponential Power Law Shear Galaxy

• ‘sie_galaxy’: Singular Isothermal Ellipsoid Galaxy

• ‘sis_galaxy’: Singular Isothermal Sphere Galaxy

default: ‘epl_shear_galaxy’

cosmologyastropy.cosmology

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_finderfunction 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

Names of the JSON files to store the necessary parameters.

default: dict(

ler_params=”ler_params.json”, unlensed_param=”unlensed_param.json”, unlensed_param_detectable=”unlensed_param_detectable.json”, lensed_param=”lensed_param.json”, lensed_param_detectable=”lensed_param_detectable.json”

)

interpolator_directorystr

Directory to store the interpolators.

default: ‘./interpolator_json’

create_new_interpolatorbool or dict

Whether to create new interpolators. Look at create_new_interpolator() for details.

Options:

• True: Create all interpolators anew

• False: Load existing interpolators if available

• dict: Specify which interpolators to create new

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:

LensGalaxyParameterDistribution,

CBCSourceParameterDistribution,

ImageProperties, and

GWSNR (if snr_finder=’gwsnr’).

Examples

Basic usage:

>>> from ler import LeR
>>> ler = LeR()
>>> unlensed_params = ler.unlensed_cbc_statistics()
>>> ler.unlensed_rate()
>>> lensed_params = ler.lensed_cbc_statistics()
>>> ler.lensed_rate()
>>> ler.rate_ratio()

property npool

Number of parallel processing cores.

Returns:

npoolint

Number of logical cores to use for multiprocessing.

default: 4

property z_min

Minimum redshift of the source population.

Returns:

z_minfloat

Minimum source redshift for sampling.

default: 0.0

property z_max

Maximum redshift of the source population.

Returns:

z_maxfloat

Maximum source redshift for sampling.

default: 10.0

property event_type

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 lens_type

Type of lens galaxy model.

Returns:

lens_typestr

Type of lens model.

Options:

• ‘epl_shear_galaxy’: Elliptical Power Law with external shear

• ‘sie_galaxy’: Singular Isothermal Ellipsoid

• ‘sis_galaxy’: Singular Isothermal Sphere

default: ‘epl_shear_galaxy’

property cosmo

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

Dictionary of JSON file names for parameter storage.

Returns:

json_file_namesdict

Dictionary with keys:

• ‘ler_params’: LeR initialization parameters

• ‘unlensed_param’: Unlensed event parameters

• ‘unlensed_param_detectable’: Detectable unlensed events

• ‘lensed_param’: Lensed event parameters

• ‘lensed_param_detectable’: Detectable lensed events

property interpolator_directory

Directory path for interpolator JSON files.

Returns:

interpolator_directorystr

Path to directory containing interpolator data files.

default: ‘./interpolator_json’

property ler_directory

Directory path for LeR output files.

Returns:

ler_directorystr

Path to directory for storing output parameter files.

default: ‘./ler_data’

property create_new_interpolator

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: False.

property pdet_finder

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 ler_args

Dictionary of all LeR initialization arguments.

Returns:

ler_argsdict

Dictionary containing all parameters used to initialize LeR and

its parent classes, useful for reproducibility.

unlensed_cbc_statistics(size=100000, batch_size=50000, resume=True, save_batch=False, output_jsonfile=True)

Generate unlensed GW source parameters with detection probabilities.

This function calls the unlensed_sampling_routine function to generate the parameters in batches. The generated parameters are stored in a JSON file; and if save_batch=True, it keeps updating the file in batches.

Parameters:

sizeint

Number of samples to generate.

default: 100000

batch_sizeint

Batch size for sampling.

default: 50000

resumebool

If True, the function will resume from the last batch.

default: True

save_batchbool

If True, saves parameters in batches during sampling.

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

default: False

output_jsonfilestr

JSON file name for storing the parameters.

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

Returns:

unlensed_paramdict

Sampled unlensed GW source parameters.

Examples

>>> from ler import LeR
>>> ler = LeR()
>>> unlensed_param = ler.unlensed_cbc_statistics()

unlensed_sampling_routine(size, output_jsonfile, resume=True, save_batch=True)

Generate unlensed GW source parameters for a single batch.

This is the core sampling routine called by unlensed_cbc_statistics. It samples GW source parameters and calculates detection probabilities.

Parameters:

sizeint

Number of samples to generate.

output_jsonfilestr

JSON file name for storing the parameters.

resumebool

If True, appends new samples to existing JSON file.

default: True

save_batchbool

If True, saves parameters in batches during sampling.

default: True

Returns:

unlensed_paramdict

Dictionary of unlensed GW source parameters.

unlensed_rate(unlensed_param=None, pdet_threshold=0.5, pdet_type='boolean', output_jsonfile=True)

Function to calculate the unlensed rate.

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

Parameters:

unlensed_paramdict or str

Dictionary of GW source parameters or JSON file name.

default: None (uses self.json_file_names[“unlensed_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

JSON file name for storing the parameters of the detectable events.

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

Returns:

total_ratefloat

Total unlensed rate (yr^-1).

unlensed_paramdict

Detectable unlensed GW source parameters.

Examples

>>> from ler import LeR
>>> ler = LeR()
>>> ler.unlensed_cbc_statistics()
>>> total_rate, unlensed_param_detectable = ler.unlensed_rate()

rate_function(detectable_size, total_size, param_type='unlensed', verbose=True)

Calculate the detection rate for unlensed or lensed events.

This is a general helper function that computes the rate based on Monte Carlo integration using the ratio of detectable to total events.

Parameters:

detectable_sizeint or float

Number of detectable events (or sum of pdet values).

total_sizeint

Total number of simulated events.

param_typestr

Type of parameters.

Options:

• ‘unlensed’: Use unlensed normalization

• ‘lensed’: Use lensed normalization

default: ‘unlensed’

verbosebool

If True, print rate information.

default: True

Returns:

ratefloat

Event rate (yr^-1).

Examples

>>> from ler import LeR
>>> ler = LeR()
>>> rate = ler.rate_function(detectable_size=100, total_size=1000)

lensed_cbc_statistics(size=100000, batch_size=50000, save_batch=False, resume=True, output_jsonfile=True)

Generate lensed GW source parameters.

This function calls the lensed_sampling_routine function to generate the parameters in batches. The generated parameters are stored in a JSON file; and if save_batch=True, it keeps updating the file in batches.

Parameters:

sizeint

Number of samples to generate.

default: 100000

batch_sizeint

Batch size for sampling.

default: 50000

save_batchbool

If True, saves parameters in batches during sampling.

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

default: True

resumebool

If True, the function will resume from the last batch.

default: True

output_jsonfilestr

JSON file name for storing the parameters.

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

Returns:

lensed_paramdict

Sampled lensed GW source parameters.

Examples

>>> from ler import LeR
>>> ler = LeR()
>>> lensed_param = ler.lensed_cbc_statistics()

lensed_sampling_routine(size, output_jsonfile, save_batch=True, resume=True)

Generate lensed GW source parameters for a single batch.

This is the core sampling routine called by lensed_cbc_statistics. It samples lens parameters, calculates image properties, and computes detection probabilities for the images of lensed events.

Parameters:

sizeint

Number of samples to generate.

output_jsonfilestr

JSON file name for storing the parameters.

save_batchbool

If True, saves parameters in batches during sampling.

default: True

resumebool

If True, appends new samples to existing JSON file.

default: True

Returns:

lensed_paramdict

Dictionary of lensed GW source parameters.

lensed_rate(lensed_param=None, pdet_threshold=[0.5, 0.5], num_img=[1, 1], output_jsonfile=True, nan_to_num=True, pdet_type='boolean')

Function to calculate the lensed rate.

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

Parameters:

lensed_paramdict or str

Dictionary of lensed GW source parameters or JSON file name.

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

pdet_thresholdfloat or list

Threshold for detection probability.

default: [0.5, 0.5]

num_imgint or list

Number of images corresponding to the pdet_threshold.

Together with pdet_threshold = [0.5, 0.5], it means that two images with pdet > 0.5.

Same condition can also be represented by pdet_threshold = 0.5 and num_img = 2.

default: [1, 1]

output_jsonfilestr

JSON file name for storing the parameters of the detectable events.

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

nan_to_numbool

If True, NaN values will be converted to 0.

default: True

pdet_typestr

Detectability condition type.

Options:

• ‘boolean’: Binary detection based on pdet_threshold

• ‘probability_distribution’: Uses pdet values directly

default: ‘boolean’

Returns:

total_ratefloat

Total lensed rate (yr^-1).

lensed_paramdict

Detectable lensed GW source parameters.

Examples

>>> from ler import LeR
>>> ler = LeR()
>>> ler.lensed_cbc_statistics()
>>> total_rate, lensed_param_detectable = ler.lensed_rate()

rate_comparison_with_rate_calculation(unlensed_param=None, pdet_threshold_unlensed=0.5, output_jsonfile_unlensed=None, lensed_param=None, pdet_threshold_lensed=[0.5, 0.5], num_img_lensed=[1, 1], output_jsonfile_lensed=None, nan_to_num=True, pdet_type='boolean')

Calculate and compare unlensed and lensed detection rates.

This function calculates both unlensed and lensed rates and computes their ratio. It stores the parameters of the detectable events in JSON files. Using this function eliminates the need to call unlensed_rate and lensed_rate separately.

Parameters:

unlensed_paramdict or str

Dictionary of GW source parameters or JSON file name.

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

pdet_threshold_unlensedfloat

Detection probability threshold for unlensed events.

default: 0.5

output_jsonfile_unlensedstr

JSON file name for storing detectable unlensed parameters.

default: None

lensed_paramdict or str

Dictionary of lensed GW source parameters or JSON file name.

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

pdet_threshold_lensedfloat or list

Detection probability threshold for lensed events.

default: [0.5, 0.5]

num_img_lensedlist

Number of images for lensed events.

default: [1, 1]

output_jsonfile_lensedstr

JSON file name for storing detectable lensed parameters.

default: None

nan_to_numbool

If True, NaN values will be converted to 0.

default: True

pdet_typestr

Detectability condition type.

Options:

• ‘boolean’: Binary detection based on pdet_threshold

• ‘probability_distribution’: Uses pdet values directly

default: ‘boolean’

Returns:

rate_ratiofloat

Ratio of unlensed rate to lensed rate.

unlensed_param_detectabledict

Dictionary of detectable unlensed GW source parameters.

lensed_param_detectabledict

Dictionary of detectable lensed GW source parameters.

Examples

>>> from ler import LeR
>>> ler = LeR()
>>> ler.unlensed_cbc_statistics()
>>> ler.lensed_cbc_statistics()
>>> rate_ratio, unlensed_param, lensed_param = ler.rate_comparison_with_rate_calculation()

rate_ratio()

Calculate and display the unlensed to lensed merger rate ratio.

This function retrieves the unlensed_rate and lensed_rate from the JSON file specified in self.json_file_names[“ler_params”] and computes their ratio.

Returns:

rate_ratiofloat

Ratio of unlensed rate to lensed rate.

Examples

>>> from ler import LeR
>>> ler = LeR()
>>> ler.unlensed_cbc_statistics()
>>> ler.lensed_cbc_statistics()
>>> ler.unlensed_rate()
>>> ler.lensed_rate()
>>> ler.rate_ratio()

selecting_n_unlensed_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='n_unlensed_param_detectable.json', meta_data_file='meta_unlensed.json', pdet_type='boolean', trim_to_size=False)

Generate a target number of detectable unlensed events by sampling in batches, with the option to stop once the cumulative rate has stabilized.

This function samples unlensed parameters and saves only the detectable events in a JSON file. It also records metadata including the total number of events and the cumulative rate.

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

Detection probability threshold.

default: 0.5

resumebool

If True, resumes from last saved batch.

default: True

output_jsonfilestr

JSON file name for storing detectable parameters.

default: ‘n_unlensed_param_detectable.json’

meta_data_filestr

JSON file name for storing metadata.

default: ‘meta_unlensed.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, trims final result to exactly size events.

default: False

Returns:

param_finaldict

Detectable unlensed GW source parameters.

Examples

>>> from ler import LeR
>>> ler = LeR()
>>> unlensed_param = ler.selecting_n_unlensed_detectable_events(size=100)

selecting_n_lensed_detectable_events(size=100, stopping_criteria=dict(relative_diff_percentage=2, number_of_last_batches_to_check=4), batch_size=50000, pdet_threshold=[0.5, 0.5], num_img=[1, 1], resume=True, pdet_type='boolean', output_jsonfile='n_lensed_params_detectable.json', meta_data_file='meta_lensed.json', trim_to_size=False, nan_to_num=True)

Generate a target number of detectable lensed events by sampling in batches, with the option to stop once the cumulative rate has stabilized.

This function samples lensed parameters and saves only the detectable events in a JSON file. It also records metadata including the total number of events and the cumulative rate.

Parameters:

sizeint

Target number of detectable samples to collect.

default: 100

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=2, number_of_last_batches_to_check=4)

batch_sizeint

Batch size for sampling.

default: 50000

pdet_thresholdfloat or list

Detection probability threshold.

default: [0.5, 0.5]

num_imglist

Number of images corresponding to each pdet_threshold.

default: [1, 1]

resumebool

If True, resumes from last saved batch.

default: True

pdet_typestr

Detectability condition type.

Options:

• ‘boolean’: Binary detection based on pdet_threshold

• ‘probability_distribution’: Uses pdet values directly

default: ‘boolean’

output_jsonfilestr

JSON file name for storing detectable parameters.

default: ‘n_lensed_params_detectable.json’

meta_data_filestr

JSON file name for storing metadata.

default: ‘meta_lensed.json’

trim_to_sizebool

If True, trims final result to exactly size events.

default: False

nan_to_numbool

If True, NaN values will be converted to 0.

default: False

Returns:

param_finaldict

Dictionary of lensed GW source parameters of detectable events.

Examples

>>> from ler import LeR
>>> ler = LeR()
>>> lensed_param = ler.selecting_n_lensed_detectable_events(size=100)