README.md

# Fermi-LAT HealPix intensity skymapping tool

Tool  to create gamma-ray intensity skymaps in HealPix format from Fermi-LAT data.

Programme (c++):

healpix_fermi_intensity_skymap.cc


  Description:

   Divides Fermi-LAT HealPix counts maps by exposure maps to produce HealPix intensity maps.
   The counts maps are assumed to have been generated by FermiTools gtbin with algorithm=HEALPIX
   The exposure maps are assumed generated by gtexpcube2 in Healpix and the same event selections as the counts

   Maps in energy ranges as columns,  and energy-integrated values both increasing ("up") and decreasing ("down") in energy  are output to separate files. 
   Gaussian-smoothed energy bins and  energy-integrated values are  also output.
   Spherical-harmonic maps A_lm are output, by energy ranges in columns.

   The two input files are arguments, the first is divided by the second, with interpolation of the second in energy, according to the energies.
   The exposure need not have the same HealPix order as the counts; if different, the exposure is rebinned to the order of counts before division.
   The pixel solid angle (uniform = 4pi/number of pixels in HealPix) is used to convert units to intensity per sr.
  
   Units: 
   
    counts:    counts in pixel in energy bands
    
    exposure:  cm^2 s
    
    intensity: photons cm^-2 sr⁻1 s⁻1  in energy bands
    

   Requires HealPix v3.11 or higher,  available from http://healpix.jpl.nasa.gov/

   Usage: 

    ./healpix_fermi_intensity_skymap  counts_filename  exposure_filename  FWHM  prefix

                  counts_filename   input HealPix  counts file   (may be .gz, in which case the output file is also .gz)
                  exposure_filename input HealPix  exposure file (may be .gz)
                  FWHM              Gaussian full width half-max in degrees for smoothing
                  prefix            prefix prepended to output files

                 
   Restrictions: must be run in same directory as input files since output filenames are based on input filenames
   
   The maps can be viewed, rotated etc with the Aladin programme provided by CDS Strasbourg.
   Energies are selected by columns using 'Edit>Preferences'.
   Note Aladin will read .gz files.

   Version 2.0


Build instructions are in the header of the file and copied here:

These are examples for MPE installation, replace with appropriate paths.

--------------------------------------------------------

linux: 

setenv FITSIO_DIRECTORY /afs/ipp-garching.mpg.de/home/a/aws/propagate/c/cfitsio/3.26/gcc_sles11_olga2/cfitsio

using HEALPix v3.11:

setenv HEALPIX_PATH /afs/ipp-garching.mpg.de/home/a/aws/Healpix/Healpix_3.11/src/cxx/generic_gcc

GNU compiler:
g++  healpix_fermi_intensity_skymap.cc -I$HEALPIX_PATH/include -L$HEALPIX_PATH/lib -I$FITSIO_DIRECTORY/include -L$FITSIO_DIRECTORY/lib -lhealpix_cxx -lcxxsupport -lsharp -lfftpack -lc_utils -lcfitsio -fopenmp -lcfitsio -o healpix_fermi_intensity_skymap


using HEALPix v3.50: (note change of fft library!)

setenv HEALPIX_PATH /afs/ipp-garching.mpg.de/home/a/aws/Healpix/Healpix_3.50/src/cxx/generic_gcc

g++  healpix_fermi_intensity_skymap.cc -I$HEALPIX_PATH/include -L$HEALPIX_PATH/lib -I$FITSIO_DIRECTORY/include -L$FITSIO_DIRECTORY/lib -lhealpix_cxx -lcxxsupport -lsharp -lpocketfft -lc_utils -lcfitsio -fopenmp -lcfitsio -o healpix_fermi_intensity_skymap

-----------------------------

using HEALPix v3.60: (note change of healpix libraries!) and newer cfitsio

module load gcc

setenv HEALPIX_PATH /afs/ipp-garching.mpg.de/home/a/aws/Healpix/Healpix_3.60_module_load_gcc

setenv FITSIO_DIRECTORY /afs/ipp-garching.mpg.de/home/a/aws/propagate/c/cfitsio/3.47/cfitsio-3.47/build

g++  healpix_fermi_intensity_skymap.cc -I$HEALPIX_PATH/include/healpix_cxx  -I$HEALPIX_PATH/include/libsharp  -L$HEALPIX_PATH/lib -I$FITSIO_DIRECTORY/include -L$FITSIO_DIRECTORY/lib -lhealpix_cxx -lsharp  -lcfitsio -fopenmp -lcfitsio -o healpix_fermi_intensity_skymap

------------------------------------------------------------------



Intel compiler:
using HEALPix v3.11

icpc  healpix_fermi_intensity_skymap.cc -I$HEALPIX_PATH/include -L$HEALPIX_PATH/lib -I$FITSIO_DIRECTORY/include -L$FITSIO_DIRECTORY/lib -lhealpix_cxx -lcxxsupport -lsharp -lfftpack -lc_utils -lcfitsio -fopenmp -lcfitsio -o healpix_fermi_intensity_skymap

MacOS:
 at present there is a problem due to OpenMP library, which is not actually used but is automatically detected by HEALPix installation, so this will be fixed. IN PROGRESS.

-----------------------------------------------------------------------------

Sample input data are provided, with the refence output for installation check.

Input files: (10 years of CLEAN event class from HEASARC, 10 energy ranges, HEALPix order 7 (gtbin:counts), 6 (gtexpcube2:exposure)

counts_healpix_full_clean_gt20MeV.fits

exposure_healpix_full_clean_gt20MeV.fits

Set runtime libraries (example from MPE, for healpix 3.60)

setenv LD_LIBRARY_PATH /afs/ipp-garching.mpg.de/home/a/aws/propagate/c/cfitsio/3.47/cfitsio-3.47/build/lib:/afs/ipp-garching.mpg.de/home/a/aws/Healpix/Healpix_3.60_module_load_gcc/lib

run command ( 1 deg smoothing, prefix=test):

   ./healpix_fermi_intensity_skymap  counts_healpix_full_clean_gt20MeV.fits exposure_healpix_full_clean_gt20MeV.fits 1 test

Output files:

test_healpix_intensity_using_counts_healpix_full_clean_gt20MeV.fits
test_healpix_intensity_integrated_up_using_counts_healpix_full_clean_gt20MeV.fits
test_healpix_intensity_integrated_down_using_counts_healpix_full_clean_gt20MeV.fits
test_healpix_intensity_smoothed_using_counts_healpix_full_clean_gt20MeV.fits
test_healpix_intensity_integrated_up_smoothed_using_counts_healpix_full_clean_gt20MeV.fits
test_healpix_intensity_integrated_down_smoothed_using_counts_healpix_full_clean_gt20MeV.fits
test_healpix_exposure_rebinned_using_exposure_healpix_full_clean_gt20MeV.fits
test_healpix_intensity_Alm_using_counts_healpix_full_clean_gt20MeV.fits

Sample images made with Aladin on these files: *.jpeg

2-5 GeV (erange6), unsmoothed

 Centred on Galactic plane
 
 Pan to North
 
 Anticentre zoom
 
 Northern hemisphere
 
 Southern hemisphere

12.6-31.7 GeV (erange8) unsmoothed

 Centred on Galactic plane


-----------------------------------
   
A. W. Strong, MPE, first release 30 Nov 2019

History:

20190806 First version v1.0

20190808 HEALPix 3.50 library 

20190820 added EBOUNDS extension to all intensity maps

20191130 added integration downward in energy. v2.0

20200530 added build for healpix-3.60 and newer cfitsio

20200828 added setenv LD_LIBRARY_PATH for runtime libraries