Complement User Manual

Jürgen Knödlseder
1 parent 92c51561
Showing 7 changed files with 223 additions and 24 deletions
doc/source/users/tutorial/index.rst
doc/source/users/tutorial/sky/index.rst
doc/source/users/user_manual/internals.rst
doc/source/users/user_manual/modules/model/par.rst
doc/source/users/user_manual/modules/obs/caldb.rst
doc/source/users/user_manual/modules/obs/energy.rst
doc/source/users/user_manual/modules/support/constants.rst
@@ -2,7 +2,7 @@ Tutorials
 =========
  
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
  
    sky/index
    linalg
-Sky coordinates, sky maps and sky regions
------------------------------------------
+Sky handling
+------------
  
 .. toctree::
    :maxdepth: 1
@@ -6,4 +6,54 @@ Under the hood
 Registry classes
 ----------------
  
-To be written (describe what a registry class is) ...
+Registry classes statically hold instances of derived classes, and can be
+used to allocate a derived class dependent on some text string.
+The code thread below illustrates how the :doxy:`GModels::read()` method
+extracts models from an XML file, allocates the requested model through the
+:doxy:`GModelRegistry::alloc()` method, and appends the model to the model
+container.
+
+**C++**
+
+.. code-block:: cpp
+   :linenos:
+
+   int n = lib->elements("source");                           // Get number of sources
+   for (int i = 0; i < n; ++i) {                              // Loop over sources
+       const GXmlElement* src = lib->element("source", i);    // Get pointer on source
+       std::string type = src->attribute("type");             // Get source model type
+       GModelRegistry registry;                               // Get model registry
+       GModel*        ptr = registry.alloc(type);             // Allocate model of specific type
+       if (ptr != NULL) {                                     // If model is valid:
+           ptr->read(*src);                                   // - read model
+           append(*ptr);                                      // - append it to container
+           delete ptr;                                        // - free model
+       }
+   }
+
+To access the registry information it is sufficient to create an instance of
+the registry. To illustrate how the registry is filled the
+``src/model/GModelSky.cpp`` file can be examined:
+
+**C++**
+
+.. code-block:: cpp
+   :linenos:
+
+   const GModelSky         g_pointsource_seed("PointSource");
+   const GModelSky         g_extendedsource_seed("ExtendedSource");
+   const GModelSky         g_diffusesource_seed("DiffuseSource");
+   const GModelSky         g_compositesource_seed("CompositeSource");
+   const GModelRegistry    g_pointsource_registry(&g_pointsource_seed);
+   const GModelRegistry    g_extendedsource_registry(&g_extendedsource_seed);
+   const GModelRegistry    g_diffusesource_registry(&g_diffusesource_seed);
+   const GModelRegistry    g_compositesource_registry(&g_compositesource_seed);
+
+Here four instances of :doxy:`GModelSky` are created as global variables which
+are appended to the :doxy:`GModelRegistry` registry by creating an instance
+of the registry which takes the address of the :doxy:`GModelSky` instance
+as argument.
+
+Registries are widely used throughout GammaLib for the handling of models and
+its components, and the handling of the observations of the different supported
+instruments.
 Model parameters
 ================
  
-To be written
+Model parameters are implemented by :doxy:`GModelPar` which derives from
+the abstract :doxy:`GOptimizerPar` base class. Each model parameter is
+factorised into a value and a scale part according to
+
+.. math::
+   p = v \times s
+
+where
+:math:`p` is the model parameter,
+:math:`v` is the model value factor, and
+:math:`s` is the model scale factor.
+All three components can be accessed or set via the
+:doxy:`GModelPar::value()`,
+:doxy:`GModelPar::factor_value()`, and
+:doxy:`GModelPar::scale()` methods.
+
+In addition, the class handles parameter errors and gradients as well
+as parameter minima or maxima.
+Parameter errors can be accessed or set via the
+:doxy:`GModelPar::error()` and :doxy:`GModelPar::factor_error()`,
+where the former concerns the error on :math:`p` while the latter concerns
+the error on :math:`v`.
+Equivalent methods exist for
+the gradient
+(:doxy:`GModelPar::gradient()` and :doxy:`GModelPar::factor_gradient()`),
+the minimum
+(:doxy:`GModelPar::min()` and :doxy:`GModelPar::factor_min()`), and
+the maximum
+(:doxy:`GModelPar::max()` and :doxy:`GModelPar::factor_max()`).
+
+Finally, :doxy:`GModelPar::fix()` and :doxy:`GModelPar::free()` methods
+allow to fix or to free a model parameter, and the :doxy:`GModelPar::is_free()`
+and :doxy:`GModelPar::is_fix()` methods allow to check whether a parameter is
+free or fixed.
+
+
 .. _um_obs_caldb:
  
-Setting up and using a calibration database
-===========================================
+Using a calibration database
+============================
  
-To be written (describe how to setup and how to use a calibration 
-database) ...
+The class :doxy:`GCaldb` implements the interface to a calibration database
+that is compliant with the HEASARC format.
+To use a calibration database, make sure that the environment variable
+``CALDB`` is set to a valid calibration database.
+The database is the open by specifying a mission and an instrument name.
+The examples below show two variants of opening the ``prod2`` database for
+``CTA``.
+
+**Python**
+
+.. code-block:: python
+   :linenos:
+
+   import gammalib                                      # Make GammaLib available
+   caldb1 = gammalib.GCaldb('cta','prod2')              # Using opening constructor
+   caldb2 = gammalib.GCaldb()
+   caldb2.open('cta','prod2')                           # Using open method
+
+**C++**
+
+.. code-block:: cpp
+   :linenos:
+
+   #include "GammaLib.hpp"                              // Make GammaLib available
+   GCaldb caldb1("cta","prod2");                        // Using opening constructor
+   GCaldb caldb2;
+   caldb2.open("cta","prod2");                          // Using open method
+
+Once opened, the database can be used to locate for example the filename
+of a response component. The examples below show how the effective area
+filename for the response ``South_5h`` is accessed via the calibration
+database.
+
+**Python**
+
+.. code-block:: python
+   :linenos:
+
+   filename = caldb1.filename('','','EFF_AREA','','','NAME(South_5h)')
+
+**C++**
+
+.. code-block:: cpp
+   :linenos:
+
+   GFilename filename = caldb1.filename("","","EFF_AREA","","","NAME(South_5h)");
@@ -3,6 +3,76 @@
 Energies in GammaLib
 ====================
  
-To be written (describe how energies are implemented in GammaLib; mention
-that the internal energy is MeV; this section should also handle EBOUNDS) 
-...
+Energies are implemented by the :doxy:`GEnergy` class that transparently
+handles energies with different units. The energy is stored internally in
+MeV, but energies can also be provided in erg, keV, GeV, TeV, as well as
+the equivalent wavelength in Angstrom.
+
+The code threads below illustrate how an energy of 511 keV can be set using
+the energy constructor or a dedicated method, and how that energy can be
+retrieved in units of MeV.
+
+**Python**
+
+.. code-block:: python
+   :linenos:
+
+   import gammalib                                      # Make GammaLib available
+   energy1 = gammalib.GEnergy(511.0,'keV')              # Using energy constructor
+   energy2 = gammalib.GEnergy()
+   energy2.keV(511.0)                                   # Using keV method
+   E_MeV1 = energy2('MeV')                              # Get energy in MeV
+   E_MeV2 = energy2.MeV()                               # Another variant to get energy in MeV
+
+**C++**
+
+.. code-block:: cpp
+   :linenos:
+
+   #include "GammaLib.hpp"                              // Make GammaLib available
+   GEnergy energy1(511.0,"keV");                        // Using energy constructor
+   GEnergy energy2;
+   energy2.keV(511.0);                                  // Using keV method
+   double E_MeV1 = energy2("MeV");                      // Get energy in MeV
+   double E_MeV2 = energy2.MeV();                       // Another variant to get energy in MeV
+
+Energies can be added and subtracted, or multiplied or divided by a floating
+point value.
+In addition, two energies can be divided, resulting in a floating point value.
+Energies can also be compared using the usual operators.
+
+Energies can be collected by the :doxy:`GEnergies` container class. The threads
+below illustrate how energies can be appended or inserted into the
+:doxy:`GEnergies` container class.
+
+**Python**
+
+.. code-block:: python
+   :linenos:
+
+   import gammalib                                      # Make GammaLib available
+   energy1  = gammalib.GEnergy(511.0,'keV')             # Set first energy
+   energy2  = gammalib.GEnergy(1024.0,'keV')            # Set second energy
+   energies = gammalib.GEnergies()                      # Create energy container instance
+   energies.append(energy1)                             # Append first energy
+   energies.insert(0,energy2)                           # Insert second energy before first energy
+
+**C++**
+
+.. code-block:: cpp
+   :linenos:
+
+   #include "GammaLib.hpp"                              // Make GammaLib available
+   GEnergy   energy1(511.0,"keV");                      // Set first energy
+   GEnergy   energy2(1024.0,"keV");                     // Set second energy
+   GEnergies energies;                                  // Create energy container instance
+   energies.append(energy1);                            // Append first energy
+   energies.insert(0,energy2);                          // Insert second energy before first energy
+
+The energy container can be saved into a file using the :doxy:`GEnergies::save()`
+method, and loaded from a file using either the load constructor or the
+:doxy:`GEnergies::load()` method.
+
+Another energy container class is :doxy:`GEbounds` which stores the energy
+boundaries for an arbitrary number of energy bins.
+
@@ -9,18 +9,18 @@ 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::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)
-``gammalib::mec2``         :math:`0.5109989461` (electron rest mass in MeV)
-========================== =====
+========================== ================================= =======
+Constant                   Value                             Purpose
+========================== ================================= =======
+``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.239841875\times 10^{-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
+``gammalib::mec2``         :math:`0.5109989461`              Electron rest mass in MeV
+========================== ================================= =======
  
  
 Functions