usim - EranOfek/AstroPack GitHub Wiki
This function can be employed to simulate an image obtained with one of the four ULTRASAT tiles exposed to a number of emission sources in its field of view. The primary outputs are an AstroImage object containing the injected source catalog and a FITS image file, as well as ds9-style region files containing positions of all the modeled sky sources and a text table with the catalog source positions (X, Y, RA, DEC), source magnitudes and count rates.
- the tile name (A, B, C, D), def. to B
- a source catalog ([X, Y] or [RA Dec]):
- an AstroCatalog object OR
- an XY source table OR
- the number of sources N to be randomly distributed in the tile FOV (def. to 10)
- source magnitudes: an array mag (or 1 mag for all, def. to 20) and the filter for which the magnitudes are set (def. to ULTRASAT); the ULTRASAT filter family may not be mixed with other families in one call
- galactic extinction in the field as E(B-V), one value for all the sources or one per source
- source spectra:
- an array of AstSpec/AstroSpec objects (a single object is used for all the sources) or
- an array of spectral parameters (‘BB’ + temp. or ‘PL’ + index) different or same for all the sources or
- Teff and log(g) of Pickles or Phoenix stellar models or
- an array of N source spectra as N table columns [+ wavelength grid in the last N+1 column if the grid differs from the 2000:1:11000 A grid]
- the desired PSF resolution (1/47.5, 1/10, ⅕, ½, 1 of the ULTRASAT pixel) (def. to ⅕)
- the PSF rotation angle: one for all the sources or one per source ('RotAng', def. to 0 deg) and the spacecraft jitter ('Jitter', def. off; amplitudes 'JitterPar' for a 300 s exposure, scaled as the square root of the exposure)
- the number of exposures in a set (def. to 3) and the exposure length (def. to 300 s)
- the aim point position in RA, DEC and the detector rotation angle (def. to 0 deg)
- the observation time ('DateObs', def. to '2026-07-01T00:00:00') and the random number seed ('Seed', def. to none)
- the background, noise and detector parameters (see below)
- extended objects (Sersic, Gaussian, flat or user-given profiles) instead of a point-source catalog ('ExtProfileType' and the other 'Ext...' arguments)
- the output directory (def. to current) and output filename template (def. to 'SimImage')
- 'Verbosity': 0 (def.) runs silently, 1 reports the progress and timing
The background components are given as rates in e-/pix/s; the defaults are the estimates used so far.
| Argument | Default | Meaning |
|---|---|---|
Zodi |
0.09 | zodiacal light (27 e-/pix in 300 s); 'model' computes it for the pointing and DateObs with ultrasat.zodiac_bck, one value per tile |
Cherenkov |
0.05 | Cherenkov background |
Stray |
0.04 | stray light |
DarkCurrent |
0.04 | dark current |
ReadNoise |
sqrt(6) | read-out noise [e-/pix] in one frame, zero-mean |
CrossTalk |
2 | cross-talk noise variance [e-^2/pix] in one frame, zero-mean |
FlatMatrix |
[] | a 4738 x 4738 flat field in the image orientation; it scales the photon counts (sources, zodiacal, Cherenkov and stray light) before the noise |
Vignetting |
'ELOP' | the 2-D map of the obscured part of the aperture (ELOP, 2022). Sources get the map instead of the radial obscuration already in the throughput (a 0-4% change); the zodiacal, Cherenkov and stray light get the map divided by its tile mean (a 10-14% drop from the aimpoint corner to the far corner). Needs ObscurationMapELOP.mat in ~/matlab/data/ULTRASAT/ (a copy is in /mnt/euclid/matlab_data/ULTRASAT/); without it usim stops with an error. 'none' turns the vignetting off |
LowCountNonLin |
'none' | the low-count detector non-linearity, e.g. @ultrasat.lowCountNonLin with its parameter in LowCountNonLinPar
|
AddCRStreaks |
false | cosmic-ray hits (a crude placeholder model) |
NoiseZody, NoiseCher, NoiseStray, NoiseDark and NoiseCross switch the components on and off, and NoisePoisson = false
gives the expected counts without noise. Each pixel gets Poisson noise below 100 expected electrons (PoissonThreshold) and
Gaussian noise above it. The low-count non-linearity is applied to the noisy image of each frame, after the cosmic rays and
before the full-well cut and the conversion to ADU.
- an AstroImage object: the image, its expected variance (the Var layer: sources, background, read-out and cross-talk noise), the mean background, the source catalog, and a header with the background and detector parameters used (ZODIRATE, CHERRATE, STRAYRAT, DARKRATE, RDNOISE, XTALKVAR, NONLIN, NONLINPA, SIMSEED, ...)
- an AstroPSF object with the PSF of every source, in the image orientation, with the source number as the dimension 'Source':
AP.getPSF('PsfArgs', {'Source', k})gives the PSF of source k (also attached to the image asPSFData) - an image in ADU, for a single exposure (
Exposure(1) = 1); its form is set byADUOutput:
ADUOutput |
ADU files | ADU volume per tile |
|---|---|---|
'threshold' (default) |
_ADU.fits: 14-bit values, each pixel read with the gain chosen by the threshold (1.6e4 e-), the gain flag in the top bit |
45 MB |
'raw' |
_ADU_HI.fits and _ADU_LO.fits: every pixel read with the high gain and with the low gain (as in the ELOP simulations) |
90 MB |
'production' |
_ADU.fits: 13-bit values without the gain bit, and _GAIN.fits: an 8-bit map of the gain used (1 = low gain) |
45 + 22 MB |
The header keyword GCHANNEL says which gain a file holds (HIGH, LOW or THRESHOLD). The returned ADU array has two planes
for 'raw' ([HI LO]) and 'production' ([ADU GainMap]).
- files (with
OutType'all' or 'FITS'):<OutName>_tile<Tile>.fits(90 MB), the ADU file(s) above,_InCat.txtand.reg(about 0.1 MB per 1000 sources together)
% Make an ULTRASAT tile 'B' image of 10 sources randomly distributed in the tile FOV,
% all with the same default ULTRASAT magnitude and BB spectrum of 5800 K, for 3 standard exposures of 300 seconds each,
% with source PSFs calculated at the scale of 1/5 pixel:
SimImage = ultrasat.usim('Cat', 10);
% Make an ULTRASAT tile 'A' image of sources with pixel coordinates from the catalog Cat,
% of ULTRASAT magnitudes listed in the vector Mag and spectra
% given by the vector of AstroSpec objects Spec, for 10 standard exposures of 300 seconds each,
% with source PSFs calculated at the scale of 1/2 pixel.
SimImage = ultrasat.usim('Cat', Cat, 'Mag', Mag, 'Spec', Spec, 'Tile', 'A', 'Exposure', [10 300], 'ImRes', 2);
% Make an ULTRASAT tile 'B' image of sources with sky coordinates from the catalog Cat, with the telescope aimpoint at RA, Dec = 210, 52
% and rotate it by 40 deg counterclockwise. Start the output file names with 'skysim':
SimImage = ultrasat.usim('Cat', Cat, 'SkyCat', true, 'RA0', 210, 'Dec0', 52, 'PlaneRotation', 40, 'OutName', 'skysim');
% Make an ULTRASAT tile 'B' image of sources with sky coordinates from the catalog Cat,
% and dereddened SDSS g magnitudes given by a vector Mag, account for extinction of E(B-V) = 0.1,
% with the telescope aimpoint at RA, Dec = 210, 52:
SimImage = ultrasat.usim('Cat', Cat, 'SkyCat', true, 'RA0', 210, 'Dec0', 52, 'Mag', Mag, 'Ebv', 0.1, 'FiltFam', 'SDSS', 'Filt', 'g');
% A single 300 s exposure with the zodiacal light computed for the pointing and date, the low-count non-linearity
% with a charge deficit of 15 e-, and a fixed random seed (the run can be repeated exactly):
[SimImage, AP, ImADU] = ultrasat.usim('Cat', Cat, 'SkyCat', true, 'RA0', 210, 'Dec0', 52, 'Exposure', [1 300], ...
'Zodi', 'model', 'DateObs', '2026-12-15T22:00:00', ...
'LowCountNonLin', @ultrasat.lowCountNonLin, 'LowCountNonLinPar', 15, 'Seed', 1);
% A single extended Sersic-profile object with a 10000 K blackbody spectrum:
SimImage = ultrasat.usim('ExtProfileType', 'sersic', 'ExtProfilePar', [70 4 1], 'ExtAxisRatio', 1, ...
'ExtSizeRA', 370, 'ExtSizeDec', 370, 'ExtOversampling', 1, ...
'ExtRA0', 221.787891, 'ExtDec0', 56.361518, 'ExtMag', 13, ...
'ExtSpecType', 'BB', 'ExtSpec', 10000, 'Tile', 'B', 'Exposure', [1 300]);ultrasat.simulateGaiaField takes the Gaia DR3 stars in a tile, assigns each star a Pickles template from its Gaia color, magnitude and parallax, and calls ultrasat.usim with these spectra. The luminosity class is read from PARSEC isochrones, which have to be installed once:
I = Installer;
I.install('PARSEC'); % 28 MB, into <data dir>/stars/PARSEC% Tile 'B' of the Kepler field, stars with predicted ULTRASAT magnitude up to 17:
[SimImage, Src] = ultrasat.simulateGaiaField('Tile', 'B', 'MaxU', 17);