slsim.Lenses package

Submodules

slsim.Lenses.lens_pop module

class slsim.Lenses.lens_pop.LensPop(deflector_population: DeflectorsBase, source_population: SourcePopBase, cosmo: Cosmology | None = None, sky_area: float | None = None, los_pop: LOSPop | None = None, use_jax=True)

Bases: LensedPopulationBase

Class to perform samples of lens population.

property deflector_number

Number of potential deflectors (meaning all objects with mass that are being considered to have potential sources behind them)

Returns:

number of potential deflectors

draw_population(kwargs_lens_cuts, multi_source=False, speed_factor=1, verbose=False)

Return full population list of all lenses within the area.

# TODO: need to implement a version of it. (improve the algorithm)

Parameters:

• kwargs_lens_cuts (dict) – validity test keywords. dictionary of cuts that one wants to apply to the lens. eg: kwargs_lens_cut = {}”min_image_separation”: 0.5, “max_image_separation”: 10, “mag_arc_limit”: {“i”, 24}, “second_bright_image_cut = {“band”: [“i”], “mag_max”:[23]}. all these cuts are optional.

• multi_source – A boolean value. If True, considers multi source lensing. If False, considers single source lensing. The default value is True.

• speed_factor – factor by which the number of deflectors is decreased to speed up the calculations.

• verbose (bool) – If True, prints progress information. Default is False.

Returns:

List of Lens instances with parameters of the deflectors and lens and source light.

Return type:

list

get_num_sources_tested(testarea=None, num_sources_tested_mean=None)

Draw a realization of the expected distribution (Poisson) around the mean for the number of source galaxies tested.

get_num_sources_tested_mean(testarea)

Compute the mean of source galaxies needed to be tested within the test area.

num_sources_tested_mean/ testarea = num_sources/ sky_area; testarea is in units of arcsec^2, f_sky is in units of deg^2. 1 deg^2 = 12960000 arcsec^2

select_lens_at_random(test_area=None, verbose=False, **kwargs_lens_cut)

Draw a random lens within the cuts of the lens and source, with possible additional cuts in the lensing configuration.

# TODO: Make sure mass function is preserved, as well as the option to draw all lenses within the cuts within the area.

Parameters:

• test_area (float or None) – Solid angle around one lensing galaxy to be investigated on (in arc-seconds^2). If None, computed using deflector’s velocity dispersion.

• kwargs_lens_cut (dict) – Dictionary of cuts that one wants to apply to the lens. Example: kwargs_lens_cut = { “min_image_separation”: 0.5, “max_image_separation”: 10, “mag_arc_limit”: {“i”: 24}, “second_brightest_image_cut”: {“i”: 24}}. All these cuts are optional.

• verbose (bool) – print statements added

Returns:

Lens() instance with parameters of the deflector and lens and source light.

Return type:

Lens

property source_number

Number of sources that are being considered to be placed in the sky area potentially aligned behind deflectors.

Returns:

number of potential sources

slsim.Lenses.lens_pop.area_theta_e_infinity(theta_e_infinity)

Draw a test area around the deflector.

Parameters:

theta_e_infinity – Einstein radius for infinitly far away source (Dds/Ds = 1)

Returns:

test area in arcsec^2

slsim.Lenses.lens module

class slsim.Lenses.lens.Lens(source_class, deflector_class, cosmo, lens_equation_solver='lenstronomy_analytical', magnification_limit=0.01, los_class=None, use_jax=True, multi_plane=None, shear=True, convergence=True, field_galaxies=None)

Bases: LensedSystemBase

Class to manage individual lenses.

add_field_galaxies(field_galaxies)

Add field galaxies to the lens. These galaxies will be included as additional light in the lens plane, and will not be explicitly included as deflectors in the lensing calculation.

Parameters:

field_galaxies (list[slsim.Sources.source.Source] or None) – List of field galaxy instances. Instances should be generated via slsim.Sources.SourcePopulation.Galaxies.draw_field_galaxies(). If None, no field galaxies are included.

add_subhalos(pyhalos_kwargs, dm_type, source_index=0)

Generate a realization of the subhalos, halo mass.

Parameters:

• pyhalos_kwargs (dict) – dictionary of parameters for the pyhalos realization.

• dm_type (str) – type of dark matter models, can be ‘CDM’, ‘WDM’, or ‘ULDM’

• source_index (int) – index of source, default =0, i.e. the first source

contrast_ratio(band, source_index=0)

Computes the surface brightness ratio (difference in magnitude per arc second square) at image positions of the source, for the source as the average surface brightness within the half light radius, for the lens light at the position of the lensed images.

Parameters:

• source_index (int) – index of source, default =0, i.e. the first source

• band – bandpass filter

Type:

str

Returns:

surface brightness ratio for all images I_source_light/I_lens_light [mag/arcsec^2]

deflector_ellipticity()

Returns:

e1_light, e2_light, e1_mass, e2_mass

deflector_light_model_lenstronomy(band)

Returns lens model instance and parameters in lenstronomy conventions.

Parameters:

band (str) – imaging band

Returns:

lens_light_model_list, kwargs_lens_light

deflector_magnitude(band)

Apparent magnitude of the deflector for a given band.

Parameters:

band (string) – imaging band

Returns:

magnitude of deflector in given band

deflector_mass_model_lenstronomy(source_index=None)

Returns lens model instance and parameters in lenstronomy conventions.

Returns:

LensModel() class, kwargs_lens

property deflector_position

Center of the deflector position.

Returns:

[x_pox, y_pos] in arc seconds

property deflector_redshift

Returns:

lens redshift

deflector_stellar_mass()

Returns:

stellar mass of deflector

deflector_velocity_dispersion()

Returns:

velocity dispersion [km/s]

dm_subhalo_mass()

Get the halo mass of the subhalos in the realization.

Returns:

list of halo masses in the realization

property einstein_radius

Einstein radius, from SIS approximation (coming from velocity dispersion) without line-of-sight correction.

Returns:

list of einstein radius of each lens-source pair.

property einstein_radius_infinity

Einstein radius when source is at infinity.

Returns:

Einstein radius of a deflector.

property extended_source_image_positions

Returns extended source image positions by solving the lens equation for each source.

Returns:

list of (x-pos, y-pos)

property extended_source_magnification

Compute the extended lensed surface brightness and calculates the integrated flux-weighted magnification factor of each extended host galaxy .

Returns:

list of integrated magnification factor of host magnitude for each source

extended_source_magnification_for_individual_image()

Macro-model magnification of extended sources. This function calculates magnification for each extended sources at each image position.

Returns:

list of signed magnification of point sources in same order as image positions.

extended_source_magnitude(band, lensed=False)

Unlensed apparent magnitude of the extended source for a given band (assumes that size is the same for different bands). This function gives magnitude for all the provided sources.

Parameters:

• band (string) – imaging band

• lensed (bool) – if True, returns the lensed magnified magnitude

Returns:

magnitude of source in given band or list of magnitude of each source.

extended_source_magnitude_for_each_image(band, lensed=False)

Extended source magnitudes, either unlensed (single value) or lensed (array) with macro-model magnifications. This function provided magnitudes of all the sources. This function assumes that all the light of an extended source is concentrated at its center and magnifies it as a point source multiple times. For a more accurate lensed extended source magnitude, please see the extended_source_magnitude() function.

Parameters:

• band (string) – imaging band

• lensed (bool) – if True, returns the lensed magnified magnitude of each image.

Returns:

list of extended source magnitudes.

property external_convergence

Returns:

external convergence

property external_shear

Returns:

the absolute external shear

field_galaxy_light_model_lenstronomy(band)

Returns field galaxy light model instance and parameters in lenstronomy conventions.

Parameters:

band (str) – imaging band

Returns:

field_galaxy_light_model_list, kwargs_field_galaxy_light

generate_id(ra=None, dec=None)

Generate a unique ID for the lens based on its position.

Parameters:

• ra – ra coordinate of the Lens

• dec – dec coordinate of the Lens

Returns:

A string representing the lens ID.

property image_number

Number of images in the lensing configuration. If a point source is present, uses point source, otherwise extended source.

Returns:

number of images for each source model

image_observer_times(t_obs)

Calculates time of the source at the different images, not correcting for redshifts, but for time delays. The time is relative to the first arriving image.

Parameters:

t_obs – time of observation [days]. It could be a single observation time or an array of observation time.

Returns:

time of the source when seen in the different images (without redshift correction)

Return type:

list of numpy array. Each element of the array corresponds to different image observation times.

kappa_star(ra, dec)

Computes the stellar surface density at location (ra, dec) in units of lensing convergence.

Parameters:

• ra – position in the image plane

• dec – position in the image plane

Returns:

kappa_star

lens_to_dataframe(index=0, df=None)

Store lens properties to a dataframe. This function assumes the name of other methods in the lens class. Thus, if the name of some method changes, this function will break. Additionally, it assumes that the source lives on one plane.

Parameters:

• index (int) – index of row that the lens is stored in. Default = 0

• df – Optional. Stores lens into an existing df if necessary, creates one if not.

Returns:

pandas DataFrame containing deflector/source mass and light properties.

lenstronomy_kwargs(band=None, time=None, microlensing=False, kwargs_microlensing=None)

Generates lenstronomy dictionary conventions for the class object.

Parameters:

• band (string or None) – imaging band, if =None, will result in un- normalized amplitudes

• time (float) – time is an image observation time in units of days. If None, provides magnitude without variability.

• microlensing (bool) – if True, include microlensing variability in the point source.

• kwargs_microlensing (dict or None) – additional (optional) dictionary of settings required by micro-lensing calculation that do not depend on the Lens() class. It is of type: kwargs_microlensing = {“kwargs_magnification_map”: kwargs_magnification_map, “point_source_morphology”: ‘gaussian’ or ‘agn’ or ‘supernovae’, “kwargs_source_morphology”: kwargs_source_morphology} The kwargs_source_morphology is required for the source morphology calculation. The kwargs_magnification_map is required for the microlensing calculation. See the classes in slsim.Microlensing for more details on the kwargs_magnification_map and kwargs_source_morphology. If None, defaults are used corresponding to the source in the lens class.

Returns:

lenstronomy model and parameter conventions

property los_linear_distortions

Line-of-sight distortions in shear and convergence.

Returns:

kappa, gamma1, gamma2

microlensing_model_class(source_index)

Returns the MicrolensingLightCurveFromLensModel class instance corresponding to a specific source index for the microlensing calculations. Only available if microlensing=True was used in point_source_magnitude.

Parameters:

source_index – index of a source in source list.

Returns:

MicrolensingLightCurveFromLensModel class instance for the specified source.

point_source_arrival_times()

Arrival time of images relative to a straight line without lensing. Negative values correspond to images arriving earlier, and positive signs correspond to images arriving later. This is for single source.

Returns:

list of arrival times for each image [days] for each source.

Return type:

list of numpy array

point_source_image_positions()

Returns point source image positions by solving the lens equation for all sources. In the absence of a point source, this function returns the solution for the center of the extended source.

Returns:

list of (x-pos, y-pos) for each source

point_source_magnification()

Macro-model magnification of point sources. This function calculates magnification for each source.

Returns:

list of signed magnification of point sources in same order as image positions.

point_source_magnitude(band, lensed=False, time=None, microlensing=False, kwargs_microlensing=None)

Point source magnitude, either unlensed (single value) or lensed (array) with macro-model magnifications. This function provided magnitudes of all the sources.

Parameters:

• band (string) – imaging band

• lensed (bool) – if True, returns the lensed magnified magnitude

• time – time is an image observation time in units of days. If None, provides magnitude without variability.

• microlensing (bool) – if using micro-lensing map to produce the lensed magnification

• kwargs_microlensing (dict) – additional (optional) dictionary of settings required by micro-lensing calculation that do not depend on the Lens() class. It is of type: kwargs_microlensing = {“kwargs_magnification_map”: kwargs_magnification_map, “point_source_morphology”: ‘gaussian’ or ‘agn’ or ‘supernovae’, “kwargs_source_morphology”: kwargs_source_morphology} The kwargs_source_morphology is required for the source morphology calculation. The kwargs_magnification_map is required for the microlensing calculation. See the classes in slsim.Microlensing for more details on the kwargs_magnification_map and kwargs_source_morphology.

Returns:

list of point source magnitudes.

snr(band, fov_arcsec=10, observatory='LSST', snr_per_pixel_threshold=1, exposure_time=None, num_exposures=None)

Calculate the signal-to-noise ratio (SNR) using the method of Holloway et al. (2023). This implementation is borrowed from mejiro, described in Wedig et al. (2025).

The method proceeds as follows:

1. Image simulation: Two images are generated using simulate_image():

   • Lensed source with no noise.

   • Lensed source, deflector, and sky background (as a flat level)

2. Per-pixel SNR calculation: The SNR for each pixel is computed as:

   \[\text{SNR}_i = \frac{N_{i,\,S}}{\sqrt{N_{i,\,\text{tot}}}}\]

   where \(N_{i,\,S}\) are the source counts in pixel \(i\) and \(N_{i,\,\text{tot}}\) are the total counts (source + deflector + sky background level).

3. Region identification: Pixels with per-pixel SNR above the threshold (default: 1) are identified. Contiguous regions of these pixels are labeled using cross-shaped connectivity.

4. Region SNR calculation: For each multi-pixel region, the SNR is:

   \[\text{SNR}_\text{region} = \frac{\sum\limits_i N_{i,\,S}}{\sqrt{\sum\limits_i N_{i,\,\text{tot}}}}\]

   where the summations are over the \(n\) pixels in the region.

5. Result: The maximum SNR among all identified regions is returned. If no pixels exceed the threshold or no multi-pixel regions are found, None is returned.

Parameters:

• band (string) – imaging band

• fov_arcsec (float) – field of view in arcseconds (default is 10)

• observatory (string) – observatory name (default is “LSST”)

• snr_per_pixel_threshold (float) – minimum SNR per pixel required to include a pixel in a region (default is 1)

• exposure_time (float or None) – exposure time in seconds for computing SNR. If None, will use defaults from lenstronomy.SimulationAPI.ObservationConfig based on the observatory.

• num_exposures (int or None) – number of exposures. If None, a default number will be retrieved from lenstronomy’s SimulationAPI.ObservationConfig based on the observatory.

Returns:

maximum SNR found among the regions above the threshold. Returns None if no pixels are above the threshold or if no multi-pixel regions are found.

Return type:

float or None

source(index=0)

Parameters:

index (int) – index of the source

Returns:

Source() class with index

source_light_model_lenstronomy(band=None, time=None, microlensing=False, kwargs_microlensing=None)

Returns source light model instance and parameters in lenstronomy conventions, which includes extended sources and point sources.

Parameters:

• band (string) – imaging band

• time – time is an image observation time in units of days. If None, provides magnitude without variability.

• microlensing (bool) – if using micro-lensing map to produce the lensed magnification

• kwargs_microlensing (dict) – additional (optional) dictionary of settings required by micro-lensing calculation that do not depend on the Lens() class.

Returns:

source_light_model_list, kwargs_source_light

property source_redshift_list

Returns:

list of source redshifts

subhalos_only_lens_model()

Get the lens model for the halos only.

Returns:

LensModel instance for the halos only, and list of kwargs for the subhalos.

validity_test(min_image_separation=0, max_image_separation=10, mag_arc_limit=None, second_brightest_image_cut=None, snr_limit=None)

Check whether multiple lensing configuration matches selection and plausibility criteria.

Parameters:

• min_image_separation – minimum image separation

• max_image_separation – maximum image separation

• mag_arc_limit (dict with key of bands and values of magnitude limits) – dictionary with key of bands and values of magnitude limits of integrated lensed arc

• second_brightest_image_cut – Dictionary containing maximum magnitude of the second-brightest image and corresponding band. If provided, selects lenses where the second-brightest image has a magnitude less than or equal to provided magnitude. e.g.: second_brightest_image_cut = {“i”: 23, “g”: 24, “r”: 22}

• snr_limit – dictionary with key of bands and values of signal-to-noise ratio limits, e.g., snr_limit = {“g”: 20}

Returns:

A boolean or dict of boolean.

slsim.Lenses.lensed_population_base module

class slsim.Lenses.lensed_population_base.LensedPopulationBase(sky_area=None, cosmo=None, use_jax=True)

Bases: ABC

Abstract Base Class to create a sample of lensed systems.

All object that inherit from Lensed Sample must contain the methods it contains.

abstractmethod deflector_number()

Number of potential deflectors (meaning all objects with mass that are being considered to have potential sources behind them)

Returns:

number of potential deflectors

abstractmethod draw_population(**kwargs)

Return full sample list of all lenses within the area.

Returns:

List of LensedSystemBase instances with parameters of the deflectors and source.

Return type:

list

abstractmethod select_lens_at_random()

Draw a random lens within the cuts of the lens and source, with possible additional cut in the lensing configuration.

# as well as option to draw all lenses within the cuts within the area

Returns:

Lens() instance with parameters of the deflector and lens and source light

abstractmethod source_number()

Number of sources that are being considered to be placed in the sky area potentially aligned behind deflectors.

Returns:

number of sources

slsim.Lenses.lensed_system_base module

class slsim.Lenses.lensed_system_base.LensedSystemBase(source_class, deflector_class, los_class=None, multi_plane=None, shear=True, convergence=False)

Bases: ABC

Abstract Base class to create a lens system with all lensing properties required to render populations.

abstractmethod deflector_ellipticity()

Ellipticity components for deflector light and mass profile.

Returns:

e1_light, e2_light, e1_mass, e2_mass

abstractmethod deflector_light_model_lenstronomy(band)

Returns lens model instance and parameters in lenstronomy conventions.

Parameters:

band (str) – imaging band

Returns:

lens_light_model_list, kwargs_lens_light

abstractmethod deflector_magnitude(band)

Apparent magnitude of the deflector for a given band (AB mag)

Parameters:

band (string) – imaging band

Returns:

magnitude of deflector in given band

abstractmethod deflector_mass_model_lenstronomy()

Returns lens mass model instance and parameters in lenstronomy conventions.

Returns:

lens_mass_model_list, kwargs_lens_mass

abstractmethod deflector_position()

Center of the deflector position.

Returns:

[x_pox, y_pos] in arc seconds

abstractmethod deflector_redshift()

Deflector redshift.

Returns:

deflector redshift

abstractmethod deflector_velocity_dispersion()

Returns:

velocity dispersion [km/s]

abstractmethod einstein_radius()

Einstein radius.

Returns:

Einstein radius [arc seconds]

abstractmethod extended_source_image_positions()

Returns extended source image positions by solving the lens equation.

Returns:

x-pos, y-pos

abstractmethod extended_source_magnification()

Extended source (or host) magnification.

Returns:

integrated magnification factor of host magnitude

abstractmethod extended_source_magnitude(band, lensed=False)

Apparent magnitude of the extended source for a given band (lensed or unlensed) (assumes that size is the same for different bands)

Parameters:

• band (string) – imaging band

• lensed (bool) – if True, returns the lensed magnified magnitude

Returns:

magnitude of source in given band

abstractmethod lenstronomy_kwargs(band=None)

Parameters:

band (string or None) – imaging band, if =None, will result in un-normalized amplitudes

Returns:

lenstronomy model and parameter conventions

abstractmethod los_linear_distortions()

Line-of-sight distortions in shear and convergence.

Returns:

kappa, gamma1, gamma2

abstractmethod point_source_image_positions()

Returns point source image positions by solving the lens equation. In the absence of a point source, this function returns the solution for the center of the extended source.

Returns:

x-pos, y-pos

abstractmethod point_source_magnification()

Macro-model magnification of point sources.

Returns:

signed magnification of point sources in same order as image positions

abstractmethod point_source_magnitude(band, lensed=False)

Point source magnitude, either unlensed (single value) or lensed (array) with macro-model magnifications.

Parameters:

• band (string) – imaging band

• lensed (bool) – if True, returns the lensed magnified magnitude

Returns:

point source magnitude

abstractmethod source_light_model_lenstronomy()

Returns source light model instance and parameters in lenstronomy conventions.

Returns:

source_light_model_list, kwargs_source_light

abstractmethod source_redshift_list()

Source redshift.

Returns:

list of each source redshift

slsim.Lenses.selection module

slsim.Lenses.selection.object_cut(galaxy_list, z_min=0, z_max=5, band=None, band_max=40, band_min=0, list_type='astropy_table', object_type='extended')

Selects a subset of a given galaxy list satisfying given criteria.

Parameters:

• galaxy_list – galaxies prior to selection criteria

• z_min – minimum redshift of selected sample

• z_max – maximum redshift of selected sample

• band – imaging band

• band_max – maximum magnitude of galaxies in band

• band_min – minimum magnitude of galaxies in band

• list_type – format of the source catalog file. Currently, it supports a single astropy table or a list of astropy tables.

• object_type – string to specify whether catalog contains an extended object or point object. This is necessary because point and extended object have different name for the magnitude.

Returns:

subset of galaxies matching the selection criteria

Module contents