Luigi Tibaldo / gammalib

New Features and Important Changes in GammaLib 2.0.0

22 October 2021


1. Introduction
---------------
This document briefly summarizes module by module the most important changes
made since the last release of GammaLib.


2. Public interface modifications
---------------------------------
The following classes have been added:
- GFunctions
- GIntegrals
- GResponseVectorCache
- GSkyDirs
- GSkyRegionRect
- GModelAssociation
- GModelAssociations
- GModelSpectralBins
- GCTAModelSkyCube
- GCTABackground2D

The following classes have been removed:
- GCTAExceptionHandler
- GCTAException
- GLATExceptionHandler
- GLATException
- GMWLExceptionHandler
- GMWLException

The following classes have been renamed:
- none

The following methods have been added:
- GApplication::eCO2()
- GApplication::stamp(GFitsHdu&)
- GApplication::stamp(GFits&)
- GApplication::stamp(GFilename&)
- GFitsTableCol::tscale()
- GResponse::convolve(GModelSky&, GObservation&, GMatrixSparse*)
- GResponse::irf_spatial(GModelSky&, GObservation&, GMatrix*)
- GObservation::model(GModels&, GMatrixSparse*)
- GObservation::model_grad(GModel&, GModelPar&)
- GObservation::grad_step_size()
- GMatrixBase::is_empty()
- GModels::eval(GObservation&, GMatrixSparse*)
- GModel::eval(GObservation&, GMatrixSparse*)
- GModel::associations()
- GModelSky::eval(GObservation&, GMatrixSparse*)
- GModelData::eval(GObservation&, GMatrixSparse*)
- GModelSky::flux(GEnergy&, GEnergy&)
- GModelSky::flux(GSkyRegion&, GEnergy&, GEnergy&)
- GModelSky::eflux(GEnergy&, GEnergy&)
- GModelSky::eflux(GSkyRegion&, GEnergy&, GEnergy&)
- GModelSky::flux_error(GEnergy&, GEnergy&)
- GModelSky::flux_error(GSkyRegion&, GEnergy&, GEnergy&)
- GModelSky::eflux_error(GEnergy&, GEnergy&)
- GModelSky::eflux_error(GSkyRegion&, GEnergy&, GEnergy&)
- GModelSpatialComposite::flux(GSkyRegion&, GEnergy&, GTime&)
- GModelSpatialDiffuseConst::flux(GSkyRegion&, GEnergy&, GTime&)
- GModelSpatialDiffuseCube::flux(GSkyRegion&, GEnergy&, GTime&)
- GModelSpatialDiffuseMap::flux(GSkyRegion&, GEnergy&, GTime&)
- GModelSpatialPointSource::flux(GSkyRegion&, GEnergy&, GTime&)
- GModelSpatialRadial::is_energy_dependent()
- GModelSpatialRadial::is_time_dependent()
- GModelSpectralFunc(GModelSpectral&, GEnergies&)
- GModelSpectralFunc::nodes()
- GModelSpectralFunc::is_empty()
- GModelSpectralFunc::append()
- GModelSpectralFunc::insert()
- GModelSpectralFunc::remove()
- GModelSpectralFunc::reserve()
- GModelSpectralFunc::extend()
- GModelSpectralFunc::energy()
- GModelSpectralFunc::intensity()
- GModelSpectralFunc::save()
- GModelSpectralNodes::error()
- GSkyMap::correlate()
- GSkyMap::flux(GSkyRegion&, int&)
- GSkyMap::flux(GSkyRegions&, int&)
- GSkyMap::solidangle(GSkyRegion&)
- GSkyMap::solidangle(GSkyRegions&)
- GOptimizerLM::npars()
- GOptimizerLM::nfree()
- GXmlElement(std::string&, int&)
- GXmlElement(std::string&, double&)
- GXmlElement(std::string&, std::string&)
- GXmlElement::value()
- GXmlElement::string()
- GXmlElement::real()
- GXmlElement::integer()
- GPhases::contains()
- GCTAEventBin::emin()
- GCTAEventBin::emax()
- GCOMObservation::GCOMObservation(GCOMDri&, GCOMDri&, GCOMDri&, GCOMDri&)
- GCOMObservation::drename()
- GCOMObservation::drbname()
- GCOMObservation::drgname()
- GCOMObservation::drxname()
- GCOMObservation::response(GCOMResponse&)
- GCOMObservation::compute_drb()
- GCOMDri::tof_correction()
- GCOMDri::num_superpackets()
- GCOMDri::num_used_superpackets()
- GCOMDri::num_skipped_superpackets()
- GCOMSelection::phase_curve()
- GCOMSelection::phases()
- gammalib::tmpnam()
- gammalib::compare()
- gammalib::xml_check_parnum()
- gammalib::xml_check_type()
- gammalib::check_energy_interval()
- gammalib::check_prj_x2s_status()
- gammalib::check_prj_s2x_status()

The following methods have been removed:
- GFitsTableCol::scale()
- GCOMObservation::drm(GModelSky&)
- GCOMResponse::irf_spatial()

The following methods have been renamed:
- none

The arguments for the following methods have been changed:
- GModelSpatial::flux(GSkyRegion&, GEnergy&, GTime&) was
  GModelSpatial::flux(GSkyRegion*, GEnergy&, GTime&)
- GCOMObservation::drm(GSkyModel&) was GCOMObservation::drm(GSource&)

The return value of the following methods has been changed:
- GCOMObservation::drb() now returns reference to GCOMDri
- GCOMObservation::drg() now returns reference to GCOMDri
- GCOMObservation::drx() now returns reference to GCOMDri


3. Configuration
-----------------
None


4. Documentation
----------------
Add Astrophysics Source Code Library (ASCL) shield to "About" page (#3630)


5. Application module
---------------------
Add GApplication::stamp() methods to write provenance information into a FITS
HDU, a FITS object or a FITS file. So far the only provenance information that
is written is the CREATOR keyword (#3662).

Add GApplication::eCO2() method to estimate the carbon footprint if the elapsed
CPU time. The carbon footprint estimation is also added to the trailer text of
an application to raise awareness (#3592).

Corrected the computation of the elapsed CPU time in an application in case
that OpenMP is enabled (#3417).


6. Base module
--------------
None


7. FITS I/O Interface
---------------------
The extension name check is now case insensitive in GFits::extno().

Added GFitsTableCol::tscale() methods and a m_tscale member to the class that
contains the optional TSCALn keyword value (m_tscale=1 in case that no scaling
keyword is found). Upon loading of a column with m_tscale!=1 the FITS scaling
will be set to 1 and TZERO to 0 so that the values are loaded unscaled. This
assures that no information is lost. If needed, scaling of the FITS column
values has to be performed manually. The GFitsTableCol::scale() method was
removed since it won't have any effect anymore (#3553).


8. Linear algebra module
------------------------
Fixed some issues with matrix methods that did not work on empty matrices. The
GMatrixBase::is_empty() method was added to check whether a matrix is empty
or not (#3541).

Fixed an incompatibility between GMatrixSparse::mix_column_prepare() and
GMatrixSparse::mix_column() methods that led in rare cases to a segmentation
fault (#3563).

Implemented GMatrixSparse::row() and GMatrixSparse::add_to_row() methods.


9. Model module
---------------
Added GModelSpectralFunc spectral model constructor that enables creating a file
function from an arbitrary spectral model (#3626).

Added GModelSpectralBins class that implements statistically independent spectral
bins as the spectral model component. In addition, added GModelSpectralNodes::error()
method so that intensity errors can be accessed directly (#3606).

Added methods to GModelSpectralFunc to allow building of a file function
in memory (#3535).

Added GModelAssociation class to implement a model association and the
GModelAssociations container class to hold a list of model associations.
The GModelAssociations class was added as a member of GModel, and
GModel::associations() getter and setter methods have been implemented to
access the associations. The associations are also automatically written in
the GModel::read_attributes() and GModel::write_attributes() methods, and
the association names are displayed by GModel::print_attributes() (#3469).

Added GModels::eval() vector evaluation method to compute the model values for
all events within a given observation (#3455).

Added methods to GSkyModel to compute the photon flux and energy flux as
well as their errors (#3439, #3074).

Added analytical gradients to the GModelSpatialRadialGauss class (#3203).

Added is_energy_dependent() and is_time_dependent() methods to GModelSpatialRadial
to allow for checking of energy or time dependence of spatial model components.

Reimplemented the GModelSpatial::flux(GSkyRegion&, GEnergy&, GTime&) method at
the level of the following derived classes so that flux computation works for all
kind of regions:
- GModelSpatialComposite
- GModelSpatialDiffuseConst 
- GModelSpatialDiffuseCube
- GModelSpatialDiffuseMap
- GModelSpatialPointSource
(#1785)

A pre-computation cache was added to the GModelSpatialGauss class (#1300).


10. Numerics module
-------------------
The GFunctions class was added to implement the virtual base class for a set of
functions. The GIntegrals class was added that performs integration over a set
of functions (#3328).


11. Observation module
----------------------
Add numerical gradient step size as member of GObservation to allow instrument-
specific step size values.

The GResponse class now support the fitting of spectral lines which requires that
energy dispersion is enabled in the computations (#3386).

Add GPhases::contains() method to check whether a phase is contained in the phase
container (#3564).

The sparse gradient matrix is now transposed in the likelihood method so that the
elements can be access column-wise instead of row-wise, which speeds-up the element
access (#3501).

Add source removal from vector cache to GResponse::remove_response_cache()
method (#3499).

The GResponseVectorCache class was added to handle caching of the vector response.
Only non-zero IRF values are stored by the class. The class was integrated in the
GResponse class (#3403).

A vectorised response computation was implemented in GResponse that computes the
IRF for all events in a given observations. This allows for a considerable reduction
of the operations, in particular for binned or stacked analysis, where the code can
benefit from the cube structure of the data. The vectorised response is now used
by all likelihood functions (#3203).

The GResponse::edisp_kern integration kernel class that is used for the integration
over true energies in case that energy dispersion should be considered now derives
from GFunctions. The actual function value is returned in the first slot of the
GNdarray returned by the GResponse::edisp_kern::eval() method, while the other slots
contain the analytical parameter gradients. The GIntegrals class is now used in the
GResponse::convolve() method to perform the true energy integration, integrating not
only the function but also any available parameter gradients (#3333).


12. Optimization module
-----------------------
The members m_npars, m_nfree and m_num_dec were not copied in the
GOptimizerLM::copy_members(). Copying of these missing members was added to the
method.

Added GOptimizerLM::npars() and GOptimizerLM::nfree() methods.


13. Sky module
--------------
Added GSkyMap::correlate() method as opposed to GSkyMap::smooth(). While the later
smoothes a map, and hence conserves the intensity in a sky map, the correlate()
method will sum the intensities over a correlation kernel and assign the result to
the sky map pixels (#3461). 

Fixed a bug in GSkyMap::stack_maps() where the stacked map was always stored in a
one-dimensional GNdarray. Now, a stacked map is saved as a two-dimensional
GNdarray for WCS maps.

Added GSkyDirs container class to hold sky directions. The GHealpix::boundaries()
method now returns an instance of GSkyDirs (#3324).

Added GSkyRegionRect class to implement a rectangular region on the sky (#3248).

Added GSkyMap::flux(GSkyRegion&, int&) and GSkyMap::flux(GSkyRegions&, int&) methods
to compute the total flux within a given sky region or a list of sky regions. The flux
returns the sum of the intensity times the solidangle for all pixels that are contained
within the sky region(s). Containment is tested using the GSkyMap::contains() methods.
Equivalent methods GSkyMap::solidangle(GSkyRegion&) and GSkyMap::solidangle(GSkyRegions&)
were added to compute the total solid angle within specified sky region(s) (#1785).


14. Support module
------------------
Added gammalib::compare() function to compare two floating point numbers with a
relative tolerance (#3552).

Added gammalib::tmpnam() function to return a temporary file name, in replacement
of the deprecated str::tmpnam() function (#3324).

The GException class was reworked so that only a limited number of standard exceptions
are thrown by GammaLib. This allows for a simpler and more coherent Python interface.
All specific exception methods were removed, and a number of help functions were
implemented to reduce code duplication (#35).


15. XML module
--------------
Added value constructors the GXmlElement interface and the methods value(), string(),
real() and integer() to access the value as string, floating point or integer value
(#3431). 


16. VO module
-------------
Use gammalib::tmpnam() instead of str::tmpnam() in GVOClient (#3324).


17. Xspec module
----------------
None


18. Test module
---------------
None


19. Multi-wavelength interface
------------------------------
None


20. Fermi-LAT interface
-----------------------
Adapted the GLATResponse interface to the vectorised response computation (#3203).


21. CTA interface
-----------------
Added the GCTABackground2D class that implements a two-dimensional background model
spanned by energy and offset angle (#3527).

Added the GCTAEventBin::emin() and emax() methods that return the energy boundaries
of the event bin (#3472).

Added the GCTAModelSkyCube class that implements a data space model for CTA (#3442).

Implement in GCTAResponseCube an optimised vectorised response computation for radial
models that applies for a stacked analysis. The code supports in particular analytical
spatial model gradients (#3203).


22. COMPTEL interface
---------------------
Add phase selection to GCOMSelection and GCOMDri (#3564).

Store DRB, DRG and DRX as instances of GCOMDri instead of GSkyMap in GCOMObservation
(#3560).

Added GCOMObservation::compute_drb() method to compute background models for COMPTEL.
So far the PHINOR and BGDLIXA background methods were implemented (#3557).

Added method to set COMPTEL response using GCOMResponse instance.

Added DRI constructor to GCOMObservation class.

Added member access methods to GCOMDri class.

Implemented ToF correction when reading EVP version 2 datasets (#3549).

Implemented ToF correction in IRF computation. The ToF correction is based on table 1
in COM-RP-ROL-DRG-057 (#3548).

Set the COMPTEL average deadtime to 0.965 as quoted in Rob van Dijk's thesis on page
62 (#3547).

Added methods to access DRI filenames in GCOMObservation.

Implemented vectorised response computation in GCOMResponse::irf_ptsrc() method (#3501).

Remove internal response caching since caching is handled by the base class response
computation methods (#2973).


23. INTEGRAL/SPI interface
--------------------------
None