.help genrsp Jul05 ftools.caltools
.ih
NAME
GENRSP -- Generic spectral response generator
.ih
USAGE
.nf
genrsp [<inrfil> [<rmffil> [<resol_reln> [<resol_file> [<fwhm> [<disperse> 
       [<tlscpe> [<instrm> [<resp_reln> [<resp_file> [<resp_low> [<resp_high> 
       [<resp_number> [<resp_break> [<resp_bnumber> [<chan_reln> [<chan_file> 
       [<chan_low> [<chan_high> [<chan_number> [<chan_break> [<chan_bnumber> 
       [<efffil> [<detfil> [<filfil> [<max_elements> [<rsp_min> [<clobber> 
       ]]]]]]]]]]]]]]]]]]]]]]]]]]]]

genrsp [inrfil=<inrfil>] [rmffil=<rmffil>] [resol_reln=<resol_reln>] 
       [resol_file=<resol_file>] [fwhm=<fwhm>] [disperse=<disperse>] 
       [tlscpe=<tlscpe>] [instrm=<instrm>] [resp_reln=<resp_reln>] 
       [resp_file=<resp_file>] [resp_low=<resp_low>] [resp_high=<resp_high>] 
       [resp_number=<resp_number>] [resp_break=<resp_break>] 
       [resp_bnumber=<resp_bnumber>] [chan_reln=<chan_reln>] 
       [chan_file=<chan_file>] [chan_low=<chan_low>] [chan_high=<chan_high>] 
       [chan_number=<chan_number>] [chan_break=<chan_break>] 
       [chan_number2=<chan_number2>] [efffil=<efffil>] [detfil=<detfil>] 
       [filfil=<filfil>] [max_elements=<max_elements>] [rsp_min=<rsp_min>] 
       [clobber=<clobber>] 
.fi
.ih
DESCRIPTION

GENRSP is a generator for the spectral response files used by XSPEC. 
It is primarily intended as a way of making quick response files when
designing new instruments.  GENRSP assumes that the response is
Gaussian which is unlikely to be the case in reality so these
responses are probably not going to be useful for analyzing actual
data.

The first parameter to set is <resol_reln> which specifies the way
that the resolution varies with energy or wavelength. The options are
CONSTANT, LINEAR, SQROOT (energy only), CZT (energy only), and
FILE. CZT is a special case and uses the relation FWHM =
E/(10*sqrt(20/E)). If FILE is specified then <resol_file> should be
used to give the filename. This should be an ascii file. The first
line should have two entries: the number of peaks in the response and
the number of energies included in the file. The remaining lines
should contain the energy followed by the difference between the input
energy and the peak, the FWHM for the peak, and the normalization for
each peak. The normalizations should sum to unity. For example the
line 
.nf
1.0 0.0 0.005 0.9 1.0 0.004 0.1
.fi
indicates that an input energy
of 1 keV will produce two response peaks, the first centered at the
input energy with a FWHM of 5 eV and the second centered at 1 keV
below the input energy with a FWHM of 4 eV and a normalization of 10%
of the response.  Note that all energies must have the same number of
peaks. If the <disperse> parameter (see below) is set to yes then
instead of energies in keV the numbers will be interpreted as
wavelengths in Angstroms. If <resol_reln> is CONSTANT, LINEAR or
SQROOT are specifed then <fwhm> should be set. In the case of LINEAR 
or SQROOT this is assumed to be the FWHM in keV at 1 keV.

If CONSTANT, LINEAR or FILE are chosen then the <disperse> parameter
specifies whether the spectrometer is dispersive or non-dispersive.

If <disperse>=yes then all parameters are assumed to be wavelengths in
Angstroms while if <disperse>=no they are assumed to be energies in
keV.

The response energy bins (ie the energies on which the model is
calculated in XSPEC) are specified using the <resp_reln> parameter. At
present there are two options: linear or file. If linear is chosen
then <resp_number> bins will be created with the first bin having a
start energy of <resp_low> and the last bin and end energy of
<resp_high>. If <resp_bnumber> is non-zero and <resp_break> is less
than <resp_high> then <resp_number> bins are created between
<resp_low> and <resp_break> and <resp_bnumber> bins between
<resp_break> and <resp_high>. If <resp_reln>='file' then the response
energies will be read from <resp_file>. This should be an ascii file
with 2 columns, the first being the start energy of the bin and the
second the end energy. Note that at present the bins must be
contiguous ie the start energy of bin i is the end energy of bin
(i-1). The units should be keV or Angstrom depending on the value of
<disperse>.

The channel energies are defined analogously to the response energies
using parameters starting chan_ instead of resp_.

All of the above can be circumvented if there is already an rmf file
which is being used as a template. In this case the file is specified
by the inrfil parameter value and all other parameters specifying the
response matrix are ignored.

There are three files that can be used to give the instrument
efficiency.  <efffil> is the effective area curve, <detfil> the
detector efficiency, and <filfil> the filter transmission. These files
should be ascii with two columns, the first the energy in keV and the
second the area, efficiency or transmission as appropriate.

The response matrix is calculated in a compressed format with only
elements having values above <rsp_min> being stored. The parameter
<max_elements> is used to allocate memory for the matrix elements so
should exceed the number of elements that are expected to be stored.
.ih
PARAMETERS
.ls inrfil [string]
The name of any input response matrix file. This will override any
use of resol_reln etc.
.le
.ls rmffil [string]
The name of the output spectral response matrix file.
.le
.ls resol_reln [string]
The relation that describes the change in resolution with energy or
wavelength. Options are CONSTANT, LINEAR, SQROOT, CZT, and FILE.
.le
.ls resol_file [string]
The filename required if <res_reln>=FILE.
.le
.ls fwhm [real]
The fiducial FWHM for <res_reln>=CONSTANT, LINEAR or SQROOT.
.le
.ls disperse [bool]
If set to yes then input parameters in wavelength, otherwise energy.
.le
.ls tlscpe [string]
The telescope name.
.le
.ls instrm [string]
The instrument name.
.le
.ls resp_reln [string]
The relation defining response energies (linear or file).
.le
.ls resp_file [string]
Filename to read for response energies.
.le
.ls resp_low [real]
The low energy or wavelength for the response energies.
.le
.ls resp_high [real]
The high energy or wavelength for the response energies.
.le
.ls resp_number [real]
The number of response energy bins.
.le
.ls resp_break [real]
The energy or wavelength where the response bins change size.
.le
.ls resp_bnumber [real]
The binsize for the response energies above <break>.
.le
.ls chan_reln [string]
The relation defining channels (linear or file).
.le
.ls chan_file [string]
Filename to read for channel energies.
.le
.ls chan_low [real]
The low energy or wavelength for the response channels.
.le
.ls chan_high [real]
The high energy or wavelength for the response channels.
.le
.ls chan_number [real]
The number of channels.
.le
.ls chan_break [real]
The energy or wavelength where the response channels change size.
.le
.ls chan_bnumber [real]
The number of channels above the break.
.le
.ls efffil [string]
The name of the file with effective areas.
.le
.ls detfil [string]
The name of the file with detector effeciencies.
.le
.ls filfil [string]
The name of the file with filter transmissions.
.le
.ls max_elements [int]
The maximum number of response elements to be stored.
.le
.ls rsp_min [real]
The maximum value of a response element to be stored.
.le
.ls clobber [bool]
If clobber = yes then overwrite the output file if a file of this name already
exists.
.le
.ih
BUGS
.endhelp




