New Features and Important Changes in GammaLib 2.1.0

8 July 2025


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


2. Public interface modifications
---------------------------------
The following classes have been added:
- GVectorSparse
- GModelDataMultiplicative
- GCOMDris
- GCOMHkd
- GCOMHkds

The following classes have been removed:
- none

The following classes have been renamed:
- none

The following methods have been added:
- gammalib::get_current_rss()
- gammalib::get_current_clock()
- GEnergy::eV()
- GEnergy::log10eV()
- GNdarray::index(int&)
- GIntegral::adaptive_gauss_kronrod()
- GMatrixSparse::add_to_column(int&, GVectorSparse&)
- GMatrixSparse::multiply_column()
- GMatrixSparse::column_to_vector()
- GMatrixSparse::colfill_init()
- GMatrixSparse::colfill_set_column()
- GMatrixSparse::colfill_flush()
- GSkyDir(std::string&)
- GSkyDir::set(std::string&)
- GSkyMap::operator==()
- GSkyMap::operator!=()
- GGti::append(GTimes&, GTimes&)
- GModelSpectralTable::nspectra()
- GModelSpectralTable::scale_energy()
- GModelSpectralTable::has_energy_scale()
- GModelSpatialComposite::normalize()
- GResponseVectorCache::load()
- GResponseVectorCache::save()
- GResponseVectorCache::read()
- GOptimizerLM::status_string()
- GCOMObservation(GCOMDri&, GCOMDri&, GCOMDri&, GCOMDri&, GCOMDri&)
- GCOMObservation::npred()
- GCOMObservation::drw()
- GCOMObservation::drwname()
- GCOMObservation::hkds()
- GCOMObservation::cachename()
- GCOMResponse::load_cache()
- GCOMResponse::save_cache()
- GCOMResponse::backproject()
- GSPIModelDataSpace::eval(GObservation&, GMatrixSparse*)
- GSPIEventCube::model_name()

The following methods have been removed:
- none

The following methods have been renamed:
- none

The arguments for the following methods have been changed:
- GApplication::log_value() methods now have optional unit parameters
- GObservation::grad_step_size() now takes a GModelPar argument
- GCOMObservation() filename constructor now takes 5 filenames on
  input; was four filenames before
- GCOMObservation::load() method now takes 5 filenames on input; was 
  four filenames before
- GCOMObservation::load() method and GCOMObservation::GCOMObservation()
  constructor now takes also a vector for housekeeping file names on
  input

The return value of the following methods has been changed:
- GModelSpatialComposite::scale now returns a pointer to GModelPar
  instead of a double
- GEvents::number() return value changed from int to double
- GEventCube::number() return value changed from int to double
- GCOMEventCube::number() return value changed from int to double
- GCTAEventCube::number() return value changed from int to double
- GLATEventCube::number() return value changed from int to double
- GMWLSpectrum::number() return value changed from int to double
- GSPIEventCube::number() return value changed from int to double
- GEventList::number() return value changed from int to double
- GCOMEventList::number() return value changed from int to double
- GCTAEventList::number() return value changed from int to double
- GLATEventList::number() return value changed from int to double
- GObservation::nobserved() return value changed from int to double
- GObservations::nobserved() return value changed from int to double
- GCTAOnOffObservation::nobserved() return value changed from int to double

3. Configuration
-----------------
The distutils module was replace by the sysconfig and setuptools modules
in setup.py, with a fallback to distutils in case that either the
sysconfig or setuptools modules are not available. Furthermore, the
production of an egg file with the setuptools was prevented (#4223).


4. Documentation
----------------
None


5. Application module
---------------------
Added optional "unit" parameter was added to the GApplication::log_value() 
methods, and if this parameter is not a zero length string a unit will
be appended to the output (#4202).


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


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


8. Linear algebra module
------------------------
Added GMatrixSparse::multiply_column() method to allow multiplication of
sparse column with a vector (#16).

Added native code to implement unary sparse matrix addition and subtraction.
The native code makes use of the sparse character of uses the column fill
stack for quick filling of the matrix (#11).

Added GVectorSparse class to reduce overhead when dealing with columns of 
sparse matrices (#9).

Added the methods colfill_init(), colfill_set_column() and colfill_flush() to
GMatrixSparse class for quick filling of matrix columns. The columns are stored
in a temporary internal stack and only written into the matrix when
colfill_flush() is called, minimising the number of memory allocations (#9).

Added GMatrixSparse::column_to_vector() method to extract a matrix column into
a preexisting vector. This avoids vector memory allocation during model fitting
and leads to a speed-up of the operations (#9).


9. Model module
---------------
The GModelDataMultiplicative class was added to handle multiplicative data
space models, in particular for SPI (#16).

The GModelSpatialEllipticalDisk and GModelSpatialEllipticalGauss classes now
use exact spherical computation for the model evaluation. The extension of
the Gaussian model was increased from 3 to 4 sigma and the clipping of the 
model values beyond that limit was removed to improve the convergence of 
model fitting (#13).

Elliptical models now interpret the position angle in Galactic coordinates,
counted counterclockwise from Galactic North, if model location is specified
in Galactic coordinates (#13).

Properly compute scale gradients in GModelSpatialComposite class and add
a flag to the void constructor that signals whether the scale factors should
be normalised. Add a GModelSpatialComposite::normalize method to return the
status of the flag (#1).

Fix bug in GModelSpectralTable::par_index where the total size of the table
model was used (including the "Normalization") factor, while "Normalization"
is not part of the table model.

The flux computation in the GModelSpatial::flux method was generalised so that
it now can handle all types of sky regions. Before the method only worked for
circular sky regions (#4467).

The solid angle computation in GSkyRegionRectangle was fixed so that it correctly
returns the solid angle of a rectangle on the sky. Before the solid angle was
computed for a cartesian rectangle (#4461).

Fixed a segfault problem when saving an empty instance of GModelSpectralTable
(#4198).

Added energy scaling of model that may be useful for table models that scale
with an energy parameter (#4069).

Added GModelSpectralTable::nspectra() method to return number of spectra in a
table model (#4069).


10. Numerics module
-------------------
Added GIntegral::adaptive_gauss_kronrod() method to adaptively compute the 
Gauss-Lobatto-Kronrod integral of a kernel function (#4204).

Added GNdarray::index(int&) method to return the index vector from an array element
index (#4069).


11. Observation module
----------------------
The GObservation::grad_step_size(GModelPar&) method now takes a model argument
and the GObservation::model_grad() and GObservation::npred_grad() methods use
this function now to determine the step size for numerical gradient computations.
This gives more flexibility to instrument specific classes to set numerical
gradient step sizes as needed. The m_grad_step_size member was removed from the
GObservation class (#13).

Added GGti::append(GTimes&, GTimes&) method to append multiple good time
intervals in a single shot (#8).

The GObservation(s)::nobserved() methods and GEvents::number() methods now
return a double precision value instead of an integer to avoid overflow
for a large number of events. This overflow occured previously during 
analysis of INTEGRAL/SPI data (#6).

Properly compute scale gradients in GResponse::irf_composite vector method (#1).

Added support for eV energy units to GEnergy.

Added GResponseVectorCache::load(), save() and read() methods to store and load
response vector cache values using a FITS file (#4159).


12. Optimization module
-----------------------
None


13. Sky module
--------------
Added coordinate string constructor and set() method to the GSkyDir class so
that sky directions can be quickly constructed from coordinate strings. The
methods also support the names of some emblematic sources, such as
"Crab", "Vela" and "Cyg X-1" (#5).

Added comparison operators for sky map. Sky maps are considered identical if their
projections are identical, their coordinate definition and their number if pixels.
The actual content of the map is not relevant (#4209).


14. Support module
------------------
Added gammalib::get_current_clock() method that returns the current system clock
in seconds (#12).

Added gammalib::get_current_rss() method that returns the current resident memory
in Bytes. The method was ported from ctools and can be removed there (#3).


15. XML module
--------------
None 


16. VO module
-------------
None


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


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


19. Multi-wavelength interface
------------------------------
The observation attributes are now extracted from the filename and extension
name.


20. Fermi-LAT interface
-----------------------
None


21. CTA interface
-----------------
A kludge was added to GCTAEventList that allows reading of FITS files where the
Monte Carlo ID keyword start from 0 and not 1, as is the standard for FITS
keywords that include numbers. This enables reading of CTA SDC event files.


22. COMPTEL interface
---------------------
Improved the accuracy of the COMPTEL response computation for extended and
diffuse source models (#14).

Added GCOMResponse::backproject() method that backprojects the event into
a sky map. This method is needed for a fast Richardson-Lucy deconvolution
of the data. The method is designed so that it could become a virtual
method of all response classes (#1).

Added support to GCOMObservation class for reading and writing of housekeeping
data (#4209).

Added GCOMHkd and GCOMHkds classes for the handling of housekeeping data
(#4209).

Added GCOMDris container class. This class specifically provides the
GCOMDris::compute_drws() that allows computation of weighting cubes for
all energy bins (#4209).

Added support for weighting cubes in GCOMObservation class. The filename
constructor takes five filenames, with the third filename being in the DRW
filename. A GCOMObservation::drw() method was added to retrieve the DRW,
GCOMObservation::drwname() methods were added to set and retrieve the DRW
filename (#4209).

Added GCOMObservation::cachename() method to set and retrieve the name of a
response cache file. If set, the response cache file will automatically
written or loaded when handling XML files. In addition, GCOMResponse methods
load_cache() and save_cache() were added to manage the loading and saving
of the response cache (#4159).

Added GCOMObservation::npred() method that computes number of events in a model
component.


23. INTEGRAL/SPI interface
--------------------------
Added the GSPIEventCube::model_name() method that returns the name of the model
with the specified index.

Implemented a SPI specific GSPIObservation::grad_step_size() method to set
parameter dependent step sizes for numerical gradient computation (#13).

Dedicated vector response computation methods were implemented in GSPIResponse
to speed up the IRF computation, in particular for extended or diffuse
spatial models (#12).

Unused parameters are now fixed in the GSPIModelDataSpace::setup_pars() method
to avoid logging of many parameters with zero curvature when doing model
fitting (#7).

The response group name that is stored in GSPIResponse is now written in the
XML file by the GSPIObservation::write() method (#4).

Implemented GSPIModelDataSpace::eval(GObservation&, GMatrixSparse*) method to
speed up considerably the evaluation of data space models (#3).


