XISSIM (Mar 2008) suzaku.xis XISSIM (Mar 2008) NAME xissim -- Suzaku XRT + XIS simulator USAGE xissim (see EXAMPLES) DESCRIPTION 'xissim' simulates the XRT + XIS system on board the Suzaku satellite. This program conducts the photon-by-photon simulation as it (1) reads a photon list generated by the photon-list generator 'mkphlist', (2) simulates the photon processes in the XRT and the XIS, (3) outputs an XIS event FITS file. The output event file may be analyzed just like real data using standard analysis tools such as 'xselect'. The 'xissim' also includes the function of 'mkphlist', and can perform the photon list generation for simulation by itself, with enable_photongen=yes. Parameters with '(PhotonGen)' in the PARAMETERS section below are used for the 'mkphlist' function. See the 'mkphlist' help file for a detailed explanation. Some hidden parameters are optimized so that the output events simulate the actual XRT + XIS data best. Users are recommended NOT to change them, unless testing non-standard instrumental environments. DESCRIPTION OF THE XRT SIMULATOR The XRT simulator is based on the ray-tracing program originally coded by Richard Fink ('xrrt' version 2.0, 1998), which has been updated by the Suzaku XRT team (version 6.4, 2006). The ray-tracing requires several FITS input files: - mirror geometry file (e.g. "ae_xrt0_mirror_20060710.fits"), - reflectivity table file (e.g. "ae_xrta_reflect_20060710.fits"), - backside scatter profile file (e.g. "ae_xrta_backprof_20060719.fits") - thermal shield transmission file (e.g. "ae_xrta_shield_20051129.fits") The first file defines geometry of the thin-foil mirror (such as the foil configuration and the obstruction by the alignment bars and sector masks), and the second file contains X-ray reflectivity data for a single foil as a function of surface energy and incident angle. The reflectivity-table file is created by the 'xrrtrt' ftool using the "atomfile" and "henkefile", which define basic atomic parameters and scattering parameters respectively. Instead of using the precalculated reflectivity table file, the foil reflectivity may be calculated on the fly from "atomfile" and "henkefile" by forcing "atomcaldb=yes" though this option is not recommended for a standard use. DESCRIPTION OF THE XIS SIMULATOR The current XIS simulator is simplified, such that it performs a photon-to-event simulation according to the probability distribution given by an input RMF file. Actual physical processes taking place within the XIS detector are NOT simulated. It is assumed that the instrumental efficiency, as well as the pulse height distribution, is included in the RMF file. For each incident photon energy, the simulator judges whether the photon is detected or not by generating a random number according to the detection efficiency given by the RMF, and, if detected, the output pulse height is determined according to the pulse height distribution in the RMF. The satellite aspect is specified by the set of Z-Y-Z Euler angles (ea1, ea2, ea3). Actual positions of the photons on the focal plane, as well as the RA and DEC of the detected events, are also output in the event file. By default, events outside of the XIS CCD chips are discarded (xis_chip_select=yes). The output FITS file contains event and GTI extensions. The current version of 'xissim' does not consider non X-ray background, event pile-up, event grade, nor CCD exposure frames. Though the output event files contains all the columns in the FITS files of the real data, the GRADE column is filled with 0, while the PHA column has the same value as the PI column. The output FITS file also contain the information of the faked photons. Make sure that you set up correct calibration files, or 'xissim' perhaps outputs a wrong result without any warning. The 'xissim' version 2007-05-28 or later fills the STATUS column appropriately as the 'xisputpixelquality' ftool does, which had been filled with 0 before. To do this, two calibration files of - CCD bad pixel file (e.g. "ae_xi0_badcolum_20070418.fits") - 55Fe calibration source area file (e.g. "ae_xi0_calmask_20060731.fits") must be specified by "badcolumfile" and "calmaskfile" parameters. The observation mode is read from header keywords in the primary extension of "phafile", e.g. WINOPT, WIN_ST, WIN_SIZ, CI, SCIN, SCIYn. When "phafile=none", which is the default, WINOPT=0, WIN_ST=0, WIN_SIZ=1024, and CI=0, i.e. window off and SCI off, are assumed. This feature can be turned off by setting "enable_pixq=no" for backward compatibility. ALIGNMENTS Alignment parameters between the detectors are defined in the "teldef" file (such as "ae_xi0_teldef_20050922.fits"). With the "teldef" file, "ae_xi0_teldef_20050922.fits", no misalignment is taken into account; namely, the XRT is pointing the satellite Z-axis direction, and the optical axis is at the center of the XIS sensor. With newer teldef file, "ae_xi0_teldef_20051009.fits" or later, in orbit alignment measurements between sensors are considered. PARAMETERS (telescop = SUZAKU) [string] Telescope name should be SUZAKU. instrume [string] Instrument name (XIS0,XIS1,XIS2,XIS3). (rand_seed = 7) [integer] Random number seed. (rand_skip = 0) [integer] Random number skip number. (simulation_mode = 0) [integer] Simulation mode (0:discard, 1:weight). (teldef = CALDB) [file name] The name of the teldef file for the XIS. (leapfile = CALDB;$ENV{LHEA_DATA}/leapsec.fits) [file name] Name of the leap second file. The default value is set to indicate that 'xissim' will search for the file in CALDB first and then in the LHEA_DATA directory if necessary (the actual path for the HEADAS installation in use will be shown). (enable_photongen = no) [boolean] If yes, enable on-the-fly photon generation. photon_flux [real] Photon flux in photons/s/cm2 (PhotonGen). flux_emin [real] Emin (keV) for photon flux (PhotonGen). flux_emax [real] Emax (keV) for photon flux (PhotonGen). (geometrical_area = 1152.41) [real] XRT geometrical area in cm2 (PhotonGen). (scale_factor = 1.0) [real] Fudge scale factor (PhotonGen). (start_time = 0.0) [real] Start time of the observation (PhotonGen). spec_mode [integer] Spectrum mode (0:QDP-SPEC, 1:MONOCHROME) (PhotonGen). image_mode [integer] Image mode (0:FITS-IMAGE, 1:POINT-LIKE, 2:UNIFORM-SKY) (PhotonGen). time_mode [integer] Time mode (0:CONSTANT, 1:POISSON) (PhotonGen). limit_mode [integer] Limit mode (0:NPHOTON, 1:EXPOSURE) (PhotonGen). qdp_spec_file [filename] Qdp spectral file name (PhotonGen). energy [real] Photon energy in keV when MONOCHROME (spec_mode = 1) (PhotonGen). ra [real] R.A. (deg) for POINT-LIKE / UNIFORM-SKY (image_mode = 1 or 2) (PhotonGen). dec [real] DEC (deg) for POINT-LIKE / UNIFORM-SKY (image_mode = 1 or 2) (PhotonGen). sky_r_min [real] Min radius (arcmin) for UNIFORM-SKY (image_mode = 2) (PhotonGen). sky_r_max [real] Max radius (arcmin) for UNIFORM-SKY (image_mode = 2) (PhotonGen). fits_image_file [filename] Image FITS file name (PhotonGen). nphoton [integer] Number of photons to generate (PhotonGen). exposure [real] Exposure time in sec (PhotonGen). pointing [string] Pointing type, AUTO/USER. ref_alpha [real] R.A. of the sky reference position. ref_delta [real] DEC. of the sky reference position. ref_roll [real] Roll angle of the sky reference. The "ref_alpha", "ref_delta", "ref_roll" parameters specify the sky reference, which determines the reference (RA, DEC) and roll angle ROLL of the SKY coordinates (X, Y). These parameters are only asked when "pointing=USER". When "pointing=AUTO", the sky reference (RA, DEC) is read from the attitude file header keywords RA_NOM, RA_DEC, specified by the "attitude" parameter unless "attitude=NONE", and ROLL is set to 0.0. When "pointing=AUTO" and "attitude=filename", they are calculated from the default Euler angles, specified by the "ea1", "ea2", and "ea3" parameters, as RA=ea1, DEC=90-ea2, ROLL=0.0. infile[1-8] [file name] The name of the input photon-list file generated by 'mkphlist'. Up to 8 files can be specified at the same time. (gtifile = none) [file name] GTI file for TIME offset. The PHOTON_TIME column in the photon file usually starts from 0.0 s unless otherwise specified, and it is treated as the time offset relative to the GTI. When the "exposure" is longer than the specified GTI or "nphoton" is large enough to exceed incident photons during the GTI (i.e. photon flux * the GTI duration), the GTI wrap-around occurs, namely, TIME starts again from the beginning of the GTI. (date_obs = "2000-01-01T00:00:00") [string] Observation start date, only used when gtifile="none". (date_end = "2000-01-01T00:00:00") [string] Observation end date, only used when gtifile="none". When date_obs = date_end, the original TIME column value in photon FITS file is used. (attitude = none) [file name] Attitude file name to read ZYZ-Euler angles. ea1 [real] Default 1st Euler Angle (degree). ea2 [real] Default 2nd Euler Angle (degree). ea3 [real] Default 3rd Euler Angle (degree). The "ea1", "ea2", "ea3" parameters are asked even if you specify an attitude file at the "attitude" parameter and used when the input attitude file does not have data on simulating time frames (GTI) specified by the "gtifile" parameter. These parameters are also used to calculate the sky reference (ref_alpha, ref_delta, ref_roll), when "pointing=AUTO" and "attitude=NONE". (aberration = yes) [boolean] Correct for aberration or not. (aperture_cosine = yes) [boolean] Consider aperture decrease by cosine factor or not. (minangle = 0.0) [real] Minimum telescope angle in degree. (maxangle = 360.0) [real] Maximum telescope angle in degree. (minradius = 57.96755) [real] Minimum telescope radius in mm. (maxradius = 200.10644) [real] Maximum telescope radius in mm. (mirrorfile = CALDB) [file name] The name of the mirror description file to be used in the XRT simulator. (mirror = "mirror") [string] FITS binary extension name (EXTNAME keyword) in the "xrtfile" for the mirror description FITS table. (obstruct = "obstruct") [string] FITS binary extension name (EXTNAME keyword) in the "xrtfile" for the obstruction description FITS table. (quadrant = "quadrant") [string] FITS binary extension name (EXTNAME keyword) in the "xrtfile" for the quadrant geometry description FITS table. (pcol = "pcol") [string] Pre-Collimator description extension name. (reflectfile = CALDB) [file name] The name of the FITS file that contains the reflectivity tables needed for the XRT simulator. (backproffile = CALDB) [file name] Backside scatter profile file (shieldfile = CALDB) [file name] XRT thermal shield transmission file xis_rmffile = "ae_xiN_YYYYMMDD.rmf" [file name] The name of the Response Matrix File (RMF) of the XIS to be used in the XIS simulator. The RMF can be generated by 'xisrmfgen' ftool. (xis_contamifile = CALDB) [file name] XIS OBF contamination file name. You may set "none" to ignore the XIS contamination. (xis_efficiency = yes) [boolean] Multiply XIS effciency or not. (xis_chip_select = yes) [boolean] Discard events fallen outside of pixels (xis_ccd_expo = 8.0) [real] Exposure time for CCD. outfile [file name] The name of the output event FITS file. (clobber = yes) [boolean] If yes, an existing file with the same name as the requested output file will be overwritten. (phafile = none) [file name] Name of the input spectrum or event file to get observation mode. If "NONE", WINOPT=0, WIN_ST=0, WIN_SIZ=1024, and CI=0, i.e. window off and SCI off, are assumed. (enable_pixq = yes) [boolean] If yes, enable to fill the STATUS column in the output event file. (hotpixfiles = none) [file name] Names of input hot pixel files. Hot pixels excluded onboard XIS-DE is stored in the DarkInit and DarkUpdate files in the XIS trend archive. Multiple file names can be specified by the comma/SPACE/TAB/semicolon separated list, or "@FILELIST" to read the file names from an indirect file of FILELIST. (badcolumfile = CALDB) [filename] Input file that describes the XIS bad columns and flickering pixels, or "CALDB" to automatically read from the calibration database. The name is ae__badcolum_YYYYMMDD.fits where is a string set to xi0, xi1, xi2, xi3 indicating the sensor and YYYYMMDD is the release date. (calmaskfile = CALDB) [filename] Input file that describes the irradiation area of 55Fe calibration source on the XIS CCD, or "CALDB" to read from the calibration database. The name is ae__calmask_YYYYMMDD.fits where is a string set to xi0, xi1, xi2, xi3 indicating the sensor and YYYYMMDD is the release date. (anl_verbose = -1) [integer] ANL verbose level (-1:full, 0:minimum). (anl_profile = yes) [booean] Enable ANL module profiling. (num_event = -1) [integer] Number of events (All events: -1, No events: 0). (event_freq = 10000) [integer] Event number printout frequency. (chatter = 2) [integer] message chatter level (0:min, 2:norm, 5:max). OUTPUT FORMAT OF A EVENT FITS FILE No. Type EXTNAME BITPIX Dimensions(columns) PCOUNT GCOUNT 0 PRIMARY 8 0 0 1 1 BINTABLE EVENTS 8 84(23) 0 0 1 Column Name Format Dims Units TLMIN TLMAX 1 TIME 1D s 2 PHA 1I chan 0 4095 3 PI 1I chan 0 4095 4 STATUS 1J 5 GRADE 1I 6 SEGMENT 1I 7 RAWX 1I pixel 8 RAWY 1I pixel 9 ACTX 1I pixel 10 ACTY 1I pixel 11 DETX 1I pixel 1 1024 12 DETY 1I pixel 1 1024 13 FOCX 1I pixel 14 FOCY 1I pixel 15 X 1I pixel 1 1536 16 Y 1I pixel 1 1536 17 XISX 1E pixel 18 XISY 1E pixel 19 WEIGHT 1E 20 PHOTON_TIME 1D s 21 PHOTON_ENERGY 1D keV 22 RA 1D deg 23 DEC 1D deg 2 BINTABLE GTI 8 16(2) 1 0 1 Column Name Format Dims Units TLMIN TLMAX 1 START 1D s 2 STOP 1D s EXAMPLES 1. Simulate with the photon-list file "crab.photons" and create event FITS file "xis1_crab.evt" with the Euler angles (83.5, 68.0, 0.0) with the XIS RMF of "xis1_crab.rmf" % xissim xissim version 2008-03-03 Written by Y.ISHISAKI (TMU) Instrument Name (XIS0,XIS1,XIS2,XIS3)[XIS1] XIS1 Name of input photon file #1[crab.photons] crab.photons Name of input photon file #2[none] none default 1st Euler Angle (deg)[83.63] 83.63 default 2nd Euler Angle theta (deg)[67.97] 67.97 default 3rd Euler Angle psi (deg)[0.0] 0.0 Name of input RMF file[ae_xi1_20060213.rmf] xis1_crab.rmf output event FITS file[xis_crab.evt] xis_crab.evt BUGS SEE ALSO mkphlist, xissimarfgen, xisrmfgen, xisputpixelquality AUTHOR This program was developed mostly in the ASTRO-E ANL environment by Yoshitaka Ishisaki (TMU) and Yoshihiro Ueda (ISAS/JAXA). The XRT ray-tracing library 'xrrt' was originally developed by Richard Fink (GSFC) and updated for Suzaku by Suzaku XRT team. LAST MODIFIED March 2008