`ler.rates`

Submodules

Package Contents

Classes

`LensGalaxyParameterDistribution`	Class to sample lens galaxy parameters, source parameters conditioned on the source being strongly lensed, and image properties
`LeR`	Class to calculate both the rates of lensed and unlensed events. Please note that parameters of the simulated events are stored in json file but not as an attribute of the class. This saves RAM memory.
`CBCSourceParameterDistribution`	Class to generate a population of compact binaries. It helps sample all the intrinsic and extrinsic parameters of compact binaries. This daughter class inherits from `CBCSourceRedshiftDistribution` class.
`GWRATES`	Class to calculate both the rates of lensed and gw events. Please note that parameters of the simulated events are stored in json file but not as an attribute of the class. This saves RAM memory.

Functions

`load_json`(file_name)	Load a json file.
`append_json`(file_name, new_dictionary[, ...])	Append and update a json file with a dictionary.
`get_param_from_json`(json_file)	Function to get the parameters from json file.
`batch_handler`(size, batch_size, sampling_routine, ...)	Function to run the sampling in batches.
`add_dict_values`(dict1, dict2)	Adds the values of two dictionaries together.
`load_json`(file_name)	Load a json file.
`append_json`(file_name, new_dictionary[, ...])	Append and update a json file with a dictionary.
`get_param_from_json`(json_file)	Function to get the parameters from json file.
`batch_handler`(size, batch_size, sampling_routine, ...)	Function to run the sampling in batches.

class ler.rates.LensGalaxyParameterDistribution(npool=4, z_min=0.0, z_max=10.0, cosmology=None, event_type='BBH', lens_type='epl_galaxy', lens_functions=None, lens_priors=None, lens_priors_params=None, directory='./interpolator_pickle', create_new_interpolator=False, **kwargs)[source]

Bases: ler.gw_source_population.CBCSourceParameterDistribution, ler.image_properties.ImageProperties, ler.lens_galaxy_population.optical_depth.OpticalDepth

Class to sample lens galaxy parameters, source parameters conditioned on the source being strongly lensed, and image properties

Parameters:

npoolint

number of processors to use

z_minfloat

minimum redshift

z_maxfloat

maximum redshift

cosmologyastropy.cosmology

Cosmology to use default: None/astropy.cosmology.FlatLambdaCDM(H0=70, Om0=0.3)

event_typestr

Type of event to generate. e.g. ‘BBH’, ‘BNS’, ‘NSBH’ default: ‘BBH’

lens_typestr

Type of lens galaxy to generate. default: ‘epl_galaxy’

lens_functions, lens_priors, lens_priors_paramsdict, dict, dict

dictionary of lens functions, priors, and priors parameters Check for default/available lens functions, priors and corresponding input parameters by running,

>>> from ler.lens_galaxy_population import LensGalaxyParameterDistribution
>>> lens = LensGalaxyParameterDistribution()
>>> print(lens.lens_functions)
>>> print(lens.lens_priors)
>>> print(lens.lens_priors_params)

directorystr

directory to store the interpolators default: ‘./interpolator_pickle’

**kwargs

keyword arguments to pass to the parent classes

Examples

>>> from ler.lens_galaxy_population import LensGalaxyParameterDistribution
>>> lens = LensGalaxyParameterDistribution()
>>> lensed_params = lens.sample_lens_parameters(size=1000)
>>> lensed_params.keys()

Instance Attributes

LensGalaxyPopulation class has the following instance attributes:

Atrributes	Type
`npool`	int
`z_min`	float
`z_max`	float
`cosmo`	astropy.cosmology
`event_type`	str
`directory`	str
`create_new_interpolator`	dict
`lens_param_samplers`	dict
`lens_param_samplers_params`	dict
`lens_sampler_names`	dict
`lens_functions`	dict
`normalization_pdf_z_lensed`	float

Instance Methods

LensGalaxyPopulation class has the following instance methods:

Methods	Type
`sample_lens_parameters()`	Function to call the specific galaxy lens parameters sampler routine.
`sample_all_routine()`	Function to sample galaxy lens parameters along with the source parameters.
`strongly_lensed_source_redshifts()`
	Function to sample source redshifts conditioned on the source being strongly lensed
`source_parameters()`	Function to sample gw source parameters
`lens_redshift_SDSS_catalogue()`	Function to sample lens redshifts, conditioned on the lens being strongly lensed
`axis_rotation_angle_uniform()`	Function to sample the axis rotation angle of the elliptical lens galaxy from a uniform distribution
`shear_norm()`	Function to sample the elliptical lens galaxy shear from a normal distribution
`mass_density_spectral_index_normal()`
	Function to sample the lens galaxy spectral index of the mass density profile from a normal distribution
`compute_einstein_radii()`	Function to compute the Einstein radii of the lens galaxies
`rjs_with_cross_section_SIE()`	Function to conduct rejection sampling wrt einstein radius
`rjs_with_cross_section_SIE()`	Function to conduct rejection sampling wrt cross_section
`rejection_sample_sl`	Function to conduct rejection sampling with the given rejection sampling function
`sample_source_redshift_sl`	Function to sample source redshifts conditioned on the source being strongly lensed
`sample_lens_redshift`	Function to sample lens redshifts, conditioned on the lens being strongly lensed
`sample_axis_rotation_angle`	Function to sample the axis rotation angle of the elliptical lens galaxy from a uniform distribution
`sample_shear`	Function to sample the elliptical lens galaxy shear from a normal distribution
`sample_mass_density_spectral_index`
	Function to sample the lens galaxy spectral index of the mass density profile from a normal distribution

property sample_source_redshift_sl

Function to sample source redshifts conditioned on the source being strongly lensed

Parameters:

sizeint: number samples to draw

Returns:

zsnumpy.ndarray (1D array of floats): source redshifts conditioned on the source being strongly lensed

Examples

>>> from ler.lens_galaxy_population import LensGalaxyParameterDistribution
>>> lens = LensGalaxyParameterDistribution()
>>> lens.sample_source_redshift_sl(size=1000)

property sample_source_parameters

Function to sample source parameters conditioned on the source being strongly lensed

Parameters:

sizeint: number of lens parameters to sample

Returns:

source_parametersdict: dictionary of source parameters conditioned on the source being strongly lensed

property sample_lens_redshift

Function to sample lens redshifts, conditioned on the lens being strongly lensed

Parameters:

zsnumpy.ndarray (1D array of floats): source redshifts

Returns:

zlnumpy.ndarray (1D array of floats): lens redshifts corresponding to the source redshifts

Examples

>>> from ler.lens_galaxy_population import LensGalaxyParameterDistribution
>>> lens = LensGalaxyParameterDistribution()
>>> zs = lens.sample_source_redshift_sl(size=1000)
>>> lens.sample_lens_redshift(zs=zs)

property sample_axis_rotation_angle

Function to sample the axis rotation angle of the elliptical lens galaxy from a uniform distribution

Parameters:

sizeint: number of lens parameters to sample

Returns:

phifloat: axis rotation angle of the elliptical lens galaxy

Examples

>>> from ler.lens_galaxy_population import LensGalaxyParameterDistribution
>>> lens = LensGalaxyParameterDistribution()
>>> lens.sample_axis_rotation_angle(size=1000)

property sample_shear

Function to sample the elliptical lens galaxy shear from a normal distribution

Parameters:

sizeint: number of lens parameters to sample

Returns:

gamma_1float: shear component in the x-direction
gamma_2float: shear component in the y-direction

Examples

>>> from ler.lens_galaxy_population import LensGalaxyParameterDistribution
>>> lens = LensGalaxyParameterDistribution()
>>> gamma_1, gamma_2 = lens.shear_norm(size=1000)

property sample_mass_density_spectral_index

Function to sample the lens galaxy spectral index of the mass density profile from a normal distribution

Parameters:

sizeint: number of lens parameters to sample

Returns:

gammafloat: spectral index of the density profile

Examples

>>> from ler.lens_galaxy_population import LensGalaxyParameterDistribution
>>> lens = LensGalaxyParameterDistribution()
>>> lens.mass_density_spectral_index_normal(size=1000)

property sample_source_parameters

Function to sample source parameters conditioned on the source being strongly lensed

Parameters:

sizeint: number of lens parameters to sample

Returns:

source_parametersdict: dictionary of source parameters conditioned on the source being strongly lensed

property available_lens_prior_list_and_its_params: Dictionary with list all the available priors and it’s corresponding parameters. This is an immutable instance attribute.

property available_lens_functions: Dictionary with list all the available lens functions. This is an immutable instance attribute.

cbc_pop

CompactBinaryPopulation class

This is an already initialized class that contains a function (CompactBinaryPopulation.sample_gw_parameters) that actually samples the source parameters.

z_min

float

minimum redshift

z_max

float

maximum redshift

m_min

float

minimum mass in detector frame

m_max

float

maximum mass in detector frame

normalization_pdf_z

float

normalization constant of the pdf p(z)

class_initialization_lens(params=None)[source]

Function to initialize the parent classes

Parameters:

paramsdict: dictionary of parameters to initialize the parent classes

lens_priors_categorization(lens_type, lens_priors=None, lens_priors_params=None, lens_functions=None)[source]

Function to categorize the lens priors/samplers

Parameters:

lens_typestr: lens type e.g. ‘epl_galaxy’ for elliptical power-law galaxy
lens_priorsdict: dictionary of priors
lens_priors_paramsdict: dictionary of priors parameters
lens_functionsdict: dictionary of lens functions

Returns:

lens_priors_dict: dictionary of priors
lens_priors_params_dict: dictionary of priors parameters
lens_sampler_names_dict: dictionary of sampler names
lens_functions_dict: dictionary of lens functions

sample_lens_parameters(size=1000, lens_parameters_input=None)[source]: Function to call the specific galaxy lens parameters sampler routine.

sample_all_routine(size=1000, lens_parameters_input=None)[source]

Function to sample galaxy lens parameters along with the source parameters.

Parameters:

sizeint: number of lens parameters to sample
lens_parameters_inputdict: dictionary of lens parameters to sample

Returns:

lens_parametersdict

dictionary of lens parameters and source parameters (lens conditions applied):

zl: lens redshifts

zs: source redshifts, lensed condition applied

sigma: velocity dispersions

q: axis ratios

theta_E: Einstein radii

phi: axis rotation angle

e1: ellipticity component 1

e2: ellipticity component 2

gamma1: shear component 1

gamma2: shear component 2

gamma: spectral index of the mass density distribution

geocent_time: time of arrival of the unlensed signal

phase: phase of the unlensed signal

psi: polarization angle of the unlensed signal

theta_jn: inclination angle of the unlensed signal

luminosity_distance: luminosity distance of the source

mass_1_source: mass 1 (larger) of the source

mass_2_source: mass 2 (smaller) of the source

ra: right ascension of the source

dec: declination of the source

Examples

>>> from ler.lens_galaxy_population import LensGalaxyParameterDistribution
>>> lens = LensGalaxyParameterDistribution()
>>> lens.sample_all_routine(size=1000)

strongly_lensed_source_redshifts(size=1000)[source]

Function to sample source redshifts and other parameters, conditioned on the source being strongly lensed.

Parameters:

sizeint: number of lens parameters to sample

Returns:

redshiftsfloat: source redshifts conditioned on the source being strongly lensed

Examples

>>> from ler.lens_galaxy_population import LensGalaxyParameterDistribution
>>> lens = LensGalaxyParameterDistribution()
>>> lens.strongly_lensed_source_redshifts(size=1000)

source_parameters(size, get_attribute=False, param=None)[source]

Function to sample gw source parameters

Parameters:

sizeint: Number of samples to draw
paramdict: Allows to pass in parameters as dict. param =

Returns:

source_parametersdict: Dictionary of source parameters source_parameters.keys() = [‘mass_1’, ‘mass_2’, ‘mass_1_source’, ‘mass_2_source’, ‘zs’, ‘luminosity_distance’, ‘inclination’, ‘polarization_angle’, ‘phase’, ‘geocent_time’, ‘ra’, ‘dec’, ‘a_1’, ‘a_2’, ‘tilt_1’, ‘tilt_2’, ‘phi_12’, ‘phi_jl’]

Examples

>>> from ler.lens_galaxy_population import LensGalaxyParameterDistribution
>>> lens = LensGalaxyParameterDistribution()
>>> lens.source_parameters(size=1000)

lens_redshift_SDSS_catalogue(zs, get_attribute=False, param=None)[source]

Function to sample lens redshifts, conditioned on the lens being strongly lensed

Parameters:

zsfloat: source redshifts
get_attributebool: If True, returns a function that can be called with zs as input

Returns:

zlfloat: lens redshifts

Examples

>>> from ler.lens_galaxy_population import LensGalaxyParameterDistribution
>>> lens = LensGalaxyParameterDistribution()
>>> lens.lens_redshift_SDSS_catalogue(zs=1.0)

axis_rotation_angle_uniform(size=1000, phi_min=0.0, phi_max=2 * np.pi, get_attribute=False, param=None)[source]

Function to sample the axis rotation angle of the elliptical lens galaxy from a uniform distribution.

Parameters:

sizeint: number of lens parameters to sample
phi_minfloat: minimum axis rotation angle of the elliptical lens galaxy
phi_maxfloat: maximum axis rotation angle of the elliptical lens galaxy
get_attributebool: If True, returns a function that can be called with size as input
paramdict: Allows to pass in above parameters as dict. e.g. param = dict(phi_min=0.0, phi_max=2 * np.pi)

Returns:

phifloat: axis rotation angle of the elliptical lens galaxy

Examples

>>> from ler.lens_galaxy_population import LensGalaxyParameterDistribution
>>> lens = LensGalaxyParameterDistribution()
>>> lens.axis_rotation_angle_uniform(size=1000)

shear_norm(size, scale=0.05, get_attribute=False, param=None)[source]

Function to sample the elliptical lens galaxy shear from a normal distribution

Parameters:

sizeint: number of lens parameters to sample
scalefloat: standard deviation of the normal distribution
get_attributebool: If True, returns a function that can be called with size as input
paramdict: Allows to pass in above parameters as dict. e.g. param = dict(scale=0.05)

Returns:

gamma_1float: shear component in the x-direction
gamma_2float: shear component in the y-direction

Examples

>>> from ler.lens_galaxy_population import LensGalaxyParameterDistribution
>>> lens = LensGalaxyParameterDistribution()
>>> gamma_1, gamma_2 = lens.shear_norm(size=1000)

mass_density_spectral_index_normal(size=1000, mean=2.0, std=0.2, get_attribute=False, param=None)[source]

Function to sample the lens galaxy spectral index of the mass density profile from a normal distribution

Parameters:

sizeint: number of lens parameters to sample
meanfloat: mean of the normal distribution
stdfloat: standard deviation of the normal distribution
paramdict: Allows to pass in above parameters as dict. e.g. param = dict(mean=2.0, std=0.2)

Returns:

gammafloat: spectral index of the density profile

Examples

>>> from ler.lens_galaxy_population import LensGalaxyParameterDistribution
>>> lens = LensGalaxyParameterDistribution()
>>> lens.mass_density_spectral_index_normal(size=1000)

compute_einstein_radii(sigma, zl, zs)[source]

Function to compute the Einstein radii of the lens galaxies

Parameters:

sigmafloat: velocity dispersion of the lens galaxy
zlfloat: lens redshifts
zsfloat: source redshifts

Returns:

theta_Efloat: Einstein radii of the lens galaxies

Examples

>>> from ler.lens_galaxy_population import LensGalaxyParameterDistribution
>>> lens = LensGalaxyParameterDistribution()
>>> sigma = 200.0
>>> zl = 0.5
>>> zs = 1.0
>>> lens.compute_einstein_radii(sigma, zl, zs)

rjs_with_cross_section_SIS(param_dict)[source]

Function to conduct rejection sampling wrt einstein radius

Parameters:

param_dictdict: dictionary of lens parameters and source parameters

Returns:

lens_paramsdict: dictionary of lens parameters after rejection sampling

rjs_with_cross_section_SIE(param_dict)[source]

Function to conduct rejection sampling wrt cross_section

Parameters:

param_dictdict: dictionary of lens parameters and source parameters

Returns:

lens_paramsdict: dictionary of lens parameters after rejection sampling

ler.rates.load_json(file_name)[source]

Load a json file.

Parameters:

file_namestr: json file name for storing the parameters.

Returns:

paramdict

ler.rates.append_json(file_name, new_dictionary, old_dictionary=None, replace=False)[source]

Append and update a json file with a dictionary.

Parameters:

file_namestr: json file name for storing the parameters.
new_dictionarydict: dictionary to be appended to the json file.
replacebool, optional: If True, replace the json file with the dictionary. Default is False.

ler.rates.get_param_from_json(json_file)[source]

Function to get the parameters from json file.

Parameters:

json_filestr: json file name for storing the parameters.

Returns:

paramdict

ler.rates.batch_handler(size, batch_size, sampling_routine, output_jsonfile, save_batch=True, resume=False)[source]

Function to run the sampling in batches.

Parameters:

sizeint: number of samples.
batch_sizeint: batch size.
sampling_routinefunction: function to sample the parameters. e.g. unlensed_sampling_routine() or lensed_sampling_routine()
output_jsonfilestr: name of the json file to store the parameters.
resumebool: if True, it will resume the sampling from the last batch. default resume = False.

ler.rates.add_dict_values(dict1, dict2)[source]

Adds the values of two dictionaries together.

Parameters:

dict1dict: dictionary to be added.
dict2dict: dictionary to be added.

Returns:

dict1dict: dictionary with added values.

class ler.rates.LeR(npool=int(4), z_min=0.0, z_max=10.0, event_type='BBH', size=100000, batch_size=50000, cosmology=None, snr_finder=None, pdet_finder=None, list_of_detectors=None, json_file_names=None, interpolator_directory='./interpolator_pickle', ler_directory='./ler_data', verbose=True, **kwargs)[source]

Bases: ler.lens_galaxy_population.LensGalaxyParameterDistribution

Class to calculate both the rates of lensed and unlensed events. Please note that parameters of the simulated events are stored in json file but not as an attribute of the class. This saves RAM memory.

Parameters:

npoolint: number of cores to use. default npool = 4.
z_minfloat: minimum redshift. default z_min = 0. for popI_II, popIII, primordial, BNS z_min = 0., 5., 5., 0. respectively.
z_maxfloat: maximum redshift. default z_max = 10. for popI_II, popIII, primordial, BNS z_max = 10., 40., 40., 2. respectively.
sizeint: number of samples for sampling. default size = 100000.
batch_sizeint: batch size for SNR calculation. default batch_size = 50000. reduce the batch size if you are getting memory error. recommended batch_size = 50000, if size = 1000000.
snr_finderstr: default snr_finder = ‘gwsnr’. if None, the SNR will be calculated using the gwsnr package. if ‘custom’, the SNR will be calculated using a custom function. The custom function should have input and output as given in GWSNR.snr method.
json_file_names: `dict`: names of the json files to strore the necessary parameters. default json_file_names = {‘ler_params’: ‘LeR_params.json’, ‘unlensed_param’: ‘unlensed_param.json’, ‘unlensed_param_detectable’: ‘unlensed_param_detectable.json’}.
kwargskeyword arguments: Note : kwargs takes input for initializing the LensGalaxyParameterDistribution, gwsnr_intialization().

Examples

>>> from ler.rates import LeR
>>> ler = LeR()
>>> unlensed_params = ler.unlensed_cbc_statistics();
>>> ler.unlensed_rate();

Instance Attributes

LeR class has the following attributes,

Atrributes	Type
`z_min`	float
`z_max`	float
`event_type`	str
`cosmo`	astropy.cosmology
`size`	int
`batch_size`	int
`json_file_names`	dict
`directory`	str
`gw_param_sampler_dict`	dict
`snr_calculator_dict`	dict
`list_of_detectors`	list
`unlensed_param`	dict
`unlensed_param_detectable`	dict
`lensed_param`	dict
`lensed_param_detectable`	dict

Instance Methods

LeR class has the following methods,

Methods	Description
`class_initialization()`	Function to initialize the parent classes
`gwsnr_intialization()`	Function to initialize the gwsnr class
`snr()`	Function to get the snr with the given parameters.
`store_ler_params()`	Function to store the all the necessary parameters.
`unlensed_cbc_statistics()`	Function to generate unlensed GW source parameters.
`unlensed_sampling_routine()`	Function to generate unlensed GW source parameters.
`unlensed_rate()`	Function to calculate the unlensed rate.
`selecting_n_unlensed_detectable_events()`
	Function to select n unlensed detectable events.
`lensed_cbc_statistics()`	Function to generate lensed GW source parameters.
`lensed_sampling_routine()`	Function to generate lensed GW source parameters.
`lensed_rate()`	Function to calculate the lensed rate.
`rate_ratio()`	Function to calculate the rate ratio.
:meth:`~rate_comparision_with_rate_calculation
	Function to compare the rates calculated using LeR between unlensed and lensed events.
`param_plot()`	Function to plot the distribution of various parameters.
`relative_mu_dt_lensed()`	Function to calculate the relative magnification and relative time-delay of lensed events.
`relative_mu_dt_unlensed()`	Function to calculate the relative magnification and relative time-delay of unlensed events.
`mu_vs_dt_plot()`	Function to plot the relative magnification vs relative time-delay.

property snr

Function to get the snr with the given parameters.

Parameters:

gw_param_dictdict

dictionary of GW source parameters. mass_1 : numpy.ndarray or float

mass_1 of the compact binary (detector frame) (Msun).

mass_2numpy.ndarray or float: mass_2 of the compact binary (detector frame) (Msun).
luminosity_distancenumpy.ndarray or float: luminosity distance of the source (Mpc).
theta_jnnumpy.ndarray or float: inclination angle of the source (rad).
psinumpy.ndarray or float: polarization angle of the source (rad).
phasenumpy.ndarray or float: phase of GW at reference frequency (rad).
geocent_timenumpy.ndarray or float: GPS time of coalescence (s).
ranumpy.ndarray or float: right ascension of the source (rad).
decnumpy.ndarray or float: declination of the source (rad).
a_1numpy.ndarray or float: dimensionless spin magnitude of the more massive object.
a_2numpy.ndarray or float: dimensionless spin magnitude of the less massive object.
tilt_1numpy.ndarray or float: tilt angle of the more massive object spin.
tilt_2numpy.ndarray or float: tilt angle of the less massive object spin.
phi_12numpy.ndarray or float: azimuthal angle between the two spin vectors.
phi_jlnumpy.ndarray or float: azimuthal angle between total angular momentum and the orbital angular momentum.

Returns:

optimal_snr_listlist

e.g. [optimal_snr_net, ‘L1’, ‘H1’, ‘V1’] optimal_snr_net : numpy.ndarray or float

optimal snr of the network.

‘H1’numpy.ndarray or float: optimal snr of H1.
‘L1’numpy.ndarray or float: optimal snr of L1.
‘V1’numpy.ndarray or float: optimal snr of V1.

property unlensed_param

Function to get data from the json file self.json_file_names[“unlensed_param”].

Returns:

unlensed_paramdict: dictionary of unlensed GW source parameters.

property unlensed_param_detectable

Function to get data from the json file self.json_file_names[“unlensed_param_detectable”].

Returns:

unlensed_param_detectabledict: dictionary of unlensed GW source parameters.

property lensed_param

Function to get data from the json file self.json_file_names[“lensed_param”].

Returns:

lensed_paramdict: dictionary of lensed GW source parameters.

property lensed_param_detectable

Function to get data from the json file self.json_file_names[“lensed_param_detectable”].

Returns:

lensed_param_detectabledict: dictionary of lensed GW source parameters.

z_min

float

Minimum redshift of the source population

z_max

float

Maximum redshift of the source population

event_type

str

Type of event to generate.

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

cosmo

astropy.cosmology

Cosmology to use for the calculation.

size

int

Number of samples for sampling.

batch_size

int

Batch size for sampling.

json_file_names

dict

Names of the json files to strore the necessary parameters.

interpolator_directory

str

Directory to store the interpolators.

ler_directory

str

Directory to store the parameters.

gw_param_sampler_dict

dict

Dictionary of parameters to initialize the CBCSourceParameterDistribution class.

lens_param_sampler_dict

dict

Dictionary of parameters to initialize the LensGalaxyParameterDistribution class.

snr_calculator_dict

dict

Dictionary of parameters to initialize the GWSNR class.

list_of_detectors

list

List of detectors.

print_all_params()[source]: Function to print all the parameters.

class_initialization(params=None)[source]

Function to initialize the parent classes. List of relevant initialized instances,

self.sample_source_redshift
self.sample_unlensed_parameters
self.normalization_pdf_z
self.sample_lens_parameters
self.normalization_pdf_z_lensed
self.image_properties
self.get_lensed_snrs

Parameters:

paramsdict: dictionary of parameters to initialize the parent classes

gwsnr_intialization(params=None)[source]

Function to initialize the gwsnr class

Parameters:

paramsdict: dictionary of parameters to initialize the gwsnr class

store_ler_params(output_jsonfile='ler_params.json')[source]

Function to store the all the necessary parameters. This is useful for reproducing the results. All the parameters stored are in string format to make it json compatible.

Parameters:

output_jsonfilestr: name of the json file to store the parameters

unlensed_cbc_statistics(size=None, resume=False, save_batch=False, output_jsonfile=None)[source]

Function to generate unlensed GW source parameters. This function also stores the parameters in json file.

Parameters:

sizeint: number of samples. default size = 100000.
resumebool: resume = False (default) or True. if True, the function will resume from the last batch.
save_batchbool: if True, the function will save the parameters in batches. if False, the function will save all the parameters at the end of sampling. save_batch=False is faster.
output_jsonfilestr: json file name for storing the parameters. default output_jsonfile = ‘unlensed_params.json’.

Returns:

unlensed_paramdict: dictionary of unlensed GW source parameters. unlensed_param.keys() = [‘zs’, ‘geocent_time’, ‘ra’, ‘dec’, ‘phase’, ‘psi’, ‘theta_jn’, ‘luminosity_distance’, ‘mass_1_source’, ‘mass_2_source’, ‘mass_1’, ‘mass_2’, ‘optimal_snr_net’, ‘L1’, ‘H1’, ‘V1’]

Examples

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

unlensed_sampling_routine(size, output_jsonfile, resume=False, save_batch=True)[source]

Function to generate unlensed GW source parameters. This function also stores the parameters in json file.

Parameters:

sizeint: number of samples. default size = 100000.
resumebool: resume = False (default) or True. if True, the function will resume from the last batch.
output_jsonfilestr: json file name for storing the parameters. default output_jsonfile = ‘unlensed_params.json’.

Returns:

unlensed_paramdict: dictionary of unlensed GW source parameters. unlensed_param.keys() = [‘zs’, ‘geocent_time’, ‘ra’, ‘dec’, ‘phase’, ‘psi’, ‘theta_jn’, ‘luminosity_distance’, ‘mass_1_source’, ‘mass_2_source’, ‘mass_1’, ‘mass_2’, ‘optimal_snr_net’, ‘L1’, ‘H1’, ‘V1’]

unlensed_rate(unlensed_param=None, snr_threshold=8.0, output_jsonfile=None, detectability_condition='step_function', snr_recalculation=False, snr_threshold_recalculation=5.5)[source]

Function to calculate the unlensed rate. This function also stores the parameters of the detectable events in json file.

Parameters:

unlensed_paramdict or str: dictionary of GW source parameters or json file name. default unlensed_param = ‘unlensed_params.json’.
snr_thresholdfloat: threshold for detection signal to noise ratio. e.g. snr_threshold = 8.
output_jsonfilestr: json file name for storing the parameters of the detectable events. default output_jsonfile = ‘unlensed_params_detectable.json’.
detectability_conditionstr: detectability condition. default detectability_condition = ‘step_function’. other options are ‘pdet’.
snr_recalculationbool: if True, the SNR of centain events (snr>snr_threshold_recalculation)will be recalculate with ‘inner product’. This is useful when the snr is calculated with ‘ann’ method. default snr_recalculation = False.
snr_threshold_recalculationfloat: threshold for recalculation of detection signal to noise ratio.

Returns:

total_ratefloat: total unlensed rate (Mpc^-3 yr^-1).
unlensed_paramdict: dictionary of unlensed GW source parameters of the detectable events. unlensed_param.keys() = [‘zs’, ‘geocent_time’, ‘ra’, ‘dec’, ‘phase’, ‘psi’, ‘theta_jn’, ‘luminosity_distance’, ‘mass_1_source’, ‘mass_2_source’, ‘mass_1’, ‘mass_2’, ‘optimal_snr_net’, ‘L1’, ‘H1’, ‘V1’]

Examples

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

lensed_cbc_statistics(size=None, save_batch=False, resume=False, output_jsonfile=None)[source]

Function to generate lensed GW source parameters. This function also stores the parameters in json file.

Parameters:

sizeint: number of samples. default size = 100000.
resumebool: resume = False (default) or True. if True, the function will resume from the last batch.
output_jsonfilestr: json file name for storing the parameters. default output_jsonfile = ‘lensed_params.json’.

Returns:

lensed_paramdict: dictionary of lensed GW source parameters. lensed_param.keys() =

Examples

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

lensed_sampling_routine(size, output_jsonfile, save_batch=True, resume=False)[source]

Function to generate lensed GW source parameters. This function also stores the parameters in json file.

Parameters:

sizeint: number of samples. default size = 100000.
resumebool: resume = False (default) or True. if True, the function will resume from the last batch.
output_jsonfilestr: json file name for storing the parameters. default output_jsonfile = ‘lensed_params.json’.

Returns:

lensed_paramdict: dictionary of lensed GW source parameters. lensed_param.keys() =

lensed_rate(lensed_param=None, snr_threshold=[8.0, 8.0], num_img=[1, 1], output_jsonfile=None, nan_to_num=True, detectability_condition='step_function', snr_recalculation=False, snr_threshold_recalculation=[5.5, 5.5])[source]

Function to calculate the lensed rate. This function also stores the parameters of the detectable events in json file.

Parameters:

lensed_paramdict or str: dictionary of GW source parameters or json file name. default lensed_param = ‘lensed_params.json’.
snr_thresholdfloat: threshold for detection signal to noise ratio. default snr_threshold = [8.0,8.0].
num_imgint: number of images. default num_img = [1,1].
output_jsonfilestr: json file name for storing the parameters of the detectable events. default output_jsonfile = ‘lensed_params_detectable.json’.
nan_to_numbool: if True, nan values will be converted to 0. default nan_to_num = True.
detectability_conditionstr: detectability condition. default detectability_condition = ‘step_function’. other options are ‘pdet’.
snr_recalculationbool: if True, the SNR of centain events (snr>snr_threshold_recalculation)will be recalculate with ‘inner product’. This is useful when the snr is calculated with ‘ann’ method. default snr_recalculation = False.
snr_threshold_recalculationfloat: threshold for recalculation of detection signal to noise ratio.

Returns:

total_ratefloat: total lensed rate (Mpc^-3 yr^-1).
lensed_paramdict: dictionary of lensed GW source parameters of the detectable events. lensed_param.keys() =

Examples

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

rate_ratio()[source]

Function to calculate and display unlensed and lensed merger rate ratio. It will get the unlensed_rate and lensed_rate from self.json_file_ler_param

Returns:

rate_ratiofloat: rate ratio.

Examples

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

rate_comparision_with_rate_calculation(unlensed_param=None, snr_threshold_unlensed=8.0, output_jsonfile_unlensed=None, lensed_param=None, snr_threshold_lensed=[8.0, 8.0], num_img=[1, 1], output_jsonfile_lensed=None, nan_to_num=True, detectability_condition='step_function')[source]

Function to calculate the unlensed and lensed rate and compare by computing the ratio. This function also stores the parameters of the detectable events in json file.

Parameters:

unlensed_paramdict or str: dictionary of GW source parameters or json file name. default unlensed_param = ‘unlensed_params.json’.
snr_threshold_unlensedfloat: threshold for detection signal to noise ratio. e.g. snr_threshold = 8.
output_jsonfile_unlensedstr: json file name for storing the parameters of the detectable events. default output_jsonfile = ‘unlensed_params_detectable.json’.
lensed_paramdict or str: dictionary of GW source parameters or json file name. default lensed_param = ‘lensed_params.json’.
snr_threshold_lensedfloat: threshold for detection signal to noise ratio. e.g. snr_threshold = 8.
output_jsonfile_lensedstr: json file name for storing the parameters of the detectable events. default output_jsonfile = ‘lensed_params_detectable.json’.
detectability_conditionstr: detectability condition. default detectability_condition = ‘step_function’. other options are ‘pdet’.

Returns:

rate_ratiofloat: rate ratio.
unlensed_paramdict: dictionary of unlensed GW source parameters of the detectable events.
lensed_paramdict: dictionary of lensed GW source parameters of the detectable events.

Examples

>>> from ler.rates import LeR
>>> ler = LeR()
>>> ler.unlensed_cbc_statistics();
>>> ler.lensed_cbc_statistics();
>>> rate_ratio, unlensed_param, lensed_param = ler.rate_comparision_with_rate_calculation()

selecting_n_unlensed_detectable_events(size=100, batch_size=None, snr_threshold=8.0, resume=False, output_jsonfile='n_unlensed_param_detectable.json', meta_data_file='meta_unlensed.json', trim_to_size=True, snr_recalculation=False, snr_threshold_recalculation=5.5)[source]

Function to select n unlensed detectable events.

Parameters:

sizeint: number of samples to be selected. default size = 100.
snr_thresholdfloat: threshold for detection signal to noise ratio. e.g. snr_threshold = 8.
resumebool: if True, it will resume the sampling from the last batch. default resume = False.
output_jsonfilestr: json file name for storing the parameters. default output_jsonfile = ‘n_unlensed_params_detectable.json’.

Returns:

param_finaldict: dictionary of unlensed GW source parameters of the detectable events. param_final.keys() = [‘zs’, ‘geocent_time’, ‘ra’, ‘dec’, ‘phase’, ‘psi’, ‘theta_jn’, ‘luminosity_distance’, ‘mass_1_source’, ‘mass_2_source’, ‘mass_1’, ‘mass_2’, ‘optimal_snr_net’, ‘L1’, ‘H1’, ‘V1’]

Examples

>>> from ler.rates import LeR
>>> ler = LeR()
>>> unlensed_param_final = ler.selecting_n_unlensed_detectable_events(size=500)

selecting_n_lensed_detectable_events(size=100, batch_size=None, snr_threshold=[8.0, 8.0], num_img=[1, 1], resume=False, detectability_condition='step_function', output_jsonfile='n_lensed_params_detectable.json', meta_data_file='meta_lensed.json', trim_to_size=True, nan_to_num=False, snr_recalculation=False, snr_threshold_recalculation=[5.5, 5.5])[source]

Function to select n lensed detectable events.

Parameters:

sizeint: number of samples to be selected. default size = 100.
snr_thresholdfloat: threshold for detection signal to noise ratio. e.g. snr_threshold = 8.
num_imgint: number of images. default num_img = 2.
resumebool: if True, it will resume the sampling from the last batch. default resume = False.
detectability_conditionstr: detectability condition. default detectability_condition = ‘step_function’. other options are ‘pdet’.
output_jsonfilestr: json file name for storing the parameters.

Returns:

param_finaldict: dictionary of lensed GW source parameters of the detectable events. param_final.keys() =

Examples

>>> from ler.rates import LeR
>>> ler = LeR()
>>> lensed_param_final = ler.selecting_n_lensed_detectable_events(size=500)

class ler.rates.CBCSourceParameterDistribution(z_min=0.0, z_max=10.0, event_type='BBH', source_priors=None, source_priors_params=None, cosmology=None, spin_zero=True, spin_precession=False, directory='./interpolator_pickle', create_new_interpolator=False)[source]

Bases: ler.gw_source_population.cbc_source_redshift_distribution.CBCSourceRedshiftDistribution

Class to generate a population of compact binaries. It helps sample all the intrinsic and extrinsic parameters of compact binaries. This daughter class inherits from CBCSourceRedshiftDistribution class.

Parameters:

z_minfloat: Minimum redshift of the source population default: 0.001
z_maxfloat: Maximum redshift of the source population default: 10.
event_typestr: Type of event to generate. e.g. ‘BBH’, ‘BNS’, ‘NSBH’
source_priors, source_priors_paramsdict, dict: Dictionary of prior sampler functions and its input parameters. Check for available priors and corresponding input parameters by running, >>> from ler.gw_source_population import CBCSourceParameterDistribution >>> cbc = CompactBinaryPopulation() >>> cbc.available_gw_prior_list_and_its_params() # To check the current chosen priors and its parameters, run, >>> print(“default priors=”,cbc.gw_param_samplers) >>> print(“default priors’s parameters=”,cbc.gw_param_samplers_params)
cosmologyastropy.cosmology: Cosmology to use default: None/astropy.cosmology.FlatLambdaCDM(H0=70, Om0=0.3)
spin_zerobool: If True, spin parameters are completely ignore in the sampling. default: True
spin_precessionbool: If spin_zero=True and spin_precession=True, spin parameters are sampled for precessing binaries. if spin_zero=True and spin_precession=False, spin parameters are sampled for aligned/anti-aligned spin binaries. default: False
directorystr: Directory to store the interpolator pickle files default: ‘./interpolator_pickle’
create_new_interpolatordict: Dictionary of boolean values and resolution to create new interpolator. default: dict(redshift_distribution=dict(create_new=False, resolution=500), z_to_luminosity_distance=dict(create_new=False, resolution=500), differential_comoving_volume=dict(create_new=False, resolution=500))

Examples

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

Instance Attributes

CompactBinaryPopulation has the following instance attributes:

Instance Methods

CompactBinaryPopulation has the following instance methods:

Methods	Type
`source_priors_categorization()`
	Function to categorize the event priors and its parameters
`lookup_table_luminosity_distance()` Function to create a lookup table for converting redshift to luminosity distance
`sample_gw_parameters()`	Function to sample all the intrinsic and extrinsic parameters of compact binaries
`sample_source_frame_masses()`	Function to sample source mass1 and mass2
`sample_geocent_time()`	Function to sample geocent time
`sample_zs()`	Function to sample source redshift
`sample_ra()`	Function to sample right ascension (sky position)
`sample_dec()`	Function to sample declination (sky position)
`sample_phase()`	Function to sample coalescence phase
`sample_psi()`	Function to sample polarization angle
`sample_theta_jn()`	Function to sample inclination angle
`sample_a1()`	Function to sample spin1 magnitude
`sample_a2()`	Function to sample spin2 magnitude
`sample_tilt_1()`	Function to sample tilt1 angle
`sample_tilt_2()`	Function to sample tilt2 angle
`sample_phi_12()`	Function to sample phi12 angle
`sample_phi_jl()`	Function to sample phi_jl angle
`binary_masses_BBH_popI_II_powerlaw_gaussian()`
	Function to sample source mass1 and mass2 with PowerLaw+PEAK model
`binary_masses_BBH_popIII_lognormal()`
	Function to sample source mass1 and mass2 with popIII orgin from lognormal distribution. Refer to Ng et al. 2022. Eqn. 1 and 4
`binary_masses_BBH_primordial_lognormal()`
	Function to sample source mass1 and mass2 with primordial orgin from lognormal distribution. Refer to Ng et al. 2022. Eqn. 1 and 4
`binary_masses_BNS_gwcosmo()`
	Function to sample source mass1 and mass2 from powerlaw distribution.
`binary_masses_BNS_bimodal()`	Function to sample source mass1 and mass2 from bimodal distribution. Refer to Will M. Farr et al. 2020 Eqn. 6
`constant_values_n_size()`	Function to return array of constant values of size n
`sampler_uniform()`	Function to sample from uniform distribution

property available_gw_prior_list_and_its_params

Dictionary with list all the available priors and it’s corresponding parameters. This is an immutable instance attribute.

Examples

>>> from ler.gw_source_population import CBCSourceParameterDistribution
>>> cbc = CompactBinaryPopulation()
>>> priors = cbc.available_gw_prior_list_and_its_params
>>> priors.keys()  # type of priors
dict_keys(['merger_rate_density', 'source_frame_masses', 'spin', 'geocent_time', 'ra', 'phase', 'psi', 'theta_jn'])
>>> priors['source_frame_masses'].keys()  # type of source_frame_masses priors
dict_keys(['binary_masses_BBH_popI_II_powerlaw_gaussian', 'binary_masses_BBH_popIII_lognormal', 'binary_masses_BBH_primordial_lognormal', 'binary_masses_BNS_gwcosmo', 'binary_masses_BNS_bimodal'])
>>> priors['source_frame_masses']['binary_masses_BBH_popI_II_powerlaw_gaussian'].keys()  # parameters of binary_masses_BBH_popI_II_powerlaw_gaussian
dict_keys(['mminbh', 'mmaxbh', 'alpha', 'mu_g', 'sigma_g', 'lambda_peak', 'delta_m', 'beta'])

property sample_zs

Function to sample redshifts with the initialized prior.

Parameters:

sizeint: Number of samples to draw

Returns:

zsnumpy.ndarray (1D array of floats): Array of redshifts

property sample_source_frame_masses

Function to sample source frame masses (mass1_source, mass2_source) with the initialized prior.

Parameters:

sizeint: Number of samples to draw

Returns:

mass_1_sourcenumpy.ndarray (1D array of floats): Array of mass1 in source frame
mass_2_sourcenumpy.ndarray (1D array of floats): Array of mass2 in source frame

property sample_geocent_time

Function to sample geocent time with the initialized prior.

Parameters:

sizeint: Number of samples to draw

Returns:

geocent_timenumpy.ndarray (1D array of floats): Array of geocent_time or time of coalescence

property sample_ra

Function to sample right ascension of sky position with the initialized prior.

Parameters:

sizeint: Number of samples to draw

Returns:

ranumpy.ndarray (1D array of floats): Array of right ascension of sky position

property sample_dec

Function to sample declination of sky position with the initialized prior.

Parameters:

sizeint: Number of samples to draw

Returns:

decnumpy.ndarray (1D array of floats): Array of declination of sky position

property sample_phase

Function to sample coalescence phase with the initialized prior.

Parameters:

sizeint: Number of samples to draw

Returns:

phasenumpy.ndarray (1D array of floats): Array of coalescence phase

property sample_psi

Function to sample polarization angle with the initialized prior.

Parameters:

sizeint: Number of samples to draw

Returns:

psinumpy.ndarray (1D array of floats): Array of polarization angle

property sample_theta_jn

Function to sample theta_jn with the initialized prior.

Parameters:

sizeint: Number of samples to draw

Returns:

theta_jnnumpy.ndarray (1D array of floats): Array of theta_jn

property sample_a_1

Function to sample spin magnitude of the compact binaries (body1) with the initialized prior.

Parameters:

sizeint: Number of samples to draw

Returns:

a_1numpy.ndarray (1D array of floats): Array of spin magnitude of the compact binaries (body1)

property sample_a_2

Function to sample spin magnitude of the compact binaries (body2) with the initialized prior.

Parameters:

sizeint: Number of samples to draw

Returns:

a_2numpy.ndarray (1D array of floats): Array of spin magnitude of the compact binaries (body2)

property sample_tilt_1

Function to sample tilt angle of the compact binaries (body1) with the initialized prior.

Parameters:

sizeint: Number of samples to draw

Returns:

tilt_1numpy.ndarray (1D array of floats): Array of tilt angle of the compact binaries (body1)

property sample_tilt_2

Function to sample tilt angle of the compact binaries (body2) with the initialized prior.

Parameters:

sizeint: Number of samples to draw

Returns:

tilt_2numpy.ndarray (1D array of floats): Array of tilt angle of the compact binaries (body2)

property sample_phi_12

Function to sample azimuthal angle between the two spins with the initialized prior.

Parameters:

sizeint: Number of samples to draw

Returns:

phi_12numpy.ndarray (1D array of floats): Array of azimuthal angle between the two spins

property sample_phi_jl

Function to sample azimuthal angle between the total angular momentum and the orbital angular momentum with the initialized prior.

Parameters:

sizeint: Number of samples to draw

Returns:

phi_jlnumpy.ndarray (1D array of floats): Array of azimuthal angle between the total angular momentum and the orbital angular momentum

z_min

float

Minimum redshift of the source population

z_max

float

Maximum redshift of the source population

event_type

str

Type of event to generate.

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

source_priors

dict

Dictionary of prior sampler functions.

source_priors_params

dict

Dictionary of prior sampler functions’ input parameters.

cosmo

astropy.cosmology

Cosmology to use.

spin_zero

bool

If True, spin prior is set to zero.

lookup_table_luminosity_distance(z_min, z_max, directory)[source]

Function to create a lookup table for the differential comoving volume and luminosity distance wrt redshift.

Parameters:

z_minfloat: Minimum redshift of the source population
z_maxfloat: Maximum redshift of the source population

Attributes:

z_to_luminosity_distancescipy.interpolate.interpolate: Function to convert redshift to luminosity distance
differential_comoving_volumescipy.interpolate.interpolate: Function to calculate the differential comoving volume

sample_gw_parameters(size=1000, param=None)[source]

Function to sample BBH/BNS/NSBH intrinsic and extrinsics parameters.

Parameters:

sizeint: Number of samples to draw

Returns:

gw_parametersdict: Dictionary of sampled parameters gw_parameters.keys() = [‘mass_1’, ‘mass_2’, ‘mass_1_source’, ‘mass_2_source’, ‘zs’, ‘luminosity_distance’, ‘theta_jn’, ‘psi’, ‘phase’, ‘geocent_time’, ‘ra’, ‘dec’, ‘a_1’, ‘a_2’, ‘tilt_1’, ‘tilt_2’, ‘phi_12’, ‘phi_jl’]

Examples

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

binary_masses_BBH_popI_II_powerlaw_gaussian(size, mminbh=4.98, mmaxbh=112.5, alpha=3.78, mu_g=32.27, sigma_g=3.88, lambda_peak=0.03, delta_m=4.8, beta=0.81, get_attribute=False, param=None)[source]

Function to sample source mass1 and mass2 with PowerLaw+PEAK model

Parameters:

sizeint: Number of samples to draw
mminbhfloat: Minimum mass of the black hole (Msun) default: 4.98
mmaxbhfloat: Maximum mass of the black hole (Msun) default: 86.22
alphafloat: Spectral index for the powerlaw of the primary mass distribution default: 2.63
mu_gfloat: Mean of the Gaussian component in the primary mass distribution default: 33.07
sigma_gfloat: Width of the Gaussian component in the primary mass distribution default: 5.69
lambda_peakfloat: Fraction of the model in the Gaussian component default: 0.10
delta_mfloat: Range of mass tapering on the lower end of the mass distribution default: 4.82
betafloat: Spectral index for the powerlaw of the mass ratio distribution
paramdict: Allows to pass in above parameters as dict. e.g. param = dict(mminbh=4.98, mmaxbh=86.22, alpha=2.63, mu_g=33.07, sigma_g=5.69, lambda_peak=0.10, delta_m=4.82, beta=1.26)

Returns:

mass_1_sourcenumpy.ndarray (1D array of floats): Array of mass1 in source frame (Msun)
mass_2_sourcenumpy.ndarray (1D array of floats): Array of mass2 in source frame (Msun)

Examples

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

binary_masses_BBH_popIII_lognormal(size, m_min=5.0, m_max=150.0, Mc=30.0, sigma=0.3, chunk_size=10000, get_attribute=False, param=None)[source]

Function to sample source mass1 and mass2 with pop III origin. Refer to Eqn. 1 and 4 of Ng et al. 2022

Parameters:

sizeint: Number of samples to draw
m_minfloat: Minimum mass of the black hole (popIII) (Msun) default: 10.
m_maxfloat: Maximum mass of the black hole (popIII) (Msun) default: 100.
Mcfloat: Mass scale; the distribution is centered around Mc default: 30.0
sigmafloat: Width of the distribution default: 0.3
paramdict: Allows to pass in above parameters as dict. e.g. param = dict(m_min=10., m_max=100., Mc=30.0, sigma=0.3)

Returns:

mass_1_sourcenumpy.ndarray (1D array of floats): Array of mass1 in source frame (Msun)
mass_2_sourcenumpy.ndarray (1D array of floats): Array of mass2 in source frame (Msun)

Examples

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

binary_masses_BBH_primordial_lognormal(size, m_min=1.0, m_max=100.0, Mc=20.0, sigma=0.3, chunk_size=10000, get_attribute=False, param=None)[source]

Function to sample source mass1 and mass2 with primordial origin. Refer to Eqn. 1 and 4 of Ng et al. 2022

Parameters:

sizeint: Number of samples to draw
m_minfloat: Minimum mass of the black hole (primordial) (Msun) default: 10.
m_maxfloat: Maximum mass of the black hole (primordial) (Msun) default: 100.
Mc, sigmafloat: Fitting parameters default: Mc=30.0, sigma=0.3
paramdict: Allows to pass in above parameters as dict. e.g. param = dict(m_min=10., m_max=100., Mc=30.0, sigma=0.3)

Returns:

mass_1_sourcenumpy.ndarray (1D array of floats): Array of mass1 in source frame (Msun)
mass_2_sourcenumpy.ndarray (1D array of floats): Array of mass2 in source frame (Msun)

binary_masses_BNS_gwcosmo(size, mminns=1.0, mmaxns=3.0, alphans=0.0, get_attribute=False, param=None)[source]

Function to calculate source mass1 and mass2 of BNS from powerlaw distribution (gwcosmo)

Parameters:

sizeint: Number of samples to draw
mminnsfloat: Minimum mass of the BNS (Msun) default: 1.0
mmaxnsfloat: Maximum mass of the BNS (Msun) default: 3.0
alphansfloat: Power law index default: 0.0

Returns:

mass_1_sourcenumpy.ndarray (1D array of floats): Array of mass1 in source frame (Msun)
mass_2_sourcenumpy.ndarray (1D array of floats): Array of mass2 in source frame (Msun)

Examples

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

binary_masses_NSBH_broken_powerlaw(size, mminbh=26, mmaxbh=125, alpha_1=6.75, alpha_2=6.75, b=0.5, delta_m=5, mminns=1.0, mmaxns=3.0, alphans=0.0, get_attribute=False, param=None)[source]

Function to calculate source mass1 and mass2 of NSBH from powerlaw distribution (gwcosmo). Parameters are mminbh=26,mmaxbh=125,alpha_1=6.75,alpha_2=6.75,b=0.5,delta_m=5,mminns=1.0,mmaxns=3.0,alphans=0.0.

Parameters:

sizeint: Number of samples to draw
mminbhfloat: Minimum mass of the black hole (Msun) default: 26
mmaxbhfloat: Maximum mass of the black hole (Msun) default: 125
alpha_1float: Power law index for the primary mass distribution default: 6.75
alpha_2float: Power law index for the secondary mass distribution default: 6.75
bfloat: Break point of the power law default: 0.5
delta_mfloat: Range of mass tapering on default: 5
mminnsfloat: Minimum mass of the neutron star (Msun) default: 1.0
mmaxnsfloat: Maximum mass of the neutron star (Msun) default: 3.0
alphansfloat: Power law index for the neutron star mass distribution default: 0.0
get_attributebool: If True, return a sampler function with size as the only input where parameters are fixed to the given values.
paramdict: Allows to pass in above parameters as dict.

Returns:

mass_1_sourcenumpy.ndarray (1D array of floats): Array of mass1 in source frame (Msun)
mass_2_sourcenumpy.ndarray (1D array of floats): Array of mass2 in source frame (Msun)

Examples

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

binary_masses_uniform(size, m_min=1.0, m_max=3.0, get_attribute=False, param=None)[source]

Function to sample source mass1 and mass2 from uniform distribution.

Parameters:

sizeint: Number of samples to draw
m_minfloat: Minimum mass of the BNS default: 1.0
m_maxfloat: Maximum mass of the BNS default: 3.0
get_attributebool: If True, return a sampler function with size as the only input where parameters are fixed to the given values.
paramdict: Allows to pass in above parameters as dict. e.g. param = dict(m_min=1.0, m_max=3.0)

Returns:

mass_1_sourcenumpy.ndarray (1D array of floats): Array of mass1 in source frame (Msun)
mass_2_sourcenumpy.ndarray (1D array of floats): Array of mass2 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, w=0.643, muL=1.352, sigmaL=0.08, muR=1.88, sigmaR=0.3, mmin=1.0, mmax=2.3, resolution=500, create_new=False, get_attribute=False, param=None)[source]

Function to sample source mass1 and mass2 from bimodal distribution. Refer to Will M. Farr et al. 2020 Eqn. 6, https://arxiv.org/pdf/2005.00032.pdf .

Parameters:

sizeint: Number of samples to draw
wfloat: Weight of the left peak default: 0.643
muLfloat: Mean of the left peak default: 1.352
sigmaLfloat: Width of the left peak default: 0.08
muRfloat: Mean of the right peak default: 1.88
sigmaRfloat: Width of the right peak default: 0.3
mminfloat: Minimum mass of the BNS default: 1.0
mmaxfloat: Maximum mass of the BNS default: 2.3
resolutionint: Number of points to sample default: 500
create_newbool: If True, create new interpolator default: False
get_attributebool: If True, return a sampler function with size as the only input where parameters are fixed to the given values.
paramdict: Allows to pass in above parameters as dict. e.g. param = dict(w=0.643, muL=1.352, sigmaL=0.08, muR=1.88, sigmaR=0.3, mmin=1.0, mmax=2.3, resolution=500)

Returns:

mass_1_sourcenumpy.ndarray (1D array of floats): Array of mass1 in source frame (Msun)
mass_2_sourcenumpy.ndarray (1D array of floats): Array of mass2 in source frame (Msun)

Examples

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

constant_values_n_size(size=100, value=0.0, get_attribute=False, param=None)[source]

Function to sample constant values of size n.

Parameters:

sizeint: Number of samples to draw
valuefloat: Constant value default: 0.0
get_attributebool: If True, return the njitted sampler function with size as the only input where parameters are fixed to the given values.
paramdict: Allows to pass in above parameters as dict. e.g. param = dict(value=0.0)

Returns:

valuesnumpy.ndarray (1D array of floats): Array of constant values

Examples

>>> from ler.gw_source_population import CBCSourceParameterDistribution
>>> cbc = CBCSourceParameterDistribution()
>>> value = cbc.constant_values_n_size(size=1000)

sampler_uniform(size, min_=0, max_=np.pi, get_attribute=False, param=None)[source]

Function to sample values from uniform distribution.

Parameters:

sizeint: Number of samples to draw
start_timefloat: Start time of the uniform distribution default: 1238166018
end_timefloat: End time of the uniform distribution default: 1238166018 + 31536000
get_attributebool: If True, return the njitted sampler function with size as the only input where parameters are fixed to the given values.
paramdict: Allows to pass in above parameters as dict.

Returns:

valuesnumpy.ndarray (1D array of floats): Array of uniformly distributed values in the range of [min_, max_]

Examples

>>> from ler.gw_source_population import CBCSourceParameterDistribution
>>> cbc = CBCSourceParameterDistribution()
>>> value = cbc.sampler_uniform(size=1000)

sampler_cosine(size, get_attribute=False, param=None)[source]

Function to sample from sine distribution at the limit of [-np.pi/2, np.pi/2]

Parameters:

sizeint: Number of samples to draw
get_attributebool: If True, return the njitted sampler function with size as the only input where parameters are fixed to the given values.
paramNone: This parameter is not used. It is only here to make the function signature consistent with other samplers.

Returns:

sinenumpy.ndarray (1D array of floats): Array of values in the range of [-np.pi/2, np.pi/2]

sampler_sine(size, get_attribute=False, param=None)[source]

Function to sample from sine distribution at the limit of [0, np.pi]

Parameters:

sizeint: Number of samples to draw
get_attributebool: If True, return the njitted sampler function with size as the only input where parameters are fixed to the given values.
paramNone: This parameter is not used. It is only here to make the function signature consistent with other samplers.

Returns:

sinenumpy.ndarray (1D array of floats): Array of values in the range of [0, np.pi]

source_priors_categorization(event_type, source_priors, event_prior_params)[source]

Function to categorize the event priors and its parameters.

Parameters:

event_typestr: Type of event to generate. e.g. ‘BBH’, ‘BNS’, ‘BBH_popIII’, ‘BBH_primordial’, ‘NSBH’
source_priorsdict: Dictionary of prior sampler functions for each parameter
event_prior_paramsdict: Dictionary of sampler parameters for each GW parameter

Returns:

source_priors_dict: Dictionary of prior sampler functions for each parameter
event_prior_params_dict: Dictionary of sampler parameters for each parameter
sampler_names_dict: Dictionary of sampler names with description

Examples

>>> from ler.gw_source_population import CBCSourceParameterDistribution
>>> cbc = CBCSourceParameterDistribution()
>>> source_priors, event_prior_params, sampler_names = cbc.source_priors_categorization(event_type='BBH', source_priors=None, event_prior_params=None)
>>> print(source_priors.keys())
>>> print(event_prior_params.keys())
>>> print(sampler_names.keys())

ler.rates.load_json(file_name)[source]

Load a json file.

Parameters:

file_namestr: json file name for storing the parameters.

Returns:

paramdict

ler.rates.append_json(file_name, new_dictionary, old_dictionary=None, replace=False)[source]

Append and update a json file with a dictionary.

Parameters:

file_namestr: json file name for storing the parameters.
new_dictionarydict: dictionary to be appended to the json file.
replacebool, optional: If True, replace the json file with the dictionary. Default is False.

ler.rates.get_param_from_json(json_file)[source]

Function to get the parameters from json file.

Parameters:

json_filestr: json file name for storing the parameters.

Returns:

paramdict

ler.rates.batch_handler(size, batch_size, sampling_routine, output_jsonfile, save_batch=True, resume=False)[source]

Function to run the sampling in batches.

Parameters:

sizeint: number of samples.
batch_sizeint: batch size.
sampling_routinefunction: function to sample the parameters. e.g. unlensed_sampling_routine() or lensed_sampling_routine()
output_jsonfilestr: name of the json file to store the parameters.
resumebool: if True, it will resume the sampling from the last batch. default resume = False.

class ler.rates.GWRATES(npool=int(4), z_min=0.0, z_max=10.0, event_type='BBH', size=100000, batch_size=50000, cosmology=None, snr_finder=None, pdet_finder=None, list_of_detectors=None, json_file_names=None, interpolator_directory='./interpolator_pickle', ler_directory='./ler_data', verbose=True, **kwargs)[source]

Bases: ler.gw_source_population.CBCSourceParameterDistribution

Class to calculate both the rates of lensed and gw events. Please note that parameters of the simulated events are stored in json file but not as an attribute of the class. This saves RAM memory.

Parameters:

npoolint: number of cores to use. default npool = 4.
z_minfloat: minimum redshift. default z_min = 0. for popI_II, popIII, primordial, BNS z_min = 0., 5., 5., 0. respectively.
z_maxfloat: maximum redshift. default z_max = 10. for popI_II, popIII, primordial, BNS z_max = 10., 40., 40., 2. respectively.
sizeint: number of samples for sampling. default size = 100000.
batch_sizeint: batch size for SNR calculation. default batch_size = 25000. reduce the batch size if you are getting memory error. recommended batch_size = 50000, if size = 1000000.
snr_finderstr: default snr_finder = ‘gwsnr’. if ‘gwsnr’, the SNR will be calculated using the gwsnr package. if ‘custom’, the SNR will be calculated using a custom function. The custom function should have input and output as given in GWSNR.snr method.
json_file_names: `dict`: names of the json files to strore the necessary parameters. default json_file_names = {‘ler_param’: ‘LeR_params.json’, ‘gw_param’: ‘gw_param.json’, ‘gw_param_detectable’: ‘gw_param_detectable.json’}.
kwargskeyword arguments: Note : kwargs takes input for initializing the CBCSourceParameterDistribution, gwsnr_intialization().

Examples

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

Instance Attributes

LeR class has the following attributes,

Atrributes	Type
`npool`	int
`z_min`	float
`z_max`	float
`event_type`	str
`cosmo`	astropy.cosmology
`size`	int
`batch_size`	int
`json_file_names`	dict
`directory`	str
`gw_param_sampler_dict`	dict
`snr_calculator_dict`	dict
`gw_param`	dict
`gw_param_detectable`	dict

Instance Methods

LeR class has the following methods,

property snr

Function to get the snr with the given parameters.

Parameters:

gw_param_dictdict

dictionary of GW source parameters. mass_1 : numpy.ndarray or float

mass_1 of the compact binary (detector frame) (Msun).

mass_2numpy.ndarray or float: mass_2 of the compact binary (detector frame) (Msun).
luminosity_distancenumpy.ndarray or float: luminosity distance of the source (Mpc).
theta_jnnumpy.ndarray or float: inclination angle of the source (rad).
psinumpy.ndarray or float: polarization angle of the source (rad).
phasenumpy.ndarray or float: phase of GW at reference frequency (rad).
geocent_timenumpy.ndarray or float: GPS time of coalescence (s).
ranumpy.ndarray or float: right ascension of the source (rad).
decnumpy.ndarray or float: declination of the source (rad).
a_1numpy.ndarray or float: dimensionless spin magnitude of the more massive object.
a_2numpy.ndarray or float: dimensionless spin magnitude of the less massive object.
tilt_1numpy.ndarray or float: tilt angle of the more massive object spin.
tilt_2numpy.ndarray or float: tilt angle of the less massive object spin.
phi_12numpy.ndarray or float: azimuthal angle between the two spin vectors.
phi_jlnumpy.ndarray or float: azimuthal angle between total angular momentum and the orbital angular momentum.

Returns:

optimal_snr_listlist

e.g. [optimal_snr_net, ‘L1’, ‘H1’, ‘V1’] optimal_snr_net : numpy.ndarray or float

optimal snr of the network.

‘H1’numpy.ndarray or float: optimal snr of H1.
‘L1’numpy.ndarray or float: optimal snr of L1.
‘V1’numpy.ndarray or float: optimal snr of V1.

property gw_param

Function to get data from the json file self.json_file_names[“gw_param”].

Returns:

gw_paramdict: dictionary of gw GW source parameters.

property gw_param_detectable

Function to get data from the json file self.json_file_names[“gw_param_detectable”].

Returns:

gw_param_detectabledict: dictionary of gw GW source parameters.

z_min

float

Minimum redshift of the source population

z_max

float

Maximum redshift of the source population

event_type

str

Type of event to generate.

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

cosmo

astropy.cosmology

Cosmology to use for the calculation.

size

int

Number of samples for sampling.

batch_size

int

Batch size for sampling.

json_file_names

dict

Names of the json files to strore the necessary parameters.

directory

str

Directory to store the interpolators.

gw_param_sampler_dict

dict

Dictionary of parameters to initialize the CBCSourceParameterDistribution class.

snr_calculator_dict

dict

Dictionary of parameters to initialize the GWSNR class.

print_all_params()[source]: Function to print all the parameters.

class_initialization(params=None)[source]

Function to initialize the parent classes. List of relevant initialized instances,

self.sample_source_redshift
self.sample_gw_parameters
self.normalization_pdf_z

Parameters:

paramsdict: dictionary of parameters to initialize the parent classes

gwsnr_intialization(params=None)[source]

Function to initialize the gwsnr class

Parameters:

paramsdict: dictionary of parameters to initialize the gwsnr class

store_gwrates_params(output_jsonfile='gwrates_params.json')[source]

Function to store the all the necessary parameters. This is useful for reproducing the results. All the parameters stored are in string format to make it json compatible.

Parameters:

output_jsonfilestr: name of the json file to store the parameters

gw_cbc_statistics(size=None, resume=False, save_batch=False, output_jsonfile=None)[source]

Function to generate gw GW source parameters. This function also stores the parameters in json file.

Parameters:

sizeint: number of samples. default size = 100000.
resumebool: resume = False (default) or True. if True, the function will resume from the last batch.
save_batchbool: if True, the function will save the parameters in batches. if False, the function will save all the parameters at the end of sampling. save_batch=False is faster.
output_jsonfilestr: json file name for storing the parameters. default output_jsonfile = ‘gw_params.json’.

Returns:

gw_paramdict: dictionary of gw GW source parameters. gw_param.keys() = [‘zs’, ‘geocent_time’, ‘ra’, ‘dec’, ‘phase’, ‘psi’, ‘theta_jn’, ‘luminosity_distance’, ‘mass_1_source’, ‘mass_2_source’, ‘mass_1’, ‘mass_2’, ‘optimal_snr_net’, ‘L1’, ‘H1’, ‘V1’]

Examples

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

gw_sampling_routine(size, output_jsonfile, resume=False, save_batch=True)[source]

Function to generate gw GW source parameters. This function also stores the parameters in json file.

Parameters:

sizeint: number of samples. default size = 100000.
resumebool: resume = False (default) or True. if True, the function will resume from the last batch.
output_jsonfilestr: json file name for storing the parameters. default output_jsonfile = ‘gw_params.json’.

Returns:

gw_paramdict: dictionary of gw GW source parameters. gw_param.keys() = [‘zs’, ‘geocent_time’, ‘ra’, ‘dec’, ‘phase’, ‘psi’, ‘theta_jn’, ‘luminosity_distance’, ‘mass_1_source’, ‘mass_2_source’, ‘mass_1’, ‘mass_2’, ‘optimal_snr_net’, ‘L1’, ‘H1’, ‘V1’]

gw_rate(gw_param=None, snr_threshold=8.0, output_jsonfile=None, detectability_condition='step_function', snr_recalculation=False, threshold_snr_recalculation=6.0)[source]

Function to calculate the gw rate. This function also stores the parameters of the detectable events in json file.

Parameters:

gw_paramdict or str: dictionary of GW source parameters or json file name. default gw_param = self.json_file_names[“gw_param”]
snr_thresholdfloat: threshold for detection signal to noise ratio. e.g. snr_threshold = 8.
output_jsonfilestr: json file name for storing the parameters of the detectable events. default output_jsonfile = ‘gw_params_detectable.json’.
detectability_conditionstr: detectability condition. default detectability_condition = ‘step_function’. other options are ‘pdet’.
snr_recalculationbool: if True, the SNR of centain events (snr>threshold_snr_recalculation)will be recalculate with ‘inner product’. This is useful when the snr is calculated with ‘ann’ method. default snr_recalculation = False.
threshold_snr_recalculationfloat: threshold for recalculation of detection signal to noise ratio.

Returns:

total_ratefloat: total gw rate (Mpc^-3 yr^-1).
gw_paramdict: dictionary of gw GW source parameters of the detectable events. gw_param.keys() = [‘zs’, ‘geocent_time’, ‘ra’, ‘dec’, ‘phase’, ‘psi’, ‘theta_jn’, ‘luminosity_distance’, ‘mass_1_source’, ‘mass_2_source’, ‘mass_1’, ‘mass_2’, ‘optimal_snr_net’, ‘L1’, ‘H1’, ‘V1’]

Examples

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

selecting_n_gw_detectable_events(size=100, batch_size=None, snr_threshold=8.0, resume=False, output_jsonfile='gw_params_n_detectable.json', meta_data_file='meta_gw.json', trim_to_size=True)[source]

Function to select n gw detectable events.

Parameters:

sizeint: number of samples to be selected. default size = 100.
snr_thresholdfloat: threshold for detection signal to noise ratio. e.g. snr_threshold = 8.
resumebool: if True, it will resume the sampling from the last batch. default resume = False.
output_jsonfilestr: json file name for storing the parameters. default output_jsonfile = ‘gw_params_detectable.json’.

Returns:

param_finaldict: dictionary of gw GW source parameters of the detectable events. param_final.keys() = [‘zs’, ‘geocent_time’, ‘ra’, ‘dec’, ‘phase’, ‘psi’, ‘theta_jn’, ‘luminosity_distance’, ‘mass_1_source’, ‘mass_2_source’, ‘mass_1’, ‘mass_2’, ‘optimal_snr_net’, ‘L1’, ‘H1’, ‘V1’]

Examples

>>> from ler.rates import GWRATES
>>> ler = GWRATES()
>>> param_final = ler.selecting_n_gw_detectable_events(size=500)

ler.rates

Submodules

Package Contents

Classes

Functions

Instance Attributes

Instance Methods

Instance Attributes

Instance Methods

Instance Attributes

Instance Methods

Instance Attributes

Instance Methods

`ler.rates`