From 85bed88b05fb72328ed39778638b59fb6c8bf2c4 Mon Sep 17 00:00:00 2001 From: Jürgen Knödlseder Date: Mon, 25 May 2015 21:21:36 +0200 Subject: [PATCH] Update user documentation. --- doc/source/installation.rst | 10 +++++----- doc/source/quickstart.rst | 8 ++++---- doc/source/user_manual/getting.rst | 6 +++--- doc/source/user_manual/internals.rst | 2 +- doc/source/user_manual/introduction.rst | 17 ++++++++++------- doc/source/user_manual/modules/app.rst | 20 +++++++++++--------- doc/source/user_manual/modules/calltree_model.png | Bin 76951 -> 0 bytes doc/source/user_manual/modules/com.rst | 16 +++++++++------- doc/source/user_manual/modules/cta.rst | 428 ++++++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- doc/source/user_manual/modules/cta_bkg.rst | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/source/user_manual/modules/cta_irf.rst | 219 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/source/user_manual/modules/cta_overview.rst | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/source/user_manual/modules/cta_xml.rst | 119 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/source/user_manual/modules/fits.rst | 12 +++++++----- doc/source/user_manual/modules/inst.rst | 2 +- doc/source/user_manual/modules/intro.rst | 2 +- doc/source/user_manual/modules/lat.rst | 14 ++++++++------ doc/source/user_manual/modules/linalg.rst | 21 +++++++++++---------- doc/source/user_manual/modules/model.rst | 198 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------------------------------------------------------------------------------- doc/source/user_manual/modules/mwl.rst | 18 ++++++++++-------- doc/source/user_manual/modules/numerics.rst | 3 +++ doc/source/user_manual/modules/obs.rst | 25 ++++++++++++++++--------- doc/source/user_manual/modules/opt.rst | 22 +++++++++++----------- doc/source/user_manual/modules/sky.rst | 28 ++++++++++++++++------------ doc/source/user_manual/modules/support.rst | 50 ++++++++++++++++++++++++++++++++++---------------- doc/source/user_manual/modules/uml_app.png | Bin 18826 -> 0 bytes doc/source/user_manual/modules/uml_com.png | Bin 75304 -> 0 bytes doc/source/user_manual/modules/uml_cta.png | Bin 227320 -> 0 bytes doc/source/user_manual/modules/uml_fits.png | Bin 128902 -> 0 bytes doc/source/user_manual/modules/uml_lat.png | Bin 122295 -> 0 bytes doc/source/user_manual/modules/uml_model.png | Bin 171967 -> 0 bytes doc/source/user_manual/modules/uml_obs.png | Bin 116858 -> 0 bytes doc/source/user_manual/modules/uml_sky.png | Bin 70235 -> 0 bytes doc/source/user_manual/modules/vo.rst | 21 +++++++++++---------- doc/source/user_manual/modules/xml.rst | 7 ++++--- doc/source/user_manual/modules/xspec.rst | 21 +++++++++++---------- doc/source/user_manual/quickstart.rst | 10 ++++++++++ 37 files changed, 860 insertions(+), 643 deletions(-) create mode 100644 doc/source/user_manual/modules/cta_bkg.rst create mode 100644 doc/source/user_manual/modules/cta_irf.rst create mode 100644 doc/source/user_manual/modules/cta_overview.rst create mode 100644 doc/source/user_manual/modules/cta_xml.rst diff --git a/doc/source/installation.rst b/doc/source/installation.rst index c3d7cd3..7bb3183 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -4,8 +4,8 @@ Installation .. note :: - These installation instructions apply to gammalib-00-04-10 and - later. gammalib-00-04-10 has been built, installed and tested + These installation instructions apply to gammalib-0.10.0 and + later. gammalib-0.10.0 has been built, installed and tested successfully on Debian, Ubuntu, Mandriva, OpenSUSE, Scientific Linux, CentOS, gentoo, Mac OS X, FreeBSD, and OpenSolaris (using gcc), so hopefully it also installs on your distribution. In case you encounter @@ -64,12 +64,12 @@ Building GammaLib Download the latest source tarball, save it in an appropriate location, and type :: - $ tar xvfz GammaLib-XX-XX-XX.tar.gz + $ tar xvfz gammalib-x.y.z.tar.gz -where ``XX-XX-XX`` is the version number of the library. Step in the created +where ``x.y.z`` is the version number of the library. Step in the created directory using :: - $ cd gammalib-XX-XX-XX + $ cd gammalib-x.y.z and build GammaLib by typing :: diff --git a/doc/source/quickstart.rst b/doc/source/quickstart.rst index 10a8bfd..c122aa6 100644 --- a/doc/source/quickstart.rst +++ b/doc/source/quickstart.rst @@ -5,7 +5,7 @@ First steps with GammaLib ------------------------- GammaLib comes with a Python interface, and as first step you should -verify that the Python interfaces workes correctly. You do this by +verify that the Python interface works correctly. You do this by typing:: >>> import gammalib @@ -62,13 +62,13 @@ Now let's append a model to this container. For this, type:: Constant .................: 1 (relative value) (fixed,scale=1,gradient) With this sequence of commands you first defined a sky direction in -celestial coordinates using ``GSkyDir``. You may easily recognise that this +celestial coordinates using ``GSkyDir``. You may recognise that this is the position of the Crab. You then used this position to define the spatial component of a sky model using ``GModelSpatialPointSource``. As the name suggests, the spatial component is a point source. Next, you defined the spectral component using ``GModelSpactralPlaw``: a power law with -normalisation of 1 and index of -2. Then, you combined the spatial and -spectral components in a point source model using ``GModelSky``. And +normalisation of 1 and a spectral index of -2. Then, you combined the spatial +and spectral components in a point source model using ``GModelSky``. And finally you appended the point source to the model container allocated previously using the append method. When you then print the model container you see that is contains now one model with 6 parameters. diff --git a/doc/source/user_manual/getting.rst b/doc/source/user_manual/getting.rst index 0b5125f..8e6cfb2 100644 --- a/doc/source/user_manual/getting.rst +++ b/doc/source/user_manual/getting.rst @@ -144,8 +144,8 @@ https://sourceforge.net/projects/gammalib/. The code can be downloaded from this site by clicking on the download button. Alternatively, the code can be downloaded and unpacked from the UNIX prompt using:: - $ wget --no-check-certificate https://downloads.sourceforge.net/project/gammalib/gammalib/gammalib-00-10-00.tar.gz - $ tar xfz gammalib-00-10-00.tar.gz + $ wget --no-check-certificate https://downloads.sourceforge.net/project/gammalib/gammalib/gammalib-0.10.0.tar.gz + $ tar xfz gammalib-0.10.0.tar.gz The GammaLib source code can also be cloned using git. This method is recommended if you plan to contribute to the development of the GammaLib @@ -484,7 +484,7 @@ Generating the reference documentation The reference documentation for GammaLib is generated directly from the source code using the `Doxygen `_ documentation system. The latest GammaLib reference manual can be found at -http://gammalib.sourceforge.net/doxygen/. +http://cta.irap.omp.eu/gammalib/doxygen/. The reference documentation is not shipped together with the source code as this would considerably increase the size of the tarball. In case diff --git a/doc/source/user_manual/internals.rst b/doc/source/user_manual/internals.rst index 18a841d..3775815 100644 --- a/doc/source/user_manual/internals.rst +++ b/doc/source/user_manual/internals.rst @@ -6,4 +6,4 @@ Under the hood Registry classes ---------------- -TBW: Describe what a registry class is. +To be written (describe what a registry class is) ... diff --git a/doc/source/user_manual/introduction.rst b/doc/source/user_manual/introduction.rst index 4c289b8..92fbb07 100644 --- a/doc/source/user_manual/introduction.rst +++ b/doc/source/user_manual/introduction.rst @@ -4,8 +4,8 @@ Introduction Scope ----- -This User Manual provides a complete description of the GammaLib C++ library. It -is equally well suited for beginners as well as experienced users. +This User Manual provides a complete description of the GammaLib C++ library. +It is equally well suited for beginners as for experienced users. Overview -------- @@ -34,16 +34,19 @@ that allows for consistent broad-band spectral fitting or imaging. GammaLib source code is freely available under the GNU General Public license version 3. The latest source code can be downloaded from -https://sourceforge.net/projects/gammalib/ which also provides bug -trackers and mailing lists. Further information and documentation on -GammaLib can be found on http://gammalib.sourceforge.net/. The present document -applies to GammaLib version 0.10. +https://sourceforge.net/projects/gammalib/. +The issue tracker can be found at +https://cta-redmine.irap.omp.eu/projects/gammalib/issues. +Further information and documentation on GammaLib can be found at +http://cta.irap.omp.eu/gammalib/. +The present document applies to GammaLib version 0.10. GammaLib is designed to compile on any POSIX compliant platform. So far, GammaLib has been successfully compiled and tested on Mac OS X, OpenBSD, OpenSolaris (using the gcc compiler) and many Linux flavours. Pre-packed binary versions of the code are also available for Mac OS X. For known problems -with specific platforms, please refer to section :ref:`sec_known_problems`. +with specific platforms, please refer to the :ref:`sec_known_problems` +section. GammaLib makes heavily use of C++ classes. Instrument independency is achieved by using abstract virtual base classes, which are implemented as derived diff --git a/doc/source/user_manual/modules/app.rst b/doc/source/user_manual/modules/app.rst index f0f4440..097d8c4 100644 --- a/doc/source/user_manual/modules/app.rst +++ b/doc/source/user_manual/modules/app.rst @@ -6,6 +6,17 @@ Creation of ftools applications Overview ~~~~~~~~ +The following figure presents an overview over the C++ classes of the +application module and their relations. + +.. _fig_uml_app: + +.. figure:: uml_app.png + :width: 35% + :align: center + + *Application module* + The application module provides classes to create ftools applications using GammaLib. A ftool application provides a parameter interface following the IRAF standard that is widely used in high-energy @@ -16,12 +27,3 @@ parameter implemented by the :doxy:`GApplicationPar` class. In addition, an application contains a logger, implemented by the :doxy:`GLog` class, which allows message passing to the console and/or a dedicated log file. -:ref:`fig_uml_app` present an overview over the C++ classes of the -application module and their relations. - -.. _fig_uml_app: - -.. figure:: uml_app.png - :width: 50% - - Application module diff --git a/doc/source/user_manual/modules/calltree_model.png b/doc/source/user_manual/modules/calltree_model.png index c9892d8..f4a7fdf 100644 Binary files a/doc/source/user_manual/modules/calltree_model.png and b/doc/source/user_manual/modules/calltree_model.png differ diff --git a/doc/source/user_manual/modules/com.rst b/doc/source/user_manual/modules/com.rst index c35193f..f20d737 100644 --- a/doc/source/user_manual/modules/com.rst +++ b/doc/source/user_manual/modules/com.rst @@ -6,16 +6,18 @@ COMPTEL interface Overview ~~~~~~~~ -The COMPTEL module provides an instrument interface for the COMPTEL -telescope that has been operated on the Compton Gamma-Ray Observatory -(CGRO) from 1991 to 2000. - -:ref:`fig_uml_com` present an overview over the C++ classes of the COMPTEL +The following figure presents an overview over the C++ classes of the COMPTEL module and their relations. .. _fig_uml_com: .. figure:: uml_com.png - :width: 80% + :width: 70% + :align: center + + *COMPTEL module* + +The COMPTEL module provides an instrument interface for the COMPTEL +telescope that has been operated on the Compton Gamma-Ray Observatory +(CGRO) from 1991 to 2000. - COMPTEL module diff --git a/doc/source/user_manual/modules/cta.rst b/doc/source/user_manual/modules/cta.rst index b8b9149..4d5729c 100644 --- a/doc/source/user_manual/modules/cta.rst +++ b/doc/source/user_manual/modules/cta.rst @@ -3,426 +3,10 @@ CTA interface ------------- -Overview -~~~~~~~~ +.. toctree:: + :maxdepth: 2 -The CTA module provides an instrument interface for Imaging Air Cherenkov -Telescopes (IACT). The interface currently supports the event list data -format developed in the context of the Cherenkov Telescope Array (CTA) -project and provides support for various instrument response formats that -are currently used in the CTA consortium or that are under study. The interface -provides support for unbinned and binned maximum likelihood analysis, and -implements Monte Carlo simulations of high-level data based on the -instrumental response functions. - -:ref:`fig_uml_cta` present an overview over the C++ classes of the CTA -module and their relations. - -.. _fig_uml_cta: - -.. figure:: uml_cta.png - :width: 100% - - CTA module - -Two types of observations are implemented so far: -:doxy:`GCTAObservation` that derives from :doxy:`GObservation` and that -describes either a binned or unbinned data set, and -:doxy:`GCTAOnOffObservation` that describes an On-Off observation -used in classical Cherenkov Telescope data analysis. -Binned or unbinned observations are collected in the -:doxy:`GObservations` container class, while the On-Off observations -are collected in a specific :doxy:`GCTAOnOffObservations` container -class (note that the :doxy:`GCTAOnOffObservations` container may vanish -in the future when :doxy:`GCTAOnOffObservation` objects will also be -collected by the :doxy:`GObservations` container class). - -The data of binned observations are stored by the -:doxy:`GCTAEventCube` class. The :doxy:`GCTAEventCube` class holds the -binned event data in form of a sky map, implemented by the -:doxy:`GSkymap` class. The sky coordinates of all sky map pixels -are stored in an array of CTA instrument directions, implemented -by the :doxy:`GCTAInstDir` class which holds a single :doxy:`GSkyDir` -object. The mean energies of the event cube -are stored in an array of :doxy:`GEnergy` objects, and the mean -time is stored by a :doxy:`GTime` object. The :doxy:`GCTAEventCube` class -holds in fact only a single event bin, implemented by the -:doxy:`GCTAEventBin` class. When the event bin is accessed using -the :doxy:`GCTAEventCube::operator[]` operator, the operator updates -references to the event cube data so that the :doxy:`GCTAEventBin` -object represents the selected event bin. This allows a memory-efficient -storage of event bin information (without storing for example the -instrument direction or the energy for each bin), while preserving -the abstract data model where an event cube of abstract type -:doxy:`GEventCube` is composed of event bins of abstract type -:doxy:`GEventBin` (see :ref:`sec_obs`). - -The data of unbinned observations are stored by the :doxy:`GCTAEventList` -class. The :doxy:`GCTAEventList` class is a container of :doxy:`GCTAEventAtom` -objects that represent individual events. Each event is composed of -a :doxy:`GCTAInstDir` object, a :doxy:`GEnergy` object and a :doxy:`GTime` object. -The region of interest covered by an event list is described by the -:doxy:`GCTARoi` class that derives from the abstract :doxy:`GRoi` class. - -In addition to the event, each :doxy:`GCTAObservation` holds a -pointing object, implemented by the :doxy:`GCTAPointing` class, and -a response object, implemented by the :doxy:`GCTAResponse` class. -The :doxy:`GCTAPointing` class holds a single sky direction of type -:doxy:`GSkyDir` to describe the fixed pointing direction of the -observation. The :doxy:`GCTAResponse` class provides the instrument -response factorised in an effective area term, a point spread -function term and an energy dispersion term -(see :ref:`sec_cta_response` for details on the response -implementation). - -Models of the instrumental background are provided by the -:doxy:`GCTAModelCubeBackground` and :doxy:`GCTAModelRadialAcceptance` -classes that derive from the abstract :doxy:`GModelData` base -class -(see :ref:`sec_cta_background` for details on the background -model implementation). - -.. _sec_cta_xml: - -Describing CTA observations using XML -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -CTA observations can be described in GammaLib using an ASCII file in XML -format (see :ref:`sec_obsxml`). The CTA specific section of this file has -the format: - -.. code-block:: xml - - - - - - - - - -for an unbinned observation and: - -.. code-block:: xml - - - - - - - - - -for a binned observation. Each parameter within the ```` tag -specifies the filename for a specific file that is needed for the analysis. -The difference between an unbinned and a binned observation is that the -first uses an event list (requiring a parameter with name ``EventList``) -while the latter uses an event cube (requiring a parameter with name -``CountsCube``). The ``EffectiveArea``, ``PointSpreadFunction`` and -``EnergyDispersion`` parameters provide the filenames of the instrument -specific response function components for each observation -(see :ref:`sec_cta_response`). Note that for compatibility reasons, -``ARF`` may be used instead of ``EffectiveArea``, ``PSF`` instead -of ``PointSpreadFunction``, and ``RMF`` instead of ``EnergyDispersion``. -The ``EffectiveArea`` parameter supports the additional optional -attributes ``sigma``, ``scale`` and ``thetacut`` to provide information -about the off-axis reponse and event selection (see -:ref:`sec_cta_response`). -So far, energy dispersion is not supported by GammaLib, hence the -``file`` attribute for the ``EnergyDispersion`` parameter can be left -blank. -The ``Background`` parameter allows specifying of a file that contains -the instrument background model for the observation. - -The ``instrument`` attribute of CTA observations can be one of -``CTA``, ``HESS``, ``MAGIC`` or ``VERITAS``. This allows mixing of -observations from difference IACTs within a single analysis. -Note that no code that is specific to any of these four instruments is -implemented in GammaLib, but the ``instrument`` attribute is used to -tie models to instruments, allowing thus to provide specific background -models for each of the instruments in a combined analysis. - - -.. _sec_cta_background: - -Modelling CTA background -~~~~~~~~~~~~~~~~~~~~~~~~ - -The generic class for modelling the CTA background is the -:doxy:`GCTAModelCubeBackground` class. This class derives from the :doxy:`GModelData` -base class and provides a description of the background count rate as -function of reconstructued sky direction, measured energy and event trigger -time. - -The XML description of the background model has the following format: - -.. code-block:: xml - - - - ... - - - ... - - - ... - - - -The ```` tag is optional and can generally be omitted from -the XML file. In that case, the background rate is assumed to be constant -in time. - -The ```` may be any of the spatial model components available -in GammaLib. In particular, a diffuse map cube can be used to provide an -energy dependent template of the background count rate over the field of -view: - -.. code-block:: xml - - - - - - - - - - -In the above example, the file ``my_background_template.fits`` contains -an image cube in the primary extension of the FITS file which describes the -count rate per solid angle and energy -(in units of :math:`counts \, s^{-1} sr^{-1} MeV^{-1}`). -The energy of each map is provided in a binary table extension with name -``ENERGIES`` which contains a single column with name ``Energy`` (the -energy unit may be specified by the ``TUNIT1`` keyword; if the keyword is -omitted, MeV is assumed as unit). - -The ``ConstantValue`` spectrum corresponds to a single scaling factor for -the background model, which in the above example is fitted in the maximum -likelihood analysis. Any spectral model available in GammaLib can be used -as the spectral component, such as for example a power law: - -.. code-block:: xml - - - - - - - - - - - - -In the above example, the map cube spectrum is multiplied by a power law. - -.. _sec_cta_response: - -Handling the instrument response -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Overview -^^^^^^^^ - -The CTA specific instrument response is described by the -:doxy:`GCTAResponseIrf` class (see :ref:`sec_response` for a general description of response -handling in GammaLib). The CTA response is factorised into -the effective area :math:`A_{\rm eff}(d, p, E, t)` (units :math:`cm^2`), -the point spread function :math:`PSF(p' | d, p, E, t)`, -and the energy dispersion :math:`E_{\rm disp}(E' | d, p, E, t)` -following: - -.. math:: - R(p', E', t' | d, p, E, t) = - A_{\rm eff}(d, p, E, t) \, - PSF(p' | d, p, E, t) \, - E_{\rm disp}(E' | d, p, E, t) - :label: irf - - -Effective area -^^^^^^^^^^^^^^ - -The :math:`A_{\rm eff}(d, p, E, t)` term is described by the abstract -:doxy:`GCTAAeff` base class. The effective area is determined using -the: - -.. code-block:: cpp - - double GCTAAeff::operator()(const double& logE, - const double& theta = 0.0, - const double& phi = 0.0, - const double& zenith = 0.0, - const double& azimuth = 0.0, - const bool& etrue = true) const; - -operator, where ``logE`` is the base 10 logarithm of the photon energy. -If ``etrue`` is true, ``logE`` is the true photon energy; otherwise, -``logE`` is the measured photon energy. -``theta`` and ``phi`` are the offset and azimuth angle of the incident -photon with respect to the camera pointing, -``zenith`` and ``azimuth`` are the zenith and azimuth angle of the -camera pointing. - -The effective area response is implemented by one of the classes -:doxy:`GCTAAeffPerfTable`, :doxy:`GCTAAeffArf` and :doxy:`GCTAAeff2D` that -implement the different response formats that are currently used in -the CTA project. Dependent on the specified response file, the -method :doxy:`GCTAResponseIrf::load_aeff` allocates the appropriate response -class. :doxy:`GCTAAeff2D` is allocated if the response file is a FITS file -containing an extension named ``EFFECTIVE AREA``; :doxy:`GCTAAeffArf` is -allocated if an extension named ``SPECRESP`` is found; otherwise, -:doxy:`GCTAAeffPerfTable` is allocated. - - -GCTAAeffPerfTable -""""""""""""""""" - -:doxy:`GCTAAeffPerfTable` reads the effective area information from an ASCII -file that has been defined by the CTA Monte Carlo workpackage -(see :ref:`sec_cta_perftable`). This file provides the full effective detection -area in units of :math:`m^2` after the background cut as function of -the base 10 logarithm of the true photon energy. No theta cut is -applied. For a given energy, the effective area is computed by -interpolating the performance table in the base 10 logarithm of energy. -Effective areas will always be non-negative. -As the response table provides only the on-axis effective area, -off-axis effective areas are estimated assuming that the radial -distribution follows a Gaussian distribution in offset angle squared: - -.. math:: - A_{\rm eff}(\theta) = A_{\rm eff}(0) - \exp \left( -\frac{1}{2} \frac{\theta^4}{\sigma^2} \right) - :label: cta_aeff_offset - -where :math:`\sigma` characterises the size of the field of view. The -:math:`\sigma` parameter is set and retrieved using the -:doxy:`GCTAAeffPerfTable::sigma` methods. When response information is -specified by an XML file (see :ref:`sec_cta_xml`), the :math:`\sigma` -parameter can be set using the optional ``sigma`` attribute. -If the :math:`\sigma` parameter is not explicitly set, -:math:`\sigma=3 \, {\rm deg}^2` is assumed as default. - - -GCTAAeffArf -""""""""""" - -:doxy:`GCTAAeffArf` extracts the effective area information from a XSPEC -compatible ancilliary response file (ARF). The ARF contains the effective -area for a specific angular (or theta) cut. It should be noted that the -:doxy:`GCTAAeffArf` class has been introduced as a work around for digesting -the ARF response provided for the 1st CTA Data Challenge (1DC). It is not -intended to use this class any longer in the future. - -To recover the full effective detection area, the value of the theta cut -as well as the form of the point spread function needs to be known. When -an ARF file is loaded using the :doxy:`GCTAAeffArf::load` method, the ARF -values are read and stored as they are encountered in the ARF file. To -recover the full effective detection area the theta cut value has to be -specified using the :doxy:`GCTAAeffArf::thetacut` method, and the -:doxy:`GCTAAeffArf::remove_thetacut` method needs to be called to rescale the ARF -values. Note that :doxy:`GCTAAeffArf::remove_thetacut` shall only be called -once after reading the ARF, as every call of the method will modify the -effective area values by multiplying it with a scaling factor. -The scaling factor required to recover the full effective area -will be obtained by integrating the area under the point spread function -out to the specified theta cut value. This provides the fraction of all -events that should fall within the theta cut. The applied scaling factor is -the inverse of this fraction: - -.. math:: - A_{\rm eff}(E) = - \frac{1} - {\int_0^{\theta_{\rm cut}} 2\pi PSF(\theta | E) \sin \theta {\rm d}\theta} - ARF(E) - -An alternative way of selecting the events is to adopt an energy dependent -theta cut so that the selection always contains a fixed fraction of the -events. This type of cut can be accomodated by specifying a scaling factor -using the :doxy:`GCTAAeffArf::scale` method prior to loading the ARF data. For -example, if the containment fraction was fixed to 80%, a scaling of 1.25 -should be applied to recover the full effective detection area. -When response information is specified by an XML file (see :ref:`sec_cta_xml`), -the ``thetacut`` and ``scale`` parameters can be defined using optional -attributes to the ``EffectiveArea`` parameter. - -The ARF format does not provide any information on the off-axis dependence -of the response, as the ARF values are supplied for a specific source -position, and hence for a specific off-axis angle with respect to the -camera centre. By default, the same effective area values are thus applied -to all off-axis angles :math:`\theta`. -An off-axis dependence may however be introduced by supplying a positive -value for the :math:`\sigma` parameter using the :doxy:`GCTAAeffArf::sigma` -method, or by adding the ``sigma`` attribute to the ``EffectiveArea`` -parameter in the XML file. In that case, equation :eq:`cta_aeff_offset` -is used for the off-axis dependence, with the supplied ARF values being -taken as the on-axis values. - - -GCTAAeff2D -"""""""""" - -:doxy:`GCTAAeff2D` reads the full effective area as function of energies -and off-axis angle from a FITS table. The FITS table is expected to be -in the :ref:`sec_cta_rsptable` format. From this two-dimensional table, -the effective area values are determine by bi-linear interpolation in -the base 10 logarithm of photon energy and the offset angle. - - -.. _sec_cta_perftable: - -Performance table -^^^^^^^^^^^^^^^^^ - -Below an example of a CTA performance table:: - - log(E) Area r68 r80 ERes. BG Rate Diff Sens - -1.7 261.6 0.3621 0.4908 0.5134 0.0189924 6.88237e-11 - -1.5 5458.2 0.2712 0.3685 0.4129 0.1009715 1.72717e-11 - -1.3 15590.0 0.1662 0.2103 0.2721 0.0575623 6.16963e-12 - -1.1 26554.1 0.1253 0.1567 0.2611 0.0213008 2.89932e-12 - -0.9 52100.5 0.1048 0.1305 0.1987 0.0088729 1.39764e-12 - -0.7 66132.1 0.0827 0.1024 0.1698 0.0010976 6.03531e-13 - -0.5 108656.8 0.0703 0.0867 0.1506 0.0004843 3.98147e-13 - -0.3 129833.0 0.0585 0.0722 0.1338 0.0001575 3.23090e-13 - -0.1 284604.3 0.0531 0.0656 0.1008 0.0001367 2.20178e-13 - 0.1 263175.3 0.0410 0.0506 0.0831 0.0000210 1.87452e-13 - 0.3 778048.6 0.0470 0.0591 0.0842 0.0000692 1.53976e-13 - 0.5 929818.8 0.0391 0.0492 0.0650 0.0000146 1.18947e-13 - 0.7 1078450.0 0.0335 0.0415 0.0541 0.0000116 1.51927e-13 - 0.9 1448579.1 0.0317 0.0397 0.0516 0.0000047 1.42439e-13 - 1.1 1899905.0 0.0290 0.0372 0.0501 0.0000081 1.96670e-13 - 1.3 2476403.8 0.0285 0.0367 0.0538 0.0000059 2.20695e-13 - 1.5 2832570.6 0.0284 0.0372 0.0636 0.0000073 3.22523e-13 - 1.7 3534065.3 0.0290 0.0386 0.0731 0.0000135 4.84153e-13 - 1.9 3250103.4 0.0238 0.0308 0.0729 0.0000044 6.26265e-13 - 2.1 3916071.6 0.0260 0.0354 0.0908 0.0000023 7.69921e-13 - --------------------------------------------- - 1) log(E) = log10(E/TeV) - bin centre - 2) Eff Area - in square metres after background cut (no theta cut) - 3) Ang. Res - 68% containment radius of gamma-ray PSF post cuts - in degrees - 4) Ang. Res - 80% containment radius of gamma-ray PSF post cuts - in degrees - 5) Fractional Energy Resolution (rms) - 6) BG Rate - inside point-source selection region - post call cuts - in Hz - 7) Diff Sens - differential sensitivity for this bin expressed as E^2 dN/dE - - in erg cm^-2 s^-1 - for a 50 hours exposure - 5 sigma significance including - systematics and statistics and at least 10 photons. - - -.. _sec_cta_rsptable: - -Response table -^^^^^^^^^^^^^^ - -The CTA response table class :doxy:`GCTAResponseTable` provides a generic -handle for multi-dimensional response information. It is based on the -response format used for storing response information for the -*Fermi*/LAT telescope. In this format, all information is stored in -a single row of a FITS binary table. Each element of the row contains -a vector column, that describes the axes of the multi-dimensional response -cube and the response information. Note that this class may in the future -be promoted to the GammaLib core, as a similar class has been implemented -in the *Fermi*/LAT interface. + cta_overview + cta_xml + cta_bkg + cta_irf diff --git a/doc/source/user_manual/modules/cta_bkg.rst b/doc/source/user_manual/modules/cta_bkg.rst new file mode 100644 index 0000000..3b99ceb --- /dev/null +++ b/doc/source/user_manual/modules/cta_bkg.rst @@ -0,0 +1,110 @@ +.. _sec_cta_background: + +Modelling CTA background +~~~~~~~~~~~~~~~~~~~~~~~~ + +The standard method for modelling the CTA instrumental background makes +use of background rate information that is included in the instrument +response functions. +For unbinned or binned analysis the background model is implemented by +the :doxy:`GCTAModelIrfBackground` class that derives from the +abstract :doxy:`GModelData` class. +The XML description of the background model has the following format: + +.. code-block:: xml + + + + + + + + + +The type of the model is ``CTAIrfBackground``. +The tag ```` allows to specify a spectral model with which the +background model in the IRF will be multiplied. +Any spectral model available in GammaLib can be used as the spectral +component of the model. +This allows to adjust the energy distribution of the background template +to the data. +In the above example the background rates are multiplied with a power law. + +For stacked analysis there is an equivalent model that makes use of the +background model provided in the ``BkgCube`` parameter of the observation +definition XML file: + +.. code-block:: xml + + + + + + + + + +The structure of the XML model is identical to the one shown before, but +the type of the model is now ``CTACubeBackground``. + +Finally, a third type of background model exists that assumes that the +spatial and spectral component of the background can be factorised and +that the spatial component is radially symmetric. +This background model is rather simplistic, and is mainly still there for +historic reasons. +Here an example of the XML definition. +The type of the model is ``RadialAcceptance``. + +.. code-block:: xml + + + + + + + + + + + + +The spatial component of the model is a Gaussian in offset angle squared. +Alternativly, a profile can be specified: + +.. code-block:: xml + + + + + + + + + + + + + + +Or a polynom: + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + diff --git a/doc/source/user_manual/modules/cta_irf.rst b/doc/source/user_manual/modules/cta_irf.rst new file mode 100644 index 0000000..c299153 --- /dev/null +++ b/doc/source/user_manual/modules/cta_irf.rst @@ -0,0 +1,219 @@ +.. _sec_cta_response: + +Handling the instrument response +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Overview +^^^^^^^^ + +The CTA specific instrument response is described by the +:doxy:`GCTAResponseIrf` class (see :ref:`sec_response` for a general +description of response handling in GammaLib). +The CTA response is factorised into +the effective area :math:`A_{\rm eff}(d, p, E, t)` (units :math:`cm^2`), +the point spread function :math:`PSF(p' | d, p, E, t)`, +and the energy dispersion :math:`E_{\rm disp}(E' | d, p, E, t)` +following: + +.. math:: + R(p', E', t' | d, p, E, t) = + A_{\rm eff}(d, p, E, t) \times + PSF(p' | d, p, E, t) \times + E_{\rm disp}(E' | d, p, E, t) + :label: irf + +Three different formats are implemented to specify the response +information for CTA: Performance Tables, Xspec response files and +Response Tables. +The following sections describe these formats. + + +.. _sec_cta_perftable: + +Performance table +^^^^^^^^^^^^^^^^^ + +Below an example of a CTA performance table:: + + log(E) Area r68 r80 ERes. BG Rate Diff Sens + -1.7 261.6 0.3621 0.4908 0.5134 0.0189924 6.88237e-11 + -1.5 5458.2 0.2712 0.3685 0.4129 0.1009715 1.72717e-11 + -1.3 15590.0 0.1662 0.2103 0.2721 0.0575623 6.16963e-12 + -1.1 26554.1 0.1253 0.1567 0.2611 0.0213008 2.89932e-12 + -0.9 52100.5 0.1048 0.1305 0.1987 0.0088729 1.39764e-12 + -0.7 66132.1 0.0827 0.1024 0.1698 0.0010976 6.03531e-13 + -0.5 108656.8 0.0703 0.0867 0.1506 0.0004843 3.98147e-13 + -0.3 129833.0 0.0585 0.0722 0.1338 0.0001575 3.23090e-13 + -0.1 284604.3 0.0531 0.0656 0.1008 0.0001367 2.20178e-13 + 0.1 263175.3 0.0410 0.0506 0.0831 0.0000210 1.87452e-13 + 0.3 778048.6 0.0470 0.0591 0.0842 0.0000692 1.53976e-13 + 0.5 929818.8 0.0391 0.0492 0.0650 0.0000146 1.18947e-13 + 0.7 1078450.0 0.0335 0.0415 0.0541 0.0000116 1.51927e-13 + 0.9 1448579.1 0.0317 0.0397 0.0516 0.0000047 1.42439e-13 + 1.1 1899905.0 0.0290 0.0372 0.0501 0.0000081 1.96670e-13 + 1.3 2476403.8 0.0285 0.0367 0.0538 0.0000059 2.20695e-13 + 1.5 2832570.6 0.0284 0.0372 0.0636 0.0000073 3.22523e-13 + 1.7 3534065.3 0.0290 0.0386 0.0731 0.0000135 4.84153e-13 + 1.9 3250103.4 0.0238 0.0308 0.0729 0.0000044 6.26265e-13 + 2.1 3916071.6 0.0260 0.0354 0.0908 0.0000023 7.69921e-13 + --------------------------------------------- + 1) log(E) = log10(E/TeV) - bin centre + 2) Eff Area - in square metres after background cut (no theta cut) + 3) Ang. Res - 68% containment radius of gamma-ray PSF post cuts - in degrees + 4) Ang. Res - 80% containment radius of gamma-ray PSF post cuts - in degrees + 5) Fractional Energy Resolution (rms) + 6) BG Rate - inside point-source selection region - post call cuts - in Hz + 7) Diff Sens - differential sensitivity for this bin expressed as E^2 dN/dE + - in erg cm^-2 s^-1 - for a 50 hours exposure - 5 sigma significance including + systematics and statistics and at least 10 photons. + + +Xspec response format +^^^^^^^^^^^^^^^^^^^^^ + +To be written ... + + +.. _sec_cta_rsptable: + +Response table +^^^^^^^^^^^^^^ + +The CTA response table class :doxy:`GCTAResponseTable` provides a generic +handle for multi-dimensional response information. It is based on the +response format used for storing response information for the +*Fermi*/LAT telescope. In this format, all information is stored in +a single row of a FITS binary table. Each element of the row contains +a vector column, that describes the axes of the multi-dimensional response +cube and the response information. Note that this class may in the future +be promoted to the GammaLib core, as a similar class has been implemented +in the *Fermi*/LAT interface. + + +Effective area +^^^^^^^^^^^^^^ + +The :math:`A_{\rm eff}(d, p, E, t)` term is described by the abstract +:doxy:`GCTAAeff` base class. The effective area is determined using +the: + +.. code-block:: cpp + + double GCTAAeff::operator()(const double& logE, + const double& theta = 0.0, + const double& phi = 0.0, + const double& zenith = 0.0, + const double& azimuth = 0.0, + const bool& etrue = true) const; + +operator, where ``logE`` is the base 10 logarithm of the photon energy. +If ``etrue`` is true, ``logE`` is the true photon energy; otherwise, +``logE`` is the measured photon energy. +``theta`` and ``phi`` are the offset and azimuth angle of the incident +photon with respect to the camera pointing, +``zenith`` and ``azimuth`` are the zenith and azimuth angle of the +camera pointing. + +The effective area response is implemented by one of the classes +:doxy:`GCTAAeffPerfTable`, :doxy:`GCTAAeffArf` and :doxy:`GCTAAeff2D` that +implement the different response formats that are currently used in +the CTA project. Dependent on the specified response file, the +method :doxy:`GCTAResponseIrf::load_aeff` allocates the appropriate response +class. :doxy:`GCTAAeff2D` is allocated if the response file is a FITS file +containing an extension named ``EFFECTIVE AREA``; :doxy:`GCTAAeffArf` is +allocated if an extension named ``SPECRESP`` is found; otherwise, +:doxy:`GCTAAeffPerfTable` is allocated. + + +GCTAAeffPerfTable +""""""""""""""""" + +:doxy:`GCTAAeffPerfTable` reads the effective area information from an ASCII +file that has been defined by the CTA Monte Carlo workpackage +(see :ref:`sec_cta_perftable`). This file provides the full effective detection +area in units of :math:`m^2` after the background cut as function of +the base 10 logarithm of the true photon energy. No theta cut is +applied. For a given energy, the effective area is computed by +interpolating the performance table in the base 10 logarithm of energy. +Effective areas will always be non-negative. +As the response table provides only the on-axis effective area, +off-axis effective areas are estimated assuming that the radial +distribution follows a Gaussian distribution in offset angle squared: + +.. math:: + A_{\rm eff}(\theta) = A_{\rm eff}(0) + \exp \left( -\frac{1}{2} \frac{\theta^4}{\sigma^2} \right) + :label: cta_aeff_offset + +where :math:`\sigma` characterises the size of the field of view. The +:math:`\sigma` parameter is set and retrieved using the +:doxy:`GCTAAeffPerfTable::sigma` methods. When response information is +specified by an XML file (see :ref:`sec_cta_xml`), the :math:`\sigma` +parameter can be set using the optional ``sigma`` attribute. +If the :math:`\sigma` parameter is not explicitly set, +:math:`\sigma=3 \, {\rm deg}^2` is assumed as default. + + +GCTAAeffArf +""""""""""" + +:doxy:`GCTAAeffArf` extracts the effective area information from a XSPEC +compatible ancilliary response file (ARF). The ARF contains the effective +area for a specific angular (or theta) cut. It should be noted that the +:doxy:`GCTAAeffArf` class has been introduced as a work around for digesting +the ARF response provided for the 1st CTA Data Challenge (1DC). It is not +intended to use this class any longer in the future. + +To recover the full effective detection area, the value of the theta cut +as well as the form of the point spread function needs to be known. When +an ARF file is loaded using the :doxy:`GCTAAeffArf::load` method, the ARF +values are read and stored as they are encountered in the ARF file. To +recover the full effective detection area the theta cut value has to be +specified using the :doxy:`GCTAAeffArf::thetacut` method, and the +:doxy:`GCTAAeffArf::remove_thetacut` method needs to be called to rescale the ARF +values. Note that :doxy:`GCTAAeffArf::remove_thetacut` shall only be called +once after reading the ARF, as every call of the method will modify the +effective area values by multiplying it with a scaling factor. +The scaling factor required to recover the full effective area +will be obtained by integrating the area under the point spread function +out to the specified theta cut value. This provides the fraction of all +events that should fall within the theta cut. The applied scaling factor is +the inverse of this fraction: + +.. math:: + A_{\rm eff}(E) = + \frac{1} + {\int_0^{\theta_{\rm cut}} 2\pi PSF(\theta | E) \sin \theta {\rm d}\theta} + ARF(E) + +An alternative way of selecting the events is to adopt an energy dependent +theta cut so that the selection always contains a fixed fraction of the +events. This type of cut can be accomodated by specifying a scaling factor +using the :doxy:`GCTAAeffArf::scale` method prior to loading the ARF data. For +example, if the containment fraction was fixed to 80%, a scaling of 1.25 +should be applied to recover the full effective detection area. +When response information is specified by an XML file (see :ref:`sec_cta_xml`), +the ``thetacut`` and ``scale`` parameters can be defined using optional +attributes to the ``EffectiveArea`` parameter. + +The ARF format does not provide any information on the off-axis dependence +of the response, as the ARF values are supplied for a specific source +position, and hence for a specific off-axis angle with respect to the +camera centre. By default, the same effective area values are thus applied +to all off-axis angles :math:`\theta`. +An off-axis dependence may however be introduced by supplying a positive +value for the :math:`\sigma` parameter using the :doxy:`GCTAAeffArf::sigma` +method, or by adding the ``sigma`` attribute to the ``EffectiveArea`` +parameter in the XML file. In that case, equation :eq:`cta_aeff_offset` +is used for the off-axis dependence, with the supplied ARF values being +taken as the on-axis values. + + +GCTAAeff2D +"""""""""" + +:doxy:`GCTAAeff2D` reads the full effective area as function of energies +and off-axis angle from a FITS table. The FITS table is expected to be +in the :ref:`sec_cta_rsptable` format. From this two-dimensional table, +the effective area values are determine by bi-linear interpolation in +the base 10 logarithm of photon energy and the offset angle. diff --git a/doc/source/user_manual/modules/cta_overview.rst b/doc/source/user_manual/modules/cta_overview.rst new file mode 100644 index 0000000..0891c4e --- /dev/null +++ b/doc/source/user_manual/modules/cta_overview.rst @@ -0,0 +1,94 @@ + +Overview +~~~~~~~~ + +The following figure presents an overview over the C++ classes of the CTA +module and their relations. + +.. _fig_uml_cta: + +.. figure:: uml_cta.png + :width: 100% + :align: center + + *CTA module* + +The CTA module provides an instrument interface for Imaging Air Cherenkov +Telescopes (IACT). The interface currently supports the event list data +format developed in the context of the Cherenkov Telescope Array (CTA) +project and provides support for various instrument response formats that +are currently used in the CTA consortium or that are under study. The interface +provides support for unbinned and binned maximum likelihood analysis, and +implements Monte Carlo simulations of high-level data based on the +instrumental response functions. + +Two types of observations are implemented so far: +:doxy:`GCTAObservation` that derives from :doxy:`GObservation` and that +describes either a binned or unbinned data set, and +:doxy:`GCTAOnOffObservation` that describes an On-Off observation +used in classical Cherenkov Telescope data analysis. +Binned or unbinned observations are collected in the +:doxy:`GObservations` container class, while the On-Off observations +are collected in a specific :doxy:`GCTAOnOffObservations` container +class (note that the :doxy:`GCTAOnOffObservations` container may vanish +in the future when :doxy:`GCTAOnOffObservation` objects will also be +collected by the :doxy:`GObservations` container class). + +The data of binned observations are stored by the +:doxy:`GCTAEventCube` class. The :doxy:`GCTAEventCube` class holds the +binned event data in form of a sky map, implemented by the +:doxy:`GSkymap` class. The sky coordinates of all sky map pixels +are stored in an array of CTA instrument directions, implemented +by the :doxy:`GCTAInstDir` class which holds a single :doxy:`GSkyDir` +object. The mean energies of the event cube +are stored in an array of :doxy:`GEnergy` objects, and the mean +time is stored by a :doxy:`GTime` object. The :doxy:`GCTAEventCube` class +holds in fact only a single event bin, implemented by the +:doxy:`GCTAEventBin` class. When the event bin is accessed using +the :doxy:`GCTAEventCube::operator[]` operator, the operator updates +references to the event cube data so that the :doxy:`GCTAEventBin` +object represents the selected event bin. This allows a memory-efficient +storage of event bin information (without storing for example the +instrument direction or the energy for each bin), while preserving +the abstract data model where an event cube of abstract type +:doxy:`GEventCube` is composed of event bins of abstract type +:doxy:`GEventBin` (see :ref:`sec_obs`). + +The data of unbinned observations are stored by the :doxy:`GCTAEventList` +class. The :doxy:`GCTAEventList` class is a container of :doxy:`GCTAEventAtom` +objects that represent individual events. Each event is composed of +a :doxy:`GCTAInstDir` object, a :doxy:`GEnergy` object and a :doxy:`GTime` object. +The region of interest covered by an event list is described by the +:doxy:`GCTARoi` class that derives from the abstract :doxy:`GRoi` class. + +In addition to the event, :doxy:`GCTAObservation` holds pointing +information implemented by the :doxy:`GCTAPointing` class. +:doxy:`GCTAObservation` holds furthermore response information. +Response information derives from the abstract :doxy:`GCTAResponse` class +that is impleted either as a factorized Instrument Response +Function by :doxy:`GCTAResponseIrf` or as a precomputed response for +stacked analysis by :doxy:`GCTAResponseCube`. +For stacked analysis the response is composed of the exposure +(implemented by :doxy:`GCTACubeExposure`), the livetime averaged point +spread function (implemented by :doxy:`GCTACubePsf`) and the livetime +averaged background rate (implemented by :doxy:`GCTACubeBackground`). +For all other analysis, the factorized IRFs are used directly. +Dependent on the response format, the components of the factorization +are stored in classes that derive from the abstract :doxy:`GCTAAeff`, +:doxy:`GCTAPsf`, :doxy:`GCTAEdisp`, and :doxy:`GCTABackground` classes +(see :ref:`sec_cta_response` for more details on the response +implementation). + +Different models of the instrumental background are provided by the +:doxy:`GCTAModelIrfBackground`, :doxy:`GCTAModelCubeBackground`, and +:doxy:`GCTAModelRadialAcceptance` classes. +All these classes implement the abstract :doxy:`GModelData` base +class. +:doxy:`GCTAModelIrfBackground` and :doxy:`GCTAModelCubeBackground` +will use the background rate information that is attached to the +response function for background modelling. +Specifically, :doxy:`GCTAModelIrfBackground` will use information +provided by :doxy:`GCTABackground` and :doxy:`GCTAModelCubeBackground` +will use information provided by :doxy:`GCTACubeBackground` +(see :ref:`sec_cta_background` for details on the background +model implementation). diff --git a/doc/source/user_manual/modules/cta_xml.rst b/doc/source/user_manual/modules/cta_xml.rst new file mode 100644 index 0000000..6615a10 --- /dev/null +++ b/doc/source/user_manual/modules/cta_xml.rst @@ -0,0 +1,119 @@ +.. _sec_cta_xml: + +Describing CTA observations using XML +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CTA observations can be described in GammaLib using an ASCII file in XML +format (see :ref:`sec_obsxml`). The CTA specific section of this file has +the format: + +.. code-block:: xml + + + + + + + + + +for an unbinned observation and + +.. code-block:: xml + + + + + + + + + +for a binned observation. +Each parameter within the ```` tag specifies the filename +for a specific file that is needed for the analysis. +The difference between an unbinned and a binned observation is that the +first uses an event list (requiring a parameter with name ``EventList``) +while the latter uses an event cube (requiring a parameter with name +``CountsCube``). +The ``EffectiveArea``, ``PointSpreadFunction``, ``EnergyDispersion`` and +``Background`` parameters provide the filenames of the instrument +specific response function components for each observation +(see :ref:`sec_cta_response`). +Alternatively, the calibration database and response name can be +specified, e.g. + +.. code-block:: xml + + + + + + +A variant of the binned analysis is the stacked analysis. +While in a binned analysis an event cube is generated for each +observation, event cubes will be summed in a stacked analysis. +Summing the events requires computation of the total exposure, +the average point spread function and the average background +rate (energy dispersion is not yet handled for stacked analysis). +Information for a stacked observation is provided in the +following format: + +.. code-block:: xml + + + + + + + + +The stacked analysis uses also an event cube but now requires the +pre-computed response cubes. +The ``ExposureCube``, ``PsfCube``, and ``BkgCube`` parameters +provide the filenames of the required components. + +The ``instrument`` attribute of CTA observations can be one of +``CTA``, ``HESS``, ``MAGIC`` or ``VERITAS``. This allows mixing of +observations from difference IACTs within a single analysis. +Note that no code that is specific to any of these four instruments is +implemented in GammaLib, but the ``instrument`` attribute is used to +tie models to instruments, allowing thus to provide specific background +models for each of the instruments in a combined analysis. + +The ``id`` attribute specifies an identifier for the observation that +needs to be unique for a given instrument. +The identifier allows to connect an observation to a specific model +component. + +Optionally, an observation can also have user defined minimum and maximum +energy boundaries. +These boundaries are specified as optional attributes in the XML file, e.g. + +.. code-block:: xml + + + ... + + +**Note that the energy boundaries are specified in units of TeV.** + +In case that neither an event list nor an event cube is available, a +CTA observation can be defined by specifying the pointing direction, +the Good Time Intervals, the region of interest, and optionally the +deadtime correction factor. +Here an example of the expected XML format: + +.. code-block:: xml + + + + + + + + + + +Note that the time reference for the Good Time Intervals is specified +using the ``TimeReference`` parameter. diff --git a/doc/source/user_manual/modules/fits.rst b/doc/source/user_manual/modules/fits.rst index b657421..ee7d448 100644 --- a/doc/source/user_manual/modules/fits.rst +++ b/doc/source/user_manual/modules/fits.rst @@ -6,15 +6,16 @@ FITS file interface Overview ~~~~~~~~ -:ref:`fig_uml_fits` present an overview over the C++ classes of the FITS +The following figure presents an overview over the C++ classes of the FITS module and their relations. .. _fig_uml_fits: .. figure:: uml_fits.png - :width: 100% + :width: 75% + :align: center - FITS module + *FITS module* The FITS module provides a high-level interface to FITS files. The module is based on the cfitsio library for file access. The C++ classes of the @@ -158,6 +159,7 @@ above example is shown below. .. _fig_fits_example: .. figure:: fits_example.png - :width: 100% + :width: 90% + :align: center - FITS file example + *FITS file example* diff --git a/doc/source/user_manual/modules/inst.rst b/doc/source/user_manual/modules/inst.rst index 7ad5597..97e6ee0 100644 --- a/doc/source/user_manual/modules/inst.rst +++ b/doc/source/user_manual/modules/inst.rst @@ -4,7 +4,7 @@ Instrument-specific interfaces ============================== .. toctree:: - :maxdepth: 2 + :maxdepth: 3 cta lat diff --git a/doc/source/user_manual/modules/intro.rst b/doc/source/user_manual/modules/intro.rst index e77a1a6..0293bb0 100644 --- a/doc/source/user_manual/modules/intro.rst +++ b/doc/source/user_manual/modules/intro.rst @@ -8,7 +8,7 @@ classes and their primary usage, as well as their underlying arithmetics. However, we do not provide a detailed description of the interface and the inner workings of each C++ class. This information is provided in the reference documentation, which can be found online at -http://gammalib.sourceforge.net/doxygen/, or which can be installed +http://cta.irap.omp.eu/gammalib/doxygen/, or which can be installed locally on your machine (see section :ref:`sec_doxygen`). Each GammaLib module is presented in a dedicated section, following the overview diff --git a/doc/source/user_manual/modules/lat.rst b/doc/source/user_manual/modules/lat.rst index a52d583..91fd9cb 100644 --- a/doc/source/user_manual/modules/lat.rst +++ b/doc/source/user_manual/modules/lat.rst @@ -6,15 +6,17 @@ Overview ~~~~~~~~ -The LAT module provides an instrument interface for the Large Area -Telescope aboard NASA's Fermi satellite. - -:ref:`fig_uml_lat` present an overview over the C++ classes of the LAT +The following figure presents an overview over the C++ classes of the LAT module and their relations. .. _fig_uml_lat: .. figure:: uml_lat.png - :width: 100% + :align: center + :width: 80% + + *LAT module* + +The LAT module provides an instrument interface for the Large Area +Telescope aboard NASA's Fermi satellite. - LAT module diff --git a/doc/source/user_manual/modules/linalg.rst b/doc/source/user_manual/modules/linalg.rst index 4132262..e9a2cb1 100644 --- a/doc/source/user_manual/modules/linalg.rst +++ b/doc/source/user_manual/modules/linalg.rst @@ -6,6 +6,17 @@ Linear algebra Overview ~~~~~~~~ +The following figure presents an overview over the C++ classes of +the linear algebra module and their relations. + +.. _fig_uml_linalg: + +.. figure:: uml_linalg.png + :width: 55% + :align: center + + *Linear algebra module* + The linear algebra module provides classes for vector and matrix manipulation. The :doxy:`GVector` class implements a double precision floating point vector, the classes :doxy:`GMatrix`, :doxy:`GMatrixSymmetric` @@ -15,16 +26,6 @@ a sparse matrix, respectively. All matrix classes derive from the abstract :doxy:`GMatrixBase` base class that provides common functionalities to all matrix classes. -:ref:`fig_uml_linalg` presents an overview over the C++ classes of -the linear algebra module and their relations. - -.. _fig_uml_linalg: - -.. figure:: uml_linalg.png - :width: 70% - - Linear algebra module - The classes :doxy:`GSparseNumeric` and :doxy:`GSparseSymbolic` are classes that are used by :doxy:`GMatrixSparse` but these classes are not exposed to the outside world (i.e. the class definitions are not diff --git a/doc/source/user_manual/modules/model.rst b/doc/source/user_manual/modules/model.rst index b739a19..bce8a9d 100644 --- a/doc/source/user_manual/modules/model.rst +++ b/doc/source/user_manual/modules/model.rst @@ -6,18 +6,19 @@ Model handling Overview ~~~~~~~~ -:ref:`fig_uml_model` present an overview over the C++ classes of the model +The following figure presents an overview over the C++ classes of the model module and their relations. .. _fig_uml_model: .. figure:: uml_model.png + :align: center :width: 100% - Model module + *Overview over the model module* The central C++ class of the model module is the abstract base class -:doxy:`GModel` which defines a model component. Model compnents are combined +:doxy:`GModel` which defines a model component. Model components are combined using the :doxy:`GModels` container C++ class. @@ -29,34 +30,33 @@ method. The ``GObservation::npred`` provides the number of predicted events by all models within the relevant dataspace for a given observation. :ref:`fig_calltree_model` shows the call tree of the -``GObservation::model()`` (left) and ``GObservation::npred`` (right) -methods. The top section shows the abstract methods, the bottom section -shows the methods that are called for :doxy:`GModelSky` models, i.e. models of -celestial sources that are folded by the instrument response. +``GObservation::model`` (left) and ``GObservation::npred`` (right) +methods. For model evaluation, the :doxy:``GObservation::model`` method loops over all models in the :doxy:`GModels` container and calls the -:doxy:`GModel::eval_gradients` method of each model. For :doxy:`GModelSky` models, -this invokes an integration over true time, true energy and all possible -true photon arrival directions that may result in the observed event -direction. The latter computation is performed by the abstract :doxy:`GResponse::irf` -method that needs to be implemented for each instrument. +:doxy:`GModel::eval_gradients` method of each model. +For :doxy:`GModelSky` models this method invokes the :doxy:`GResponse::convolve` +method that calls among others the :doxy:`GResponse::irf` method. +That method needs to be implement for each instruments. The ``GObservation::npred`` method performs an integration over observed -time, observed energy and observed arrival direction. The two former are -performed by the ``GObservation::npred_temp`` and -``GObservation::npred_spec`` methods within the :doxy:`GObservation` class, -the spatial integral is done within the :doxy:`GModel` class by invoking the -``GModel::npred`` method. For :doxy:`GModelSky` models, the integral is -performed by the abstract :doxy:`GResponse::nroi` method that needs to be -implemented for each instrument. +time, observed energy and observed arrival direction. +The integrate over observed time is for the moment a simple multiplication +with ontime. +The intergal over observed energy is performed by the +``GObservation::npred_spec`` method that calls the +:doxy:`GModel::eval_gradients` method. +For :doxy:`GModelSky` models this method calls the :doxy:`GResponse::nroi` +method that needs to be implement for each instruments. .. _fig_calltree_model: .. figure:: calltree_model.png - :width: 100% + :width: 70% + :align: center - Call tree for model evaluation + *Call tree for model evaluation* Spectral models @@ -83,6 +83,66 @@ The XML format for specifying a constant is: +Node function +^^^^^^^^^^^^^ + +The generalisation of the broken power law is the node function, which is +defined by a set of energy and intensity values, the so called nodes, +which are connected by power laws. + +The XML format for specifying a node function is: + +.. code-block:: xml + + + + + + + + + + + + +(in this example there are two nodes; the number of nodes in a node +function is arbitrary). + + +File function +^^^^^^^^^^^^^ + +A function defined using an input ASCII file with columns of energy and +differential flux values. The energy units are assumed to be MeV and the +flux values are assumed to +:math:`{\rm cm}^{-2} {\rm s}^{-1} {\rm MeV}^{-1}` +(the only exception being a model for which the spatial component is +a constant diffuse model :doxy:`GModelSpatialDiffuseConst`; in this case, +the units are +:math:`{\rm cm}^{-2} {\rm s}^{-1} {\rm MeV}^{-1} {\rm sr}^{-1}`). +The sole parameter is a multiplicative normalization: + +.. math:: + \frac{dN}{dE} = N_0 \left. \frac{dN}{dE} \right\rvert_{\rm file} + +where the parameters in the XML definition have the following mappings: + +* :math:`N_0` = ``Normalization`` + +The XML format for specifying a file function is: + +.. code-block:: xml + + + + + +If the file is given as relative path, the path is relative to the working +directory of the executable. Alternatively, an absolute path may be +specified. Any environment variable present in the path name will be +expanded. + + Power law ^^^^^^^^^ @@ -142,11 +202,12 @@ the errors if one is using the PowerLaw form. Exponentially cut-off power law ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The :doxy:`GModelSpectralExpPlaw` class implements the exponentially cut-off power law function +The :doxy:`GModelSpectralExpPlaw` class implements the exponentially +cut-off power law function .. math:: \frac{dN}{dE} = k_0 \left( \frac{E}{E_0} \right)^{\gamma} - \exp \left( \frac{-E}{\tt E_{\rm cut}} \right) + \exp \left( \frac{-E}{E_{\rm cut}} \right) where the parameters in the XML definition have the following mappings: @@ -167,6 +228,37 @@ The XML format for specifying an exponentially cut-off power law is: +Super exponentially cut-off power law +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The :doxy:`GModelSpectralSuperExpPlaw` class implements the super +exponentially cut-off power law function + +.. math:: + \frac{dN}{dE} = k_0 \left( \frac{E}{E_0} \right)^{\gamma} + \exp \left( + -\left( \frac{E}{E_{\rm cut}} \right)^{\alpha} + \right) + +where the parameters in the XML definition have the following mappings: + +* :math:`k_0` = ``Prefactor`` +* :math:`\gamma` = ``Index1`` +* :math:`\alpha` = ``Index2`` +* :math:`E_0` = ``Scale`` +* :math:`E_{\rm cut}` = ``Cutoff`` + +.. code-block:: xml + + + + + + + + + + Broken power law ^^^^^^^^^^^^^^^^ @@ -226,32 +318,6 @@ The XML format for specifying a Gaussian is: -Node function -^^^^^^^^^^^^^ - -The generalisation of the broken power law is the node function, which is -defined by a set of energy and intensity values, the so called nodes, -which are connected by power laws. - -The XML format for specifying a node function is: - -.. code-block:: xml - - - - - - - - - - - - -(in this example there are two nodes; the number of nodes in a node -function is arbitrary). - - Log parabola ^^^^^^^^^^^^ @@ -294,37 +360,3 @@ where * ``alpha`` = -``Index`` * ``beta`` = -``Curvature`` - - -File function -^^^^^^^^^^^^^ - -A function defined using an input ASCII file with columns of energy and -differential flux values. The energy units are assumed to be MeV and the -flux values are assumed to -:math:`{\rm cm}^{-2} {\rm s}^{-1} {\rm MeV}^{-1}` -(the only exception being a model for which the spatial component is -a constant diffuse model :doxy:`GModelSpatialDiffuseConst`; in this case, -the units are -:math:`{\rm cm}^{-2} {\rm s}^{-1} {\rm MeV}^{-1} {\rm sr}^{-1}`). -The sole parameter is a multiplicative normalization: - -.. math:: - \frac{dN}{dE} = N_0 \left. \frac{dN}{dE} \right\rvert_{\rm file} - -where the parameters in the XML definition have the following mappings: - -* :math:`N_0` = ``Normalization`` - -The XML format for specifying a file function is: - -.. code-block:: xml - - - - - -If the file is given as relative path, the path is relative to the working -directory of the executable. Alternatively, an absolute path may be -specified. Any environment variable present in the path name will be -expanded. diff --git a/doc/source/user_manual/modules/mwl.rst b/doc/source/user_manual/modules/mwl.rst index d4df56a..353126b 100644 --- a/doc/source/user_manual/modules/mwl.rst +++ b/doc/source/user_manual/modules/mwl.rst @@ -6,17 +6,19 @@ Multi-wavelength interface Overview ~~~~~~~~ -The multi-wavelength module provides an interface for spectral energy -distributions (SEDs). The SED defines the observed photon flux as function -of energy (or frequency) from a particular source, and this information -can be used in a fit to determine spectral source parameters. - -:ref:`fig_uml_mwl` present an overview over the C++ classes of the +The following figure presents an overview over the C++ classes of the multi-wavelength module and their relations. .. _fig_uml_mwl: .. figure:: uml_mwl.png - :width: 40% + :width: 30% + :align: center + + *Multi-wavelength module* + +The multi-wavelength module provides an interface for spectral energy +distributions (SEDs). The SED defines the observed photon flux as function +of energy (or frequency) from a particular source, and this information +can be used in a fit to determine spectral source parameters. - Multi-wavelength module diff --git a/doc/source/user_manual/modules/numerics.rst b/doc/source/user_manual/modules/numerics.rst index 01a3102..26288fb 100644 --- a/doc/source/user_manual/modules/numerics.rst +++ b/doc/source/user_manual/modules/numerics.rst @@ -37,6 +37,7 @@ Constant Value ``gammalib::ln2`` :math:`\log 2` (natural logarithm of 2) ``gammalib::ln10`` :math:`\log 10` (natural logarithm of 10) ``gammalib::inv_ln2`` :math:`(\log 2)^{-1}` +``gammalib::inv_ln10`` :math:`(\log 10)^{-1}` ``gammalib::onethird`` :math:`1/3` ``gammalib::twothird`` :math:`2/3` ``gammalib::fourthird`` :math:`4/3` @@ -64,6 +65,8 @@ Function Description ``gammalib::atan2d`` Arc tangens function for argument x/y given in degrees ``gammalib::sincosd`` Returns sine and cosine for argument given in degrees ``gammalib::gammln`` Natural logarithm of gamma function +``gammalib::erfcc`` Complementary error function +``gammalib::erfinv`` Inverse error function ``gammalib::modulo`` Remainder of division x/y ===================== =========== diff --git a/doc/source/user_manual/modules/obs.rst b/doc/source/user_manual/modules/obs.rst index e619313..d7ebe74 100644 --- a/doc/source/user_manual/modules/obs.rst +++ b/doc/source/user_manual/modules/obs.rst @@ -6,15 +6,16 @@ Observation handling Overview ~~~~~~~~ -:ref:`fig_uml_obs` present an overview over the C++ classes of the obs +The following figure presents an overview over the C++ classes of the obs module and their relations. .. _fig_uml_obs: .. figure:: uml_obs.png + :align: center :width: 100% - Observation module + *Overview over the obs module* The central C++ class of the obs module is the abstract base class :doxy:`GObservation` which defines the instrument-independent interface for a @@ -115,15 +116,17 @@ for an unbinned observation and by: .. code-block:: xml - + for a binned observation. Here, ``EventList`` specifies a FITS file containing -an event list and ``CountsMap`` specifies a FITS file containing a counts map. -The other tags specify the components of the instrumental response function. +an event list and ``CountsCube`` specifies a FITS file containing a counts +cube. +The other tags specify the components of the instrumental response function +and are optional. Similar definitions exist for the other instruments. The observations are loaded from the XML file descriptor using the load @@ -281,7 +284,9 @@ which provides the time dependent deadtime correction factor. Setting up and using a calibration database ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -TBW: Describe how to setup and how to use a calibration database. +To be written (describe how to setup and how to use a calibration +database) ... + .. _sec_time: @@ -356,12 +361,14 @@ OGIP compliant header keywords. Energies in GammaLib ~~~~~~~~~~~~~~~~~~~~ -TBW: Describe how energies are implemented in GammaLib. Mention that the -internal energy is MeV. This section should also handle EBOUNDS. +To be written (describe how energies are implemented in GammaLib; mention +that the internal energy is MeV; this section should also handle EBOUNDS) +... .. _sec_roi: Regions of Interest ~~~~~~~~~~~~~~~~~~~ -TBW: Describe what a ROI is and why this is needed (unbinned analysis). +To be written (describe what a ROI is and that this is needed for unbinned +analysis) ... diff --git a/doc/source/user_manual/modules/opt.rst b/doc/source/user_manual/modules/opt.rst index 1f2ce78..6c2a7ed 100644 --- a/doc/source/user_manual/modules/opt.rst +++ b/doc/source/user_manual/modules/opt.rst @@ -6,6 +6,17 @@ Optimizers Overview ~~~~~~~~ +The following figure presents an overview over the C++ classes of +the optimizer module and their relations. + +.. _fig_uml_opt: + +.. figure:: uml_opt.png + :width: 50% + :align: center + + *Optimizer module* + The optimizer module provides classes for function optimization. The abstract :doxy:`GOptimizerFunction` base class defines the interface for the function that should be optimized. The :doxy:`GOptimizerPar` @@ -16,17 +27,6 @@ the only optimizer algorithm implemented in GammaLib is the Levenberg-Marquardt algorithm, implemented by the class :doxy:`GOptimizerLM`. - -:ref:`fig_uml_opt` presents an overview over the C++ classes of -the optimizer module and their relations. - -.. _fig_uml_opt: - -.. figure:: uml_opt.png - :width: 60% - - Optimizer module - The model parameter class :doxy:`GModelPar`, as a specific implementation of the optimizer parameter class, derives from :doxy:`GOptimizerPar`. One implementation of an optimizer function is the diff --git a/doc/source/user_manual/modules/sky.rst b/doc/source/user_manual/modules/sky.rst index e0cb8d8..fb789f6 100644 --- a/doc/source/user_manual/modules/sky.rst +++ b/doc/source/user_manual/modules/sky.rst @@ -6,6 +6,17 @@ Sky maps, sky coordinates and sky regions Overview ~~~~~~~~ +The following figure presents an overview over the C++ classes of the sky +module and their relations. + +.. _fig_uml_sky: + +.. figure:: uml_sky.png + :align: center + :width: 75% + + *Sky module* + The sky module provides classes to handle sky maps, sky coordinates and sky regions. Sky maps are implemented by the :doxy:`GSkymap` class which stores @@ -20,9 +31,9 @@ implements the relation for the HEALPix pixelisation scheme, the abstract :doxy:`GWcs` base class represents the relation for World Coordinate Systems. Specific World Coordinate System projections are implemented by the :doxy:`GWcsAIT`, :doxy:`GWcsAZP`, :doxy:`GWcsCAR`, -:doxy:`GWcsMER`, :doxy:`GWcsSTG` and :doxy:`GWcsTAN` classes. Instances of -all specific World Coordinate System classes are collected in -the :doxy:`GWcsRegistry` registry class. +:doxy:`GWcsMER`, :doxy:`GWcsMOL`, :doxy:`GWcsSTG` and :doxy:`GWcsTAN` +classes. Instances of all specific World Coordinate System classes +are collected in the :doxy:`GWcsRegistry` registry class. Sky coordinates are implemented by the :doxy:`GSkyDir` class that specifies celestial coordinates in either equatorial (Right Ascension @@ -36,12 +47,5 @@ So far, only a simple circular sky region is implemented by the :doxy:`GSkyRegionCircle` class. Sky regions are collected in the :doxy:`GSkyRegions` container class. -:ref:`fig_uml_sky` present an overview over the C++ classes of the sky -module and their relations. - -.. _fig_uml_sky: - -.. figure:: uml_sky.png - :width: 100% - - Sky module +Coordinates in the horizon system (altitude and azimuth) are implemented +by the :doxy:`GHorizDir` class. \ No newline at end of file diff --git a/doc/source/user_manual/modules/support.rst b/doc/source/user_manual/modules/support.rst index 2d3982f..8e9d358 100644 --- a/doc/source/user_manual/modules/support.rst +++ b/doc/source/user_manual/modules/support.rst @@ -6,6 +6,18 @@ Support functions and classes Overview ~~~~~~~~ +The following figure presents an overview over the C++ classes of the +support module and their relations. + +.. _fig_uml_support: + +.. figure:: uml_support.png + :width: 75% + :align: center + + *Support module* + + The support module contains a number of functions and classes that are needed to support core functionnalities of GammaLib. An overview of the functions and C++ classes present in this module is given in @@ -25,13 +37,6 @@ and :doxy:`GUrlString` are derived from :doxy:`GUrl` and implement a file storag and a string storage, respectively. As most of the classes are unrelated, they will be described individually in the following sections. -.. _fig_uml_support: - -.. figure:: uml_support.png - :width: 100% - - Support module - Column Separated Value tables ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -207,7 +212,7 @@ The :doxy:`GRan::chisq2` method draws random numbers from the propability distribution .. math:: - p(x) = \frac{1}{2\pi} x \exp( -\frac{1}{2} x^2 ) + p(x) = \frac{1}{2\pi} x \exp \left( -\frac{1}{2} x^2 \right) This method can be used to simulate the random radial offset of a measured source position from the true source position, assuming an azimuthally @@ -225,14 +230,17 @@ Constants The following constants are available: -======================== ===== -Constant Value -======================== ===== -``gammalib::MeV2erg`` :math:`1.6021765 \times 10^{-6}` (converts MeV to erg) -``gammalib::erg2MeV`` :math:`624150.96` (converts erg to MeV) -``gammalib::pc2cm`` :math:`3.08568025 \times 10^{18}` (converts pc to cm) -``gammalib::sec_in_day`` :math:`86400.0` (number of seconds in one day) -======================== ===== +========================== ===== +Constant Value +========================== ===== +``gammalib::MeV2erg`` :math:`1.6021765 \times 10^{-6}` (converts MeV to erg) +``gammalib::erg2MeV`` :math:`624150.96` (converts erg to MeV) +``gammalib::MeV2Angstrom`` :math:`1.239841875e-2` (converts MeV to Angstrom) +``gammalib::pc2cm`` :math:`3.08568025 \times 10^{18}` (converts pc to cm) +``gammalib::sec_in_day`` :math:`86400.0` (number of seconds in one day) +``gammalib::sec2day`` :math:`1/86400` (converts seconds to days) +``gammalib::tai2tt`` :math:`32.184` (converts TAI to TT system) +========================== ===== Functions @@ -246,6 +254,7 @@ Function Description ``gammalib::strip_whitespace`` Strips all leading and trailing whitespace from string. ``gammalib::strip_chars`` Strips all leading and trailing characters from string. ``gammalib::expand_env`` Replace any environment variables in string by its value. +``gammalib::filepath`` Build path from filename and path. ``gammalib::str`` Conversion of C-types to strings. ``gammalib::tochar`` Conversion of string to ``char``. ``gammalib::toshort`` Conversion of string to ``short``. @@ -268,11 +277,20 @@ Function Description ``gammalib::parformat`` Format string for parameter value display. ``gammalib::plaw_photon_flux`` Compute photon flux under a power law. ``gammalib::plaw_energy_flux`` Compute energy flux under a power law. +``gammalib::elogmean`` Computes geometric mean of energy. ``gammalib::file_exists`` Check whether a file exists. +``gammalib::dir_exists`` Check whether a directory exists. ``gammalib::is_infinite`` Check whether a double precision value is infinite. ``gammalib::is_notanumber`` Check whether a double precision value is not a number. ``gammalib::contains`` Check whether a string contains a sub-string. ``gammalib::warning`` Dump warning in console. +``gammalib::xml2str`` Converts XML to string. +``gammalib::str2xml`` Converts string to XML. +``gammalib::xml_has_par`` Checks is XML file has parameter. +``gammalib::xml_need_par`` Require specific parameter in XML file. +``gammalib::xml_get_par`` Get parameter from XML file. +``gammalib::xml_check_par`` Check parameter in XML file. +``gammalib::recv`` Receive on socket with timeout. ============================== =========== diff --git a/doc/source/user_manual/modules/uml_app.png b/doc/source/user_manual/modules/uml_app.png index 11bfed9..aec3228 100644 Binary files a/doc/source/user_manual/modules/uml_app.png and b/doc/source/user_manual/modules/uml_app.png differ diff --git a/doc/source/user_manual/modules/uml_com.png b/doc/source/user_manual/modules/uml_com.png index cbe8859..bf86b5d 100644 Binary files a/doc/source/user_manual/modules/uml_com.png and b/doc/source/user_manual/modules/uml_com.png differ diff --git a/doc/source/user_manual/modules/uml_cta.png b/doc/source/user_manual/modules/uml_cta.png index b9c2608..132e8f5 100644 Binary files a/doc/source/user_manual/modules/uml_cta.png and b/doc/source/user_manual/modules/uml_cta.png differ diff --git a/doc/source/user_manual/modules/uml_fits.png b/doc/source/user_manual/modules/uml_fits.png index d9e3b0c..81c6a01 100644 Binary files a/doc/source/user_manual/modules/uml_fits.png and b/doc/source/user_manual/modules/uml_fits.png differ diff --git a/doc/source/user_manual/modules/uml_lat.png b/doc/source/user_manual/modules/uml_lat.png index 8e25e76..9867aa9 100644 Binary files a/doc/source/user_manual/modules/uml_lat.png and b/doc/source/user_manual/modules/uml_lat.png differ diff --git a/doc/source/user_manual/modules/uml_model.png b/doc/source/user_manual/modules/uml_model.png index 05059f1..d60c9b8 100644 Binary files a/doc/source/user_manual/modules/uml_model.png and b/doc/source/user_manual/modules/uml_model.png differ diff --git a/doc/source/user_manual/modules/uml_obs.png b/doc/source/user_manual/modules/uml_obs.png index b9e997b..88637eb 100644 Binary files a/doc/source/user_manual/modules/uml_obs.png and b/doc/source/user_manual/modules/uml_obs.png differ diff --git a/doc/source/user_manual/modules/uml_sky.png b/doc/source/user_manual/modules/uml_sky.png index a1d066e..57ab810 100644 Binary files a/doc/source/user_manual/modules/uml_sky.png and b/doc/source/user_manual/modules/uml_sky.png differ diff --git a/doc/source/user_manual/modules/vo.rst b/doc/source/user_manual/modules/vo.rst index d496685..3828f3f 100644 --- a/doc/source/user_manual/modules/vo.rst +++ b/doc/source/user_manual/modules/vo.rst @@ -6,20 +6,21 @@ Virtual Observatory interface Overview ~~~~~~~~ -The VO module provides classes that interface GammaLib to the Virtual -Observatory infrastructure. So far the module contains the :doxy:`GVOClient` -and the :doxy:`GVOHub` classes. :doxy:`GVOClient` implements a -Virtual Observatory client while :doxy:`GVOHub` implement a hub for -inter-client communication. -If a client needs to connect to a Hub and no Hub is currently running -on the system, the client will launch it's own Hub. - -:ref:`fig_uml_vo` presents an overview over the C++ classes of the VO +The following figure presents an overview over the C++ classes of the VO module and their relations. .. _fig_uml_vo: .. figure:: uml_vo.png :width: 30% + :align: center - VO module + *VO module* + +The VO module provides classes that interface GammaLib to the Virtual +Observatory infrastructure. So far the module contains the :doxy:`GVOClient` +and the :doxy:`GVOHub` classes. :doxy:`GVOClient` implements a +Virtual Observatory client while :doxy:`GVOHub` implements a hub for +inter-client communication. +If a client needs to connect to a Hub and no Hub is running on the system, +the client will launch it's own Hub. diff --git a/doc/source/user_manual/modules/xml.rst b/doc/source/user_manual/modules/xml.rst index c534350..f36a46b 100644 --- a/doc/source/user_manual/modules/xml.rst +++ b/doc/source/user_manual/modules/xml.rst @@ -6,15 +6,16 @@ XML file interface Overview ~~~~~~~~ -:ref:`fig_uml_xml` present an overview over the C++ classes of the XML +The followinf figure presents an overview over the C++ classes of the XML module and their relations. .. _fig_uml_xml: .. figure:: uml_xml.png - :width: 100% + :width: 80% + :align: center - XML module + *XML module* The XML module provides classes that allow creation, writing and reading of files in the Extensible Markup Language (XML) format. diff --git a/doc/source/user_manual/modules/xspec.rst b/doc/source/user_manual/modules/xspec.rst index 7ff4ca2..65df6f9 100644 --- a/doc/source/user_manual/modules/xspec.rst +++ b/doc/source/user_manual/modules/xspec.rst @@ -6,19 +6,20 @@ Xspec interface Overview ~~~~~~~~ -The Xspec module provides an interface to data in the XSPEC format. Event -data storage is implemented by the :doxy:`GPha` class that provides -the number of events measured per channel. The effective area taking -into account any event selection cuts is implemented by the :doxy:`GArf` -class. And energy redistribution information is implemented by the -:doxy:`GRmf` class. - -:ref:`fig_uml_xspec` present an overview over the C++ classes of the Xspec +The following figure presents an overview over the C++ classes of the Xspec module and their relations. .. _fig_uml_xspec: .. figure:: uml_xspec.png - :width: 50% + :width: 40% + :align: center - Xspec module + *Xspec module* + +The Xspec module provides an interface to data in the XSPEC format. Event +data storage is implemented by the :doxy:`GPha` class that provides +the number of events measured per channel. The effective area taking +into account any event selection cuts is implemented by the :doxy:`GArf` +class. And energy redistribution information is implemented by the +:doxy:`GRmf` class. diff --git a/doc/source/user_manual/quickstart.rst b/doc/source/user_manual/quickstart.rst index e0e82bd..7def1ec 100644 --- a/doc/source/user_manual/quickstart.rst +++ b/doc/source/user_manual/quickstart.rst @@ -4,12 +4,22 @@ Getting started with GammaLib A quick GammaLib tutorial ------------------------- +To be written ... + + Using GammaLib from Python -------------------------- +To be written ... + + Programming guidelines ---------------------- +To be written ... + + Frequently asked questions -------------------------- +To be written ... -- libgit2 0.21.4