Eirik Hatlen / gammalib

New Features and Important Changes in GammaLib 1.2.0

10 November 2016


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:
- GModelSpectralExpInvPlaw
- GModelSpectralPlawEnergyFlux
- GModelSpectralMultiplicative
- GModelSpectralComposite
- GModelSpatialComposite
- GVOTable
- GNdarray
- GFft
- GFftWavetable

The following classes have been removed:
- ...

The following classes have been renamed:
- GModelSpectralPlawPhotonFlux, was GModelSpectralPlaw2

The following methods have been added:
- GApplication::log_string()
- GApplication::log_value()
- GApplication::log_header1()
- GApplication::log_header2()
- GApplication::log_header3()
- GApplication::operator[](const int& index)
- GApplication::pars()
- GApplicationPar::current_value()
- GLog::is_open()
- GLog::is_empty()
- GLog::written_size()
- GSkyMap::is_empty()
- GTime::jd(const std::string& timesys)
- GTime::mjd(const std::string& timesys)
- GTime::secs(const std::string& timesys)
- GTime::days(const std::string& timesys)
- GTime::jd(const double& time, const std::string& timesys)
- GTime::mjd(const double& time, const std::string& timesys)
- GTime::secs(const double& time, const std::string& timesys)
- GTime::days(const double& time, const std::string& timesys)
- GTime::gmst()
- GTime::gast()
- GTime::lmst(const double& geolon)
- GTime::last(const double& geolon)
- GTime::now()
- GFits::publish()
- gammalib::rstrip_chars()
- GObservations::save_covmat()

The following methods have been removed:
- <all classes>::eval_gradients()
  The eval_gradients() methods duplicate much of the code of the eval()
  methods. To increase the maintainability of the code, the eval_gradients()
  methods have been removed, and the computation of partial derivatives is
  now done by the eval() methods if the optional gradients argument is set
  to true.

The following methods have been renamed:
- GModelSpectralPlawPhotonFlux::flux(), was GModelSpectralPlaw2::integral()
- GLog::buffer_size(), was GLog::max_size()

The arguments for the following methods have been changed:
- GApplication::log_parameters() now has a mandatory GChatter argument
- <all classes>::eval() has now an optional gradients parameter (see above)

The return value of the following methods has been changed:
- GSkyMap::write() now returns a pointer to GFitsHDU instead of void


3. Configuration
-----------------
The Python wrappers were always removed when typing "make clean", even if
they had been shipped with the code. Now, the Python wrappers are only
removed in a "make clean" if they have been built (#1826).


4. Application module
---------------------
The GApplication::log_parameters() method now takes a mandatory GChatter
argument to enable displaying of parameters only above a given chattiness
level. This avoids a log-level check in the client code. For the same
purpose, the GApplication methods log_string(), log_value(), log_header1(),
log_header2(), and log_header3() have been introduced. There are three
variants of log_value() for strings, integers and double precision values
(#1828).

The application name and version and now conserved in a GApplication::clear()
method call and the application is properly initialised like in the call of
a constructor (#1835).

The GLog::copy_members() method simply copied the file pointer, hence after
a copy of a log instance there were two instances holding the same pointer
to the file, and as soon as one instance closes the log file the file
pointer in the second instance became invalid. This has been fixed by
duplicating the file descriptor and opening the log file in the copied
instance using the duplicated descriptor. This solves the problems (#1823).

A GLog::is_open() method has been added to assess whether a log file is
actually opened. The GLog::is_empty() method has been added to assess whether
a log file is actually empty (#1837).

The GLog::size() method now returns the actual size of the log file, including
the number of characters on disk.

The GLog::max_size() method has been renamed to GLog::buffer_size since this
is more explicit (#1837).

GApplication::pars() methods have been added to allow to retrieve or to set all
application parameters. The GApplicationPar::current_value() method has been
added to retrieve the current parameter value without querying for the parameter
(#1838).

Operators have been added to GApplication that allow the access of application
parameters by index (#1838).


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


6. FITS I/O Interface
---------------------
Add GFits::publish() methods that publish a FITS HDU to an Virtual Observatory
hub. If the FITS HDU is an image it will be published as a FITS image, which
table HDUs will be published as VO tables (#1231).


7. Linear algebra module
------------------------
None


8. Model module
---------------
The GModelSpectralPlaw2 class has been renamed to GModelSpectralPlawPhotonFlux
and the integral() methods were renamed to flux(). A new class
GModelSpectralPlawEnergyFlux has been added that handles integral energy
fluxes as opposed to GModelSpectralPlawPhotonFlux that handles integral
photon fluxes. Unit tests have been added for the new class (#1790).

The GModelSpectralExpInvPlaw class has been added that uses a cut-off
parameter instead of a cut-off energy for the exponentially cut-off
power law. The cut-off parameter is the inverse of the cut-off energy
(#1800).

The GModelSpectralMultiplicative class has been added that implements the
product of spectral model components as a new spectral model (#1861).

The GModelSpectralComposite and GModelSpatialComposite classes have been
added that implement composite spectral and spatial models, which are sums
of models as a new model component (#1706).


9. Numerics module
------------------
The GNdarray class has been added that implements a n-dimensional double
precision floating point array (#1768).

The GFft class has been added that performs a Fast Fourier Transformation
of a n-dimensional array. The GFftWavetable class is a support class for
GFft that provides the trigonometric coefficients for a factorisation. For
the moment, GFft does only support 1-dimensional and 2-dimensional arrays
(#1731).


10. Observation module
----------------------
Time setting and getting methods for Julian Days, Modified Julian Days,
native seconds and native days are now available in the GTime class that
allow specifying the time system. Currently, TT, TAI and UTC are supported.
Methods have also been added to the GTime class that return the Greenwich
mean and apparent siderial times, and the local mean and apparent siderial
times that depend on the geographic longitude. Finally, a now() method has
been added to the GTime class that sets the time to the current time (see
#1856).

The GObservations::save_covmat() method computes and saves the covariance
matrix into a FITS file (#1863).


11. Optimization module
-----------------------
None


12. Sky module
--------------
The GSkyMap::write() method now returns a pointer to the written GFitsHDU
object. In case that no sky map is written, for example because none has been
defined so far, the method returns NONE. The GSkyMap::publish() method will
detect the NONE value and will do nothing if no sky map exists (#1835).

The GSkyMap::is_empty() method signals whether a sky map contains no pixels
or no maps (#1828).


13. Support module
------------------
The gammalib::rstrip_chars() function has been added to right strip characters
from a string.

The gammalib::str() functions for single and double precision floating point
numbers now have an increased precision so that significant digits are no
longer lost.


14. XML module
--------------
None


15. VO module
-------------
A GVOTable class has been added that allows handling of VO tables, including
transformation of FITS tables into VO tables and sending VO tables through the
VO hub to other applications (#1231).


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


17. Test module
---------------
A GTestSuite::test_value() method for double precision values has been added
that automatically requires a relative precision of 1.0e-7. The default value
for "eps" has been removed from the former double precision test_value()
method. This should allow writing of more compact unit tests.


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


19. Fermi-LAT interface
----------------------
None


20. CTA interface
-----------------
The dimension of response tables is now checked for being consistent with the
axis dimension (#1848).

The formula for the containment radius computation in GCTAPsf2D::containment_radius
was wrong and has been corrected (#1876).


21. COMPTEL interface
---------------------
None