GENRSP (Jul05)               ftools.caltools              GENRSP (Jul05)



NAME
    GENRSP -- Generic spectral response generator
    
    
USAGE
    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>] 

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 "1.0 0.0 0.005 0.9 1.0 0.004 0.1" 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 if 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.
    
    
PARAMETERS

    inrfil [string]
        The name of any input response  matrix file. This will  override 
        any use of resol_reln etc.
    
    rmffil [string]
        The name of the output spectral response matrix file.
    
    resol_reln [string]
        The relation  that  describes  the  change  in  resolution  with
        energy  or  wavelength.  Options  are CONSTANT, LINEAR, SQROOT, 
        CZT, and FILE.
    
    resol_file [string]
        The filename required if <resol_reln>=FILE.
    
    fwhm [real]
        The fiducial FWHM for <resol_reln>=CONSTANT, LINEAR or SQROOT.
    
    disperse [bool]
        If set to yes then input  parameters  in  wavelength,  otherwise
        energy.
    
    tlscpe [string]
        The telescope name.
    
    instrm [string]
        The instrument name.

    resp_reln [string]
        The relation defining response energies (linear or file).

    resp_file [string]
        Filename to read for response energies.

    resp_low [real]
        The low energy or wavelength for the response energies.

    resp_high [real]
        The high energy or wavelength for the response energies.

    resp_number [real]
        The number of response energy bins.

    resp_break [real]
        The energy or wavelength where the response bins change size.

    resp_bnumber [real]
        The binsize for the response energies above <break>.

    chan_reln [string]
        The relation defining channels (linear or file).

    chan_file [string]
        Filename to read for channel energies.

    chan_low [real]
        The low energy or wavelength for the response channels.
    
    chan_high [real]
        The high energy or wavelength for the response channels.
    
    chan_number [real]
        The number of channels.
    
    chan_break [real]
        The  energy  or  wavelength  where  the response channels change
        size.
    
    chan_bnumber [real]
        The number of channels above the break.
    
    efffil [string]
        The name of the file with effective areas.
    
    detfil [string]
        The name of the file with detector effeciencies.
    
    filfil [string]
        The name of the file with filter transmissions.
    
    max_elements [int]
        The maximum number of response elements to be stored.
    
    rsp_min [real]
        The maximum value of a response element to be stored.
    
    clobber [bool]
        If clobber = yes then overwrite the output file  if  a  file  of
        this name already exists.
    
    
BUGS