dustyarfmod - For X-ray point sources with dust halos, makes an effective area correction (or modifier) file, with the option of running raytracing simulations for the calculations.
An X-ray source surrounded by dust can appear in X-ray images as having an extended halo, whereas without the dust it may appear as a point source. The halo modifies the X-ray telescope effective area, and the spatial distribution of the image on the focal plane, compared to a point source. The spatial distribution of the extended halo emission is in general energy-dependent, and depends on the distribution and other properties of the dust in the interstellar medium. The tool dustyarfmod generates a file that calculates a function of energy that modifies the point-source effective area. This file can be input to aharfgen or xaarfgen to generate an ARF (Ancillary Response File), containing the net effective area, as if the source were a point source. The tool dustyarfmod takes as input a dust model FITS file in a specified format (see parameter 'dustmodelfile' below), and can perform raytracing simulations in order to calcluate the modifier function for the effective area, or it can calculate a theoretical limit function (see below) without raytracing. The dustyarfmod tool creates several output files in addition to the principal effective area modifier file, and uses the input parameter 'outroot' as a root for the names of the output files. The file that should be input to aharfgen or xaarfgen has a name that ends in '_auxtran.fits' or '_mean_auxtran.fits', and the aharfgen or xaarfgen input parameter 'auxtransfile' should be set to the name of this file. The other output files created by dustyarfmod are for diagnostic purposes and/or theoretical invesitgations (see description of the parameter 'outroot' for details). Raytracing is peformed by dustyarfmod by running xrtraytrace, and the dust calculations are peformed by running the tool dustmodeleffarea.
The statistical quality of the output of dustyarfmod depends on the number of photons used in the raytracing simulations, which can take many hours to complete on a single machine. However, dustyarfmod is capable of utilizing distributed computing, running several instances on a multi-core machine, and/or running several instances on different machines. The tool can be run in several modes that facilitate management of distributed runs and collation of the results from multiple runs. One of the modes of operation of dustyarfmod does not use raytracing at all (and is therefore very quick to run), because this mode calculates a theoretical limit function that is mission-independent, and independent of off-axis angle, and it represents the maximum possible deviation of the effective area relative to a point source, for a given dust model and column density. This is useful for assessing whether raytracing is needed: if this worst-case estimate is acceptable for a given application and energy range, then raytracing can be skipped. The theoretical limit function can also inform if there is a "safe" energy range in which the effects of dust scattering on the effective area are negligible. In some applications, low-statistics raytracing may be sufficient if only quantitative estimates of effects on the effective area are required, as opposed to applications that require a high-quality ARF for spectral-fitting purposes.
Two different raytracing runs are needed for a full dustyarfmod calculation of the effective area modifier function (in the output auxtran file). Raytracing (using the tool xrtraytrace) is performed for a point-source and for a diffuse source. The latter does not correspond to the actual dust halo model, but is used by dustyarfmod to internally create a halo raytracing model using weights calculated from the input dust model file. Nevertheless, the diffuse raytracing event files are referred to as halo files. In this scheme, the raytracing files are, for a given pointing, "universal", and are not tied to a particular dust model. Therefore, the same raytracing files can be used for runs of dustyarfmod with different dust model files, different values of the column density parameter ('nh'), different focal-plane selection regions, and different energy ranges. To facilitate this, dustyarfmod checks whether any files exist in the current directory that have a name equal to a raytracing file name that it generates from the input parameter 'outroot' (see description of the parameter 'outroot' for details on the rules for the file names generated). If any matches are found in the directory that the tool is running in, new raytracing corresponding to the matching file or files is not performed. However, output files made previously using the same raytracing event files must be renamed, otherwise they will be over-written by a new run. Alternatively, raytracing event files made previously can be renamed, or copied to new names, that correspond to a different 'outroot' parameter value than any used for previous runs.
The position of the center of the X-ray source relative to the optical axis can either be set manually (using the parameters 'offaxis' and 'azimuth'), or it can be set by means of the exposure map file (parameter 'emapfile'). In the header of extension 1 (OFFAXISHIST) of 'emapfile', the keywords RA_OBJ and DEC_OBJ correspond to the true source RA and DEC respectively. The user should check that this is actually the case. Also, if there are systemtic errors in the attitude of the satellite, these keywords may need to be adjusted manually. See help files for the tools xaexpmap and xaarfgen for details on how the exposure map file works. Note that dustyarfmod does not treat attitude variation, and only uses the mean, nominal pointing parameters in the header of extension 1 in the exposure map file, as opposed to the attitude histogram in the exposure map file. Attitude variation can be crudely emulated in dustyarfmod by manually specifying a series of pairs of the pointing parameters 'offaxis' and 'azimuth' instead of a single pair. Each pair of pointing parameters is given an equal weight. In order to assign different effective weights to different pointing directions, repeat pairs of pointing parameters an approriate number of times. Note that the 'numphoton' parameter specifies the number of raytracing photons per energy per pointing. The dustyarfmod tool also gives an option to stop after only performing raytracing. This is useful when peforming parallel or distributed raytracing runs, or if it is found that more raytracing is required to achieve better statistics. The actual dust calculations can then later be performed with a final run of dustyarfmod with all of the raytracing event files collected together.
In an another mode of operation, dustyarfmod performs no raytracing and no dust calculations, but instead calculates mean functions from the outputs of previous runs of dustyarfmod. A summary of all of the different modes of operation of dustyarfmod is given below.
(1) 'rtmode=0', 'dustmodelfile = file name': Calculate theoretical limit function only (no raytracing). Output is the net auxtran file, which contains the theoretical lower limit function.
(2) 'rtmode > 1', 'dustmodelfile = NONE': Collate mode. The mean auxtran output file is created from previously created auxtran files, specified by the parameters 'outroot', 'startpart', and 'endpart'. Optional mean halo and point-source effective area files are also created, depending on the value of the input parameter 'rtsource' (see below).
(3) 'rtmode=1': Run raytracing only. Perform raytracing for the dust halo ('rtsource=0'), or point source ('rtsource=1'), or both ('rtsource=2'). However, stop after performing the raytracing, without making an auxtran file.
(4) 'rtmode=2', 'dustmodelfile = file name': Run or use raytracing, and perform dust calculations. Perform, or use raytracing results for the dust halo ('rtsource=0'), or point source ('rtsource=1'), or both ('rtsource=2'). Make halo and/or point-source effective area files, and an auxtran file if 'rtsource=2'.
For modes (1) and (2), no raytracing CalDB files or raytracing parameters are needed, no exposure map file is needed, no pointing parameters are needed, a teldef file (telescope definition file) is not needed, and no region file is needed. Modes (1), (2), and (3) do not run the tool dustmodeleffarea. Note that collate mode creates a mean auxtran file that has an extra column (AUXTRANSERR), corresponding to the standard deviation of the axutran function at each energy.
The name of the input dust model FITS file. The file is not required in collate mode, or when performing raytracing for a point source only. The file contains data corresponding to an energy-dependent spatial distribution model of the dust halo, specifically quantifying the spatial distribution of the emission from the halo for a set of discrete energies. Only azimuthally-symmetric, circular halos are supported. The format of the dust model file must be as follows:
(1) The primary extension contains a 2D array that models the dust halo emission, with radial distance from the center along the "X" axis of the image, and energy along the "Y" axis. The value in each pixel is, for a given energy, the number of halo photons per arcsec^2, or per arcmin^2, as a fraction of the total number of point-source photons at that energy.
(2) Extension 1, called ENERGYGRID, contains a column called ENERGY, that has data type 1D. The energy values must be in units of keV.
(3) Extension 2, called RADIUS, contains a colum called THETA, that has a data type 1D. The values in the array are distance to the center of the halo, in units of arcsec or arcmin. The pixel values in the primary extension image must be consistent with the units in extension 2. The number of rows in this extension is equal to the "X" dimension of the image in the primary extension.
(4) Extension 3, called TAUABS, contains a column called TAUNH22, that has a data type 1D. The values in this array correspond to the optical depth to absorption along the line-of-sight, per 10^22 cm^-2 of column density, for each energy value in extension 1. The number of rows in this extension is equal to the "Y" dimension of the image in the primary extension. The values of TAUNH22 multiplied by the column density in units of 10^22 cm^-2 (the 'nh' input parameter to dustyarfmod), is the dimensionless extinction optical depth.
Type of source for which to perform calculations, as follows:
An auxtran file can only be made from raytracing if 'rtsource=2' and 'rtmode=2'.
The name and extension of the FITS file containing an energy grid [keV] to use for raytracing. The name of the column containing the energies must be ENERGY. The energy values must lie in the range covered by the dust model FITS file, but there is freedom in the number of grid points, and their spacing can be arbitrary. Alternatively, a value of NONE for 'energygridfile' causes dustyarfmod to internally generate an energy grid array between the minimum and maximum energies that are covered by the dust model FITS file. The energy grid in 'energygridfile', or the internally generated grid, is not necessarily the energy grid that will be used for the output auxtran and effective area files. If 'rtmode=0' (theoretical limit function only), or 'smoothing=yes', the energy grid in the output auxtran file will be the native energy grid in 'dustmodelfile'. Otherwise, if an input auxtran file is specified, the output auxtran file will have the same energy grid as the input auxtran file. In all other cases, the output auxtran file will have the energy grid in 'energygridfile'.
In the case that 'energygridfile=NONE', the internal, pre-determined, energy grid range is the minimum and maximum energy in 'dustmodelfile', and the bin widths are as follows:
Root name for constructing output file names.
The output auxtran files have the names:
{outroot}_part{N}_auxtran.fits, where the string {N}= 'startpart' to {N}= 'endpart', and {outroot} is the string input parameter 'outroot'.
Likewise, the output effective area files have the names:
{outroot}_part{N}_ptsrc_ea.fits (point source) and
{outroot}_part{N}_halo_ea.fits (halo).
The halo effective area files do not include the effects of dust extinction changing the spatial distribution of the halo emission as a function of energy, but these effects are included in the calculation of the function in auxtran files.
Note that, whereas the auxtran output file with the naming convention given above is calculated as the ratio of the net effective area to the point source effective area, dustyarfmod creates an additional auxtran file for diagnostic purposes, that is the ratio of only the halo effective area to the point-source effective area.
An output file is also created that contains the ratio of the extended source to point-source effective area: {outroot}_part{N}_haloratio.fits (however, despite the name, the extended source effective area is for flat, uniform emission, without the weighting factors for the dust halo model).
The raytracing event files created by dustyarfmod running xrtraytrace have the names:
{outroot}_part{N}_ptsrc_evt.fits (point source)
{outroot}_part{N}_halo_evt.fits (halo)
Note that if 'startpart=1' and 'endpart=1, the substring "_part1_" is not included in any of the file names.
In collation mode (for 'endpart' > 'startpart'), or for multipart raytracing runs, the mean output auxtran file has the name
{outroot} + {partsidstr} + "_mean_auxtran.fits", where {partsidstr} = "_part{M}_part{N}" and {M} = string('startpart'), {N} = string('endpart'). Again, if {M}={N}=1, the substring {partidstr} is omitted.
Similar to the auxtran files, the names of the mean effective area files are:
{outroot} + {partsidstr} + "_ptsrc_mean_effarea.fits" (point source) and
{outroot} + {partsidstr} + "_halo_mean_effarea.fits" (halo).
The effective area files have the same FITS format as the effective area files produced directly by xrtraytrace (see help file for xrtraytrace). They are not ARF files. The name of the extension is EFFAREA. There are two or three columns, one is called ENERGY (units keV), and another is called EFFAREA (in units of cm^2). If the effective area file is made by calculating the mean from many effective area files, there is a third column called EAERROR (in units of cm^2), which is the standard deviation error on the mean.
For the dust model file dust_uniform_model1.fits, calculate, for a column density of 10^21 cm^-2, the worst-case modification of the effective area compared to a point source.
dustyarfmod dustmodelfile=dust_uniform_model1.fits nh=0.1 rtmode=0 rtsource=2 outroot=dust_uniform_model1_tlimitThe output effective modifier function will be in the output file dust_uniform_model1_tlimit_auxtran.fits.
A point source with a dust halo with a column density of 5 x 10^21 cm^-2 is observed by the XRISM Xtend instrument, 1' off-axis, such that the telescope azimuthal angle for the center of the source is 110 degrees. A spectrum is extracted from a 2.5' radius circle, centered on the source, using the region file src.reg (in RA, DEC coordinates). The dust model file is dust_model2.fits. Create an auxtran file, for input into xaarfgen, that gives the modification function to convert the point-source effective area to the net effective area that includes the halo. Use the smoothing option, 600,000 photons per energy for raytracing, and use the internal raytracing energy grid.
dustyarfmod telescop=XRISM instrume=XTEND dustmodelfile=dust_model2.fits nh=0.5 rtmode=2 rtsource=2 numphoton=600000 \ offaxis=1.0 azimuth=110.0 regmode=RADEC regionfile=src.reg smoothing=yes outroot=dust_uniform_mode2
The output auxtran file is dust_uniform_mode2_auxtran.fits.
For the XRISM Resolve instrument, run dustyarfmod with 100 different random number seeds on three different machines, for an on-axis point source with a dust halo described by the model file dust_model3.fits, and a column density of 10^22 cm^-2, using the internal energy grid, and 100,000 photons per energy. Do not calculate the auxtran files for the three separate sets of runs (example 4 shows how to make the mean auxtran file for all 100 parts). A region file is not needed for this example, because dustyarfmod stops after raytracing is complete.
Run dustyarfmod on machine 1 with the following command:
dustyarfmod dustmodelfile=dust_model3.fits rtmode=1 rtsource=2 startpart=1 endpart=35 outroot=dust_model3
Run dustyarfmod on machine 2 with the same command as above except that:
startpart=36 endpart=70
Run dustyarfmod on machine 3 with the same command again, except that:
startpart=71 endpart=100
Move all the output files from machines 2 and 3 onto machine 1, in the directory where you ran dustyarfmod on machine 1. Run dustyarfmod with the following command:
dustyarfmod dustmodelfile=dust_model3.fits rtmode=2 rtsource=2 regionfile=src3.reg startpart=1 endpart=100 outroot=dust_model3
The output auxtran file will be dust_model3_part1_part100_mean_auxtran.fits.