NAME

xrtreftable - Calculates the probability of reflection and transmission of X-ray photons impinging on a reflecting surface as a function of energy and incident angle. Also calculates mass-absorption coefficients of constituents of the reflecting foils.

USAGE

xrtreftable telescop instrume atomicfile atmscafile atmsctng energyfile anglefile mirrorfile outfile outext roughmodel desc

DESCRIPTION

The xrtreftable task calculates the probability of reflection (or reflectivity) and transmission of a photon impinging on a reflecting surface. The reflection and transmission depend on the energy of the photon and incident angle. The task obtains information on the composition of the mirror surface from an extension called SURFACE in the telescope description file (TDF). Both single-layer and multi-layer coatings for the mirrors are supported by xrtreftable. The reflection and transmission probabilities are written to the first extension of the output file as a function of energy and incident angle. The task supports more than one group of mirror foils, whereby the mirrors in the same group share the same surface coating properties (for example, in a real X-ray telescope, mirror groups having different surface compositions may be arranged to be located at different radii ranges). The xrtreftable task writes the reflectivity of one mirror group as one column, and the corresponding transmission for that group as another column, with each column containing a two-dimensional array of probability as a function of energy and incident angle.

In raytracing applications, transmission through the "thick" components of mirror foils (as opposed to the "thin" surface) may also be required. Therefore, xrtreftable calculates mass-absorption coefficients as a function of energy and stores these values in the second extension of the output file, one column per thick material. The thick material properties are also specified in the SURFACE extension of the TDF.

OUTPUT

The first extension of the output FITS file contains the reflection and transmission probabilities as a function of energy and incident angle. The first column is a repeat of the energy grid given in the input file. There are reflection and transmission columns for each group from the mirror surface file. These columns are vectors, with one element per angle. Thus, if there are 800 energies and 600 angles, the output extensions have 800 rows, and each reflection and transmission column is a vector with 600 elements.

The second extension in the output file contains the mass absorption coefficients for the thick-layer components in the telescope. Again, the first column is a copy of the energy grid. The following columns are the mass-absorption coefficients [cm^{2} g^{-1}] for each thick material for each energy. Keywords in the header of the extension specify the material and density for each column.

PARAMETERS

telescop = HITOMI [string]
Mission name (also the value of the keyword TELESCOP to write to the output file for CALDB).

instrume = SXS [string]
Instrument name (also the value of the keyword INSTRUME to write to the output file for CALDB).

atomicfile = CALDB [filename CALDB|file name]
Name of the atomic data input file (FITS format with binary table extension). If the extension is not specified in the parameter, the task opens the first binary table in the file. The five columns (and units) required are: 1) Z (atomic number), 2) chemical symbol, 3) name, 4) weight [amu], and 5) density [g cm^{-3}]. If the parameter is set to CALDB, the atomic data are read from a file in the calibration database (CalDB).

atmscafile = CALDB [filename CALDB|file name]
Name of the atomic scattering input file (FITS format with binary table extensions). This file is used to calculate the optical constants (as a function of energy) of the telescope reflecting mirror surface materials. Different extensions of the file contain different compilations of data in the literature. The extension name can be specified in the extended file name format (name followed by extension name enclosed by []). If the extension is not specified in the parameter, the task uses the value of the parameter 'atmsctng' as the extension name. The 'atmsctng' parameter is also used if 'atmscafile' is set to CALDB. The file contains the real and imaginary components of the atomic scattering form factors as a function of energy [eV]. Each extension of the file can contain a different compilation of form factors (the actual extension to be used is specified as part of the input file name string). The energy range of the form factors must cover the energy range for which the user is attempting to make a reflectivity/transmission file.

Details of the compilations of atomic scattering factors in each extension, as well as references, can be found in the FITS file header. For the Hitomi SXS+SXT-S and SXI+SXT-I, the name of the extension that should be used is HENKEMODSXT. The same extension name is to be used for both instruments aboard XRISM. For HXI1+HXT1 and HXI2+HXT2, the name of the extension that should be used is HENKESSKCHANTLER.

atmsctng = Henke2013 [string]
Name of the extension in the atomic scattering file ('atmscafile') containing the atomic scattering data.

energyfile [filename]
The energy grid, either as a list of energies [keV], or as a FITS file with the grid in a binary table extension named ENERGYGRID (in the latter case the units can be eV or keV). The column name required is ENERGY [eV or keV].

anglefile [filename]
Name of the angle grid input file. This must be a FITS file with a binary table extension named ANGLEGRID. The column required is ANGLE [radians].

mirrorfile = CALDB [filename CALDB|file name]
Name of the mirror surface input file. This must be a FITS file with a binary table extension named SURFACE. This file contains the information about the layers (either single layer with only a substrate, or multi-layer with multiple layers of coatings above a substrate) of material on the surface of the mirror, separated into groups. The file should be sorted by group, then by layer. The eight columns (and units) required are:

If the 'mirrorfile=CALDB', the mirror file (telescope description file, or TDF) is retrieved from the CalDB.

outfile [filename]
Name of the output file for the reflectivity table.

outext = AH_SXT_FRONT [string]
Extension name for the output reflectivity table.

roughmodel = NC [string NC|DW|NONE]
Name of the model to calculate roughness (DW = Debye-Waller, NC = Nevot-Croce).

(roughkey = ROUGHMOD) [string]
Keyword name to write in header to store the roughness model.

(validdate = "2999-01-01") [string]

The UTC date (in YYYY-MM-DD format) when this calibration data should first be used. This is the earliest date that the xrtreftable output file is valid. This date is written to the output file in the keyword CVSD0001, required for any file entered into the CalDB.

(validtime = "00:00:00") [string]

The UTC time (in hh:mm:ss format), together with the day 'validdate', that corresponds to the earliest time and date that xrtreftable output file is valid. This is the time and data that the xrtreftable output file is valid. This information is written to the output file in the keyword CVST0001, required for any file entered into the CalDB.

desc = "XRT foil reflectivity and transmission" [string]
Value to write for the CalDB description keyword, CDES0001, in the output file.

(clobber = no) [boolean yes|no]
Overwrites the existing output file if set to yes.

(chatter = 1) [integer 0|1|2|3]
Chatter level for output. Set to 0 to suppress output, or to 1, 2, or 3 for increasing the chatter of the output.

(logfile = !DEFAULT) [string DEFAULT|NONE|file name]
Log file name. If set to DEFAULT, uses the name of the task and, if preceded by "!", overwrites the file if it exists. If set to NONE, no log file is created.

(debug = no) [boolean yes|no]
Diagnostic output is printed to the screen if set to yes.

(history = yes) [boolean yes|no]
Records tool parameters in HISTORY.

EXAMPLES

  1. Run the task, entering all the relevant information that is appropriate for the Hitomi telescope HXT1.
    2. xrtreftable atomicfile="atomicData_1997-11-01.fits[ATOMDATA]"
                 atmscafile="atomic_scattering.fits[HenkeSskChantler]" 
                 energyfile=energy_grid_4to120keV.fits 
                 anglefile=angle_grid_ah_hxt_reflect_20081103.fits 
                 mirrorfile="ah_hx1_mirror_20131001v001.fits[SURFACE]"
                 outfile=xrtreftable.fits 
		 outext=HITOMI_HXT_FRONT 
                 roughmodel=NC 
                 telescop=HITOMI 
		 instrume=HXT1 
                 validdate="2014-01-01" 
		 validtime="00:00:00"
                 desc="XRT foil reflectivity and transmission"
  2. Run the task, entering all the relevant information that is appropriate for the XRISM Resolve telescope.
    3. xrtreftable atomicfile=CALDB
                 atmscafile=CALDB
	    	 atmsctng=HENKEMODSXT
                 energyfile=energy_grid_rsl.fits
                 anglefile=angle_grid_rsl.fits
                 mirrorfile=CALDB
                 outfile=xrtreftable_resolve.fits 
		 outext=XRISM_XMA_FRONT
                 roughmodel=NC
                 telescop=XRISM
                 instrume=RESOLVE
                 validdate="2019-01-01" 
		 validtime="00:00:00"
                 desc="XMA foil reflectivity and transmission"

    SEE ALSO

    xrtraytrace, ahgetvector

    LAST MODIFIED

    February 22, 2024