SIMPUT – Simulation input
The SIMPUT (SIMulation inPUT) file format developed by Schmid et al. (2013) is a FITS-based standard for handling source descriptions for simulations of astronomical observations. It is optimized for X-Ray telescopes but can be used for different energy regimes. You can find examples of such SIMPUT files here.
SIMPUT format description
A SIMPUT file describes one or more sources by information about position, flux and energy spectrum as well as optional spatial flux distribution (“images”) and timing information (“lightcurves”). The description on this page aims to give an overview on the format. For more details, unit conventions and examples please refer to the format definition document.
The core of each SIMPUT description is contained in the “Source Catalog”, which is a binary table FITS extension called SRC_CAT. Each row in this table specifies one simulated source. The table has the following columns:
- SRC_ID (required)
- SRC_NAME (optional)
- RA (required)
- DEC (required)
- IMGROTA (optional)
- IMGSCAL (optional)
- E_MIN (required)
- E_MAX (required)
- FLUX (required)
- SPECTRUM (required)
- IMAGE (optional)
- TIMING (optional)
Columns marked as (optional) need not to be filled.
The values of E_MIN and E_MAX define a reference energy band in which the integrated spectrum of the source has a flux of FLUX. The latter value is used to rescale the spectrum referenced by the FITS Extended Filename Syntax expression contained in the string SPECTRUM (this approach allows to reuse the same spectral shape for several sources, as is necessary, e.g., when simulating the X-ray background as the sum of thousands of point sources). It points to a row in another FITS extension (which may be located in another file). In this table, the spectrum is defined. The preferred way for the definition is the Mission-Independent Spectrum. A binary table containing such spectra has the following columns:
- NAME (optional)
- ENERGY (required)
- FLUXDENSITY (required)
Each entry in the columns ENERGY and FLUXDENSITY contains a vector of energy or flux density values which define the spectral shape. The absolute height is neglected but substituted by the renormalization using the reference energy band flux.
Optional detail can be added to each source by defining the spatial brightness distribution with a FITS-image. If desired, such an image can be referenced with the entry of IMAGE in the same way as a spectrum. In addition, the image can be rotated and scaled by giving the respective values in the fields IMGROTA and IMGSCAL. For details about the process behind the evaluation of images please refer to Christian Schmid’s PhD thesis.
With the reference contained in the field TIMING, information about the source’s temporal behaviour can be given. This can either be achieved by a direct lightcurve or by a Power Spectral Density (PSD). For more information about the usage of timing information please refer to Christian Schmid’s PhDthesis and the format definition document.
Tools
The SIMPUT-package is downloaded and maintained as a subpackage of the SIXTE-package using GIT (for installation instructions see Installation). It consists of the SIMPUT library and various predefined, stand-alone tools for basic SIMPUT tasks. For a lot of excercises the tools provide everything what is needed to create the required SIMPUT files or handle them properly. The most important are listed in the following:
- simputfile: This tool produces a source catalog containing one source with the specified properties. It supports XSPEC and ISIS parameter files for the spectral property definition and ASCII tables with information about the lightcurve or PSD. Additionally, if no such information is prepared, it can be assembled from basic properties such as black body components and powerlaw index for the spectrum as well as Lorentzian functions for PSD properties. Image references are also supported.
- simputmerge: This tool merges multiple SIMPUT files to one.
- simputverify: This tool compares the specified SIMPUT file to the standard and gives an error if a conflict is encountered.
- galabs: This tool applies the effect of Galactic absorption to the sources specified in the SIMPUT file. The galactic NH is determined by using a high-resolution map of the LAB 21cm radio survey of the full sky. The sources’ spectra are folded with an absorption of the column density at their position and the flux is recalculated.
- simputmultispec: In this advanced tool 2D maps can be used to specify how parameters of a model change over the observed image. An exmaple on how this tool is used can be found below.
Library
Most of SIMPUT (and SIXTE) is implemented in C-language. The SIMPUT C-library contains low- and high-level routines for access and writing of SIMPUT files. It is used by the SIXTE package but provides functionality for creating more elaborated source catalogs than the SIMPUT tools. It makes extensive use of the CFITSIO library and features functions for handling large numbers of individual sources.
Example: Usage of simputmultispec
simputmultispec is the perfect tool to simulate a more complicated setup of an extended source. While the standard simput tools already allow to add an image as a brightness distribution, this tool takes it even a step further. In addition to the brightness distribution, images of model parameters (such as, e.g., temperature or abundance) can be specified. Currently this option is working for ISIS or XSPEC models. Internally, not for every single value a different spectrum is used, but one avarage spectrum for a certain range of values. The number of different values for which the model should be calculated can be specified.
Below an example call in the case of XSPEC is given.
simputmultispec Simput=example_multispec.simput \ ImageFile="data/A2146_SXB.fits" \ Emin=0.5 Emax=10.0 \ srcFlux=7.995076796356145e-12 \ ParamFiles="data/A2146_kt.fits;data/A2146_ab.fits" \ XSPECFile=mod.xcm \ ParamNames="2;3" \ ParamsNumValues="8;8" \ ParamsLogScale="yes;no" \ RA=239.064583333 Dec=66.3470277776 \ Elow=0.1 Eup=15 Estep=0.001 \ chatter=0 clobber=yes
- ImageFile: Image of the Brightness Distribution
- Emin/Emax: Energy band for which the source flux is given
- srcFlux: Source flux of the complete image as given
- ParamFiles: A list of parameter images (separated by a ‘;’)
- XSPECFile: The XSPEC model file (called ISISFile for ISIS)
- ParamNames: Semicolon separated list of parameter names (real names in ISIS and number of the parameters in XSPEC), as given in the Parameter File. The first parameter in the list corresponds to the first image given.
- ParamNumValues: Number of different parameter values for which the spectra are calculated (again, a list for each parameter).
- ParamLogScale: Specify if the parameter values are linear (“no”) or logarithmically (“yes”) spaced.
- RA/Dec (important): Here the RA/Dec values as given in the brightness distribution image for the WCS coordinate system should be given (named CRVAL1 and CRVAL2 in the FITS Header) unless you intentially want to put your source at a different position on the sky.