New Features and Important Changes in GammaLib 1.1.0 Author(s) : Juergen Knoedlseder 24 June 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: - GCTAPsfTable - GWcsSIN The following classes have been removed: - GCTAOnOffObservations The following methods have been added to the public interface: - GApplication::logFileClose() - GObservation::events() (non-const variant) - GObservation::nobserved() - GObservations::nobserved() - GFilename::operator std::string() - GFilename::exists() - GFilename::is_fits() - GFilename::remove() - GFilaname::protocol() - GFilename::path() - GFilename::file() - GCsv::append() - GSkyMap::shape() - GSkyMap::ndim() - GModelSky::spatial() - GModelSky::spectral() - GModelSky::temporal() - GArf::columns() - GArf::at() - GArf::append() - GArf::operator()(int,int) - GArf::operator[](std::string) - GXmlDocument::filename() - GXmlNode::filename() - GXmlNode::parent() - GCTAObservation(GFilename) constructor - GCTAResponseTable::axis(std::string) - GCTAResponseTable::table(std::string) - GCTAResponseTable::has_axis(std::string) - GCTAResponseTable::has_table(std::string) - GCTAEventCube::weights() - GCTAEventBin::weight() - friend GTime operator+(const GTime& time, const double& seconds) - friend GTime operator+(const double& seconds, const GTime& time) - friend GTime operator-(const GTime& time, const double& seconds) - friend double operator-(const GTime& a, const GTime& b) - GTime::operator+=(const double& seconds) - GTime::operator-=(const double& seconds) - friend double operator/(const GEnergy& a, const GEnergy& b); The following methods have been removed: - GFilename::size() - gammalib::file_exists() - gammalib::file_exists_gzip() - gammalib::is_fits() - GTime::operator+=(const GTime& time) - GTime::operator-=(const GTime& time) - GTime::operator*=(const double& scale) - GTime::operator/=(const double& scale) - friend GTime operator+(const GTime &a, const GTime &b) - friend GTime operator-(const GTime &a, const GTime &b) - friend GTime operator* (const GTime &time, const double &s) - friend GTime operator*(const double &s, const GTime &time) - friend GTime operator*(const GTime &time, const double &s) - friend GTime operator/(const GTime &time, const double &s) - GXmlElement::parent() - GCTACubeExposure::elogmeans() - GCTACubePsf::elogmeans() - GCTACubeBackground::elogmeans() The following methods have been renamed: - GCTAResponseTable::tables(), was GCTAResponseTable::size() - GCTAResponseTable::axis_bins(), was GCTAResponseTable::axis() - GFilename::is_empty(), was GFilename::empty() - GFilename::url(), was GFilename::filename() - GCTAEventCube::counts(), was GCTAEventCube::map() The following classes now use GFilename for filenames arguments instead of std::string: - GApplicationPar - GApplicationPars - GArf - GCsv - GEbounds - GEnergies - GEventCube, GCOMEventCube, GCTAEventCube, GLATEventCube, GMWLSpectrum - GEventList, GCTAEventList, GLATEventList - GEvents - GGti - GLog - GModelSpatialDiffuseCube - GModelSpatialDiffuseMap - GModelSpectralFunc - GModels - GNodeArray - GObservations - GPha - GRmf - GSkyMap - GSkyRegions - GTestSuites - GXml - GCTAAeff, GCTAAeff2D, GCTAAeffArf, GCTAAeffPerfTable - GCTABackground, GCTABackground3D, GCTABackgroundPerfTable - GCTACubeBackground, GCTACubeExposure, GCTACubePsf - GCTAEdisp, GCTAEdisp2D, GCTAEdispPerfTable, GCTAEdispRmf - GCTAObservation - GCTAOnOffObservations - GCTAPointing - GCTAPsf, GCTAPsf2D, GCTAPsfKing, GCTAPsfPerfTable, GCTAPsfVector The return value has been changed for the following methods: - GFits::filename() returns now GFilename instead of std::string - GCTAObservation::eventtype() returns now std::string instead of const std::string& - GCaldb::filename() returns now GFilename instead of std::string The interface for the following methods has been changed: - GFitsImage naxes constructor - GFitsImageByte naxes constructor - GFitsImageDouble naxes constructor - GFitsImageFloat naxes constructor - GFitsImageLong naxes constructor - GFitsImageLongLong naxes constructor - GFitsImageSByte naxes constructor - GFitsImageShort naxes constructor - GFitsImageULong naxes constructor - GFitsImageUShort naxes constructor - GSkyMap::save() 3. Configuration ----------------- None 4. Application module --------------------- The GApplicationPar::filename() methods now take and return GFilename objects instead of std::string objects (#1671). A GApplication::logFileClose() method has been added to force writing the trailer and closing the log file. This is primarily useful for usage in Python where the desctructor is not always called. 5. Base module -------------- None 6. FITS I/O Interface --------------------- The GFitsTableCol::insert() method did not work corretly for an empty column since it de-allocated memory without having necessarily memory on disk. This was corrected by allocating now memory after inserting elements into an empty FITS column. GFits now uses the GFilename class to store the FITS filename (fixes #1649). The GFitsImage naxes constructor now takes a std::vector as argument instead of a pointer to an array and a dimension (#1779). 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 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). 9. Numerics module ------------------ None 10. Observation module ---------------------- A non-const GObservation::events() method has been added to allow for the manipulation of events within an observation without the need to create a local copy. The argument of GObservation::deadc(GTime) now defaults to GTime() so that no argument is needed when calling the method. This reflects the fact that the deadtime correction is often computed as an average value over the observation, and does in fact not depend on time (#1670). The GTime operators have been revised as time is implemented as an absolute quantity, while addition and subtraction of GTime objects are relative operations. The GTime arguments of the operators have thus be replaced by double precision values that specify relative time in seconds. The multiplication and division operators have been removed (#1714). The GObservations::nobserved() method has been added that returns the total number of events in an observation container. The method is used by the print() method. The method uses the GObservation::nobserved() method that have also been added to determine for each observation the number of observed events (#1723). A division operator has been added to the GEnergy method to compute the ratio of two energies. 11. Optimization module ----------------------- None 12. Sky module -------------- The GSkyMap load() and save() methods now support the handling of FITS extension names. Users can now specify with which extension name a sky map is written to a FITS file, and from which extension name it should be loaded. This allows to have multiple sky maps in the same file, and to mix also HEALPix and WCS maps in the same file (#1695). A GSkyMap::publish() method has been added that publishes the sky map on a Virtual Observatory Hub. This finally makes GammaLib interoperable with VO imaging tools (#1231). A shape member was added to the GSkyMap class to enable handling of images with more than 3 dimensions. The shape() methods set or retrieve the number of maps in each of the dimensions, the ndim() method returns the number of dimensions. Note that a longitude and latitude dimensions are not counted in the map dimensions, i.e. a 3D image cube with longitude, latitude and a number of maps has a dimension of 1 (#1733). An optional extname argument has been added to the GSkyMap::save() method so that the extension name can be set (#1787). The Orthographic/synthesis (SIN) projection has been added to the WCS projections (#1798). 13. Support module ------------------ The GFilename class has been extended and some methods have been renamed. The full filename including and FITS extension is now returned by an implicit type conversion operator std::string(). The filename() method has been renamed to url(), and the methods exists(), is_fits() and remove() have been added to replace functions of the GTools module that were used for this purpose in the past. Furthermore, the method protocol() returns the access protocol (e.g. http, ftp, file) of the file name, the method path() returns the path of th file name, and the method file() returns the file name without the path. Put FITS access in a critical OMP zone to make GFilename::is_fits() thread safe (#1717). The gammalib::number() function was added to convert a singular noun into a plural noun is the number of instances of the noun is not one (#1743). The GCsv::append() method appends a list of strings to a CSV file. This allow easy creation of a CSV file, in particular from Python lists (#1773). 14. XML module -------------- The GXmlAttribute class does no longer store the hyphens of an attribute, but the hyphens are stripped upon construction, and added back when writing the attribute into a URL. The side effect of this new behaviour is that XML test reports are also written in case that an exception has occured during a unit test (#1746). The node parent attribute has been move from the GXmlElement class to the GXmlNode class, the parent() access methods have also been moved to GXmlNode. A filename() method has been added to the GXmlNode and GXmlDocument classes that enables accessing the file name of the XML file from a GXmlNode object. The method walks up the parents until the root node is found, and it gets the file name from the root node (#1808). 15. VO module ------------- A GVOClient::publish() method was added that allows publishing of a FITS image to the Hub. The FITS image will be saved into a temporary storage location and the Hub will be informed that an image is available. 16. Xspec module ---------------- The GArf class now also handles additional double precision columns that may be needed for response computation. 17. Test module --------------- A GTestSuite::test_value() method has been added for strings to simplify the writing of test cases for string comparison (#1772). 18. Multi-wavelength interface ------------------------------ None 19. Fermi-LAT interface ---------------------- Pass 8 response function and data are now supported. The LAT module has been adapted so that event types can be handled. Note that the fisheye effect is not taken into account (#1517). 20. CTA interface ----------------- The response table instrument response functions now rely on the FITS table column names to determine the information instead of hard-wired column indices (#1656). Event fetching and disposal has been implemented in the GCTAEventList class by additing the fetch() and dispose() methods. Now, events are only loaded upon request and can be dispatched after user to save memory. The event fetching and disposal logic has been removed from GCTAObservation (#1648). Add GCTAEventList::remove() method to remove events from an event list. The GCTAEventList::append() method now also appends empty elements to the additional columns so that all event list columns have finally the same length. The GCTAEdisp2D::compute_ebounds_obs() and GCTAEdisp2::compute_ebounds_src() methods have been corrected so that they return the energy intervals covered by valid matrix elements. With the code before there were problems with not setting correctly the maximum energies of the intervals (#1662). The extension name for the GTI HDU is now determined from the data sub-space keyword provided in the events FITS file header. This allows to have multiple GTIs (and also event lists) in a single FITS file. We do however require that the event and GTI extension reside in the same FITS file. The name of the GTI extension can be recovered using the GCTAEventList::gtiname() method. This satisfies the feature request #1598. A second variant of a write() method has been added to GCTAEventList that allows specifying the events and Good Time Intervals FITS extension names. The standard write() method will call this new write() method using the events extension name extracted from the file name and the GTI extension name set by the m_gti_extname member. The GCTAObservation::write() method was also extended and now has two optional arguments that allow specifying the events and Good Time Interval FITS extension names. These are simply forwared to the new GCTAEventList::write(). The GCTAObservation::save() method has now a special logic that decodes any optionally specified extension in the format [EVENTS;GTI] into an events and a Good Time Intervals extension name. These changes satisfy the feature request #1598. A rejection method is now used in GCTABackground3D::mc() to assure that the Monte Carlo simulated instrument directions are identical to the model evaluations (#1722). Add GCTACubeEdisp class that computes the mean energy dispersion for a stacked analysis. This class is now used in GCTAResponseCube to take into account the energy dispersion is a stacked analysis (#1721, #1801). A filename constructor has been added to GCTAObservation that allows constructing a CTA observation from an event list or a counts cube. A dummy argument has been added to the instrument constructor so that it does not conflict with the filename constructor (#1744). The interpolation scheme was changed in GCTABackground3D. Formerly, if one of the rates above and below the requested energy was zero, the rate from the non-zero node was taken, resulting in a discontinuity. Now the rate is set to zero. The classes GCTACubePsf and GCTACubeEdisp now save the information in 4D images instead of folding two dimension in a single dimension of a 3D image. The GCTAOnOffObservations container class has now been removed, as On/Off observations are now stored as any other observation in the GObservations container (#1669). The On/Off fitting of CTA data has now been implemented (#1044). The GCTAPsfTable class has been added to support non-parametric point spread function histograms (#1786). The classes GCTACubeExposure, GCTACubePsf and GCTACubeBackground store response values for given sets of energies, and now the energies are written into the FITS files instead of the energy boundaries enclosing these energies. This provides a more explicit storage of the response information, as before the energies had to be inferred from the energy boundaries of the bins (#1788). The GCTACubeExposure::elogmeans(), GCTACubePsf::elogmeans(), and GCTACubeBackground::elogmeans() methods have been removed as the energies() methods provide now essentially the same information. A weight sky map has been added to the CTA event cube, and the weight of each bin is multiplied to the bin size in the GCTAEventBin::size() method so that model values are weigthed according to the bin weight. This enables the usage of only partially covered bins, arising for example from different energy thresholds or ROIs (#1789). The cube response classes GCTACubeExposure, GCTACubePsf, GCTACubeEdisp and GCTACubeBackground do no longer select on RoI and energy boundaries as this is now handled by the weight array (#1789). The GCTAAeff2D class no longer extrapolates the effective area beyond the boundaries of the response table, but sets the effective area values to zero (#1784). 21. COMPTEL interface --------------------- None