Karim Sabri / gammalib

New Features and Important Changes in GammaLib 1.2.0

Author(s) : Juergen Knoedlseder

22 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()
- GModelSpatial::region()

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
---------------
Sky directions drawn by GModelSpatialDiffuseConst::mc() are now restricted
to the simulation cone that has previously been defined using the mc_norm()
method. This speeds up considerbly the Monte Carlo simulations for an
isotropic diffuse model (#1674). 

The GModelSpectral eval() and eval_gradients() methods use an empty GTim()
object as default time argument since all spectral models are so far time-
independent. This avoids that a user needs to specify a dummy time argument
(#1672).

The set_mc_cone() methods of the GModelSpatialDiffuseCube class and the
GModelSpatialDiffuseMap class now recompute only the Monte Carlo acceptance
cone in case that the cone centre or radius have changed since the last
computation. This speeds up the computations (#1673).

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

A region() method has been added to the GModelSpatial base class and all
derived classes that returns a pointer to a sky region that bounds the
spatial model. For the moment, only circular sky regions have been
implemented (#1764).

Add GModelSpatialRadialProfile class to handle arbitrary radial profiles.
The method deals with pre-computation and normalization of the profiles,
and implements the eval(), eval_grandients() and mc() method. The class
GModelSpatialRadialProfileGauss has been added to show how to implement
radial profile for the case of a Gaussian, and also to cross-check the
results with the GModelSpatialRadialGauss class that should return basically
the same results (#1520).

The GModelSpatialDiffuseCube::mc() method now uses a rejection method for
simulating sky directions, which makes the MC method identical to the model
evaluation method, using in both cases a log-log interpolation. The simulation
cone is now used for Monte Carlo simulations (#1722).

Also the GModelSpatialDiffuseMap::mc() method now uses a rejection method for
simulating sky directions (#1725).

The methods spatial(), spectral() and temporal() have been added to GModelSky
to allow setting of model components.

Private methods GModel::read_attributes() and GModel::write_attributes() have
been added to centralize the reading and writing of model attributes. These
methods are now called at all relevant places, reducing code duplication and
assuring that all attributes are correctly read by all classes and constructors
(#1765).

The GModelSpatialDiffuseMap, GModelSpatialDiffuseCube and GModelSpectralFunc
class now support the specifications of file names that are relative to the
XML file (#1808).

The spatial model components have been renamed to enhance the readability and
to make them more homogenous. The Fermi/LAT Science Tools should also evolve
to support the new names:
* "PointSource" (alias: "SkyDirFunction")
* "RadialDisk" (alias: "DiskFunction")
* "RadialGaussian" (alias: "GaussFunction")
* "RadialShell" (alias: "ShellFunction")
* "EllipticalDisk"
* "EllipticalGaussian" (alias: "EllipticalGauss")
* "DiffuseIsotropic" (alias: "ConstantValue")
* "DiffuseMap" (alias: "SpatialMap")
* "DiffuseMapCube" (alias: "MapCubeFunction")
By default the old model names are still supported. Support of the old model
names can be turned off by specifying the --disable-legacy-model-names option
to the ./configure script (#1818).

The model classes now write the same XML element names than those that were read
in. In that way a maximum legacy for the Fermi/LAT data format is assured (#1820).

The spectral registry class now also checks for model parameter names which allows
to have models of the same type but with different parameters in the registry
(#1824). The interface for the GModelSpectralRegistry::alloc() method has been
changed so that it no longer takes a name string but an XML element. The same has
been done for the GModelSpatialRegistry and GModelTemporalRegistry classes so that
more general model definition XML file handling can be implemented.

The names of some spectral model components have been modified to be more
explicit and homogenous:
* "Constant" (was "ConstantValue")
* "PowerLaw" (combines "PowerLaw" and "PowerLaw2")
* "BrokenPowerLaw"
* "ExponentialCutoffPowerLaw" (was "ExpCutoff")
* "SuperExponentialCutoffPowerLaw" (was "PLSuperExpCutoff")
* "Gaussian"
* "LogParabola"
* "FileFunction"
* "NodeFunction"
By default the old model names are still supported. Support of the old model
names can be turned off by specifying the --disable-legacy-model-names option
to the ./configure script (#1821).


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


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