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

'xrtreftable' 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 tool 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 tool 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 tool 'xrtreftable' 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, so 'xrtreftable' calculates mass-absorption coefficients as a function of energy and these are stored in extension 2 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, then the output extension have 800 rows, and each reflection and transmission column is a vector with 600 elements.

The second extension in the output file holds 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 (in units of centimeters-squared per gram) for each thick material at that energy. Keywords in the header of the extension specify the material and density for each column.

PARAMETERS

telescop [string]
Mission name (value of the keyword TELESCOP to write in header keyword for CALDB.)

instrume [string]
Instrument name (value of the keyword INSTRUME to write in header keyword for CALDB.)

atomicfile [filename]
Name of the atomic data input file (FITS format with binary table extension.) If the extension is not specified in the parameter, the tool opens to 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), 5.Density (grams per cubic centimeter)
If the parameter 'atomicfile' is set to CALDB, the file is read from the calibration database.

atmscafile [filename]
Name of the atomic scattering input file (FITS format with binary table extension.) 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 tool uses the value of the parameter 'atmsctng' as the extension name. This second 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 in 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. The five columns (and units) required are: 1. Z (Atomic Number), 2.rowindex, 3. energy (eV), 4. f1real, 5. f2img.
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 SXS+SXT-S and SXI+SXT-I, the name of the extension that should be used is HENKEMODSXT. For HXI1+HXT1 and HXI2+HXT2, the name of the extension that is used should be HenkeSskChantler.

atmsctng [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 (in 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 (and unit) 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 (and unit) required is ANGLE (radian)

mirrorfile [filename]
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:

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

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

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

(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 date as of which the xrtreftable output file is valid. This date is written to the output file in the keyword CVSD0001, required for any file entered into CALDB.

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

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 xrtreftable output file is valid. This date is written to the output file in the keyword CVST0001, required for any file entered into CALDB.

desc [string]
CALDB description.

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

(chatter = 1) [integer]
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]
Log filename. If set to DEFAULT uses the name of the task and, if preceded by '!', overwrite the file if it exists. If set to NONE no log file is created.

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

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

(mode = ql) [string]
Mode to query the parameter file. Acceptable values include: "ql (query and learn/remember), "hl" (hidden and learn/remember), "q" (query but don't remember), "h" (hidden).

EXAMPLES

    1. Run the tool, entering all the relevant information that is appropriate for the telescope HXT1. 
    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 tool with all the arguments in the user's ~/pfiles/xrtreftable.par file, without prompts to enter parameters. 
    xrtreftable mode=h

    SEE ALSO

    LAST MODIFIED

    February 2016