NAME

USAGE

DESCRIPTION

The rslmkrsp task is a script that runs rslrmf and xaarfgen to make a Resolve spectral response (RSP) file that combines the RMF (redistribution matrix file) with the auxiliary response file (ARF). The task is equivalent to separately running xaarfgen and rslmkrmf with 'outrsp=yes', except that rslmkrsp results in a more accurate effective area function for bright sources, and rslmkrsp has additonal functionality for mitigating the effects of false low-res secondary (Ls) events and anomalous branching ratios. The rslmkrsp task calculates a more accurate effective area because the telescope effective area functions have different energy dependennce for different pixels, and the task accounts for pixel-to-pixel variation in the grade fractions that contribute to the spectrum that is extracted for spectral fitting. Such pixel-to-pixel variation in the grade fractions increases with increasing source brightness and affects the relative weights of the telescope effective area functions for each pixel. For the purpose of the rslmkrsp task, there is no simple definition of what constitutes a bright source. However, the spatial variation in grade fractions can be examined with the task rslbratios. When this spatial variation is negligible, the combined spectral response from the RMF and ARF, made by rslmkrmf and xaarfgen respectively, is the same as the single spectral response made by rslmkrsp. Regardless of source brightness, the line-spread-function (LSF) properties of the spectral response made by the two methods are identical.

The user is directed to the help files for rslmkrmf, rslrmf, and xaarfgen for more information about the functionality and usage of rskmkrsp. Many of the parameters for rslmkrsp are passed directly to one of the two subtasks (xaarfgen or rslrmf) and are therefore the same as the parameters for those tasks. Parameters that are unique to rslmkrsp allow users to modify the calculation of grade fractions by selecting an energy range and by specifying whether or not to include Ls events. These parameters are 'gfelo' and 'gfehi' for specifying the lower and upper energy respectively for calculating grade fractions, and the Boolean 'includels' for including or excluding Ls events. The restricted energy range enables more accurate calculation of the grade fractions (and therefore net effective area) by mitigating the effects of anomalous branching ratios. The option to include or exclude Ls events allows two extremal effective area functions to be calculated (lower and upper limits respectively), as a mitigation strategy for dealing with false Ls events. The task rslbratios can be used to calculate diganostic functions that can guide setting the 'gfelo', 'gfehi', and 'includels' parameters.

A useful feature of rslmkrsp for generating the effective area that is not available when xaarfgen is run by itself, is that a pixel list can be specified (using the 'pixlist' parameter), instead of a region file by setting 'regionfile=NONE'. If 'pixlist' and 'regionfile' are both not NONE, then the regionfile takes precedence, and 'pixlist' is ignored. Only region files in DET coordinates are supported. The full array (excluding pixel 12) can be specified by setting 'regionfile=ALL'. Note that if both 'pixlist' and 'regionfile' are NONE, rslmkrsp stops.

Both of the tasks rslrmf and xaarfgen called by rslmkrsp can have long run times, so a run of rslmkrsp can potentially take hours to complete. However, you can do quicker initial assessments by first choosing 'whichrmf=S' (redistribution matrices with only the Gaussian core components of the LSF). You can also quickly compare results using rslmkrsp with results using the regular method of running rskmkrmf (with whichrmf=S') and xaarfgen, using the raytracing event file made by rslmkrsp as input to the standalone run of xaarfgen.

PARAMETERS

inevtfile [filename]

Name of input event file used to calculate the grade and pixel weighting factors.

outfileroot = grdcorresp [filename]

Output root name for all output files.

includels = yes [boolean yes|no]

Include or exclude Ls events in grade fraction calculations.

gfelo = 3.0 [double]

Lower energy [keV] for calculating grade fractions.

gfehi = 12.0 [double]

Upper energy [keV] for calculating grade fractions.

(splitrmf = no) [boolean yes|no]

If 'splitrmf=yes', split the RMF/RSP into core and ELC responses.

(elcbinfac = 32) [integer]

If 'splitrmf=yes', 'elcbinfac' is the rebinning factor for the ELC component of the RMF/RSP, which must be an exact divisor of 'nchanin'. If 'splitrmf=no', 'elcbinfac' is ignored.

(splitcomb = no) [boolean yes|no]

If 'splitrmf=yes' and 'splitcomb=yes', the two response matrices (corresponding to the core and ELC components) will be placed into a single file.

(resolist = 0) [string 0|1|2|3|4|ALL]

List of grades (ITYPE). ITYPE=0 for grade Hp, ITYPE=1 for Mp, ITYPE=2 for Ms, ITYPE=3 for Lp, and ITYPE=4 for Ls. Multiple numerical values may be entered separated by a comma (e.g. 'resolist=1,2,3'). If 'resolist=ALL', all grades are considered.

(secondaries = yes) [boolean yes|no]

If 'secondaries=yes' an attempt will first be made to find unique secondaries calibration, otherwise Mp and Lp will be used for Ms and Ls, respectively.

(pixlist = 0-35) [string]

List of pixels in the form of comma-separated ranges, e.g., 'pixlist=0-3,7,13-25,30'. If 'regionfile' is not NONE, then 'regionfile' takes precedence over 'pixlist', and 'pixlist' is ignored.

(teldeffile = CALDB) [filename CALDB|file name]

Input teldef file name. If set to CALDB, the file is read from the calibration database, CalDB.

(rmfparamfile = CALDB) [filename CALDB|file name]

Name of the input RMF parameter file. If set to CALDB, the file is read from the CalDB.

(whichrmf = L) [string S|M|L|X]

Type of RMF to construct: (S)mall, (M)edium, (L)arge, or (X)tra-large.

(eminin = 0.0) [double]

Minimum energy [eV] of the RMF matrix input energy grid.

(dein = 0.5) [string]

Energy bin width [eV] for each energy interval of the input energy grid for the RMF matrix. If a single value (e.g., 'dein=0.5') is input, a constant energy bin width for the entire matrix is used. To create an energy grid starting at 'eminin' with variable bin width, the user may input multiple values separated by commas (e.g., 'dein=0.5,2.0'). The number of channels in each energy interval is specified with 'nchanin'. Note that if 'splitrmf=yes', then only a single energy range is allowed (i.e., only one value of 'dein' is permitted).

(nchanin = 60000) [string]

Number of channels in each energy interval of the input energy grid for the RMF matrix. If a single value (e.g., 'nchanin=60000') is input, a constant energy bin width for the entire matrix is used. To create an energy grid starting at 'eminin' with variable bin width, the user may input multiple values separated by commas (e.g., 'nchanin=26000,6500'). In this case multiple grids are created with numbers of bins given by each value, and variable widths given by the corresponding value of "dein'. The 'dein' and 'nchanin' parameters must have the same number of entries, and the values in 'nchanin' must be integers. Note that if 'splitrmf=yes', then only a single energy range is allowed (i.e., only one value of nchanin is permitted).

(useingrd = yes) [boolean yes|no]

If 'useingrd' is set to yes, the output energy grid is identical to the input energy grid and the output grid parameters are ignored. In this case 'nchanin' and 'dein' must have single values. If 'useingrd' is set to no, the output grid is determined by the 'eminout', 'deout', and 'nchanout' parameters.

(eminout = 0.0) [double]

Minimum energy [eV] of the RSP EBOUNDS extension (output) energy grid; this parameter is ignored if 'useingrd=yes'.

(deout = 0.5) [double]

Width of the RSP EBOUNDS extension (output) energy grid bins [eV]; this parameter is ignored if 'useingrd=yes'.

(nchanout = 60000) [integer]

Number of channels in the RSP EBOUNDS extension (ouput) energy grid; this parameter is ignored if 'useingrd=yes'.

(rmfthresh = 1.0e-9) [double]

Lower threshold for the RSP matrix. If the calculated matrix value is less than 'rmfthresh' it is set to 0 before being recorded in output RSP file.

(emincont = 10.0) [double]

Lower energy limit [eV] of electron loss continuum.

xrtevtfile [filename]

Name of event/history file created by the raytracing program xrtraytrace, and used by xaarfgen. If 'xrtevtfile' does not exist, xaarfgen creates it by running xrtraytrace. If 'xrtevtfile' is the name of an existing file that was previously created by xaarfgen, this file is used instead of creating a new one.

source_ra = 150.0 [double]

Right ascension (RA, degrees) of the X-ray source for which the ARF is to be created. For 'sourcetype=FLATCIRCLE' or 'sourcetype=BETAMODEL', 'source_ra' is the RA of the center of the source. For 'sourcetype=IMAGE', the parameter 'source_ra' represents the RA position of the targeted source within the image. If there is no obvious source, 'source_ra' should be set to the RA position of the center of the image.

source_dec = 50.0 [double]

Declination (DEC, degrees) of the X-ray source for which the ARF is to be created. For 'sourcetype=FLATCIRCLE' or 'sourcetype=BETAMODEL', 'source_dec' is the DEC value of the center of the source. For 'sourcetype=IMAGE', the parameter 'source_dec' represents the DEC position of the targeted source within the image. If there is no obvious source in the image, 'source_dec' should be set to the DEC position of the center of the image.

(nompntpars = "43.0 65.0 130.0 43.0 65.0") [string]

This parameter is only used if no exposure map is input to xaarfgen ('emapfile=NONE'). The parameter consists of a string of five numbers as follows: (1) RA of satellite pointing direction, (2) DEC of satellite pointing direction, (3) roll angle of satellite, (4) RA of the telescope optical axis, and (5) DEC of the telescope optical axis. However, note that the option 'emapfile=NONE' is still experimental and not recommended.

emapfile = [filename]

Name of the exposure map file (created by the task xaexpmap) containing histograms of satellite attitude and related quantities, including partial pixel exposure information. There is also an effective exposure time image in the primary extension of the exposure map file, but it is not needed by xaarfgen.

qefile = CALDB [filename CALDB|NONE|file name]

Name of the file containing the quantum efficiency (QE) for the detector. If the parameter is set to CALDB, the file is read from the CalDB. For Xtend, the QE is combined with the optical blocking layer (OBL) transmission. Spatial dependence of the QE is treated by xaarfgen for both the Resolve and Xtend instruments.

(obffile = CALDB) [filename CALDB|NONE|file name]

Name of the optical blocking filter file (needed for Resolve only). If the parameter is set to CALDB, the file is read from the CalDB.

(fwfile = CALDB) [filename CALDB|NONE|file name]

Name of the filter wheel filter file (needed for Resolve only). If the parameter is set to CALDB, the file is read from the CalDB, using the FILTER keyword in 'emapfile' to determine which CalDB filter file to retrieve. If the parameter is set to NONE, the filter wheel is effectively removed (this will never happen inflight, but the option is available for theoretical investigations and ground data analysis).

contamifile = CALDB [filename CALDB|NONE|file name]

Name of the file containing information to calculate the transmission due to contaminants on the detector as a function of time, energy, and detector position. If the parameter is set to CALDB, the file is read from the CalDB. This file for both Resolve and Xtend has so far had a column density of 0.0 for all contaminants since the launch of XRISM.

(abund = 1.0) [string]

Relative abundances of contaminants modifier. Either several values, or a single value can be specified in the string 'abund'. If there is more than one value, the number of values must be equal to the number of contaminant components in the contamination CalDB file, and each value of the abundance modifier multiplies the abundance of the corresponding component, in the order that the component columns appear in the contamination file. If there is only one numerical value in the string 'abund', then that single value multiplies the abundances of all of the contaminant materials in the calibration file.

(cols = 0.0) [string]

Additional column densities for contaminants [1E18 cm^{-2}]. The column densities of all of the contaminant materials in the calibration file are modified by adding values from this parameter to the value in contamifile. The number of numerical values in the parameter string must be the same as the number of values in the string for the 'abun' parameter. If there is only one value, that value is applied to all of the contaminant components.

(covfac = 1.0) [string]

Partial covering modifier for contaminant materials. The partial covering factor of all of the contaminant materials in the calibration file are modified by multiplying them by values from this parameter. The number of numerical values in the parameter string must be the same as the number of values in the string for the 'abun' parameter. If there is only one value, that value is applied to all of the contaminant components.

gatevalvefile = CALDB [filename CALDB|file name]

Name of the Resolve gate valve calibration file. This file is only necessary for Resolve observations that have the gate valve closed (for which the value of the GATEVALV keyword in 'emapfile' will be 'CLOSED'). The file accounts for the blocking and attenuation effects of the gate valve. If 'gatevalvefile=CALDB', the gate valve file in the CalDB is used.

erange = "0.50 17.0 2.0 8.0" [string]

A string containing four numbers corresponding to two energy ranges in units of keV. The first and second numbers correspond to the minimum and maximum energy, respectively, of the valid data in the output ARF file (points outside this range are filled with zeros). Restricting the energy range to a narrower band may be used to shorten the run time if a restricted energy range is sufficient for the application (but note that the range should not be less than 4 keV or so). The third and fourth numbers in the input parameter string are only relevant if 'sourcetype=IMAGE' (one of the extended source options), and are set to the lower and upper energy bound, respectively, of the input image. Important note: due to the particular ways that xaarfgen works to calculate the effective area, the actual energy range of the output ARF may not always exactly match the request in the 'erange' parameter. This is a feature, not a bug. If the actual energy range of the effective area is not satisfactory, rslmkrsp must be run again with new numbers in the first and second positions of the 'erange' parameter.

onaxisffile = CALDB [filename CALDB|file name and extension]

Name of the file and extension that contains the on-axis telescope effective area, appropriate for the instrument, pre-calculated on a fine energy grid. If the parameter is set to CALDB, the file is read from the CalDB.

onaxiscfile = CALDB [filename CALDB|file name and extension]

Name of file and extension that contains the on-axis telescope effective area, appropriate for the instrument, pre-calculated on a coarse energy grid. If the parameter is set to CALDB, the file is read from the CalDB.

regionfile [filename file name|NONE|ALL]

Name of the source region selection file, in DET coordinates. The format is that of a standard SAO region file. Only region files in DET coordinates are supported. If 'regionfile=ALL' then all pixels (except for pixel 12) will be used and the 'pixlist' parameter is ignored. If 'regionfile=NONE' then the pixels listed in the 'pixlist' parameter are used.

(rslgapreg = no) [boolean yes|no]

This is a parameter normally used by xaarfgen to treat realistic pixel geometries with inter-pixel gaps. However, the parameter has not yet been implemented in rskmkrsp, so has no effect. Resolve pixel gaps are treated as an empirical correction to the effective area, using the standard DET coordinate grid geometry and keywords in CalDB.

(doublesonly = no) [boolean yes|no]

If 'doublesonly=yes', the output RSP file will contain the effectve area only for photon paths through the telescope that contain a double reflection event (a primary mirror foil reflection immediately followed by a secondary mirror foil reflection). Double reflection events may include other interactions with the telescope. If 'doublesonly=no', all pathways through the telescope contribute to the effective area in the output RSP file.

mirrorfile = CALDB [filename CALDB|file name and extension]

Name of the telescope description file (TDF) and the extension (e.g., MIRROR) that holds the geometrical description of primary and secondary mirror foils. It is assumed that the name of the pre-collimator extension is COLLIMATOR. If 'mirrorfile' is set to CALDB, the file is read from the CalDB.

obstructfile = CALDB [filename CALDB|file name and extension]

Name of the telescope description file (TDF) and the extension (e.g., OBSTRUCT) that holds the geometrical description of the telescope support structures. If the parameter is set to CALDB, the file is read from the CalDB.

frontreffile = CALDB [filename CALDB|file name and extension]

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. Note that the second extension in the reflectivity file contains mass-absorption coefficients that are used by the raytracing code xrtraytrace, to calculate transmission probabilities of the "thick" materials (as opposed to thin films) in the telescope.

backreffile = CALDB [filename CALDB|file name and extension]

Name of the reflectivity file and the extension for the backside reflectivity of the mirror foils.

pcolreffile = CALDB [filename CALDB|file name and extension]

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.

scatterfile = CALDB [filename CALDB|file name and extension]

Name of the file containing the scattering angle probability distributions for the direction of reflected rays relative to regular (incident angle = reflected angle) specular reflection. The file contains data for the frontside of mirror foils, the backside 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.

numphoton = 20000 [integer]

The value of the parameter 'numphoton' corresponds roughly to the number of raytracing photons allocated to each attitude histogram bin (in the exposure map file), per energy grid point. If any attitude bin has a time interval significantly larger than the average time interval, aharfgen allocates additional raytracing photons to that attitude position.

(minphoton = 100) [integer]

The minimum number of raytracing photons that successfully reach the focal plane, per raytracing energy grid point, that is acceptable to make an ARF. The number of focal plane photons that contribute to the ARF must exceed 'minphoton' for every energy, otherwise the program aborts. Note that even if minphoton is exceeded at all energies, this does not guarantee that the resulting ARF is robust and sufficiently accurate. In general, about 5000 or more photons per energy (over the extraction region) give good results, but the actual minimum number varies case-by-case, and fewer may be sufficient in some cases. The default value of minphoton is deliberately very small, in order that the results are made available for diagnostic evaluation. In general, it is not recommended to set 'minphoton' to a high value in the first place, because it is not possible to reliably estimate what 'numphoton' should be in advance, in order for that value of 'minphoton' to be satisfied for all energies, which could result in repeated failures after very long run times. It could also run into memory problems and/or a raytracing file size that is unmanageable.

sourcetype = POINT [string POINT|FLATCIRCLE|BETAMODEL|IMAGE]

Method for treatment of the spatial distribution of the X-ray source. (1) POINT: Point source at infinity. Photons arrive at random points on the active region of the telescope aperture from a single direction. (2) FLATCIRCLE: Extended source at infinity that has a spatial distribution with uniform flux over a circular region (zero outside of the circle). (3) BETAMODEL: Extended source at infinity that has a spatial distribution described by the "beta model" (see 'betapars' parameter). (4) IMAGE: A FITS image file (in RADEC coordinates) is used by xaarfgen to create a photon event list using the simulation code heasim. This event list is subsequently input into the raytracing code by xaarfgen. The input image file may be made from data from a different mission (with better spatial resolution than XRISM), or from a model. The name of the image file is given by the parameter 'imgfile'.

(betapars = "0.50 0.60 5.0") [string]

Parameters of the beta model if 'sourcetype=BETAMODEL' as follows: (1) beta model core radius [arcmin], (2) the index beta of the beta model, and (3) the maximum radius [arcmin] of the source spatial distribution.

(flatradius = 10.0) [double]

The radius [arcmin] of the extended source for the flat spatial distribution option 'sourcetype=FLATCIRCLE'.

imgfile = NONE [filename file name|NONE]

Name of the input image file to be used for raytracing if the input parameter 'sourcetype=IMAGE'. The image should be in the primary extension and the coordinate system should be RADEC (in RA/DEC units). The minimal mandatory keywords required are the standard ones describing the X and Y grids: CRPIX1, CRVAL1, CDELT1, CUNIT1, CRPIX2, CRVAL2, CDELT2, and CUNIT2. The units of the pixel contents in the image do not matter because xaarfgen creates a normalized probability distribution from the image.

(auxtransfile = NONE) [filename NONE|CALDB|file name]

Name of the input auxiliary transmission file. This file is used to apply an additional transmission modifier to the output ARF. This could correspond to modeling effects of unknown origin that are not accounted for in the telescope calibration files used by the raytracing, or it could be a function generated by the tool dustyarfmod that converts a point-source ARF to one that is appropriate for a point-source surrounded by a specified model of a dust scattering halo. If 'auxtransfile=CALDB', the file is read from the CalDB. However, the functions in these CalDB files for both instruments are simply unity for all energies, and there is currently no plan to change that for XRISM.

(polydeg = DEFAULT) [string DEFAULT|1|2|3|4|5|6|7|8|9|10]

The parameter 'polydeg' defines the polynomial order for the fitting of an internal function. The allowed values are 1 to 10. If 'polydeg=DEFAULT', the order is set to a value obtained internally by testing for fitting stability.

(seed = 29075) [integer]

Random number generator seed; uses system time for 'seed=0'.

(cleanup = no) [boolean yes|no]

Delete temporary files if 'cleanup=yes'.

(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 task parameters in HISTORY.

EXAMPLES

1. Create a large-sized RSP file (rslmkrsp_out.rsp) for hi-res (Hp) events using all pixels, with weights derived from the cleaned Resolve event file, xa000125000rsl_p0px1000_cl.evt. Ls events are not included in the grade fraction calculations, which are restricted to only using events with energies in the range 3.0 to 10.0 keV in this example. The exposure map file xa000125000rsl_p0px1000.expo is made with the task xaexpmap.

    rslmkrsp inevtfile=xa000125000rsl_p0px1000_cl.evt outfileroot=rslmkrsp_out whichrmf=L \
    includels=no gfelo=3.0 gfehi=10.0 resolist="0" regionfile=ALL xrtevtfile=xrt_file.fits \
    source_ra=182.634929134412 source_dec=39.4065454898143 emapfile=xa000125000rsl_p0px1000.expo \
    erange="0.3 18.0 2 8" numphoton=300000 seed=7 clobber=yes chatter=3
  

SEE ALSO

LAST MODIFIED

September 7, 2025