iful.simulation_api

Simulation API module for mock IFU data generation, lensed galaxy simulation, and FITS export.

This module provides classes and functions to construct mock ImageSet objects, set up Lenstronomy models, simulate 3D lensed galaxy datacubes, inject realistic instrument noise, and export the resulting synthetic data to standard FITS files.

Functions

add_instrument_noise(datacube[, ...])

Adds Gaussian background/readout noise to the datacube.

create_simulation_models(imset[, theta_E, ...])

Initializes and configures the FlatModel and IFULModel instances for the simulation.

export_to_fits(filename, datacube_noisy, ...)

Saves the simulated datacube to a FITS file with proper WCS headers.

run_galaxy_simulation(ifulmodel, sim_params)

Evaluates the lensing configuration and returns the lensed image, unlensed source, and caustic/critical curve coordinates.

Classes

SimulationMockImageSet(size, ...)

Mock ImageSet configured for JWST NIRSpec G235M simulation.
class iful.simulation_api.SimulationMockImageSet(size, pixscale_arcsec, zs, wavelengths_full, psf_path)[source]

Bases: ImageSet

Mock ImageSet configured for JWST NIRSpec G235M simulation.

Subclasses ImageSet to populate synthetic 3D datacubes, WCS headers, pixel scales, exposure times, and PSF matrices.

Parameters:

  • size (int) – Spatial size of the image grid in pixels (e.g. 50 for a 50x50 grid).

  • pixscale_arcsec (float) – Pixel scale in arcseconds per pixel.

  • zs (float) – Redshift of the lensed source.

  • wavelengths_full (numpy.ndarray) – 1D array of wavelengths across the full mock bandpass.

  • psf_path (str) – File path to .npy file containing the PSF kernel array.

iful.simulation_api.add_instrument_noise(datacube, bg_noise_std_frac=0.02, seed=42)[source]

Adds Gaussian background/readout noise to the datacube.

Parameters:

  • datacube (numpy.ndarray) – 3D synthetic datacube without noise.

  • bg_noise_std_frac (float, default=0.02) – Standard deviation of background noise as a fraction of peak datacube flux.

  • seed (int, default=42) – Random seed for reproducibility.

Returns:

(noisy_datacube, bg_noise_realization)

Return type:

tuple of (numpy.ndarray, numpy.ndarray)

iful.simulation_api.create_simulation_models(imset, theta_E=0.8, source_x=0.09, source_y=0.09, iful_profiles=None)[source]

Initializes and configures the FlatModel and IFULModel instances for the simulation.

Parameters:

  • imset (ImageSet) – ImageSet or SimulationMockImageSet instance.

  • theta_E (float, default=0.8) – Einstein radius in arcseconds for EPL lens model.

  • source_x (float, default=0.09) – Source position RA offset in arcseconds.

  • source_y (float, default=0.09) – Source position Dec offset in arcseconds.

  • iful_profiles (list of str, optional) – Profile names for [v_los, v_disp, flux]. Defaults to [‘ARCTAN’, ‘CONSTANT_FITTED_BH’, ‘SERSIC’].

Returns:

Configured FlatModel and IFULModel object pair ready for simulation runs.

Return type:

tuple of (FlatModel, IFULModel)

iful.simulation_api.export_to_fits(filename, datacube_noisy, wavelengths_full, header_wcs, redshift=3.8, exptime=1000.0, comment=None)[source]

Saves the simulated datacube to a FITS file with proper WCS headers.

Parameters:

  • filename (str) – Output file path for the FITS file.

  • datacube_noisy (numpy.ndarray) – 3D noisy datacube array to write.

  • wavelengths_full (numpy.ndarray) – 1D wavelength array.

  • header_wcs (astropy.io.fits.Header) – Base WCS header dictionary to copy into FITS header.

  • redshift (float, default=3.8) – Source redshift value stored in header.

  • exptime (float, default=1000.0) – Exposure time in seconds.

  • comment (str, optional) – Comment string for FITS header.

iful.simulation_api.run_galaxy_simulation(ifulmodel, sim_params, compute_window=3, grid_scale=0.01, source_grid_size=100, source_grid_scale=0.015)[source]

Evaluates the lensing configuration and returns the lensed image, unlensed source, and caustic/critical curve coordinates.

Parameters:

  • ifulmodel (IFULModel) – Target IFULModel instance.

  • sim_params (array-like) – Array of parameter values for the lens model.

  • compute_window (float, default=3) – Window size for critical curve calculation (arcseconds).

  • grid_scale (float, default=0.01) – Grid resolution scale for critical curve computation (arcseconds).

  • source_grid_size (int, default=100) – Number of grid points along each axis for evaluating unlensed source light.

  • source_grid_scale (float, default=0.015) – Pixel scale of unlensed source grid (arcseconds).

Returns:

(lensed_image, unlensed_source, ra_crit, dec_crit, ra_caustic, dec_caustic)

Return type:

tuple