NAME 

     gtpsf - Calculates the effective point spread function, as a
             function of energy at a given source location, averaged
             over an observation.


USAGE
 
     gtpsf expcube outfile irfs ra dec emin emax nenergies thetamax ntheta


DESCRIPTION
       
     This tool calculates the effective point spread function (PSF), as a
     function of energy at a given source location, averaged over an
     observation. The PSF and theta values are stored in different
     extensions of the output FITS file (#1 and #2, respectively). 
     The units of each PSF are sr^{-1}: Integrating each PSF over theta
     and azimuthally, unity is obtained. 
      

PARAMETERS

     expcube [filename]
         FITS file containing livetime as a function of sky position
         and off-axis angle also referred to as the "exposure
         hypercube file". This file should be generated by gtltcube.
  	  	 
     outfile [filename]
  	 Name of the output FITS file.
  	  	 
     (outtable) [string]
         Name of the output file binary table extension which contains the 
         results. Default is "PSF".
  	  	 
     irfs [string]
         Instrument response function. Default is "P7SOURCE_V6".
  	  	 
     evtype [integer]
   	  The evtype to be used in generating the bacground data. The
   	  default is INDEF which will use the default in the input
   	  file. This can be overridded by entering the desired event
   	  type e.g. 3 for FRONT + BACK events. 

     ra [double]
  	 Right Ascension (J2000) of desired source position in
  	 decimal degrees.
  	  	 
     dec [double]
  	 Declination (J2000) of desired source position in
  	 decimal degrees.
  	  	 
     emin [double]
         Minimum of the energy range covered, in MeV. The range of this 
         parameter depends on the response function used. Currently it is  
         recommended that emin be larger or equal to 18 MeV. Default is "20".
  	  	 
     emax [double]
         Maximum of the energy range covered, in MeV. The range of this 
         parameter depends on the response function used. Currently it is 
         recommended that emax be smaller or equal to 5.6e6 MeV. Default is 
	 "2e5".
  	  	 
     nenergies [integer]
  	 Number of logarithmically spaced energies. It should be larger 
         than 1. Default is "20".
  	  	 
     thetamax [double]
  	 Maximum angle of apparent photon direction with respect to the 
         source direction (degrees). Default is "30". The lowest value
	 for this parameter is inversely proportional to the minimum energy
	 considered: Some tens of degrees are necesssary to sample 
	 correctly the PSF at energies of a few MeV.
  	  	 
     ntheta [integer]
  	 Number of theta bins. The bins are spaced as a power of 2 (y=ax^2,
	 where a=(thetamax/ntheta^2). Default is "300". The lowest value
	 for this parameter should be no less than a few to have a reasonable
	 representation of the PSF shape.

    (chatter) [integer]  
         This parameter fixes the output verbosity: no screen output (0),
         nominal screen output (2), maximum verbosity (4). Default is "2".

    (clobber) [boolean]
         If true, an existing file of the same name will be overwritten. 
         Default is "yes".
    
    (debug) [boolean]
         Activate debugging mode. Default is "no". When debug is "no", all 
         exceptions that are not caught and
         handled by individual tool-specific code are caught by a top-level
         exception handler that displays information about the exception and
         then exits. When debug is "yes", such exceptions are not caught by the
         top level code. Instead the tool produces a segmentation violation,
         which is more useful for debugging. When debugging mode is enabled,
         the tool produces more verbose output describing any errors or
         exceptions that are encountered.
    
    (gui) [boolean]
         Graphical User Interface (GUI) mode is activated if set to "yes".
         Default is "no".
    
    (mode) [string]
         Mode of automatic parameters: "h" for batch, "ql" for interactive. 
         Default is "ql".


EXAMPLES
 
     gtpsf handles parameters following the FTOOLs model: They 
     can be passed by answering a prompt or as a list in a command 
     line. This facilitates calling gtpsf from a script.
 
     To be prompted for gtpsf options type in the command line: 

>gtpsf 
 
     The user will be prompted for the parameter values. Not all 
     parameter are prompted: some of them are "hidden".  To
     change one of the "hidden" parameter, the user should specify the values in
     the command line or modify its mode by editing the parameter 
     file. For example, if the user does not want to overwrite the
     existing output file, the user should set the parameter "clobber=no", e.g.:
 
>gtpsf clobber=no  
  
     An example of how to run the tool is given below: 

> gtpsf 
Livetime cube file[] expCube.fits 
output file name[] psf.fits
Response functions[P7SOURCE_V6] 
Source Right Ascension (J2000 degrees) (0:360) [] 193.98
Source Declination (J2000 degrees) (-90:90) [] -5.82
minimum energy (MeV)[20.] 100
maximum energy (MeV)[2e5] 100000
number of energies[20] 
maximum angle (degrees)[30.] 
number of angles[300] 

     That last example could be also run in the command line as follows: 
 
>gtpsf expcube=expCube.fits outfile=psf.fits irfs=P7SOURCE_V6 ra=193.98 \
       dec=-5.82 emin=100.0 emax=100000.0 nenergies=20 thetamax=30 ntheta=300 


LIST OF BUGS


SEE ALSO 

     gtltcube 

