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_priors=None, lens_priors_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_priorsdict or None

Dictionary specifying lens parameter sampling functions.

default: None (uses defaults from OpticalDepth)

lens_priors_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())

property zs_sl

Function to sample source redshifts conditioned on strong lensing.

Returns:

zs_slFunctionConditioning

Sampler object for strongly-lensed source redshift.

property cross_section_based_sampler

Cross-section based lens parameter sampler function. This is an initialized function of sampler_functions.create_importance_sampler or sampler_functions.create_rejection_sampler based on the configuration.

This function samples lens parameters weighted by the strong lensing cross-section.

Parameters:

sizeint

Number of strongly-lensed parameter sets to sample.

Returns:

zsnumpy.ndarray

Array of source redshifts.

zlnumpy.ndarray

Array of lens redshifts.

sigmanumpy.ndarray

Array of velocity dispersions.

qnumpy.ndarray

Array of axis ratios.

phinumpy.ndarray

Array of axis rotation angles.

gammanumpy.ndarray

Array of density profile slopes.

gamma1numpy.ndarray

Array of external shear components in the x-direction.

gamma2numpy.ndarray

Array of external shear components in the y-direction.

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_priors

Dictionary of lens parameter sampler function names.

Returns:

lens_priorsdict

Dictionary mapping parameter names to sampler function names.

Keys include: ‘zs_sl’, ‘lens_redshift’,

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

‘external_shear1’, ‘external_shear2’, ‘density_profile_slope’.

property lens_priors_params

Dictionary of parameters for lens parameter samplers.

Returns:

lens_priors_paramsdict

Dictionary with sampler parameters.

Each key corresponds to a sampler in lens_priors.

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’.

sample_lens_parameters_routine

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):

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)
geocent_time	s	geocent time
ra	rad	right ascension
dec	rad	declination
phase	rad	phase of GW at reference freq
psi	rad	polarization angle
theta_jn	rad	inclination angle
a_1		spin of the primary compact binary
a_2		spin of the secondary compact binary
luminosity_distance	Mpc	luminosity distance of the source
mass_1_source	Msun	mass of the primary compact binary (source frame)
mass_2_source	Msun	mass of the secondary compact binary (source frame)
mass_1	Msun	mass of the primary compact binary (detector frame)
mass_2	Msun	mass of the secondary compact binary (detector frame)

Examples

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

epl_shear_sl_parameters_rvs(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)

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)

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 or ler.utils.FunctionConditioning

Array of source redshifts conditioned on strong lensing, or the sampler object.

Notes

This sampler needs a merger-rate-weighted intrinsic source redshift model via self.merger_rate_density_based_source_redshift. That attribute is provided by CBCSourceParameterDistribution and therefore is available in LensGalaxyParameterDistribution (which inherits both).

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}")