ler.lens_galaxy_population.lens_galaxy_parameter_distribution

Module for lens galaxy parameter distributions.

This module contains the LensGalaxyParameterDistribution class which samples lens galaxy parameters and source parameters conditioned on the source being strongly lensed. It handles the distribution of lens parameters such as velocity dispersion, axis ratio, rotation angle, shear, and density profile slope.

Inheritance hierarchy:

• CBCSourceParameterDistribution

• ImageProperties

• OpticalDepth

Usage:

Basic workflow example:

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

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

Module Contents

Classes

LensGalaxyParameterDistribution

Sample lens galaxy parameters conditioned on strong lensing.

class ler.lens_galaxy_population.lens_galaxy_parameter_distribution.LensGalaxyParameterDistribution(npool=4, z_min=0.0, z_max=10.0, cosmology=None, event_type='BBH', lens_type='epl_shear_galaxy', lens_functions=None, lens_functions_params=None, lens_param_samplers=None, lens_param_samplers_params=None, directory='./interpolator_json', create_new_interpolator=False, buffer_size=1000, **kwargs)

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

Sample lens galaxy parameters conditioned on strong lensing.

This class handles the distribution of lens galaxy parameters such as velocity dispersion, axis ratio, axis rotation angle, shear, and density profile slope. It samples source parameters conditioned on the source being strongly lensed using cross-section based rejection or importance sampling.

Key Features:

• Samples lens parameters using EPL+shear galaxy model

• Supports rejection and importance sampling based on cross-section

• Computes optical depth weighted source redshift distributions

• Integrates with GW source population and image property calculations

Parameters:

npoolint

Number of processors to use for parallel sampling.

default: 4

z_minfloat

Minimum redshift for source and lens populations.

default: 0.0

z_maxfloat

Maximum redshift for source and lens populations.

default: 10.0

cosmologyastropy.cosmology or None

Cosmology object for distance calculations.

default: None (uses FlatLambdaCDM with H0=70, Om0=0.3)

event_typestr

Type of compact binary coalescence event.

Options:

• ‘BBH’: Binary black hole

• ‘BNS’: Binary neutron star

• ‘NSBH’: Neutron star-black hole

default: ‘BBH’

lens_typestr

Type of lens galaxy model to use.

default: ‘epl_shear_galaxy’

lens_functionsdict or None

Dictionary specifying lens-related functions.

default: None (uses defaults from OpticalDepth)

lens_functions_paramsdict or None

Parameters for lens functions.

default: None

lens_param_samplersdict or None

Dictionary specifying lens parameter sampling functions.

default: None (uses defaults from OpticalDepth)

lens_param_samplers_paramsdict or None

Parameters for lens parameter samplers.

default: None

directorystr

Directory for storing interpolator files.

default: ‘./interpolator_json’

create_new_interpolatorbool

If True, recreates interpolators even if files exist.

default: False

buffer_sizeint

Buffer size for batch sampling of lens parameters.

default: 1000

**kwargsdict

Additional keyword arguments passed to parent classes:

CBCSourceParameterDistribution,

ImageProperties,

OpticalDepth.

Examples

Basic usage:

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

Instance Methods

LensGalaxyParameterDistribution has the following methods:

Instance Attributes

LensGalaxyParameterDistribution has the following attributes:

Attribute	Type	Unit	Description
npool	int		Number of processors for parallel computation
z_min	float		Minimum redshift
z_max	float		Maximum redshift
cosmo	astropy.cosmology		Cosmology object for calculations
event_type	str		Type of CBC event (BBH, BNS, NSBH)
directory	str		Path to interpolator storage directory
lens_param_samplers	dict		Dictionary of lens parameter sampler names
lens_param_samplers_params	dict		Parameters for lens parameter samplers
lens_functions	dict		Dictionary of lens function names
normalization_pdf_z_lensed	float		Normalization constant for lensed source z pdf

property source_redshift_sl

Function to sample source redshifts conditioned on strong lensing.

Returns:

source_redshift_sller.functions.FunctionConditioning

Function for sampling source redshifts conditioned on strong lensing.

property normalization_pdf_z_lensed

Normalization constant for the lensed source redshift pdf.

This constant is used to normalize the probability distribution

of source redshifts conditioned on strong lensing. It is computed

by integrating the merger rate density times optical depth.

Returns:

normalization_pdf_z_lensedfloat

Normalization constant for lensed redshift distribution.

property lens_param_samplers

Dictionary of lens parameter sampler function names.

Returns:

lens_param_samplersdict

Dictionary mapping parameter names to sampler function names.

Keys include: ‘source_redshift_sl’, ‘lens_redshift’,

‘velocity_dispersion’, ‘axis_ratio’, ‘axis_rotation_angle’,

‘external_shear’, ‘density_profile_slope’.

property lens_param_samplers_params

Dictionary of parameters for lens parameter samplers.

Returns:

lens_param_samplers_paramsdict

Dictionary with sampler parameters.

Each key corresponds to a sampler in lens_param_samplers.

property lens_functions

Dictionary of lens-related function names.

Returns:

lens_functionsdict

Dictionary mapping function types to function names.

Keys include: ‘param_sampler_type’, ‘cross_section_based_sampler’,

‘optical_depth’, ‘cross_section’.

event_type = "'BBH'"

str

Type of event to generate.

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

sample_lens_parameters_routine

cross_section_based_sampler

sample_lens_parameters(size=1000)

Sample lens galaxy and source parameters conditioned on strong lensing.

This method samples both lens galaxy parameters (velocity dispersion, axis ratio, shear, etc.) and gravitational wave source parameters, with the source redshift distribution weighted by strong lensing optical depth.

Parameters:

sizeint

Number of lens-source parameter sets to sample.

default: 1000

Returns:

lens_parametersdict

Dictionary containing sampled lens and source parameters.

The included parameters and their units are as follows (for default settings):

Examples

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

sample_all_routine_epl_shear_sl(size=1000)

Sample EPL+shear galaxy lens parameters with strong lensing condition.

Parameters:

sizeint

Number of lens parameters to sample.

default: 1000

Returns:

lens_parametersdict

Dictionary of sampled lens parameters.

The included parameters and their units are as follows (for default settings):

Parameter	Units	Description
zl		redshift of the lens
zs		redshift of the source
sigma	km s^-1	velocity dispersion
q		axis ratio
theta_E	radian	Einstein radius
phi	rad	axis rotation angle. counter-clockwise from the positive x-axis (RA-like axis) to the major axis of the projected mass distribution.
gamma		density profile slope of EPL galaxy
gamma1		external shear component in the x-direction (RA-like axis)
gamma2		external shear component in the y-direction (Dec-like axis)

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

Sample source redshifts conditioned on strong lensing.

Parameters:

sizeint

Number of samples to generate.

default: 1000

get_attributebool

If True, returns the sampler object instead of samples.

default: False

**kwargsdict

Additional parameters

Returns:

redshiftsnumpy.ndarray

Array of source redshifts conditioned on strong lensing.

Examples

>>> from ler.lens_galaxy_population import LensGalaxyParameterDistribution
>>> lens = LensGalaxyParameterDistribution()
>>> zs = lens.strongly_lensed_source_redshift(size=1000)
>>> print(f"strongly lensed source redshift: {zs.mean():.2f}")

sample_all_routine_epl_shear_intrinsic(size=1000)

Sample EPL+shear galaxy lens parameters from intrinsic distributions.

Samples lens parameters from their intrinsic distributions without applying strong lensing cross-section weighting.

Parameters:

sizeint

Number of lens parameters to sample.

default: 1000

Returns:

lens_parametersdict

Dictionary of sampled lens parameters.

The included parameters and their units are as follows (for default settings):

Parameter	Units	Description
zl		redshift of the lens
zs		redshift of the source
sigma	km s^-1	velocity dispersion
q		axis ratio
theta_E	radian	Einstein radius
phi	rad	axis rotation angle. counter-clockwise from the positive x-axis (RA-like axis) to the major axis of the projected mass distribution.
gamma		density profile slope of EPL galaxy
gamma1		external shear component in the x-direction (RA-like axis)
gamma2		external shear component in the y-direction (Dec-like axis)