NAME
heasim - Multi-mission high-energy astrophysics simulation tool
USAGE
heasim mission instrume rapoint decpoint roll exposure insrcdeffile outfile
psffile vigfile rmffile arffille intbackfile
DESCRIPTION
The heasim task is a multi-mission high-energy astrophysics simulation
tool. The heasim task utilizes a pseudo Monte-Carlo approach that
redistributes the source photons in position and energy according
to the input files appropriate to the chosen telescope/detector
system. The output is a FITS event file, from which data products
may be extracted and analyzed using e.g., xselect, xspec, etc.
The parameters 'mission' and 'instrume' specify the mission
name and the instrument name respectively, for a specific mission. The specific
characteristics of the supported instruments (e.g. , pixel size,
field-of-view, etc.) are collected in the mission database file
(parameter 'mdbfile'). The parameters 'rapoint' and 'decpoint' define the
pointing direction, and the 'roll' parameter defines the rotation angle (all
in decimal degrees). The exposure time [s] is entered in as
the parameter 'exposure'. The positions of X-ray sources, along with their spectral,
spatial, and temporal characteristics, are input via the source
definition file (parameter 'insrcdeffile'). The point spread function (PSF),
vignetting, spectral response, effective area, and internal
background for each detector are input using the parameters
'psffile', 'vigfile', 'rmffile', 'arffille', and 'intbackfile',
respectively. The sky background may be calculated using the
skyback task, and the output files from skyback may be used as input for
heasim. The parameter 'psbackfile' accepts a file containing a list
of the resolved background point sources as calculated and output
from skyback. The parameter 'pszbackfile' accepts a file that lists
the point-source intrinsic redshifts and absorption column densities for these
same sources. The parameter 'difbackfile' accepts the file that
lists a single diffuse background extended source as calculated
and output by skyback. The simulation may be split into multiple
subexposures by setting the 'flagsubex' parameter to yes, and the
'subexpsosure' parameter to a value that differs from the parameter
'exposure'. Resampling of event locations from sky pixels onto
larger detector pixels is controlled by the 'resample'
parameter. Basic event pileup may be simulated with the 'dtpileup'
timescale parameter in units of seconds.
The heasim task calculates simulated events for each input source in the
source definition file (and background) with the following
steps.
- The absorbed input spectrum [photons cm^{-2} s^{-1}] vs. energy
[keV], based on the input spectral model or user spectrum file, is
calculated for each energy bin in the ARF file.
- This spectrum is then converted to counts/bin vs. bin on the same input energy grid by
multiplying by the exposure time and effective area.
- The sum over all bins is calculated to provide the total number of events.
- For each source,
the code loops over each input energy bin, and over the counts in
each bin, probabilistically assigning a sky position to each
event according to the source spatial distribution. This
distribution may be determined either by a model or by an input
image (or subimage).
- An event may be discarded based on the vignetting.
- An event may be scattered by the PSF.
- Events are discarded if located outside the FOV.
- Discarded events are assigned final
discrete SKY coordinates that are resampled within detector pixels
unless resampling is switched off.
- For each energy bin, the
RMF is used to redistribute the input energy and assign output PI
values for each photon not discarded due to vignetting or falling
outside the FOV.
- These events are then assigned times
according to the source temporal characteristics (constant,
periodic, or burst).
Sky background sources, i.e. from the output
of skyback, are identically processed. Internal background events
from the input internal background spectrum, following rescaling
to the detector area and observation exposure time, are assigned
random detector locations and times within the exposure. Events
from all sources and from the internal background are merged and
sorted on time, with an option to identify pileup. If the
simulation is split into subexpsoures, this procedure is repeated
for each subexposure, with the time-sorting, pileup calculation,
and final output completed within each interval to reduce memory
usage.
The source definition file allows one to specify the spatial,
spectral, and temporal characteristics of the source(s) to be
simulated. This file is always required. This is an ASCII file,
where each row contains comma-separated parameters
dedicated to a single source. The format of each row is:
ra, dec, NH, spec_mod, spec_par, flux, bandpass, filename, format, units, source_specs,
where ra and dec identify the position of the source to simulate
[degrees], and NH is the column density [cm^{-2}]. The spectral
characteristics may be specified in two different ways: (1) as a
single-component spectral model with one spectral parameter and
flux in a specified energy band, using the parameters spec_mod,
spec_par, flux, and bandpass; or, alternatively (2) a spectrum can
be input using the parameters filename, format, and units (see
description in the user guide). All of these parameters are
required, except for source_specs - a string that may be added to
specify the timing or spatial characteristics for sources. The
specific strings for source_specs are: pulse(period, pulse_frac); burst(tburst,
risetime, decaytime, burstratio); extmod(beta, beta, core_radius,
ellipticity, pos_angle, Rmin, Rmax); extmod(ellipse, ellipticity,
pos_angle, Rmin, Rmax); extmod(power, slope, Rmin, Rmax);
extmod(gauss, fwhm_x, fwhm_y, pos_angle); extmod(flat, Rmin,
Rmax); and image(filename, xmin, xmax, ymin, ymax). These options are
described in detail in the heasim user guide.
Setting the 'flagsubex' parameter to yes and the 'subexposure' parameter
to a value different than the 'exposure' parameter, may be used to reduce
memory usage by splitting the simulation into several separate,
consecutive sub-simulations. In this case, heasim processes the
simulated events within the time specified in 'subexposure', writes
these events to the output file, and proceeds to the next
subexposure. If 'subexposure' is equal to the 'exposure' parameter, all
events are processed together (even for 'flagsubex=yes'). If subexposure
> exposure, the subexposure durations are optimized to have less
than 500,000 counts per subexposure. By default, the parameters
'flagsubex' and 'subexposure' are set to allow the optimization mode
('flagsubex=yes' and 'subexposure =1.0e9'). This option cannot be used to
simulate variable sources.
If the 'skipfov' parameter is set to no, events outside of the
field-of-view, as defined by 'mdbfile', are not discarded.
The heasim output events file contains the following columns: the
time of the event (TIME), the SKY coordinates (X and Y), the energy
channel (PI), and a flag (PILEUP) set to 1 if the event is piled up, and 0
otherwise.
For additional details on the parameters, source definition file
format and options, the mission database content, calibration
file format, and on running heasim, please see the heasim user
guide. Support files for heasim, including the user guide,
can be obtained by anonymous FTP. The task hitomiversion can be
run to display the FTP location and names of the files.
PARAMETERS
- mission = Hitomi [string]
- Name of the mission to be simulated, e.g. Hitomi, Suzaku, XMM.
- instrume = SXI [string]
- Name of the instrument to be simulated, e.g. SXS, SXI, HXI, etc.
- rapoint [double]
- Right ascension (RA) of the pointing position. This may be different
from the source right ascension specified in the source definition file.
The units are decimal degrees in J2000 epoch.
- decpoint [double]
- Declination (DEC) of the pointing position. This may be different from the source
declination specified in the source definition file.
The units are decimal degrees in J2000 epoch.
- roll = 0.00 [double]
- Rotation angle [decimal degrees] applied to the detector when converting between RA/DEC and coordinates
aligned with the detector. A roll angle of 0.0 corresponds to the DETX and DETY detector axes aligned with the
RA and DEC axes respectively. A non-zero roll angle corresponds to a counter-clockwise rotation of the DETX and DETY
axes relative to the RA and DEC axes.
- exposure = 10000. [double]
- Exposure time [s]. Longer simulation
times result in more photons being "detected".
- insrcdeffile [filename]
- The file name of the source definition file (ASCII) containing the
characteristics of the sources that are to be simulated.
- outfile = heasim_evt.fits [filename]
- The file name of the simulated output FITS event file.
- psffile [filename NONE|file name]
- The file name with the point-spread function (PSF) information, either in PSF or EEF form,
for use in the simulation. The file format is either ASCII
or FITS (see the calibration files section of the heasim users guide). If set to Gaussian, a Gaussian PSF with
FWHM from the mission database file is used. If set to NONE, the photons are not scattered
and maintain the original source spatial distribution.
- vigfile [filename NONE|file name]
- The file name with the vignetting information. The file format is either
ASCII or FITS (see the calibration files section of the heasim users guide).
If set to NONE, no vignetting is applied.
- rmffile [filename NONE|file name]
- The file name with the response matrix file (RMF) information.
The parameter 'rmffile' is used to assign energy bins to events (PI value), since for a given input energy, it gives the
probability of redistribution of the input energy into the final output energy grid.
If the parameter is set to NONE, the final energy bin assigned to the event does not use the redistribution
matrix, but instead uses the energy grid from the ARF.
The file format is FITS (see the calibration files section of the heasim users guide).
- arffile [filename]
- The file name with the ancillary response file (ARF) information.
This file contains the effective area for different energies.
The file format is FITS (see the calibration files section of the heasim users guide).
- intbackfile [filename NONE|file name]
- The file name with the internal background spectrum of the instrument.
The file format is a standard spectral file in FITS format (see the calibration
files section of the heasim users guide). If set to NONE, heasim does not add events due to the internal background.
- (psbackfile = NONE) [filename NONE|file name]
- The file name for the sky background component from resolved background point sources.
For each source, the file contains the sky position and spectral information.
These resolved background point sources may be calculated by the task skyback.
The format is similar to the source definition file. The heasim task calculates the events
from the background point sources and adds them to the final event file.
- (difbackfile = NONE) [filename NONE|file name]
- The file name for the unresolved sky background contribution. The file contains data
for the central sky position, radial extent, and name of file for the diffuse spectrum.
Both this source file, and spectrum for the unresolved background, may be calculated by
skyback. The format is similar to the source definition file. The heasim task calculates the events
from the unresolved background and adds them to the final event file.
- (pszbackfile = NONE) [filename NONE|file name]
- The file name with the auxiliary data of the resolved background point sources.
The file contains two columns, redshift and intrinsic absorption column density of the resolved
background point sources in 'psbackfile'. These values may be calculated by skyback.
If this file is absent, all redshifts and intrinsic absorption column densities are
assumed to be 0.
- (arfrmftol = 0.01) [double]
- Tolerance required for the agreement of the RMF and ARF energy scales. The difference between the
ARF and RMF energy grid values as a fraction of the ARF bin width must be smaller than 'arfrmftol'.
If the fractional difference in energies exceeds the tolerance value, the simulation exits prematurely, notifying
the user.
- (flagsubex = yes) [boolean yes|no]
- If set to yes (optimization mode), the simulation is split into multiple observations. This may be
used to reduce memory usage (only) for sources that do not vary in time.
- (subexposure = 1.0e9) [double]
- Subexposure time [s]. If 'flagsubex' is set to yes (optimization mode with 'subexposure=1.0e9'), this parameter is used
to effectively split the simulation into multiple observations with this duration.
If greater than the 'exposure' parameter, the subexposure duration is optimized,
such that there are no more than 500,000 estimated counts per subexspoure.
- (resample = yes) [boolean yes|no]
- If set to yes, the coordinates of simulated photons are recalculated by placing them at a random location within a detector pixel.
- (skipfov = no) [boolean yes|no]
- If set to yes, events out of the FOV are not discarded.
- (dtpileup = 0.0) [double]
- Timescale [s] for pileup. Two or more events are flagged if their times are
within this timescale, and in the same detector pixel. These events are flagged as
pileup events.
- (getinfile = no) [boolean yes|no]
- If set to yes, heasim_source_sample.txt is copied to the current working directory
and used in place of whatever the 'insrcdeffile' parameter
was set to. In addition, the pointing determined by the 'rapoint' and 'decpoint' parameters is
replaced by the source position.
- (filter = NONE) [string]
- NOT CURRENTLY USED, set to NONE. Specifies the instrument filter used.
- (instmode = NONE) [string]
- NOT CURRENTLY USED, set to NONE.
Specifies for example the CCD readout mode.
- (seed = 1) [integer]
- Random number generator seed; uses system time for 'seed=0'.
- (mdbfile = $ENV{LHEA_DATA}/heasim.mdb) [string]
- The name of the mission database file, which gives mission-specific parameters
necessary for the simulated observation (see the MDB file section in the heasim user guide). The default heasim.mdb
file may be found under $HEADAS/..//refdata.
- (clobber = no) [boolean yes|no]
- Overwrite the existing output file if set to yes.
- (debug = no) [boolean yes|no]
- Diagnostic output is printed to the screen if set to yes.
EXAMPLES
- Simulate a 10 ks Hitomi/SXI observation of a source characterized by the source definition file source.txt, with pointing direction 'ra=150', 'dec=50'. The input calibration EEF, RMF, and ARF files are sxi_eef.fits, sxi.rmf, and sxi.arf, respectively; and there is no vignetting, internal background, or sky background in the simulation. The subexposure option is turned off, and the output events FITS file is hitomi_sxi.fits.
heasim hitomi sxi 150.00 50.00 0.0 10000. source.txt hitomi_sxi.fits sxi_eef.fits none sxi.rmf sxi.arf none \
flagsubex=no
Please see the heasim user guide for more complex examples.
SEE ALSO
skyback
LAST MODIFIED
November 1, 2023