Fermi LAT Multi-Processor Scripts (version 1.4)

The Fermi Science Tools (http://fermi.gsfc.nasa.gov/ssc) are a suite
of tools developed for the analysis of both Fermi LAT and GBM
data. This suite was developed by the FSSC and the instrument teams,
and was reviewed by the Fermi Users' Group.  The LAT Multi-Processor
Scripts are a set of python scripts to facilitate the analysis of LAT
data.  This package depends on the Fermi Science Tools.

The current tools available are

    * gtdiffrsp_mp.py
    * gtexpmap_mp.py
    * gtltcube_mp.py
    * gttsmap_mp.py (Unbinned Only)

Installation: navigate to the gtapps_mp directory and execute

   > python setup.py install

To receive information on program execution for a specific script execute:

   > python <gtapp>_mp.py -h

See below for details on each tool.

* gtdiffrsp_mp.py *

  Submits the gtdiffrsp program as separate threads via python and
  joins up the resulting temporary files at the end resulting in a
  single file. This greatly reduces the running time. For more details
  on gtdiffrsp see the gtdiffrsp help file.

  usage: gtdiffrsp_mp.py [-h] [--savetmp SAVETMP]
         		 jobs evfile scfile srcmdl irf outfile

  positional arguments:	    
  jobs               The number of jobs you wish to spawn (usually the number
                     of cores on your machine).
  evfile             Input event file. See gtdiffrsp help for more
                     information.
  scfile             Spacecraft file. See gtdiffrsp help for more information.
  srcmdl             The source model file to use. See gtdiffrsp help for more
                     information.
  irf                The IRFs to use. See gtdiffrsp help for more information.
  outfile            Output file name.

  optional arguments:
  -h, --help         show this help message and exit
  --savetmp SAVETMP  Save the temporary files (default is False).

  example: 
  This computes the diffuse response for the data in the file
  '3C279_events.fits' using 4 separate threads using the spacecraft
  file 'SC.fits', the model file '3C279_model.xml' and the P7SOURCE_V6
  instrument response functions.  It saves the output in
  '3C279_events_diffrsp.fits'

  > python gtdiffrsp_mp.py 4 3C279_events.fits SC.fits 3C279_model.xml
    P7SOURCE_V6 3C279_events_diffrsp.fits

* gtexpmap_mp.py *

  Submits the gtexpmap program as operate threads via python and joins
  up the resulting temporary exposure maps at the end resulting in a
  single exposure map for the input event file. This greatly reduces the
  running time. For more details on gtexpmap see the gtexpmap help
  file. Note that the checksum and datasum are incorrect for the final
  file. The number of spawned jobs is equal to xbins x ybins.

  usage: gtexpmap_mp.py [-h] [--savetmp SAVETMP]
  	          	nlong nlat xbins ybins sfile evfile expcube IRFS srcrad
         		nenergies outfile

  positional arguments:
  nlong              Number of longitude points. See gtexpmap help for more
                     information.
  nlat               Number of latitude points. See gtexpmap help for more
                     information.
  xbins              The number of bins along the x-axis. Must divide evenly
                     into nlong.
  ybins              The number of bins along the y-axis. Must divide evenly
                     into nlat.
  sfile              The spacecraft data file. See gtexpmap help for more
                     information.
  evfile             Input event file. See gtexpmap help for more information.
  expcube            Input livetime cube. See gtexpmap help for more
                     information.
  IRFS               IRFs to use. See gtexpmap help for more information.
  srcrad             Radius. See gtexpmap help for more information.
  nenergies          Number of energy slices. See gtexpmap help for more
                     information.
  outfile            Output file name.

  optional arguments:
  -h, --help         show this help message and exit
  --savetmp SAVETMP  Save the temporary files (default is False).

  example: 
  This computes a 30 degree radius exposure map for a the data in
  '3C279_filtered_gti.fits' with 120 by 120 pixels and 20 energy bins
  using the spacecraft file 'SC.fits', the exposure cube
  '3C279_ltcube.fits' and the P7SOURCE_V6 instrument response files.
  It submits 6 jobs by making xbins = 3 and ybins = 2 (3*2 = 6).  Both
  3 and 2 divide equally into 120.  The resulting file is saved as
  '3C279_expmap.fits'.

  > python gtexpmap_mp.py 120 120 3 2 SC.fits 3C279_filtered_gti.fits
    3C279_ltcube.fits P7SOURCE_V6 30 20 3C279_expmap.fits

* gtltcube_mp.py *

  Submits the gtltcube program as operate threads via python and joins
  up the resulting temporary exposure cubes at the end resulting in a
  single exposure cube for the input event file. This greatly reduces
  the running time. For more details on gtltcube see the gtltcube help
  file.

  usage: gtltcube_mp.py [-h] [--savetmp SAVETMP] [--zmax ZMAX]
  	                jobs sfile evfile outfile

  positional arguments:
  jobs               The number of jobs you wish to spawn (usually the number
                     of cores on your machine).
  sfile              The spacecraft data file. See gtltcube help for more
                     information.
  evfile             Input event file. See gtltcube help for more information.
  outfile            Output file name.

  optional arguments:
  -h, --help         show this help message and exit
  --savetmp SAVETMP  Save the temporary files (default is False).
  --zmax ZMAX        zmax parameter for gtltcube (default is 180)

  example:
  This example creates a livetime cube for the file
  '3C279_filtered_gti.fits' using 8 threads and the 'SC.fits'
  spacecraft file.  It saves the output to '3C279_ltcube.fits'.  It
  also sets the zmax value to 100 (the recommended value).

  > python gtltcube_mp.py 8 SC.fits 3C279_filtered_gti.fits
    3C279_ltcube.fits --zmax 100

* gttsmap_mp.py *

  Generates a TS Map by running separate pixels on separate
  threads. It creates a template counts map to determine the location
  of the pixels and the calculates the TS of a test source at each
  pixel on that map. It then merges the results at the end. The map is
  divided into separate regions (called 000,001,002...) depending on
  the number of jobs the user requests. It creates subdirectories for
  each region and operates on them within the subdirectory.  For more
  details on the parameters see the gttsmap help file. NOTE: ONLY DOES
  AN UNBINNED ANALYSIS. NOTE2: Any files referenced in the model XML
  file must be referenced by absolute and not relative directories
  (ie. not ./ or ../)"

  usage: gttsmap_mp.py [-h] [--savetmp SAVETMP]
  	               nxpix nypix jobs evfile scfile expcube srcmdl IRFS
                       optimizer ftol toltype binsz coordsys xref yref proj
                       outfile UNBINNED expmap

		       	  
  positional arguments:
  nxpix              Number of pixels along x-axis. See gttsmap help for more
                     information.
  nypix              Number of pixels along y-axis. See gttsmap help for more
                     information.
  jobs               The number of concurrent jobs.
  evfile             Input event file. See gttsmap help for more information.
  scfile             The spacecraft data file. See gttsmap help for more
                     information.
  expcube            Input livetime cube. See gttsmap help for more
                     information.
  srcmdl 	     XML source model definition. See gttsmap help for more
                     information.  Any files in the xml (like the
                     diffuse models) need to be referenced by absolute
                     directories.
  IRFS               IRFs to use. See gttsmap help for more information.
  optimizer          The optimizer (e.g. NEWMINUIT). See gttsmap help for more
                     information.
  ftol               Fit tolerance. See gttsmap help for more information.
  toltype            Tolerance type (0 for RELATIVE and 1 for ABSOLUTE). See
                     gttsmap help for more information.
  binsz              Image scale (deg/pix). See gttsmap help for more
                     information.
  coordsys           CEL or GAL. See gttsmap help for more information.
  xref               x-coord of center (RA or l). See gttsmap help for more
                     information.
  yref               y-coord of center (DEC or b). See gttsmap help for more
                     information.
  proj               Coordinate projection. See gttsmap help for more
                     information.
  outfile            Output file name.
  analysis           UNBINNED. Only unbinned analysis supported.
  expmap             Input exposure map. See gttsmap help for more
                     information.

  optional arguments:
  -h, --help         show this help message and exit
  --savetmp SAVETMP  Save the temporary files (default is False).

  example:
  This example creates a TS Map called '3C279_tsmap.fits' with 100
  bins and using 6 threads.  Each bin is 0.5 degrees square.  It uses
  the event file '3C279_filtered_gti.fits', the spacecraft file
  'SC.fits', the exposure map '3C279_expmap.fits', the livetime cube
  '3C279_ltcube.fits', the model file '3C279_model.xml' and the
  P7SOURCE_V6.  The optimization is done by the MINUIT optimizer at an
  absolute tolerance of 1e-5.  The map is centered on 193.98,-5.82 and
  is created using the STG celestial coordinate system.

  > python gttsmap_mp.py 10 10 6 3C279_filtered_gti.fits SC.fits
    3C279_ltcube.fits 3C279_model.xml P7SOURCE_V6
    MINUIT 1e-05 1 0.5 CEL 193.98 -5.82 STG 3C279_tsmap.fits UNBINNED
    3C279_expmap.fits