xrtraytrace -- Perform raytracing simulations of X-ray telescopes, calculating photon paths, PSF, EEF, and effective area
'xrtraytrace' is a standalone raytracing code that simulates the passage of photons through a thin-foil type X-ray telescope, from the aperture through to the focal plane. Although the code is generalized to be used with any X-ray telescope of the thin-foil variety, it is currently only tested for the telescopes aboard Hitomi. Several options are possible for generating the source photons that are injected into the telescope, and details of these are described below, under the description of the input parameter 'source'. The raytracing code can be used to generate grids of results corresponding to multiple source positions relative to the telescope optical axis. The code calculates the path of each photon, and the final impact coordinates on the focal plane, if the photon survived to reach it. It also calculates the Point Spread Function (PSF), Encircled Energy Fraction (EEF), and effective area (EA). Intermediate impact coordinates along the photon paths can also be recorded in a photon history file. This file also contains many aggregate and statistical quantities pertaining to the raytrace run. The raytracing code itself does not apply any specific instrumental masks, so the focal plane is effectively infinite in extent. Focal-plane photons must be filtered for impact on a specific instrument or focal-plane region. No detector efficiency effects are applied in the raytracing, so the effective area calculated is that for the telescope only (i.e., the effective area file is not an "ARF"). Note that the effective area includes only paths that include a "double reflection" (i.e. exactly one front-side primary mirror reflection and exactly one front-side secondary mirror reflection). The path may include other interactions such as transmission and pre-collimator reflection.
The smallest mirror and pre-collimator foil unit that the raytracing code deals with is a section of a foil that is bounded by two alignment bars in the support structure, and these alignment bars define a "sector." The smallest foil unit is named sub-foil, and each sub-foil corresponds to a unique row in the FITS Telescope Description File (TDF), whose columns define the sub-foil properties.
The coordinate system used by 'xrtraytrace' is inherited directly from the TDF. In this system the positions of the mirror foils are fixed by describing a point on a foil by its radius from a central axis, and its height from the focal plane. The focal plane is the x-y plane and the z-axis is the central axis of the cylindrical telescope structure. This Cartesian frame of reference is used for all telescope components and for all photon positions and direction vectors. When misalignments are applied to the various telescope components, the abstract coordinate system remains fixed in that the x-y plane is always the focal plane, and the z-axis is always the original central telescope axis. All rotations and/or shifts are defined relative to this fixed coordinate system.
NOTE: The mirror calibration file and the 'xrtraytrace' were changed to account of any rotation of the telescope respect to the focal plane in Dec 2016. This informaton is stored in a keyword, TELFPROT that is read by 'xrtraytrace'. Previosu version of the software do not read this keyword and the results do not account for the rotation.
The TDF contains information the full geometrical structure of the telescope, as well as details of the properties of the reflective surface coatings of the mirror foils (see parameter 'mirrorfile').
Note that "old-style" TDF's (such as those for ASCA and Suzaku) do not work with the current code because the file format has evolved to become more complex.
This file describes the reflectivity and transmission properties of the telescope mirror and pre-collimator foils as follows (see parameter 'frontreffile'):
1st Extension: Front-side mirror reflectivity and surface thin-film transmission
2nd Extension: Mass-absorption coefficients of all the materials making up the surface and bodies of mirror and pre-collimator foils.
3rd Extension: Reflectivity of the back-sides of mirror foils.
4th Extension: Reflectivity of the pre-collimator foils.
(Note that 'xrtraytrace' calculates the net transmission from the front-side to the back-side of foils using BOTH the transmission data in the 1st extension and the mass-absorption coefficient data in the second extension.)
The file is generated by initially running the tool 'xrtreftable', which uses the TDF to generate the 1st and second extension. The third and fourth extension data cannot be calculated from theory and are based on measurements. The third and fourth extensions must be appended onto the file generated by 'xrtreftable'.
The raytracing code can handle both eV and keV units of energy in the reflectivity file extensions.
All of the output files are optional. However if no output files are requested, 'xrtraytrace' aborts.
1. PSF (Point Spread Function) or EEF (Encircled Energy Fraction) file. The 'xrtraytrace' code writes either a PSF image file OR an EEF file, depending on input parameter settings (see descriptions for the input parameters 'psfpars' and 'outpsffile' below).
If there are 10 or fewer energy points in the input energy grid, a PSF image or EEF function is written to a separate extension for each energy, off-axis angle, and azimuthal (roll) angle. However, if more than 10 energies are in the energy list, then the PSF or EEF is summed over all photon energies for a given pair of off-axis and azimuthal angles. A unique extension is written for each unique pair of angles.
The PSF image is normalized so that the sum over all photons in the focal plane is 1.0. The EEF is normalized so that it is 1.0 at the radial position on the focal plane of the furthest photon impact from the optical axis.
The PSF image always shows the source at the center of the image. The actual position of the center of the source can be found in the FITS header keywords XCENTER and YCENTER.
2. Effective Area (EA) file, containing the effective area (of the telescope only), as a function of energy (see description for the input parameter 'outeafile' below for details).
3. Photon history file. Records path history information for each photon, as well as aggregate and statistical quantities for the entire raytrace run. See description for the input parameter 'outphistfile' for more details about the history file contents, and caveats.
Name of the telescope description file (TDF) and the extension that holds the geometrical description of primary and secondary mirror foils (e.g. MIRROR). It is assumed that the name of the pre-collimator extension is COLLIMATOR. If CALDB is specified, the file is read from the calibration database, based on the TELESCOP and INSTRUME input parameters.
Name of the telescope description file and the extension that holds the geometrical description of the telescope support structures (e.g. OBSTRUCT). If CALDB is specified, the file is read from the calibration database, based on the TELESCOP and INSTRUME input parameters.
Name of the reflectivity file and the extension for the front-side reflectivity of the mirror foils. The extension also includes the thin surface film transmission. The names of the reflectivity and transmission columns are linked to groups of mirror foils that they apply to, by means of a column called FREFLECT in the TDF. The second extension in the reflectivity file contains mass-absorption coefficients that are used by xrtraytrace to calculate transmission probabilities of the "thick" materials (as opposed to thin films) in the telescope. If CALDB is specified, the file is read from the calibration database, based on the TELESCOP and INSTRUME input parameters.
Name of the reflectivity file and the extension for the back-side reflectivity of the mirror foils. If CALDB is specified, the file is read from the calibration database, based on the TELESCOP and INSTRUME input parameters.
Name of the reflectivity file and the extension for the reflectivity of the pre-collimator blades/foils. The pre-collimator reflectivity is the same for front-side and back-side reflection. If CALDB is specified, the file is read from the calibration database, based on the TELESCOP and INSTRUME input parameters.
Name of the file containing the scattering angle probability distributions for the direction of reflected rays relative to the specular direction. The file contains data for the front-side of mirror foils, the back-side of mirror foils, and for the pre-collimator blades. In general, foils in different physical regions of the telescope can have different scattering distributions. The column names are referenced in the SCATTER column in the TDF. This field is only used if the "scattermode" parameter is not 'none'. If CALDB is specified, the file is read from the calibration database, based on the TELESCOP and INSTRUME input parameters.
For running modes that do not take input photons from a file (see parameter 'source'), 'numphoton' is the number of input photons entering the telescope aperture for each unique value of the energy (see 'energy' parameter), and off-axis angle and azimuthal angle pairs. For running modes that do take input photons from a file, each row of the input file corresponds to one photon.
In the case that the running mode does not take input photons from a file (see parameter 'source'), the 'energy' parameter specifies the energies of the input photons in a number of different ways as follows:
For raytrace runs that use a multilayer reflectivity file (e.g. for HXT1 or HXT2), all of the raytracing energies in the raytracing energy grid must have exact values that are present in the energy grid of the reflectivity file. With option (1) above this is automatically satisfied but, for the other two options, this correspondence must be explicitly satisfied by the input list (option 2) or file (option 3). If there is a mismatch in the energy grids and the reflectivity file describes a multilayer mirror, the raytracing program stops because correct interpolation of the reflectivity cannot be guaranteed.
For running modes that do take input photons from a file, there are two options for the photon energies. First, if the keyword UNQELIST in the input photon FITS file is TRUE, then an energy grid of unique values is read from the list of numbers specified in the string 'energy'. This unique list of energies is used to pre-interpolate reflectivity and transmission values (to reduce runtime). Energy values in each row of the input photon file are then compared with the unique energy list. The second option is to use the energy values in each row of the energy column of the input photon file (one row corresponds to one photon), even if it means interpolating the reflectivity and transmission more than once for the same energy.
Random number seed. If the value is zero then the code uses the system time to generate a random number.
This parameter, a string of 6 integers, controls turning on and off the 'tilt' and 'twist' angular misalignment offsets in the TDF columns SYSTILT and SYSTWIST. The six numbers correspond to the following: (1) tilt for pre-collimator, (2) tilt for primary mirrors, (3) tilt for secondary mirrors, (4) twist for pre-collimator, (5) twist for primary mirrors, (6) twist for secondary mirrors.
A negative value of any of the six numbers turns off the corresponding misalignment component for all sub-foils in the stated category. The 'tilt' is an angular offset from the default foil position (in arcsec, a positive value specifying a rotation of the top of the foil towards the telescope symmetry axis). The 'tilt' rotation requires a pivot axis and three such axes are defined for the pre-collimator, primary, and secondary mirror foils. A single number between 0.0 and 1.0 for each of the 3 categories of foil specifies the fractional distance of the axis from the bottom edge of a sub-foil, the axis being parallel to the bottom edge of the sub-foil. The keywords in the TDF are as follows:
The 'twist' angular offset (in arcsec) is a rotation around an axis that is perpendicular to the tilt axis, intersecting it at the midpoint, and parallel to the optical axis of the telescope.
The 'misalign' parameter set should not be changed from the default values to maintain fidelity with the calibration of the telescope as embodied in the TDF. The only reason to adjust the misalign parameter set would be for fine-tuning the calibration.
Method for treating transmission of photons in the mirror and pre-collimator.
Scattering "switch" for treating scattering of photons on mirror and pre-collimator foils. If this field is not 'none', there must be a valid file in the "scatterfile" field.
Method for generating input photons for the raytracing.
Parameters of the beta model if 'source=beta' is specified.
The radius (in arcmin), of the extended source for the flat spatial distribution option, 'source=flatcircle'.
Name of the input photon file and extension for the options 'source=photonlist' and 'source=groundmodel'. In both cases the extension containing the data must be specified as part of the input file name. Each row of the file corresponds to one photon. The columns describe various attributes of the input photons. Note that the telescope coordinate system is such that the x-y plane coincides with the focal plane, and the z-axis corresponds to the telescope rotational symmetry axis.
A string containing parameters that define the entry point on the telescope aperture for single-point injection for 'source=diagnosticmode'. The meanings of the numbers are as follows:
For running modes that do not take input photons from a file, the list of numbers in the string 'offaxis' corresponds to off-axis input photon source positions (angular deviation from the telescope optical axis in arcmin).
For extended sources, the off-axis angle corresponds to the offset of the center of the source.
For each off-axis angle, the raytracing code injects 'numphoton' photons into the telescope for EACH energy in the specified energy grid. For each off-axis angle and energy pair, the roll angle can take a single value, or it can take several values in a nested loop (see parameter 'roll' below).
For each triple set of numbers consisting of energy, off-axis angle (offaxis), and roll angle, xrtraytrace injects 'numphoton' photons.
The raytraced events appears in a single output file regardless of the photon energy, off-axis angle, and roll angle (see description of the input parameter 'outphistfile' below).
For running modes that do not take input photons from a file, the list of numbers in the string 'roll' corresponds to input photon source directions that have the same angular offset (parameter 'offaxis') from the optical axis, but the photon direction vector makes different rotation angles relative to the x-axis. The units of the azimuthal, or 'roll', angle are degrees.
For the extended source options 'flatcircle' and 'betamodel', the roll angle corresponds to the rotational offset of the direction of the ray to the center of the source.
For each triple set of numbers consisting of energy, off-axis angle (offaxis), and roll angle, xrtraytrace injects 'numphoton' photons.
There are two modes of operation: (a) Normal Mode: If all of the numbers in the 'roll' list are positive, then a raytracing run is performed for each off-axis angle for every value of roll angle in the list (i.e., by means of nested loop, the total number of runs is equal to the number of off-axis angles multiplied by the number of roll angles). (b) Pair Mode: If the first value of roll in the list is negative then for each value of off-axis angle, the value of the roll angle is taken from the corresponding position in the list (i.e. the nth off-axis angle run is performed for only the nth roll angle). In the latter mode the total number of runs is simply equal to the number of off-axis angles. The values of roll angle used are the absolute values of the list members. The code checks that the number of roll angle values is exactly equal to the number of off-axis angle values. If this is not the case, the program stops.
If xrtraytrace is to be run in "Pair Mode" and the first roll angle desired in the list is 0.0, the actual value that should be used is -360.0, because -0.0 is not interpreted correctly.
The actual roll angle used for any of the numbers in the 'roll' parameter list is the modulus of the absolute value of that number, with 360 degrees. Thus, one should never require any of the roll angles for actual input to a raytrace run to be negative; a genuinely negative roll angle should have 360 degrees added to it before putting it in the list.
The raytraced events appears in a single output file regardless of the photon energy, off-axis angle, and roll angle (see description for the input parameter 'outphistfile' below).
The roll angle in xrtraytrace is not the same quantity as the satellite roll angle and the two should not be confused with each other.
This parameter defines a partial annular region on the telescope aperture that effectively restricts the entry of photons relative to the full aperture. It is used to compare raytracing simulations with ground-based experimental results since a telescope generally does not have its aperture restricted in this way in-flight. The four numbers in the input parameter string 'annulus' are defined as follows:
If the upper radius of the annulus is greater than the outer housing radius, (as defined by the keyword PMAXRAD in the TDF), the outer radius is internally set equal to the outer housing radius by the raytracing code.
If a rectangular aperture is requested, then the outer annulus radius should be set to a negative value. (See description for the input parameter 'rectangle.') Note that both the partial annulus and rectangular aperture can be turned off in this way, in which case the full telescope aperture is used (which is an annulus).
This parameter defines a rectangular region on the telescope aperture that effectively restricts the entry of photons relative to the full aperture. It is used to compare raytracing simulations with ground-based experimental results since a telescope generally does not have its aperture restricted in this way in-flight. The four numbers in the input parameter string 'annulus' are defined as follows:
If any corner of the rectangle does not lie inside the annulus that corresponds to the full telescope aperture, then the raytracing code simply uses the full annulus-shaped aperture.
The rectangular aperture can be switched off by setting either (or both) of the values of the rectangle height and width to have a negative value. If the rectangular aperture is turned off, an annular aperture is used with the parameters defined by the input parameter string 'annulus' if both the inner and outer annulus radii have positive values, otherwise the full annular aperture is used.
Name of the output effective area (EA) FITS file. It is only written if the input photons to the raytracing code are not from a file. Each extension contains the effective area versus energy function for each pair of values of the off-axis angle and the roll angle for which the raytracing run was performed.
Only photon paths that include exactly one primary mirror reflection and exactly one secondary mirror reflection (i.e. a "double reflection") contribute to the EA. The path may or may not include reflection on the pre-collimator surfaces, back-side mirror surfaces, and transmission events. Paths that do not include a double reflection are likely to appear as noise or background in real data and do not in general contribute to the principal focused image.
The EA file can be suppressed by specifying "none" for the file name.
Name of the output file containing the PSF (point-spread function) images or the EEF (encircled energy fraction). It is only written if the input photons to the raytracing code are not from a file. Two types of file can written:
The PSF/EEF file can be suppressed by specifying "none" for the file name.
Numbers in the input parameter string specify parameters for the PSF or EEF calculation as follows:
The z-coordinate (mm) of the x-y plane that are recorded as part of the final impact coordinates for photons that successfully emerge from the telescope pre-collimator, mirror, and support structure without being absorbed. The default is 0.0, which means that this "results plane" is the focal plane.
Write results to the photon history file only for those photons that impact the results plane (each row if the history file event data corresponds to one photon).
Name of the output photon history (event) file. This is a FITS file that contains detailed information about the photons that were traced and their paths.
The history file can be suppressed by specifying "none" for the file name.
The history file has two extensions:
Extension 1 (PHOTONHISTORY) contains between 12 and 45 columns, as described below.
Extension 2 (INPUTPHOTONS) contains 4 columns as follows:
The photon direction vector is referenced to the telescope coordinate frame, in which the z-axis coincides with the optical axis, and the focal plane coincides with the x-y plane. The history file contains many quantities in FITS header keywords that are aggregates or statistical constructions of useful information about the raytraced photon path histories through the telescope.
There are three options for the amount of detail that is written to the PHOTONHISTORY extension, selectable with the 'phisttype' parameter described below. Each row of data in the history file corresponds to one photon that was input to the raytracing code. Depending on what was selected for the parameter 'resplaneonly', the extension can contain information about every photon that was input to the raytracing code, regardless of the eventual fate of that photon, or it can contain information on only those photons that impacted the results plane (see parameter description for 'resultsplanez' for definition of the results plane.
The history file contains up to 45 columns. If all 45 columns are selected to be written ('phisttype=full') there are 21 columns corresponding to the x, y, and z coordinates of up to 7 interactions between the photon corresponding to a particular row, and the telescope components. The 7 sets of coordinates do not include the initial position or the final position (these are contained in separate columns).
Note that, for events that do not reach the focal plane, the final impact coordinates are not always calculated by the code in the interest of keeping the runtime as low as possible. Any coordinates in the history file columns that are not computed by the code are given the dummy value of -1.0e30, or similarly large negative number.
Note also that there are no columns giving the initial z-coordinates of the photons because, except when the source is not at infinity, they all have a single value corresponding to the z-coordinate of the aperture, which is given by the FITS header keyword, ZAPRTURE in the history file. (In the case of the 'groundmodel' option, the initial z-coordinates of the photons are specified individually and they are already in the photon list input file that must be supplied for the 'groundmodel' option.)
The 45 columns in the history file are as follows:
Designating the 4 characters of the "pathcode" portion for each interaction as ABCD, the definitions are as follows:
If 'phisttype= full', all 45 columns listed for outphistfile are written to the history file.
If 'phisttype = basic', the same columns are written as for "full", except that the 21 columns for the photon path coordinates (event1x, etc. ) are not written.
If 'phisttype = brief', only the following 12 columns are written (see original descriptions from the full set):
These columns have been described above.
Treatment of objects that are situated above and below the telescope body that are described in the AZIMUTHALSTRUCT extension of the TDF (for example, thermal shields and central cover).
If 'fastmode=yes', the raytracing code runs a factor of a few faster (depending on input parameters) than if 'fastmode=no'. However, with 'fastmode=yes', the results may not be accurate when the off-axis angle is large, the transmission significant, or misalignments severe. The 'fastmode=yes' option is intended for a fast calculation of effective area for nominal pointing positions.
The UTC date (in yyyy-mm-dd format) when this calibration data should first be used. This is the date as of which the xrtraytrace output files are valid. This date is written to all output files in the keyword CVSD0001, which is required for any file entered into CALDB.
The UTC time (in hh:mm:ss format) on the day 'validdate' when this calibration data should first be used. This is the time as of which the xrtraytrace output files are valid. This date is written to all output files in the keyword CVST0001, which is required for any file entered into CALDB.
Whether or not to overwrite any existing output file.
Chatter level to designate desired amount output. Valid numbers are integers between 0 and 3. All output is sent to the log file regardless of chatter level.
Set the name of the log file. Special values are DEFAULT and NONE for the default file name or no log file respectively. The default is the name xrtraytrace.log. If the parameter is set to an empty string, an error is generated. If the parameter begins with an exclamation point (!), then any existing log file with the chosen name is overwritten, otherwise new log information is appended to any current file with that name.
Whether or not to display debugging information (yes/no). If turned on, this parameter causes error messages to print a stacktrace in addition to the usual error message.
Record tool parameters in history keywords in all output files (yes/no)
Sets how automatic parameters are specified. Legal values are h, hl, q, and ql. Hidden parameters (h) are not presented to the user and take the default value from the parameter file, but can be specified as command-line arguments. Queried parameters (q) are prompted for input from the user, but give the default value from the parameter file as a choice. Either type with learning enabled (e.g. ql) cause the default value to change to that given in the previous run.
1. The following example runs xrtraytrace for the case of the Hitomi SXT with a point source at infinity, on-axis, full aperture illumination, 5 keV photon energy, and other options as detailed in the parameter list:
xrtraytrace mirrorfile="ah_sxs_mirror_20131001v002.fits[MIRROR]" obstructfile="ah_sxs_mirror_20131001v002.fits[OBSTRUCT]" frontreffile="ah_sxs_reftrans_20131001v002.fits[AH_SXT_FRONT]" backreffile="ah_sxs_reftrans_20131001v002.fits[REFPROBBACK]" pcolreffile="ah_sxs_reftrans_20131001v002.fits[REFPROBPCOL]" scatterfile="ah_sxs_scatter_20131001v002.fits" numphoton=10000 energy="5.0" seed=29075 misalign="0 0 0 0 0 0" transmode="none" scattermode="none" source="point" betapars="0.50 0.60 5" flatradius=5.0 psrcfile="none" diagpars="2 5 174 0.70 0.50" offaxis="0.0" roll="0.0" annulus="-1 100000.0 0.0 360.0" rectangle="0.0 0.0 -40.0 -50.0" outeafile="xrtraytrace_ea.fits" outpsffile="xrtraytrace_psf_img.fits" psfpars="1 100 0.25" resultsplanez=0.0 outphistfile="xrtraytrace_history.fits" validdate="2999-01-01" validtime="00:00:00" clobber="no" chatter=2 logfile="xrtraytrace.log" debug="no" history="yes" mode="ql"
The example run produces the output files: