Add documentation on normalisation of diffuse map and diffuse map cube models (#2997)

Jürgen Knödlseder
1 parent 7da5e0b4
Showing 2 changed files with 92 additions and 3 deletions
doc/source/users/user_manual/models_implementation.rst
doc/source/users/user_manual/models_spatial_src.rst
@@ -15,6 +15,42 @@ a temporal component (tag ``&lt;temporal&gt;``).
 .. math::
    M(p,E,t) = M_{\rm spatial}(p|E) \times M_{\rm spectral}(E) \times M_{\rm temporal}(t)
  
+where :math:`M(p,E,t)` is given in units of
+:math:`photons \,\, cm^{-2} s^{-1} MeV^{-1} sr^{-1}`.
+
+The spatial model component describes the energy dependent morphology of the
+source.
+It satisfies
+
+.. math::
+   \int_{\Omega} M_{\rm spatial}(p|E) \, d\Omega = 1
+
+for all :math:`E`, hence the spatial component does not
+impact the spatially integrated spectral and temporal properties of the
+source (the integration is done here over the spatial parameters
+:math:`p` in a spherical coordinate system).
+The units of the spatial model component are
+:math:`[M_{\rm spatial}] = {\rm sr}^{-1}`
+(but see the exception of the
+:ref:`DiffuseMapCube spatial model component <um_models_spatial_src_diffuse_cube>`).
+
+The spectral model component describes the spatially integrated spectral
+distribution of the source.
+It satisfies
+
+.. math::
+   \int_{E} M_{\rm spectral}(E) \, dE = \Phi
+
+where :math:`\Phi` is the spatially and spectrally integrated total source
+flux.
+The units of the spectral model component
+are :math:`[M_{\rm spectral}] = {\rm cm}^{-2} {\rm s}^{-1} {\rm MeV}^{-1}`.
+
+The temporal model component describes the relative variation of the
+source flux with respect to the mean value given by the spectral model
+component.
+The temporal model component is unit less.
+
 In this specific example, the source component ``Crab`` describes 
 a point source at the location of the Crab nebula with a power law spectral
 shape that is constant in time.
@@ -61,6 +61,9 @@ Point source
 Radial source
 ^^^^^^^^^^^^^
  
+RadialDisk
+~~~~~~~~~~
+
   The ``RadialDisk`` model describes a uniform intensity distribution within
   a given radius
  
@@ -83,6 +86,9 @@ Radial source
   * ``DEC`` is the Declination (degrees)
   * ``Radius`` is the disk radius (degrees)
  
+RadialGaussian
+~~~~~~~~~~~~~~
+
   The ``RadialGaussian`` model describes a Gaussian intensity distribution
  
   .. code-block:: xml
@@ -108,7 +114,10 @@ Radial source
  
   * ``RA`` is the Right Ascension (degrees)
   * ``DEC`` is the Declination (degrees)
-  * :math:`\sigma` == ``Sigma`` (degrees)
+  * :math:`\sigma` = ``Sigma`` (degrees)
+
+RadialShell
+~~~~~~~~~~~
  
   The ``RadialShell`` model describes a spherical shell projected on the sky
  
@@ -159,6 +168,9 @@ Radial source
 Elliptical source
 ^^^^^^^^^^^^^^^^^
  
+EllipticalDisk
+~~~~~~~~~~~~~~
+
   The ``EllipticalDisk`` model describes a uniform intensity distribution within
   an elliptical circumference:
  
@@ -185,6 +197,9 @@ Elliptical source
   * ``MinorRadius`` is the minor radius of the ellipse (degrees)
   * ``MajorRadius`` is the major radius of the ellipse (degrees)
  
+EllipticalGaussian
+~~~~~~~~~~~~~~~~~~
+
   The ``EllipticalGaussian`` model describes a Gaussian intensity distribution
  
   .. code-block:: xml
@@ -232,6 +247,9 @@ Elliptical source
 Diffuse source
 ^^^^^^^^^^^^^^
  
+DiffuseIsotropic
+~~~~~~~~~~~~~~~~
+
   The ``DiffuseIsotropic`` model describes an isotropic intensity distribution
  
   .. code-block:: xml
@@ -253,6 +271,9 @@ Diffuse source
      For compatibility with the Fermi/LAT ScienceTools the model type
      ``DiffuseIsotropic`` can be replaced by ``ConstantValue``.
  
+DiffuseMap
+~~~~~~~~~~
+
   The ``DiffuseMap`` model describes an arbitrary intensity distribution in
   form of a sky map
  
@@ -281,8 +302,15 @@ Diffuse source
      ``Normalization`` can be replaced by ``Prefactor``.
  
   .. note::
-     You may add the ``normalize="0"`` to the spatial model tag to avoid the
-     normalization of the diffuse map to an integral of unity
+     By default, the diffuse map is normalised so that
+
+     .. math::
+        \int_{\Omega} M_{\rm spatial}(p|E) \, d\Omega = 1
+
+     which means that the units of the spatial model component are
+     :math:`[M_{\rm spatial}] = {\rm sr}^{-1}`.
+     To avoid the normalisation you may add the ``normalize="0"`` attribute
+     to the spatial model tag.
  
      .. code-block:: xml
  
@@ -295,6 +323,19 @@ Diffuse source
           </spectrum>
         </source>
  
+     In that case, generally
+
+     .. math::
+        \int_{\Omega} M_{\rm spatial}(p|E) \, d\Omega \neq 1
+
+     and the spectral component cannot be directly interpreted as a physical
+     source intensity.
+
+  .. _um_models_spatial_src_diffuse_cube:
+
+DiffuseMapCube
+~~~~~~~~~~~~~~
+
   The ``DiffuseMapCube`` model describes an arbitrary energy-dependent intensity
   distribution in form of a map cube
  
@@ -313,6 +354,18 @@ Diffuse source
  
   * ``Normalization`` is a normalization value
  
+  Note that the map cube is not normalised to unit, hence generally
+
+  .. math::
+     \int_{\Omega} M_{\rm spatial}(p|E) \, d\Omega \neq 1
+
+  To compute the flux in a given energy band for a ``DiffuseMapCube`` model
+  you have to integrated both the spatial and spectral components, i.e.
+
+  .. math::
+     \Phi = \int_{\Omega} \int_{E} M_{\rm spatial}(p|E) \times
+            M_{\rm spectral}(E)\, d\Omega \, dE
+
   .. note::
      For compatibility with the Fermi/LAT ScienceTools the model type
      ``DiffuseMapCube`` can be replaced by ``MapCubeFunction`` and the parameter