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 background data. The
   	  default is INDEF which will use the default in the input
   	  file. This can be overridden 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