Engines

mejiro wraps various image simulation packages to provide a consistent interface for simulating images. Each wrapped package is referred to as an “engine.” The following engines are currently supported:

GalSim: Roman, HWO
STPSF (PSFs only): Roman

An engine is specified when generating a simulated exposure, i.e., an instance of mejiro.exposure.Exposure. The engine is specified in the engine keyword argument, and any specific parameters passed to the engine are specified in the engine_params dictionary. For example, to simulate a Roman image using GalSim:

from mejiro.galaxy_galaxy import SampleGG
from mejiro.instruments.roman import Roman
from mejiro.synthetic_image import SyntheticImage
from mejiro.exposure import Exposure

synthetic_image = SyntheticImage(strong_lens=SampleGG(),
                                instrument=Roman(),
                                band='F129',
                                fov_arcsec=5)

exposure = Exposure(synthetic_image,
                    exposure_time=146,
                    engine='galsim')

To see the available options for each engine, check the default parameters using GalSimEngine.defaults(instrument_name). For example, the default parameters for simulating Roman images with GalSim are:

from mejiro.engines.galsim_engine import GalSimEngine
from pprint import pprint

pprint(GalSimEngine.defaults('Roman'))

{
    'min_zodi_factor': 1.5,
    'sky_background': True,
    'detector_effects': True,
    'poisson_noise': True,
    'reciprocity_failure': True,
    'dark_noise': True,
    'nonlinearity': True,
    'ipc': True,
    'read_noise': True,
}

`engine`

class mejiro.engines.engine.Engine[source]

Bases: ABC

Abstract base class for all simulation engines.

Subclasses must implement defaults and validate_engine_params for each instrument they support.

abstract defaults(instrument_name)[source]

Return default engine parameters for the given instrument.

Parameters:: instrument_name (str) – Name of the instrument for which to retrieve defaults.
Returns:: Mapping of parameter names to their default values.
Return type:: dict
Raises:: NotImplementedError – If the instrument is not supported by this engine.

static instrument_not_supported(instrument_name)[source]

Raise an error if the instrument is not supported.

Parameters:: instrument_name (str) – Name of the unsupported instrument.
Raises:: NotImplementedError – Always raised to indicate the instrument is not supported.

abstract validate_engine_params(instrument_name, engine_params)[source]

Validate engine parameters for the given instrument.

Parameters:

instrument_name (str) – Name of the instrument whose parameters are being validated.
engine_params (dict) – Mapping of parameter names to values to validate.

Raises:

NotImplementedError – If the instrument is not supported by this engine.
ValueError – If any parameter value is invalid for the given instrument.

`galsim_engine`

class mejiro.engines.galsim_engine.GalSimEngine[source]

Bases: Engine

static defaults(instrument_name)[source]

Return default engine parameters for the given instrument.

Parameters:: instrument_name (str) – Name of the instrument for which to retrieve defaults.
Returns:: Mapping of parameter names to their default values.
Return type:: dict
Raises:: NotImplementedError – If the instrument is not supported by this engine.

static get_empty_image(num_pix, pixel_scale)[source]

Create an empty image using GalSim with dtype np.float64.

Parameters:

num_pix (int) – The number of pixels along each dimension of the image.
pixel_scale (float) – The scale of each pixel in the image.

Returns:

An empty image with the specified dimensions and pixel scale with dtype float64.

Return type:

galsim.ImageD

static get_exposure(synthetic_image, exposure_time, engine_params={})[source]

static get_gaussian_psf(fwhm, flux=1.0)[source]

Generate a Gaussian Point Spread Function (PSF) using GalSim.

Parameters:

fwhm (float) – Full width at half maximum.
flux (float, optional) – Transmission. Default is 1.

Returns:

A GalSim Gaussian object representing the PSF.

Return type:

galsim.Gaussian

static get_piece(array, exposure_time, pixel_scale)[source]

static get_roman_exposure(synthetic_image, exposure_time, engine_params={})[source]

static get_roman_psf(band, detector=1, detector_position=(2048, 2048), pupil_bin=1)[source]

Generate a Point Spread Function (PSF) for the Roman Space Telescope using GalSim. Note that mejiro’s preferred package for generating Roman PSFs is STPSF.

Parameters:

band (str) – The band for which the PSF is to be generated.
detector (int, optional) – The Roman detector number (SCA), by default 1.
detector_position (tuple of float, optional) – The position on the detector in pixels, by default (2048, 2048).
pupil_bin (int, optional) – The binning factor for the pupil plane, by default 1.

Returns:

The PSF object for the specified parameters.

Return type:

galsim.GSObject

static get_roman_sky_background(roman, band, exposure_time, num_pix, min_zodi_factor=1.5, background_cps=None)[source]

static get_sky_background(instrument, band, exposure_time, num_pix, pixel_scale)[source]

static validate_engine_params(instrument_name, engine_params)[source]

Validate engine parameters for the given instrument.

Parameters:

instrument_name (str) – Name of the instrument whose parameters are being validated.
engine_params (dict) – Mapping of parameter names to values to validate.

Raises:

NotImplementedError – If the instrument is not supported by this engine.
ValueError – If any parameter value is invalid for the given instrument.

`stpsf_engine`

class mejiro.engines.stpsf_engine.STPSFEngine[source]

Bases: Engine

static cache_psf(id_string, psf_cache_dir)[source]

Save a PSF to the provided directory.

Parameters:

id_string (str) – The PSF identifier string.
psf_cache_dir (str) – The directory where cached PSFs are stored.

Return type:

None

static defaults(instrument_name)[source]

Return default engine parameters for the given instrument.

Parameters:: instrument_name (str) – Name of the instrument for which to retrieve defaults.
Returns:: Mapping of parameter names to their default values.
Return type:: dict
Raises:: NotImplementedError – If the instrument is not supported by this engine.

static get_cached_psf(id_string, psf_cache_dir)[source]

Check if a PSF exists in the provided cache directory. If found, load and return it. Otherwise, return None.

Parameters:

id_string (str) – The PSF identifier string.
psf_cache_dir (str or None) – The directory where cached PSFs are stored. If None, defaults to the directory installed with mejiro.

Returns:

The cached PSF if found, otherwise None.

Return type:

numpy.ndarray or None

static get_jwst_psf(band, oversample, num_pix, check_cache=False, psf_cache_dir=None, **calc_psf_kwargs)[source]

static get_jwst_psf_id(band, oversample, num_pix)[source]

Generate a PSF identifier string. mejiro’s JWST simulation uses this under-the-hood to cache and retrieve JWST PSFs.

Parameters:

band (str) – The band.
oversample (int) – The oversampling factor.
num_pix (int) – The number of pixels on a side.

Returns:

A unique identifier string for the PSF.

Return type:

str

static get_jwst_psf_kwargs(band, oversample, num_pix, check_cache=False, psf_cache_dir=None)[source]

static get_params_from_psf_id(psf_id)[source]

Converts mejiro’s Roman PSF identifier string format back to a list of PSF parameters.

Parameters:: psf_id (str) – mejiro’s Roman PSF identifier string.
Returns:: A tuple containing the following elements: - band (str): The band. - detector (int): The detector number. - detector_position (tuple of int): The (x, y) position on the detector. - oversample (int): The oversampling factor. - num_pix (int): The number of pixels on a side.
Return type:: tuple

static get_psf_id(band, detector, detector_position, oversample, num_pix)[source]

Generate a PSF identifier string. mejiro’s Roman simulation uses this under-the-hood to cache and retrieve Roman PSFs.

Parameters:

band (str) – The band.
detector (str) – The detector number.
detector_position (tuple of int) – The (x, y) position on the detector.
oversample (int) – The oversampling factor.
num_pix (int) – The number of pixels on a side.

Returns:

A unique identifier string for the PSF.

Return type:

str

static get_roman_psf(band, detector, detector_position, oversample, num_pix, check_cache=False, psf_cache_dir=None, require_cached=False, **calc_psf_kwargs)[source]

Generate a Roman WFI PSF using STPSF.

Parameters:

band (str) – The band.
detector (int) – The detector number.
detector_position (tuple of int) – The (x, y) position on the detector.
oversample (int) – The oversampling factor.
num_pix (int) – The number of pixels on a side. This parameter is passed to STPSF’s fov_pixels parameter.
check_cache (bool, optional) – If True, check the cache for an existing PSF before generating a new one. Default is True.
psf_cache_dir (str, optional) – The directory where cached PSFs are stored. If None, defaults to the directory installed with mejiro. Default is None.
**calc_psf_kwargs (dict) – Additional keyword arguments to pass to STPSF’s calc_psf method.

Returns:

The PSF kernel.

Return type:

np.ndarray

static get_roman_psf_from_id(psf_id, check_cache=True, psf_cache_dir=None, **calc_psf_kwargs)[source]

Wrapper method for get_roman_psf that accepts the PSF’s identifier string.

Parameters:

psf_id (str) – The identifier for the PSF, which encodes various parameters.
check_cache (bool, optional) – If True, check the cache for an existing PSF before generating a new one. Default is True.
psf_cache_dir (str, optional) – The directory where cached PSFs are stored. If None, defaults to the directory installed with mejiro. Default is None.
**calc_psf_kwargs (dict) – Additional keyword arguments to pass to STPSF’s calc_psf method.

Returns:

The PSF kernel.

Return type:

np.ndarray

static get_roman_psf_kwargs(band, detector, detector_position, oversample, num_pix, check_cache=False, psf_cache_dir=None, require_cached=False)[source]

static validate_engine_params(engine_params)[source]

Validate engine parameters for the given instrument.

Parameters:

instrument_name (str) – Name of the instrument whose parameters are being validated.
engine_params (dict) – Mapping of parameter names to values to validate.

Raises:

NotImplementedError – If the instrument is not supported by this engine.
ValueError – If any parameter value is invalid for the given instrument.

Engines

engine

galsim_engine

stpsf_engine

`engine`

`galsim_engine`

`stpsf_engine`