ler.image_properties

Submodules

• ler.image_properties.image_properties
• ler.image_properties.multiprocessing_routine

Package Contents

Classes

ImageProperties

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

Functions

solve_lens_equation(lens_parameters)	Solve the lens equation to find image properties.
phi_q2_ellipticity(phi, q)	Convert position angle and axis ratio to ellipticity components.
solve_lens_equation(lens_parameters)	Solve the lens equation to find image properties.

Attributes

cosmo
MAX_RETRIES
MIN_MAGNIFICATION

ler.image_properties.cosmo

ler.image_properties.solve_lens_equation(lens_parameters)

Solve the lens equation to find image properties.

Uses the analytical solver from lenstronomy to find image positions, magnifications, time delays, and hessian properties for strongly lensed sources. Source positions are sampled from within the caustic region to ensure multiple imaging.

Parameters:

lens_parametersnumpy.ndarray

Array of lens configuration parameters with the following structure:

• [0]: n_min_images - minimum number of images required

• [1]: e1 - ellipticity component 1

• [2]: e2 - ellipticity component 2

• [3]: gamma - power-law slope of mass density

• [4]: gamma1 - external shear component 1

• [5]: gamma2 - external shear component 2

• [6]: zl - lens redshift

• [7]: zs - source redshift

• [8]: einstein_radius - Einstein radius (units: radians)

• [9]: iteration - iteration index for tracking

• [10:]: lens_model_list - lens model names (e.g., ‘EPL_NUMBA’, ‘SHEAR’)

Returns:

x_sourcefloat

Source x-position (units: radians).

y_sourcefloat

Source y-position (units: radians).

x0_image_positionnumpy.ndarray

Image x-positions (units: radians).

x1_image_positionnumpy.ndarray

Image y-positions (units: radians).

magnificationsnumpy.ndarray

Magnification factors for each image.

time_delaysnumpy.ndarray

Time delays for each image (units: seconds).

nImagesint

Number of images formed.

determinantnumpy.ndarray

Determinant of the lensing Jacobian for each image.

tracenumpy.ndarray

Trace of the lensing Jacobian for each image.

iterationint

Iteration index passed through for tracking.

Examples

>>> from ler.image_properties.multiprocessing_routine import solve_lens_equation
>>> import numpy as np
>>> from multiprocessing import Pool
>>> lens_parameters1 = np.array([2, 0.024, -0.016, 1.89, 0.10, 0.09, 0.25, 0.94, 2.5e-06, 0, 'EPL_NUMBA', 'SHEAR'], dtype=object)
>>> lens_parameters2 = np.array([2, -0.040, -0.014, 2.00, 0.08, -0.01, 1.09, 2.55, 1.0e-06, 1, 'EPL_NUMBA', 'SHEAR'], dtype=object)
>>> input_arguments = np.vstack((lens_parameters1, lens_parameters2))
>>> with Pool(2) as p:
...     result = p.map(solve_lens_equation, input_arguments)
>>> print(f"Number of images: {result[0][6]}")

ler.image_properties.phi_q2_ellipticity(phi, q)

Convert position angle and axis ratio to ellipticity components.

Parameters:

phinumpy.ndarray

Position angle of the major axis (radians).

qnumpy.ndarray

Axis ratio (0 < q <= 1).

Returns:

e1numpy.ndarray

First ellipticity component.

e2numpy.ndarray

Second ellipticity component.

class ler.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) | +----------------------------------+-----------+------------------------------------------------+

ler.image_properties.MAX_RETRIES = '100'

ler.image_properties.MIN_MAGNIFICATION = '0.01'

ler.image_properties.solve_lens_equation(lens_parameters)

Solve the lens equation to find image properties.

Uses the analytical solver from lenstronomy to find image positions, magnifications, time delays, and hessian properties for strongly lensed sources. Source positions are sampled from within the caustic region to ensure multiple imaging.

Parameters:

lens_parametersnumpy.ndarray

Array of lens configuration parameters with the following structure:

• [0]: n_min_images - minimum number of images required

• [1]: e1 - ellipticity component 1

• [2]: e2 - ellipticity component 2

• [3]: gamma - power-law slope of mass density

• [4]: gamma1 - external shear component 1

• [5]: gamma2 - external shear component 2

• [6]: zl - lens redshift

• [7]: zs - source redshift

• [8]: einstein_radius - Einstein radius (units: radians)

• [9]: iteration - iteration index for tracking

• [10:]: lens_model_list - lens model names (e.g., ‘EPL_NUMBA’, ‘SHEAR’)

Returns:

x_sourcefloat

Source x-position (units: radians).

y_sourcefloat

Source y-position (units: radians).

x0_image_positionnumpy.ndarray

Image x-positions (units: radians).

x1_image_positionnumpy.ndarray

Image y-positions (units: radians).

magnificationsnumpy.ndarray

Magnification factors for each image.

time_delaysnumpy.ndarray

Time delays for each image (units: seconds).

nImagesint

Number of images formed.

determinantnumpy.ndarray

Determinant of the lensing Jacobian for each image.

tracenumpy.ndarray

Trace of the lensing Jacobian for each image.

iterationint

Iteration index passed through for tracking.

Examples

>>> from ler.image_properties.multiprocessing_routine import solve_lens_equation
>>> import numpy as np
>>> from multiprocessing import Pool
>>> lens_parameters1 = np.array([2, 0.024, -0.016, 1.89, 0.10, 0.09, 0.25, 0.94, 2.5e-06, 0, 'EPL_NUMBA', 'SHEAR'], dtype=object)
>>> lens_parameters2 = np.array([2, -0.040, -0.014, 2.00, 0.08, -0.01, 1.09, 2.55, 1.0e-06, 1, 'EPL_NUMBA', 'SHEAR'], dtype=object)
>>> input_arguments = np.vstack((lens_parameters1, lens_parameters2))
>>> with Pool(2) as p:
...     result = p.map(solve_lens_equation, input_arguments)
>>> print(f"Number of images: {result[0][6]}")