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.

  1. 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.
  2. 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.
  3. The sum over all bins is calculated to provide the total number of events.
  4. 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).
  5. An event may be discarded based on the vignetting.
  6. An event may be scattered by the PSF.
  7. Events are discarded if located outside the FOV.
  8. Discarded events are assigned final discrete SKY coordinates that are resampled within detector pixels unless resampling is switched off.
  9. 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.
  10. 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

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

    2. Please see the heasim user guide for more complex examples.

    SEE ALSO

    skyback

    LAST MODIFIED

    November 1, 2023