slsim.ImageSimulation package

Submodules

slsim.ImageSimulation.image_quality_lenstronomy module

slsim.ImageSimulation.image_quality_lenstronomy.check_speclite_name(band)

Checks if the raw band name is a valid speclite filter.

Returns the band name if valid, otherwise returns None. This will serve as the default speclite_fmt for observatories that use the same band names as their speclite filters.

slsim.ImageSimulation.image_quality_lenstronomy.get_all_supported_bands()

Return every band name currently registered across all observatories.

Returns:

Flat list of band name strings.

Return type:

list of str

slsim.ImageSimulation.image_quality_lenstronomy.get_observatory(band)

Determine the observatory based on the imaging band.

Queries the registry; works for any registered observatory.

Parameters:

band – Imaging band name.

Raises:

ValueError – if the band does not belong to any observatory.

slsim.ImageSimulation.image_quality_lenstronomy.get_speclite_filtername(band)

Get the speclite filter name corresponding to the given band.

Parameters:

band (str) – imaging band name

Returns:

speclite filter name

Return type:

str

Raises:

ValueError – if the band is not registered or has no speclite filter.

Default Supported bands:

• LSST: ‘u’, ‘g’, ‘r’, ‘i’, ‘z’, ‘y’

• Roman: ‘F062’, ‘F087’, ‘F106’, ‘F129’, ‘F158’, ‘F184’, ‘F146’, ‘F213’

• Euclid: ‘VIS’

slsim.ImageSimulation.image_quality_lenstronomy.get_speclite_filternames(bands)

Get a list of speclite filter names corresponding to the provided bands.

Parameters:

bands (list of str) – list of imaging band names. E.g., [‘u’, ‘g’, ‘r’, ‘F062’, ‘VIS’].

Returns:

list of speclite filter names in the same order as input bands

Return type:

list of str

Raises:

ValueError – if any band is not recognized for any observatory or has no speclite filter.

Supported bands:

• LSST: ‘u’, ‘g’, ‘r’, ‘i’, ‘z’, ‘y’

• Roman: ‘F062’, ‘F087’, ‘F106’, ‘F129’, ‘F158’, ‘F184’, ‘F146’, ‘F213’

• Euclid: ‘VIS’

slsim.ImageSimulation.image_quality_lenstronomy.kwargs_single_band(band, observatory=None, **kwargs)

Return the lenstronomy single-band keyword dict for a given band.

Parameters:

• band (str) – Imaging band name (e.g. 'g', 'F062', 'VIS', etc.).

• observatory (str or None) – Observatory name. When None the observatory registry is queried automatically based on band.

• kwargs – Additional keyword arguments forwarded to the observatory class constructor (e.g. coadd_years).

Returns:

Configuration dict of imaging data for lenstronomy.

Return type:

dict

slsim.ImageSimulation.image_quality_lenstronomy.register_observatory(name: str, observatory_class, bands: list, speclite_fmt=<function check_speclite_name>)

Register a new observatory to integrate it with image simulation tools.

This allows external or user-defined observatories (e.g., “MidEx”) to be automatically recognized by functions like kwargs_single_band.

Parameters:

• name (str) – The identifier for the observatory (e.g., “MidEx”).

• observatory_class (type) – The class defining the observatory’s configuration. Similar to the lenstronomy.SimulationAPI.ObservationConfig classes, this class must fulfill two requirements: 1. Its constructor must accept band as a keyword argument. 2. It must expose a kwargs_single_band() method that returns a dictionary of lenstronomy observation parameters.

• bands (list[str]) – List of band name strings owned by this observatory. E.g., for LSST this would be [‘u’, ‘g’, ‘r’, ‘i’, ‘z’, ‘y’].

• speclite_fmt (callable, optional) – A callable function that takes a band string and returns the corresponding speclite filter name (e.g., lambda b: f"MidEx-{b}"). Set to None if the observatory does not utilize speclite filters.

Given below is a simple example of how to define a custom observatory and register it using this function. A sophisticated example demonstrating full image simulation capabilities can be found at https://github.com/timedilatesme/MidEx-sims/blob/main/v1/lagn_sims.ipynb

Example:

import copy
import lenstronomy.Util.util as util
import slsim.simulation.image_quality_lenstronomy as iql

# Specify bands and their corresponding observation parameters for the custom observatory
custom_band_obs = {
    "A": {"exposure_time": 90.0, "sky_brightness": 22.0, "magnitude_zero_point": 26.0},
    "B": {"exposure_time": 90.0, "sky_brightness": 21.5, "magnitude_zero_point": 25.8}
}

# Define the observatory class
class CustomObs(object):
    """Class containing CustomObs instrument and observation configurations."""

    def __init__(self, band="A", **kwargs):
        if band not in custom_band_obs:
            raise ValueError(f"Band '{band}' not supported! Choose from {list(custom_band_obs.keys())}.")

        self.obs = copy.deepcopy(custom_band_obs[band])
        self.camera = {
            "read_noise": 5.0,
            "pixel_scale": 0.15,
            "ccd_gain": 2.0,
        }

    def kwargs_single_band(self):
        return util.merge_dicts(self.camera, self.obs)

# Register the new observatory
iql.register_observatory(
    name="CustomObs",
    observatory_class=CustomObs,
    bands=list(_custom_band_obs.keys()),
    speclite_fmt=lambda b: f"CustomObs-{b}"
)

slsim.ImageSimulation.image_simulation module

slsim.ImageSimulation.image_simulation.centered_coordinate_system(num_pix, transform_pix2angle)

Returns dictionary for Coordinate Grid such that (0,0) is centered with given input orientation coordinate transformation matrix.

Parameters:

• num_pix (int) – number of pixels

• transform_pix2angle – transformation matrix (2x2) of pixels into coordinate displacements

Returns:

dict with ra_at_xy_0, dec_at_xy_0, transfrom_pix2angle

slsim.ImageSimulation.image_simulation.deflector_images_with_different_zeropoint(lens_class, band, mag_zero_point, delta_pix, num_pix)

Creates deflector images with different magnitude zero point. This function is useful when one wants to simulate variable lens images. For this, we need to simulate delctor images for different exposure (where we want to inject lenses) and those exposure could have different magnitude zero point.

Parameters:

• lens_class – Lens() object

• band – imaging band

• mag_zero_point – list of magnitude zero point in band for sequence of exposure

• delta_pix – pixel scale of image generated

• num_pix – number of pixels per axis

Returns:

list of deflector images with different zero point

slsim.ImageSimulation.image_simulation.image_data_class(lens_class, band, mag_zero_point, delta_pix, num_pix, transform_pix2angle)

Provides data class for image.

Parameters:

• lens_class – Lens() object

• band – imaging band

• mag_zero_point – magnitude zero point in band

• delta_pix – pixel scale of image generated

• num_pix – number of pixels per axis

• transform_pix2angle – transformation matrix (2x2) of pixels into coordinate displacements

Returns:

image data class

slsim.ImageSimulation.image_simulation.image_plus_poisson_noise(image, exposure_time, gain=1, coadd_zero_point=27, single_visit_zero_point=27)

Creates an image with Poisson noise.

Parameters:

• image – an image

• exposure_time – exposure time or exposure map for an image

• band – imaging band

• gain – Amplifier gain (default 1).

• coadd_zero_point – Zero point of the coadded image (default 27).

• single_visit_zero_point – Zero point of the single-visit image (default 27 for g-band).

Returns:

image with possion noise. The function returns ADU/sec in all cases, regardless of whether gain = 1 or not. The noise is applied in the electron domain, but the final image is converted back to ADU/sec.

slsim.ImageSimulation.image_simulation.image_plus_poisson_noise_for_list_of_image(images, exposure_times)

Creates an image with possion noise.

Parameters:

• images – list of images

• exposure_time – list of exposure times or exposure maps

Returns:

list of images with possion noise

slsim.ImageSimulation.image_simulation.lens_image(lens_class, band, mag_zero_point, num_pix, psf_kernel, transform_pix2angle, exposure_time=None, t_obs=None, std_gaussian_noise=None, with_source=True, with_deflector=True, gain=0.7, single_visit_mag_zero_points={'g': 32.33, 'i': 31.85, 'r': 32.17, 'y': 30.63, 'z': 31.45}, microlensing=False)

Creates lens image on the basis of given information. It can simulate both static lens image and variable lens image.

Parameters:

• lens_class – Lens() object

• band – imaging band

• mag_zero_point – magnitude zero point for the exposure

• num_pix – number of pixels per axis

• psf_kernels – psf kernel for the exposures being.

• transform_pix2angle – transformation matrix (2x2) of pixels into coordinate displacements

• exposure_time – exposure time for for the exposure. It could be single exposure time or a exposure map.

• t_obs – an observation time [day]. This is applicable only for variable source. In case of point source, if we do not provide t_obs, considers no variability in the lens.

• std_gaussian_noise – standard deviation for a gaussian noise

• with_source – If True, simulates image with extended source in lens configuration.

• with_deflector – If True, simulates image with deflector.

• gain – Amplifier gain (default 0.7 for LSST).

• single_visit_mag_zero_points – Zero points of the single-visit image in different bands. It is a dictionary of the form: { ‘g’: 32.33, ‘r’: 32.17, ‘i’: 31.85, ‘z’: 31.45, ‘y’: 30.63 }. It sould contain at least values for the band in which one need to simulate images. Default values are average magnitude zero points for LSST single visists in each band.

• microlensing – boolean flag to include microlensing variability

Returns:

lens image

slsim.ImageSimulation.image_simulation.lens_image_series(lens_class, band, mag_zero_point, num_pix, psf_kernel, transform_pix2angle, exposure_time=None, t_obs=None, std_gaussian_noise=None, with_source=True, with_deflector=True, gain=0.7, single_visit_mag_zero_points={'g': 32.33, 'i': 31.85, 'r': 32.17, 'y': 30.63, 'z': 31.45}, microlensing=False)

Creates lens image on the basis of given information. This function is designed to simulate time series images of a lens.

Parameters:

• lens_class – Lens() object

• band – imaging band (or list of bands). if float: assumed to apply to the full image series.

• mag_zero_point – list of magnitude zero point for sequence of exposure

• num_pix – number of pixels per axis

• psf_kernels – list of psf kernel for each exposure.

• transform_pix2angle – list of transformation matrix (2x2) of pixels into coordinate displacements for each exposure

• exposure_time – list of exposure time for each exposure. It could be single exposure time or a exposure map.

• t_obs – array of image observation time [day] for a lens.

• std_gaussian_noise – array of standard deviation for gaussian noise for each image

• with_source – If True, simulates image with extended source in lens configuration.

• with_deflector – If True, simulates image with deflector.

• gain – Amplifier gain (default 0.7 for LSST).

• single_visit_mag_zero_points – Zero points of the single-visit image in different bands. It is a dictionary of the form: { ‘g’: 32.33, ‘r’: 32.17, ‘i’: 31.85, ‘z’: 31.45, ‘y’: 30.63 }. It sould contain at least values for the band in which one need to simulate images. Default values are average magnitude zero points for LSST single visists in each band.

• microlensing – boolean flag to include microlensing variability

Returns:

list of series of images of a lens

slsim.ImageSimulation.image_simulation.point_source_coordinate_properties(lens_class, band, mag_zero_point, delta_pix, num_pix, transform_pix2angle)

Provides pixel coordinates for deflector and images. Currently, this function only works for point source.

Parameters:

• lens_class – Lens() object

• band – imaging band

• mag_zero_point – magnitude zero point in band

• delta_pix – pixel scale of image generated

• num_pix – number of pixels per axis

• transform_pix2angle – transformation matrix (2x2) of pixels into coordinate displacements

Returns:

Dictionary of deflector and image coordinate in pixel unit and other coordinate properties.

slsim.ImageSimulation.image_simulation.point_source_image_at_time(lens_class, band, mag_zero_point, delta_pix, num_pix, psf_kernel, transform_pix2angle, time, microlensing=False)

Creates lensed point source images with variability at a given time on the basis of given information.

Parameters:

• lens_class – Lens() object

• band – imaging band

• mag_zero_point – magnitude zero point in band

• delta_pix – pixel scale of image generated

• num_pix – number of pixels per axis

• psf_kernel – psf kernel for the given exposure.

• transform_pix2angle – transformation matrix (2x2) of pixels into coordinate displacements

• time – time is an image observation time [day].

• microlensing – boolean flag to include microlensing variability

Returns:

point source images with variability

slsim.ImageSimulation.image_simulation.point_source_image_with_variability(lens_class, band, mag_zero_point, delta_pix, num_pix, psf_kernels, transform_pix2angle, t_obs)

Creates lensed point source images with variability for series of time on the basis of given information.

Parameters:

• lens_class – Lens() object

• band – imaging band

• mag_zero_point – magnitude zero point for each exposure

• delta_pix – pixel scale of image generated

• num_pix – number of pixels per axis

• psf_kernels – psf kernels in the sequence of exposures being simulated.

• transform_pix2angle – transformation matrix (2x2) of pixels into coordinate displacements

• t_obs – array of image observation time [day].

Returns:

array of point source images with variability

slsim.ImageSimulation.image_simulation.point_source_image_without_variability(lens_class, band, mag_zero_point, delta_pix, num_pix, psf_kernel, transform_pix2angle)

Creates lensed point source images without variability on the basis of given information.

Parameters:

• lens_class – Lens() object

• band – imaging band

• mag_zero_point – magnitude zero point in band

• delta_pix – pixel scale of image generated

• num_pix – number of pixels per axis

• psf_kernel – psf kernel for an image.

• transform_pix2angle – transformation matrix (2x2) of pixels into coordinate displacements

Returns:

point source images

slsim.ImageSimulation.image_simulation.rgb_image_from_image_list(image_list, stretch)

Creates a rgb image using list of images in r, g, and b.

Parameters:

image_list – images in r, g, and b band. Here, ‘i’, ‘r’, and ‘g’ band are consider as r, g, and b respectively.

Returns:

rgb image

slsim.ImageSimulation.image_simulation.sharp_image(lens_class, band, mag_zero_point, delta_pix, num_pix, with_source=True, with_deflector=True)

Creates an unconvolved image of a selected lens. Point source image is not included in this function.

Parameters:

• lens_class – Lens() object

• band – imaging band

• mag_zero_point – magnitude zero point in band

• delta_pix – pixel scale of image generated

• num_pix – number of pixels per axis

• with_source – bool, if True computes source

• with_deflector – bool, if True includes deflector light

Returns:

2d array unblurred image

slsim.ImageSimulation.image_simulation.sharp_rgb_image(lens_class, rgb_band_list, mag_zero_point, delta_pix, num_pix)

Creates an unconvolved rgb image of a selected lens.

Parameters:

• lens_class – Lens() object

• rgb_band_list – imaging band list. Here, ‘i’, ‘r’, and ‘g’ band are consider as r, g, and b respectively.

• mag_zero_point – magnitude zero point in band

• delta_pix – pixel scale of image generated

• num_pix – number of pixels per axis

Returns:

rgb image

slsim.ImageSimulation.image_simulation.simulate_image(lens_class, band, num_pix, add_noise=True, add_background_counts=False, observatory='LSST', t_obs=None, exposure_time=None, num_exposures=None, kwargs_psf=None, kwargs_numerics=None, kwargs_single_band=None, with_source=True, with_deflector=True, with_point_source=True, image_units_counts=False, microlensing=False, kwargs_microlensing=None, **kwargs)

Creates an image of a selected lens with noise.

Parameters:

• lens_class – class object containing all information of the lensing system (e.g., Lens())

• band – imaging band

• num_pix – number of pixels per axis

• add_noise – if True, add noise

• add_background_counts (bool) – whether to add the absolute count of photons on the background. If =False; the mean background is subtracted (not the noise)

• observatory (str) – telescope type to be simulated

• t_obs – an observation time in units of days. This is applicable only for variable source. In case of point source, if we do not provide t_obs, considers no variability in the lens.

• 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 and survey mode.

• 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 and survey mode.

• kwargs_psf (dict) – (optional) specific PSF quantities to overwrite default options (“psf_type”, “kernel_point_source”, “point_source_supersampling_factor”)

• (optional) (kwargs_single_band) – options are “point_source_supersampling_factor”, “supersampling_factor”, and more in lenstronomy.ImSim.Numerics.numerics class

• (optional) – not intended to be provided directly by the user – this is more efficient for the SNR criterion in the validity test

• with_source (bool) – if True, include source light

• with_deflector (bool) – if True, include deflector light

• with_point_source (bool) – if True, include point source light

• image_units_counts (bool) – if True, return image in units of counts instead of counts/second (default: False)

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

• kwargs (dict) – additional keyword arguments for the bands

Returns:

simulated image

Return type:

2d numpy array

slsim.ImageSimulation.roman_image_simulation module

slsim.ImageSimulation.roman_image_simulation.add_sky_plus_thermal_background(image, band, detector, num_pix, exposure_time, ra, dec, date)

Adds a sky and thermal background to image, corresponding to a specific band, detector, date, and coordinate in the sky.

Parameters:

• image (galsim Image class) – image to add the background to

• band (string) – imaging band

• detector (integer from 1 to 18) – The specific Roman detector being used to generate the psf

• num_pix (integer) – number of pixels per axis

• ra (float or None) – Coordinate in space used to generate sky background

• dec (float or None) – Coordinate in space used to generate sky background

• date (datetime.datetime class) – Date used to generate sky background. The date must be consistent with the ra and dec coordinates.

Returns:

image with added background

Return type:

galsim Image class

slsim.ImageSimulation.roman_image_simulation.get_bandpass(band)

Parameters:

band (string) – imaging band

Returns:

galsim bandpass object corresponding to specific band

Return type:

galsim Bandpass class

slsim.ImageSimulation.roman_image_simulation.get_bandpass_key(band)

Translates the Roman bands to keys used in galsim.

Parameters:

band (string) – The Roman band to be translated

Returns:

Translated band

Return type:

string

slsim.ImageSimulation.roman_image_simulation.get_psf(band, detector, detector_pos, oversample, psf_directory)

Obtain galsim psf corresponding to specific WFI detector, position, band, and supersampling factor, using stpsf.

Parameters:

• band (str) – The specific band corresponding to the psf.

• detector (int) – The specific Roman detector being used to generate the psf (from 1 to 18).

• detector_pos (int) – The position of the detector being used to generate the psf. Must be between 4 + num_pix * oversample and 4092 - num_pix * oversample.

• oversample (int) – Number of times that each pixel’s side is subdivided for higher accuracy psf convolution.

• psf_directory (str) – Path to directory containing psf file(s) where the psf can be loaded. Otherwise, the psf will be generated by stpsf on the fly, which is very slow.

Returns:

An image of the psf generated by stpsf.

Return type:

galsim.InterpolatedImage

Notes on psf naming convention:

The name of the psf file inside the directory follows this convention:

psf_file_name = f"{band}_{detector}_{detector_pos[0]}_{detector_pos[1]}_{oversample}.pkl"

For example:

psf_file_name = "F106_SCA03_1934_1293_5.pkl"

slsim.ImageSimulation.roman_image_simulation.simulate_roman_image(lens_class, band, num_pix, oversample=3, add_noise=True, subtract_mean_background=True, with_source=True, with_deflector=True, exposure_time=None, num_exposures=None, t_obs=None, survey_mode='wide_area', detector=None, detector_pos=None, seed=None, ra=None, dec=None, date=datetime.datetime(2027, 7, 7, 0, 0), psf_directory=None)

Creates a Roman-simulated image of a selected lens with noise, using galsim’s noise settings and PSFs from STPSF.

Parameters:

• lens_class – class object containing all information of the lensing system (e.g., Lens())

• band (str) – imaging band.

• num_pix (int) – number of pixels per axis.

• add_noise (bool) – determines whether sky background and detector effects are added or not. See https://galsim-developers.github.io/GalSim/_build/html/roman.html#galsim.roman.allDetectorEffects for specific details about the detector effects.

• subtract_mean_background (bool) – whether to subtract the mean count of photons on the background (not the noise).

• with_source (bool) – determines whether source is included in image.

• with_deflector (bool) – determines whether deflector is included in image.

• exposure_time (int, optional) – exposure time of image. If None, a default exposure time will be retrieved from lenstronomy’s SimulationAPI.ObservationConfig based on the Roman survey mode.

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

• t_obs – an observation time in units of days. This is applicable only for variable source. In case of point source, if we do not provide t_obs, considers no variability in the lens.

• survey_mode (str) – survey mode of the Roman detector. Can be “wide_area” or “time_domain”.

• detector (int, optional) – The specific WFI detector being used to generate the psf (from 1 to 18). If None, one will be selected at random.

• detector_pos (tuple, optional) – The pixel on the detector being used to generate the psf. Must be a 2-tuple of integers between 4 + num_pix * oversample and 4092 - num_pix * oversample.

• seed (int, optional) – An rng seed used for generating detector effects in galsim.

• ra (float, optional) – Coordinate in space used to generate sky background. For possible coordinates, see https://roman-docs.stsci.edu/files/215024143/215024145/2/1768495040130/outlines.png

• dec (float, optional) – Coordinate in space used to generate sky background. For possible coordinates, see https://roman-docs.stsci.edu/files/215024143/215024145/2/1768495040130/outlines.png

• date (datetime.datetime) – Date used to generate sky background. The date must be consistent with the ra and dec coordinates.

• psf_directory (str) – Path to directory containing psf file(s) where the psf can be loaded. Otherwise, the psf will be generated by stpsf on the fly, which is very slow. See the note in the get_psf method’s docstring for details on the PSF file naming convention.

Returns:

simulated image in units of flux per second.

Return type:

numpy.ndarray

Module contents