Using simx
Note: This describes the basic version of simx; version 2 can use a new type of input file, the SIMPUT FITS file. Some examples of SIMPUT usage can be found in the test/ directory, but otherwise the documentation is still being written.
simx uses the ever-popular IRAF interface that should be familiar to FTOOLS and CIAO users. It expects to find its parameter file in a directory pointed to by the PFILES system variable. If you are an FTOOLS user, you probably have a directory 'pfiles' in your home directory, e.g. /home/user/pfiles. Running simx-setup, described below, will set up the PFILES environment properly so that this is done automatically.
Setting up to run simx
The mission and, or instrument description is provided by data in the file xselect.mdb, in the simx/inputs/ directory. simx must be able to find this file, which it does via the SIMX system variable. This is set by the simx-setup.{csh|sh} script, found in simx/bin. Thus, before running simx, you must first run the setup script via:
unix% source /path/to/simx/bin/simx-setup.csh
or (if running a BASH-type shell)
unix% ./path/to/simx/bin/simx-setup.sh
Running simx
After running simx-setup, all should be ready. To run simx, simply set the simulation parameters in simx.par to the desired values by editing the file directly in an editor (this method is somewhat risky) or using pset, e.g.:
unix% pset simx OutputFileName = MySimRun
unix% pset simx Exposure=10000
Refer to Complete list of user parameter options for a list of parameter options, and then run simx:
unix% /path/to/simx/bin/simx
The code will generate an output event file in the current directory which can be viewed with ds9 or used with the CIAO tools dmextract or the FTOOL xselect. A modified version of xselect.mdb is needed to use these files with xselect; it can be found in the test directory of simx. To use this file with xselect instead of the default xselect.mdb that comes with FTOOLS, set the following environment variable:
unix% setenv XSELECT_MDB /path/to/simx/test/xselect.mdb
Astro-H SWG members can also view this page, where Jelle de Plaa shows how to do a complete simulation of a galaxy cluster (Note: Requires Astro-H SWG password).
Complete list of user parameter options
| OutputFileName | The output event file stem; final file will be this step with "_evt.fits" appended |
| PointingRA | Right Ascension (in decimal degrees) of the pointing direction of the satellite |
| PointingDec | Declination (in decimal degrees) of the pointing direction of the satellite |
| Exposure | Exposure time (in seconds) |
| UseSimput | Yes or No; default is No |
| SimputFile | Name of SIMPUT file, used if UseSimput=Yes. Note that if in use, a SIMPUT file overrides the source flux, position, and spectrum information as all of this information and more is stored in the SIMPUT file. SIMPUT files can also model time-varying sources, including pulsars and QPOs. |
| SourceFlux | Total source flux (in erg/cm2/s); a source with 1E-11 erg/cm2/s is reasonably bright |
| SourceImageType | Either Image or Point; if Image, a FITS image file must be provided as the SourceImageFile parameter. If Point, the point source position must be provided in SourcePointRA and SourcePointDec |
| SourcePointRA | Right Ascension (in decimal degrees) of the point source; only used if SourceImageType = Point. If this value and the SourcePointDec match the PointingRA and PointingDec, the source will be centered on the detector |
| SourcePointDec | Declination (in decimal degrees) of the point source SourceImageFile FITS-format file containing the image to simulate |
| SourceSpectrumType | One of XSPEC_File, Sherpa_File, or Mono; see spectrum notes for more information, |
| SourceSpectrumFile | The name of source spectrum file, if SourceSpectrumType=XSPEC_File or Sherpa_File |
| MonoEnergy | The energy (in keV) of the mono-energetic spectrum if SourceSpectrumType = Mono |
| RandomSeed | The initial random seed. If you set this to -1, the code will use the current time to seed the random number generator, while any other value will always generate the same sequence of random numbers |
| MissionName | Currently, can be set to Astro-H, Athena, XraySurveyor, NGHXT, or microX |
| InstrumentName | Allowable settings for this depend upon the Mission setting and the values available in the xselect.mdb. Currently, for Athena this can be set to XIFU (for the calorimeter array) or WFI (the Wide Field Imager). For Astro-H, this can be SXS, HXI, or SGD. |
| FilterName | This should likely be left to the default value of None, unless you have a specific desire to test a filter. See the xselect.mdb file for possible filter values for each mission/instrument pair. |
| ScaleBkgnd | Linear scale factor for background. By default set to 1.0, but can be modified to test the impact of higher or lower values of the background. |
| OutputSimput | IF a user-defined source has been set up in simx, should simx output an equivalent SIMPUT file? This is a Boolean, defaults to yes. This SIMPUT file can then be used in subsequent runs, or sent to a colleague, in the certain knowledge that the same source will be used. It can also be merged with other SIMPUT files using routines in the bin/ directory. |
| File_bkgnd | Filename, including full path, of the desired background pha file if a non-standard background is desired. Otherwise, setting this to $XSELECT_MDB will ensure it picks up the value from the xselect.mdb file |
| File_arf | Filename, including full path, of an effective area file if a non-standard effective area is desired. Otherwise, setting this to $XSELECT_MDB will ensure it picks up the value from the xselect.mdb file |
| File_rmf | Filename, including full path, of a response file if a non-standard one is desired. Otherwise, setting this to $XSELECT_MDB will ensure it picks up the value from the xselect.mdb file |
Using simx output files
simx outputs FITS files in the OGIP 'Event File' format. This format can be read directly by saoimage / ds9, and by the FTOOL xselect. xselect uses the same xselect.mdb as simx, and so the one step that must be done before running xselect is to set the XSELECT_MDB environment variable to point to the correct xselect.mdb file. By default it reads a standard xselect.mdb file in the FTOOLS distribution, but this can be changed using the command:
unix% setenv XSELECT_MDB $SIMX/inputs/xselect.mdb (CSH version) or
unix% set XSELECT_MDB $SIMX/inputs/xselect.mdb
unix% export XSELECT_MDB (BASH version)
After that, xselect will automatically pick up the correct mission when the simx output files are read and will use the proper binning and column names for the extraction.