Heasim is a multi-mission high-energy astrophysics simulation tool. Heasim 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 are for specifying the mission name and the instrument names for that 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, decpoint define the pointing direction, and the roll parameter the rotation angle (all in decimal degrees). The exposure time in seconds is entered in as the parameter exposure. The source(s) position; and spectral, spatial, and temporal characteristics are input via the source definition file (parameter insrcdeffile). Point spread function, 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 tool and the output files from skyback may be input to heasim. The parameter psbackfile accepts a file containing a list of the resolved background point sources as calculated and output by skyback. The parameter pszbackfile accepts a file that lists the point source intrinsic redshifts and absorptions 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 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.
Heasim calculates simulated events for each input source in the source definition file (and background) with the following steps. (1) The absorbed input spectrum (in photons cm-2 s-1 vs keV) based on the input spectral model or user spectrum file is calculated in each energy bin in the arf file. (2) This is then converted to cts/bin vs bin on this input energy grid by multiplying by the exposure time and effective area. (3) The sum over all bins yields the total number of events. For each source, the code loops over each input energy bin, and over the counts in each bin (4) 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, and (6) "scattered" by the PSF. (7) Events are discarded if located outside the FOV, and (8) assigned final discrete sky coordinates that are resampled within detector pixels unless resampling is switched off. For each energy bin, (9) 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 (10) 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 parameters, separated by commas, and is 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 identifies the position of the source to simulate (degrees), and NH is the column density. The spectral characteristics may be specified in two different ways: (a) 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 (b) 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 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); 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 the subexposure, writes these events to the output file and proceeds to the next subexposure. If the 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 the mdb file 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 set to 1 if the event is piled up (and 0 otherwise), PILEUP.
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.
1. Simulate 10 ksec Hitomi SXI simulation 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; 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.