XRSSIM (Dec 2005) ftools.xrssim XRSSIM (Dec 2005) NAME xrssim -- Suzaku XRT+XRS simulator USAGE xrssim (see EXAMPLES) DESCRIPTION This task simulates the XRT+XRS detector on board the Suzaku satellite. This program (1) reads a photon list generated by the photon-list generator 'mkphlist', (2) simulates the process of the XRT and the XRS, and (3) outputs an XRS event FITS file. The output event file may be analyzed just like real data using standard analysis tools like xselect. The hidden parameters are optimized so that the output events simulate the actual XRT+XRS data best. Users are recommended NOT to change any hidden parameters, 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.2, 2005). The ray-tracing requires several FITS input files: mirror geometry file (e.g. 'ae_xrt0_mirror_20050505.fits'), reflectivity table file (e.g. 'ae_xrta_reflect_20050808.fits'), precollimator geometry file (e.g. 'ae_xrts_pcol_20050505.fits'), precollimator reflectivity file (e.g. 'ae_xrta_reflect_20050808.fits'), backside scatter profile file (e.g. 'ae_xrta_backprof_20050614.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'; this option is not recommended for standard use though. The thermal shield transmission is taken into account as a default (considerthermalshield = yes). DESCRIPTION OF THE XRS SIMULATOR The current XRS simulator is simplified, such that it performs a photon-to-event simulation according to the probability distribution given by the input RMF file. Actual physical processes taking place within the XRS 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 Z-Y-Z Euler angles (ea_phi, ea_theta, ea_psi). The XRS PIXEL number (0-31) is output when the ray-traced photon falls one of the 32 XRS pixels. 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. Optionally, events outside of the XRS pixels may be discarded (xrs_pixel_select=no). The XRS filter-wheel transmission may be included optionally ('xrs_filter' parameter). ALIGNMENTS Alignment parameters between the detectors are defined in the 'teldef file' (such as 'ae_xrs_teldef_20050622.fits'). At present, 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 XRS sensor. 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 (xrs_area_scale = 1.0) [real] Effective area scaling factor for XRS (must be less than or equal to 1). (xrs_rmffile = "astroe_xrs.rmf") [file name] The name of the Response Matrix File (RMF) of the XRS to be used in the XRS simulator. (xrs_efficiency=yes) [boolean] Multiply XRS efficiency? (yes/no) (xrs_pixel_select=no) [boolean] If 'yes', events fallen outside of XRS pixels will be discarded. fw_file = "none" [string] XRS Filter Wheel filter transmission file gv_file = "none" [string] XRS Gate Valve filter transmission file outfile [file name] The name of the output event FITS file. (clobber = yes) [boolean] If true, an existing file with the same name as the requested output file will be overwritten. (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 extname='EVENTS' TNAME TTYPE TUNIT 1: TIME 1D sec Detected time (astetime) of the event 2: PHA 1I ch Detected pulse height (ch) of the event, currently equal to PI 3: PI 1I ch Detected pulse height invariant (ch) of the event 4: PIXEL 1I ch Detected pixel number (0-31) of the event. PIXEL=-1 (only when xrs_pixel_select=no) means that the event have fallen outside of the pixels. 5: DETX 1I ch 6: DETY 1I ch Detected location of the event on the detector plane. 7: X 1I pixel 8: Y 1I pixel Location of the event on the sky. 9 ROLL 1E deg Roll angle of the XRS sensor at the event detection. ROLL=0 when DETY points the North, and measured in counter-clockwise. 10 FLAG_SECONDARY: Flag is on for the XRS secondary event. 11 FLAG_MIDRES: Flag is on for the XRS mid-resolution event. 12 FLAG_LOWRES: Flag is on for the XRS low-resolution event. 13: XRSX 1E mm 14: XRSY 1E mm Location of the XRT-reflected photon on the XRS detector plane (in mm). This is simulator specific information. 15: FOCX 1E arcmin 16: FOCY 1E arcmin Location of the event on the focal plane. 17: WEIGHT 1E Weight of the photons, i.e. probability of the event to be detected. 18: PHOTON_TIME 1D sec 19: PHOTON_ENERGY 1D keV 20: RA 1D deg 21: DEC 1D deg These are taken from the incident photon list. EXAMPLES 1. Simulation using photon-list file 'crab.photons' and create event FITS file 'crab.events' with the Euler angles (83.5,68.0,0.0). No filter wheels used, and events outside of the XRS pixels are NOT discarded. % xrssim default 1st Euler Angle (deg) [83.5] default 2nd Euler Angle theta (deg) [68.0] default 3rd Euler Angle psi (deg) [0.0] Name of input photon file #1 [crab.photons] Name of input photon file #2 [none] Filter selection NONE/Be50um/Be100um/Be300um [none] Discard events fallen outside of pixels [no] output event FITS file [crab.events] SEE ALSO mkphlist, xissim 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.