xrtraytrace - Perform raytracing simulations of X-ray telescopes, calculating photon paths, PSF, EEF, and effective area
The xrtraytrace task 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. 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 (also referred to as an event 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 "ancilliary response file", or 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). However, the path may include other interactions in addition to a double-reflection, 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 bound by two alignment bars in the support structure; these alignment bars define a "sector". The smallest foil unit is named a 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 internally by xrtraytrace is inherited directly from the TDF. This system is "look-down", and 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. However, the directions of input and output photons are specified in the satellite coordinate system, which differs from the TDF system by a rotation around the z-axis. This rotation is specified by the keyword TELFPROT in the TDF.
Note that versions of xrtraytrace prior to 1.10.4 suffered from a bug in which the pre-collimator reflectivity was inadvertently replaced by the back-side mirror reflectivity.
Required:
Examples:
ah_sxs_mirror_20140101v003.fits (Hitomi SXT-S)The TDF contains information on 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 (such as those for ASCA and Suzaku) do not work with xrtraytrace because the file format has evolved to become more complex.
Examples:
ah_sxs_reftrans_20140101v003.fits (Hitomi SXT-S)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 xrtreftable task, which uses the TDF to generate the first and second extensions. 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.
Optional:
All of the output files are optional. However, if no output files are requested, xrtraytrace aborts.
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 in order for the sum over all photons in the focal plane to be equal to 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.
This file contains the effective area (of the telescope only) as a function of energy (see description for the input parameter 'outeafile' below for details).
This file, also known as the raytracing event 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 file and TDF extension that holds the geometrical description of the primary and secondary mirror foils. 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 keywords.
Name of the file and TDF extension that holds the geometrical description of the telescope support structures. If CALDB is specified, the file is read from the calibration database based on the TELESCOP and INSTRUME keywords.
Name of the reflectivity file and 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 keywords.
Name of the reflectivity file and 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 keywords.
Name of the reflectivity file and 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 keywords.
Name of the file containing the scattering angle probability distributions for the direction of reflected rays relative to specular reflection in which the reflected angle is equal to the incident angle. 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 indexed 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 keywords.
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 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 the Hitomi HXT-1 or HXT-2), all of the raytracing energies in the raytracing energy grid must have the 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, an energy grid of unique values is read from the list of numbers specified in the 'energy' parameter. This unique list of energies is used to pre-interpolate reflectivity and transmission values (to reduce run time). 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 generator seed. The system time is used if 'seed=0'.
This parameter 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, and (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 three 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 that specify the three fractions are as follows:
The twist angular offset [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 rotation is clockwise, looking down on the focal plane from the telescope aperture.
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 foils.
Scattering switch for treating scattering of photons on mirror and pre-collimator foils. If this parameter is not NONE, 'scatterfile' must be assigned the name of a valid file.
Method for generating input photons for the raytracing.
Parameters of the beta model if 'source=BETAMODEL' is specified.
The radius [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, either forming a nested loop, or associating one roll angle value with each off-axis angle (see parameter 'roll' below).
For each triple set of numbers consisting of energy, off-axis angle, and roll angle, xrtraytrace injects 'numphoton' photons.
The raytraced events appear 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 have a photon direction vector that makes different (counter-clockwise) rotation angles relative to the telescope x-axis. The units of the azimuthal, or 'roll', angle are degrees.
For the extended source options 'source=FLATCIRCLE' and 'source=BETAMODEL', the roll angle corresponds to the counter-clockwise rotational offset of the direction of the ray to the center of the source, relative to the telescope x-axis.
For each triple set of numbers consisting of energy, off-axis angle, and roll angle, xrtraytrace injects 'numphoton' photons.
There are two modes of operation:
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 appear 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, 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 'rectangle' are defined as follows:
If any corner of the rectangle does not lie inside the annulus that corresponds to the full telescope aperture, 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 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', unless the outer annulus radius is negative, in which case the full annular aperture is used.
Name of the output effective area (EA) FITS file. This file is only written if the input photons to the raytracing code are not from a file. Each extension contains the effective area vs. 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 (often referred to as stray light), are likely to appear as noise or background in real data, and do not in general contribute to the principal focused image.
Name of the output file containing the PSF images or the EEF. This file is only written if the input photons to the raytracing code are not from a file. Two types of files can be written:
Numbers in the input parameter string specifying parameters for the PSF or EEF calculation as follows:
The z-coordinates [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 value means that this "results plane" is the focal plane.
If 'resplaneonly=yes', xrtraytrace will 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:
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 the selection for the 'resplaneonly' parameter, 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) and are written in the TDF frame, not in the physical telescope frame as the other coordinate columns are.
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 run time 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 a 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 'source=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 'source=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:
A=(interaction type)
BC=(impacted object)
D=(impacted face)
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 above for the full set):
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 is significant, or misalignment is severe. The 'fastmode=yes' option is intended for a fast calculation of effective area for nominal pointing positions.
If any raytracing output files are to become calibration files, 'validdate' is the earliest UTC date (in YYYY-MM-DD format) for which this calibration data is valid. This date is written to all output files in the keyword CVSD0001, which is required for any file entered into CALDB.
If any raytracing output files are to become calibration files, 'validtime' is the UTC time (in hh:mm:ss format) on the day 'validdate', which together represent the earliest date and time for which this calibration data is valid. This date is written to all output files in the keyword CVST0001, which is required for any file entered into CALDB.
1. The following example runs xrtraytrace for the case of the Hitomi SXT-S with a point source at infinity, on-axis, full aperture illumination, 5 keV photon energy, and other options as detailed in the parameter list below.
xrtraytrace mirrorfile="ah_sxs_mirror_20140101v003.fits[MIRROR]" obstructfile="ah_sxs_mirror_20140101v003.fits[OBSTRUCT]" frontreffile="ah_sxs_reftrans_20140101v003.fits[AH_SXT_FRONT]" backreffile="ah_sxs_reftrans_20140101v002.fits[REFPROBBACK]" pcolreffile="ah_sxs_reftrans_20140101v002.fits[REFPROBPCOL]" scatterfile=ah_sxs_scatter_20140101v001.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
This example run produces the following output files: