Welcome to the Arcus simulator!
This software was put together between Summer 2014 and Summer 2018 by Jörn Wilms with input from Andy Ptak, Randall Smith, Ryan Allured, Randy McEntaffer, Mark Bautz, Moritz Guenther, and many others. It is a prototype implementation of a simulation and data reconstruction pipeline for this mission that includes most of the relevant detector physics and reconstruction algorithms.
The software has only been tested on Linux (specifically ubuntu 16.04), it should work on Mac, but I am giving no guarantees or support since I do not have access to a Mac-System for testing.
Before installation, make sure the following software packages are available:
- perl 5 and the following non-standard perl modules:
- List::MoreUtils (liblist-moreutils-perl)
- Astro::FITS::CFITSIO (libastro-fits-cfitsio-perl)
- Scalar::Util::Numeric (libscalar-util-numeric-perl)
- Math::Random (libmath-random-perl)
- Parallel::ForkManager (libparallel-forkmanager-perl)
- Term::ProgressBar (libterm-progressbar-perl)
- XML::LibXML (libxml-libxml-simple-perl)
Values in parentheses list the Ubuntu package names where available. Other packages should be installed via CPAN, see http://www.cpan.org/modules/INSTALL.html for instructions on how to do this.
- HEASOFT available from https://heasarc.gsfc.nasa.gov/lheasoft/download.html
- SIMPUT and SIXTE available from https://www.sternwarte.uni-erlangen.de/research/sixte/simulation.php
MAC users: please follow the installation instructions for MACs on this web page TO. THE. LETTER. and do not make any assumptions that you can take any shortcuts.
- isis and s-lang (if you want to use the visualization scripts), available from http://space.mit.edu/asc/isis/ as well as the s-lang xfig module (https://www.jedsoft.org/fun/slxfig/) and the Remeis isisscripts https://www.sternwarte.uni-erlangen.de/isis/.
Installation of Arcus-SIXTE
Installation from the tarball
To install Arcus-SIXTE, download the newest version from
decrypt it with
gpg -d ARCUS-Sixte.tar.gz.gpg -o ARCUS-Sixte.tar.gz
and untar it somewhere:
tar xzvf ARCUS-Sixte.tar.gz
Furthermore, download the ARCUS calibration files that are needed for the simulation from
decrypt it with
gpg -d ARCUS-Sixte-CALDB.tar.gz.gpg -o ARCUS-Sixte-CALDB.tar.gz
and untar them IN THE SAME DIRECTORY in which you untarred Arcus-SIXTE.
SIMULATING ARCUS OBSERVATIONS
First SIXTE and ARCUS-SIXTE need to be set up:
If you use a csh-derivate:
setenv SIXTE /path/to/your/sixte/install source $SIXTE/bin/sixte-install.csh setenv ARCUS /path/to/your/arcus/install source $ARCUS/arcus-install.csh
If you use bash or some other sh -derivate:
export SIXTE=/path/to/your/sixte/install . $SIXTE/bin/sixte-install.sh export ARCUS=/path/to/your/arcus/install . $ARCUS/arcus-install.sh
where the ARCUS environment variable should point at the top directory of the arcus tree (if a/b/c is the directory into which you untarred
Arcus-SIXTE, then ARCUS should be /a/b/c/arcus
Generating a new SIMPUT file
Sources are defined using the SIMPUT format, to ensure the portability of the sources. A SIMPUT-file can easily be generated from an XSPEC model file (an xcm-file) or an ISIS par-file. The programs used for this use the local XSPEC or ISIS installation, i.e., all local models are available. Since SIMPUT-files include fluxed spectra, they are portable and can be used for simulations even on machines that do not have the local model available. Note that since ARCUS is very high resolution, you need to make sure that the ARCUS resolution is adequately oversampled. The recommendation is to use something like 50000 energy bins in the interval from 0.1 to 2.5keV.
The distribution comes with a few examples in $ARCUS/pipelines/objects and with bash-scripts that generate the SIMPUT files:
cd $ARCUS/pipeline/objects ./mcrab.bash ./apec_cold.bash
A full description of how to generate SIMPUT files is contained in the
Running ARCUS-Sixte simulations
A full simulation run from the SIMPUT file to the final extracted spectrum and event list is performed with
arcus_pipeline.pl --simput=objectname.simput --exposure=123456
where the exposure time is in seconds. By default the output is written in a directory whose name is based on the file name of the simput file (the directory name is the basename of the SIMPUT-file without extensions). Alternatively, set the output directory name with the –outputdir argument.
The pipeline script has many additional arguments which you should leave at their default values. Please contact Joern Wilms if you need to use them.
The simulation pipeline performs the following steps:
- generate input photons with SIXTE-tool phogen
- map these photons onto the ARCUS focal plane CCDs with arcus_channel.pl
- simulate the photon detection with SIXTE tool gendetsim
- perform pattern recombination with SIXTE tool evpat
- correct photon energies for each grade with ARCUS tool pha2pi
- grade events with the ARCUS tool arcus_reconstruct.pl
- generate channel and order dependent binned spectra with arcus_pha.sl
During the runs you will be seeing some warning messages from the various tools. These can be safely ignored.
Steps 3-5 are run in parallel for each CCD. By default, all available cores are used (up to 16). If a different number of cores should be used, use the –max_processes argument of arcus_pipeline, e.g.,
arcus_pipeline.pl .... --max_processes=5
to limit the pipeline to 5 cores.
After the simulation run, the following files are available in outputdir:
- photons.fits.gz : all source photons
- focalplane.fits.gz: photons hitting the focal plane
- impact_ccd01.fits.gz … impact_ccd16.fits.gz: impact positions of photons on the 16 CCDs. Note: missing files indicate that no photon hit a CCD
- raw_ccd01.fits.gz … raw_ccd16.fits.gz: raw events from each CCD (including splits)
- graded_ccd01.fits.gz: event lists for each CCD, after split recombination and PHA to PI conversion
- arcusevents.fits.gz: event file containing all graded events.
The FITS column names in arcusevents.fits.gz have the following meaning:
- TIME: arrival time of the event
- FRAME: CCD frame number of the event
- CCDID: ID of the CCD on which the event was detected
- PI : pulse invariant reconstructed energy of the event
- RAWX : impact position of the event on the CCD in pixels (x-coordinate)
- RAWY : impact position of the event on the CCD in pixels (y-coordinate)
- TYPE : event grade, ASCA notation
- FOCX : x-coordinate of impact in focal plane coordinates (mm)
- FOCY : y-coordinate of imapct in focal plane coordinates (mm)
- CCDENERGY: energy corresponding to the PI value (keV)
- DETX : impact position on the CCD (mm, reconstructed from RAWX)
- DETY : impact position on the CCD (mm, reconstructed from RAWY)
- CHANNEL: reconstructed ARCUS grating channel (0-3)
- ORDER : reconstructed ARCUS order (integer, -10000 means no order could be assigned)
- REALORDER: Order calculated from impact position and CCD energy (real)
- MLAMBDA: m times lambda obtained from CCD energy and realorder
- LAMBDA: reconstructed wavelength (A)
- ENERGY: reconstructed gratings energy (keV)
- ALPHA : angle along dispersion direction between impact and optical axis (deg)
- BETA : angle perpendicular to dispersion direction (deg)
- X : impact position in focal assembly, x-coordinate (mm)
- Y : impact position in focal assembly, y-coordinate (mm)
- Z : impact position in focal assembly, z-coordinate (mm)
The following columns contain diagnostic information, they will not be available in flight event files:
- RA : original sky position of the source (this is NOT a reconstructed RA!)
- DEC : original sky position of the source (this is NOT a reconstructed DEC!)
- PH_ID: array containing the IDs of the photons causing this event (note: in case of pile up, multiple photons can result in one event; use this in combination with the PH_ID columns in the other FITS files to trace the event back to its original photon(in photons.fits.gz)
- SRC_ID: source(s) from which the original photon(s) were emitted
- PILEUP: flag denoting that this event is due to pile up
FOCX/FOCY: the focal plane coordinate system is a virtual coordinate system. Starting at CCD01, the x-coordinate is measured along the DETX coordinate of each CCD, ignoring any CCD gaps. This is useful for plotting, but not for much else. The y-coordinate equals DETY.
It will sometimes be necessary to rerun the event grading, e.g., if different extraction strategies are to be tested. To do so cd into outputdir (!) and rerun arcus_reconstruct.pl:
arcus_reconstruct.pl [options] .
note the dot at the end.
The following extraction options are available:
- –arcwidth: width of the extraction region perpendicular to the dispersion direction (mm)
- –energywidth: maximum allowed deviation in keV between the CCD energy and the theoretical photon energy from the grating equation for a photon to be assigned to a given order (keV; default: 0.1keV)
- –efwhm : dito maximum allowed deviation in CCD resolution units (FWHM; default: 1.)
- –zeroxwidth: x-width of the 0 order eclusion region (mm)
- –zeroywidth: y-width of the 0 order exclusion region (mm)
- –minarea : minimum effective area at which to consider a grating order (NOT YET USED)
NOTE 1: changes of the above values also affect the effective area and response matrix.
NOTE 2: Other options of the script are for specialists and should not be used.
For visualization purposes, the following s-lang scripts are available (detailed usage instructions are available for each script by invoking it with the –help option):
- arcus_plot_banana.sl: make a pdf of a banana plot for a CCD
This script needs to be run on a graded event file such as graded_ccd01.fits (etc.) or on arcusevents.fits.gz. For example
arcus_plot_banana.sl --ccd=5 --channel=2 ./arcusevents.fits.gz
This produces the file arcus_banana.pdf
- arcus_plot_focalplane.sl: plot an image of the whole focal plane in FOC coordinates. Example:
- arcus_plot_ccdimage.sl: plot an intensity image for a graded_ccd or raw_ccd event file. Example: