NAME

lemat - the SAX/LECS Matrix Generation Program

SYNOPSIS

lemat [infile=] <filename> [parameter=value ...]

DESCRIPTION

lemat is the program to generate response matrices for the SAX LECS. It needs as input a spectral file created by XSELECT. This includes the WMAP image of the extracted data. This is used to determine the extraction region shape and the fraction of events that fall within the region. All forms of extraction region shape allowed by XSELECT can be handled by lemat.

The output from lemat is the area response file (ARF) and redistribution matrix file (RMF) appropriate to the input and selection criteria. These files, together with the input spectrum, can then be read into XSPEC for spectral analysis. The mirror response and strongback obscuration are modeled by means of raytracing, the results of which are automatically stored on disk in file rayfile.

A response matrix should be generated for each source position, since the response of the LECS depends on position (due to the complex obscuration pattern of the window support structure) and each extraction radius. Currently, a default extraction radius of 35 pixels (about 8 arc minutes) is used. This ensures that about 95% of 0.28 keV photons are included. However, a smaller extraction radius may be appropriate for absorbed and/or background dominated sources. There is no need to repeat the raytracing for different extraction radii, but the same source position. In this case simply set parameter raytrace=no and give the relevant rayfile name.

The program logic is as follows:

1. Read Input parameters from command line or parameter file.
2. Open and read input PHA File.
3. Check PHA file structure and contents compatible with program.
4. Read and decode WMAP (weighted image map) primary array data to get information on source position and extraction region size.
5. Calculate source position centroid
6. Populate Energy Boundary Data Arrays
7. Get Calibration Data from CALDB
   • > Gain for BL corrected and non-corrected cases
   • > Energy Resolution for BL corrected and non-corrected cases
8. Get effective area data.
   • > Mirror efficiency through ray-tracing
   • > Strongback and grid Transmission through raytracing
   • > Measured window transmission
   • > Measured protection window transmission
   • > Detector PSF losses through ray-tracing
   • > Theoretical detector absorption efficiency
9. Write RMF output file
   • > matrix extension
   • > ebounds extension
10. Write ARF output file

The current calibration status is as follows:



Item	Status	Complete
Window Transmission	Bessy measurements	Yes
Prot. Window Transmission	Bessy measurements	Yes
Gain Curve	Panter measurements	Yes
Escape Data	Bessy/Panter measurements	Yes
Resolution function	Measured shape (Bessy & Panter)	Yes
Resolution E dependence	Measured dependence	Yes
Mirror Area	From ray tracing	Yes
Detector PSF losses	From ray tracing	Yes
Grid and strongback trans	From ray tracing	Yes
Detector Efficiency	Theoretical	Yes


The following files types need to be available for lemat (they are normally stored in the LECS CALDB and their contents described in the LECS ground calibration document LEDA/0015):



Name	Contents
WTRANS	Window area densities for 5 elements
WATOM	Window mass absorption coefficients for 5 elements
WINFUD	Window fudge factors for near edges
XEATOM	Xenon absorption coefficients
FTRANS	Protection window transmission measurements
LINESHAPE	KeV to PI (and PIC), FWHM, etc relations
OPTICSGEO	Optical axis pixel coordinates

PARAMETERS

The following command line parameters are recognized by the program:

infile = "" [string]

This is the input FITS spectral file for which the response is to be generated. The file should be in accordance with the format described in 'The OGIP Spectral File Format', OGIP/92.007.



outfile1 = "INFILE.RMF" [string]

This is the output redistribution matrix file (RMF) that will be produced. If it is not specified, a file with the same name as the input name but with extension .rmf will be created. The format of the file is described in 'The Calibration Requirements for Spectral Analysis', OGIP calibration memo CAL/GEN/92-002.



outfile2 = "INFILE.ARF" [string]

This is the output area response file (ARF) that will be produced. If it is not specified, a file with the same name as the input name but with extension .arf will be created. The format of the file is described in 'The Calibration Requirements for Spectral Analysis', OGIP calibration memo CAL/GEN/92-002.



raytrace = no [boolean: yes|no]

Boolean switch to indicate whether raytracing should be performed (=yes) (and the results stored in file rayfile), or whether the raytrace results should be read from the file specified by the rayfile parameter.



rayfile = "LEMAT.RAY" [string]

This is the filename where the raytrace output will be stored if parameter raytrace=yes, or the file from which the raytrace results will be read if raytrace=no.



chatter = 5 [integer: 0-10]

Specifies the program chattiness level, i.e. the amount of screen output that will be issued during program execution. Level 0 means "mute" except for error messages 1 will output filenames only, 2 will add input spectrum details, 3 will include processing details, 5 is the default, 6 includes overwritten file info, and 10 is too verbose for most.



maxsep = 5.0 [real: 0.0-100.]

The maximum separation between the source position determined by centroiding and the pixel where the peak counts occur. If this value is exceeded, the peak position will be used (unless xpos and ypos are set).



xpos = 0.0 [real: 0.0-255.]

This hidden parameter can be used to override the source RAWX position obtained by assuming that the source is located at the location given by the peak counts when it has a value >0.0.



ypos = 0.0 [real: 0.0-255.]

This hidden parameter can be used to override the source RAWY position obtained by assuming that the source is located at the location given by the peak counts when it has a value >0.0.



clobber = yes [boolean: yes|no]

This hidden parameter can be used to enable or disable overwriting of already existing ARF and RMF files.



seed = 0 [integer: 0-65535]

This hidden parameter can be used to specify a particular seed value for the random number generator used in the ray tracing algorithm. If it is set to 0, the system clock is used to calculate a seed.



nphotons = 5000 [integer: 500-1000000]

This hidden parameter is the number of photons exiting from the Mirror Units at each energy in the ray tracing. Please leave at the default value unless you are an expert user.



nrayen = 45 [integer: 5-1025]

This hidden parameter is the number of energies for which the ray tracing will be performed. Please leave at the default value unless you are an expert user.



plot_arf = no [boolean: yes|no]

This hidden paramater can be used to plot the various contributions to the ARF using QDP/PLT for diagnostic purposes. In addition, QDP automatically creates two output files infile.qdp and infile.pco which enable the plot to be recreated later. After plotting the program remains with the PLT> prompt. Type 'exit' to continue in lemat.



plot_rmf = 0.0 [real: 0.0-15.0]

This hidden paramater can be used to plot the Response of the LECS to monochromatic X-rays with energy =plot_rmf using QDP/PLT. This is primarily useful for diagnostic purposes. After plotting the program remains with the PLT> prompt. Type 'exit' to continue in lemat.



plot_psf = 0.0 [real: 0.0-15.0]

This hidden parameter can be used to plot the Point Spread Function of the mirror system incident on the cell entrance window support structure using QDP/PLT. The single parameter is the energy in keV; a value of 0.0 disables the plotting. After plotting the program remains with the PLT> prompt. Type 'exit' to continue in lemat.



plotdev = "/xwin" [string]

This hidden parameter can be used to set the PGPLOT device used with the plot_arf, plot_rmf and plot_psf commands. All devices supported by the installed FTOOLS PGPLOT library can be specified.



pltcmd = " " [string]

This parameter represents any legitimate PLT command that is to be added to the standard QDP commands used in plotting either the ARF, RMF or PSF. Pltcmd can also be of the form @filename in which case the commands within file filename.pco are added to the default commands.



origin = "SSD/ESA" [string]

This hidden parameter can be used to set the output FITS files "ORIGIN" parameter.



wtrans = "CALDB" [string]

This hidden parameter can be used to set the filename for the WTRANS calibration file type. The default is to use the Calibration Database.



lineshape = "CALDB" [string]

This hidden parameter can be used to set the filename for the LINESHAPE calibration file type. The default is to use the Calibration Database.



watom = "CALDB" [string]

This hidden parameter can be used to set the filename for the WATOM calibration file type. The default is to use the Calibration Database.



winfud = "CALDB" [string]

This hidden parameter can be used to set the filename for the WINFUD calibration file type. The default is to use the Calibration Database.



xeatom = "CALDB" [string]

This hidden parameter can be used to set the filename for the XEATOM calibration file type. The default is to use the Calibration Database.



optics = "CALDB" [string]

This hidden parameter can be used to set the filename for the OPTICSGEO calibration file type. The default is to use the Calibration Database.



make_arf = yes [boolean: yes|no]

This hidden parameter can be used to switch on and off the production of an ARF file. Normally only used for development purposes.



make_rmf = yes [boolean: yes|no]

This hidden parameter can be used to switch on and off the production of an RMF file. Normally only used for development purposes.



anom = 0 [integer: 0-4]

This hidden parameter controls which rays are generated by the raytracing code. A value of 0 includes only good `double reflection' rays. 1= front cone only, 2= back cone only, 3= straight through and 4 = everything. This parameter should be left at a value of 0.



help = no [boolean: yes|no]

This hidden parameter can be used to produce a short listing of the input parameters for lemat.

EXAMPLES

1. To create RMF and ARF files for an input file 'herx1.pha', created using XSELECT using all default parameters. The output files will be automatically named 'herx1.rmf' and 'herx1.arf', type:

      lemat herx1.pha
   

2. To create RMF and ARF files for an input file 'herx1.pha' for a position in the FOV of RAWX,RAWY = 130,142, type:

      lemat herx1.pha xpos=130. ypos=142.
   

   To create RMF and ARF files for an input file 'herx1.pha' but using 100 raytracing energies and 10000 photons exiting the mirrors at each energy (this will take some time....) type:

      lemat herx1.pha nphotons=10000 nrayen=100
   

3. To create RMF and ARF files for an input file 'herx1.pha' and plot the LECS spectral resolution at 5.3 keV type:

      lemat herx1.pha plot_rmf=5.3
   

FURTHER DOCUMENTATION

1. XSPEC User Manual
2. XSELECT User Manual

SEE ALSO

calcgain, evelin, xspec, xselect

BUGS AND LIMITATIONS

For some strange reason the user must have write access to the spectral file. Note that PIC spectra and extended spectra are not currently supported. For faint sources, the peak positions are not always reliably estimated and it is better to either use the position of the source centroid, or input manually the source coordinates.