ler.image_properties.image_properties

Module for computing image properties of strongly lensed gravitational wave events.

This module contains the ImageProperties class, which computes image positions, magnifications, time delays, and other lensing-related quantities for gravitational wave sources that are strongly lensed by intervening galaxies. The class uses multiprocessing to efficiently solve lens equations for large samples.

Usage:

Basic workflow example:

>>> from ler.image_properties import ImageProperties
>>> ip = ImageProperties()
>>> lens_parameters = dict(zs=np.array([2.0]), zl=np.array([0.5]), ...)
>>> result = ip.image_properties(lens_parameters)

Copyright (C) 2026 Phurailatpam Hemanta Kumar. Distributed under MIT License.

Module Contents

Classes

ImageProperties

Class to compute image properties of strongly lensed gravitational wave events.

Attributes

cosmo

ler.image_properties.image_properties.cosmo

class ler.image_properties.image_properties.ImageProperties(npool=4, n_min_images=2, n_max_images=4, lens_model_list=['EPL_NUMBA', 'SHEAR'], cosmology=None, time_window=365 * 24 * 3600 * 2, spin_zero=True, spin_precession=False, pdet_finder=None, effective_params_in_output=True)

Class to compute image properties of strongly lensed gravitational wave events.

This class solves the lens equation to find image positions, magnifications, time delays, and image types (morse phase) for strongly lensed sources. It uses multiprocessing for efficient computation of large samples.

Key Features:

• Solves lens equations using multiprocessing for efficiency

• Computes image positions, magnifications, and time delays

• Classifies image types using morse phase

• Calculates detection probabilities for lensed images

Parameters:

npoolint

Number of processes for multiprocessing.

default: 4

n_min_imagesint

Minimum number of images required for a valid lensing event.

default: 2

n_max_imagesint

Maximum number of images to consider per event.

default: 4

time_windowfloat

Time window for lensed events from min(geocent_time) (units: seconds).

default: 365*24*3600*2 (2 years)

effective_params_in_outputbool

Whether to include effective parameters (effective_phase, effective_ra, effective_dec) in the output.

default: True

lens_model_listlist

List of lens models to use.

default: [‘EPL_NUMBA’, ‘SHEAR’]

cosmologyastropy.cosmology or None

Cosmology for distance calculations.

If None, uses default LambdaCDM.

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

spin_zerobool

If True, spin parameters are set to zero (no spin sampling).

default: False

spin_precessionbool

If True (and spin_zero=False), sample precessing spin parameters.

If False (and spin_zero=False), sample aligned/anti-aligned spins.

default: False

Examples

Basic usage:

>>> from ler.image_properties import ImageProperties
>>> ip = ImageProperties()
>>> lens_parameters = dict(
...     zs=np.array([2.0]),
...     zl=np.array([0.5]),
...     gamma1=np.array([0.0]),
...     gamma2=np.array([0.0]),
...     phi=np.array([0.0]),
...     q=np.array([0.8]),
...     gamma=np.array([2.0]),
...     theta_E=np.array([1.0])
... )
>>> result = ip.image_properties(lens_parameters)
>>> print(result.keys())

Instance Methods

ImageProperties has the following methods:

Method	Description
image_properties()	Compute image properties for lensed events
get_lensed_snrs()	Compute detection probability for lensed images

Instance Attributes

ImageProperties has the following attributes:

Attribute	Type	Unit	Description
npool	int		Number of multiprocessing workers
n_min_images	int		Minimum number of images required
n_max_images	int		Maximum number of images per event
time_window	float	s	Time window for lensed events
effective_params_in_output	bool		To include effective parameters in output
lens_model_list	list		List of lens models
cosmo	astropy.cosmology		Cosmology for calculations
spin_zero	bool		Flag for zero spin assumption
spin_precession	bool		Flag for spin precession
pdet_finder	callable		Probability of detection calculator
pdet_finder_output_keys	list		Keys for probability of detection outputs

property npool

Number of multiprocessing workers.

Returns:

npoolint

Number of processes for multiprocessing.

default: 4

property n_min_images

Minimum number of images required for a valid lensing event.

Returns:

n_min_imagesint

Minimum number of images required.

default: 2

property n_max_images

Maximum number of images per event.

Returns:

n_max_imagesint

Maximum number of images to consider per event.

default: 4

property lens_model_list

List of lens models to use.

Returns:

lens_model_listlist

List of lens model names.

default: [‘EPL_NUMBA’, ‘SHEAR’]

property spin_zero

Flag for zero spin assumption.

Returns:

spin_zerobool

Whether to assume zero spin for compact objects.

If True, spin parameters are set to zero (no spin sampling).

If False, spin parameters are sampled.

default: False

property spin_precession

Flag for spin precession.

Returns:

spin_precessionbool

Whether to include spin precession effects.

If True (and spin_zero=False), sample precessing spin parameters.

If False (and spin_zero=False), sample aligned/anti-aligned spins.

default: False

property time_window

Time window for lensed events.

Returns:

time_windowfloat

Time window for lensed events (units: s).

default: 365*24*3600*20 (20 years)

property cosmo

Astropy cosmology object for calculations.

Returns:

cosmoastropy.cosmology

Cosmology used for distance calculations.

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

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 pdet_finder_output_keys

Output keys from the detection probability finder function.

Returns:

pdet_finder_output_keyslist

List of keys returned by the pdet_finder function.

default: None

property effective_params_in_output

Flag to include effective parameters in output.

Returns:

effective_params_in_outputbool

Whether to include effective parameters in the output of get_lensed_snrs.

default: False

image_properties(lens_parameters)

Compute image properties for strongly lensed events.

Solves the lens equation using multiprocessing to find image positions, magnifications, time delays, and image types for each lensing event.

Parameters:

lens_parametersdict

Dictionary containing lens and source parameters shown in the table:

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)

Returns:

lens_parametersdict

Updated dictionary with additional image properties with the following description:

x0_image_positions	radian	x-coordinate (RA-like axis) of the images
x1_image_positions	radian	y-coordinate (Dec-like axis) of the images
magnifications		magnifications
time_delays		time delays
image_type		image type
n_images		number of images
x_source	radian	x-coordinate (RA-like axis) of the source
y_source	radian	y-coordinate (Dec-like axis) of the source

get_lensed_snrs(lensed_param, pdet_finder=None, effective_params_in_output=False)

Compute detection probability for each lensed image.

Calculates the effective luminosity distance, geocent time, and phase for each image accounting for magnification and morse phase, then computes detection probabilities using the provided calculator.

Parameters:

lensed_paramdict

Dictionary containing lensed source and image parameters given below:

pdet_findercallable

Function that computes detection probability given GW parameters.

effective_params_in_outputbool

If True, includes effective parameters in output lensed_param.

Returns:

result_dictdict

Dictionary containing:

• ‘pdet_net’: network detection probability (shape: size x n_max_images)

• Individual detector probabilities if pdet_finder outputs them

lensed_paramdict

Updated dictionary with effective parameters shown below:

+----------------------------------+-----------+------------------------------------------------| | Parameter | Units | Description +==================================+===========+================================================+ | effective_luminosity_distance | Mpc | magnification-corrected distance | | | | luminosity_distance / sqrt(|magnifications_i|) | +----------------------------------+-----------+------------------------------------------------| | effective_geocent_time | s | time-delay-corrected GPS time | | | | geocent_time + time_delays_i | +----------------------------------+-----------+------------------------------------------------| | effective_phase | rad | morse-phase-corrected phase | | | | phi - morse_phase_i | +----------------------------------+-----------+------------------------------------------------+ | effective_ra | rad | RA of the image | | | | ra + (x0_image_positions_i - x_source)/cos(dec)| +----------------------------------+-----------+------------------------------------------------+ | effective_dec | rad | Dec of the image | | | | dec + (x1_image_positions_i - y_source) | +----------------------------------+-----------+------------------------------------------------+

produce_effective_params(lensed_param)

Produce effective parameters for each lensed image.

Calculates the effective luminosity distance, geocent time, phase, RA, and Dec for each image accounting for magnification and morse phase.

Parameters:

lensed_paramdict

Dictionary containing lensed source and image parameters.

Returns:

lensed_paramdict

Updated dictionary with effective parameters shown below:

+----------------------------------+-----------+------------------------------------------------| | Parameter | Units | Description +==================================+===========+================================================+ | effective_luminosity_distance | Mpc | magnification-corrected distance | | | | luminosity_distance / sqrt(|magnifications_i|) | +----------------------------------+-----------+------------------------------------------------| | effective_geocent_time | s | time-delay-corrected GPS time | | | | geocent_time + time_delays_i | +----------------------------------+-----------+------------------------------------------------| | effective_phase | rad | morse-phase-corrected phase | | | | phi - morse_phase_i | +----------------------------------+-----------+------------------------------------------------+ | effective_ra | rad | RA of the image | | | | ra + (x0_image_positions_i - x_source)/cos(dec)| +----------------------------------+-----------+------------------------------------------------+ | effective_dec | rad | Dec of the image | | | | dec + (x1_image_positions_i - y_source) | +----------------------------------+-----------+------------------------------------------------+