Eirik Hatlen / gammalib

New Features and Important Changes in GammaLib 2.0.0

15 January 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
- GCTAModelSkyCube

The following classes have been removed:
- none

The following classes have been renamed:
- none

The following methods have been added:
- GResponse::convolve(GModelSky&, GObservation&, GMatrixSparse*)
- GResponse::irf_spatial(GModelSky&, GObservation&, GMatrix*)
- GObservation::model(GModels&, GMatrixSparse*)
- GObservation::model_grad(GModel&, GModelPar&)
- 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&)
- GModelSpatialRadial::is_energy_dependent()
- GModelSpatialRadial::is_time_dependent()
- GSkyMap::correlate()
- 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()
- GCTAEventBin::emin()
- GCTAEventBin::emax()
- gammalib::tmpnam()

The following methods have been removed:
- none

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:
- none


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


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


5. Base module
--------------
None


6. FITS I/O Interface
---------------------
None


7. Linear algebra module
------------------------
Implemented GMatrixSparse::row() and GMatrixSparse::add_to_row() methods.



8. Model module
---------------
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.

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


9. 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).


10. Observation module
----------------------
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).


11. Optimization module
-----------------------
Added GOptimizerLM::npars() and GOptimizerLM::nfree() methods.


12. 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).


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


14. 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). 


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


16. Xspec module
----------------
None


17. Test module
---------------
None


18. Multi-wavelength interface
------------------------------
None


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


20. CTA interface
-----------------
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).


21. COMPTEL interface
---------------------
Implement vectorised response computation in GCOMResponse::irf_ptsrc() method (#3501).


22. INTEGRAL/SPI interface
--------------------------
None