Update documentation and tutorials

Jürgen Knödlseder
1 parent 8346a522
Showing 6 changed files with 235 additions and 75 deletions
doc/source/help/faq.rst
doc/source/users/glossary.rst
doc/source/users/tutorials/quickstart/ctools-from-python.ipynb
doc/source/users/user_manual/introduction.rst
doc/source/users/user_manual/models_implementation.rst
doc/source/users/user_manual/models_spatial_src.rst
@@ -17,6 +17,7 @@ asked.
 - :ref:`I want to upgrade ctools, do I have to upgrade GammaLib? <faq_upgrade>`
 - :ref:`Should I used binned or unbinned analysis? <faq_analysis>`
 - :ref:`How precise are ctools? <faq_precision>`
+- :ref:`How to get a ctools log file when running the tool from Python? <faq_python_logging>`
  
  
 .. _faq_ctools_gammalib:
@@ -45,77 +46,97 @@ asked.
  
 .. topic:: Are ctools and GammaLib specific to CTA?
  
-  The short answer is: ctools yes, GammaLib no.
-
-  ctools have been specifically designed to provide the functionalities that 
-  are required to analyse CTA data.
-  This does not mean that ctools can not be used for analysing data from 
-  other Imaging Air Cherenkov Telescopes; the sole requirement is that the
-  data and response files are provided in a CTA compliant format.
-  However, ctools are not designed to analyse data from Fermi/LAT, 
-  INTEGRAL, COMPTEL or other gamma-ray telescopes.
-  Nevertheless, some joint multi-telescope analysis is supported by ctools.
-
-  GammaLib, however, is a universal framework with a core that is completely
-  independent of any telescope.
-  Plugins are used to interface GammaLib with the data and response files of
-  specific telescopes.
-  For every new instrument that shall be supported a new plugin needs to be
-  developed.
-  So far, plugins exists for CTA (and Imaging Air Cherenkov Telescopes in
-  general), Fermi/LAT, and COMPTEL.
-  Some support for integration of any arbitrary multi-wavelength data 
-  exists.
+   The short answer is: ctools yes, GammaLib no.
+
+   ctools have been specifically designed to provide the functionalities that
+   are required to analyse CTA data.
+   This does not mean that ctools can not be used for analysing data from
+   other Imaging Air Cherenkov Telescopes; the sole requirement is that the
+   data and response files are provided in a CTA compliant format.
+   However, ctools are not designed to analyse data from Fermi/LAT,
+   INTEGRAL, COMPTEL or other gamma-ray telescopes.
+   Nevertheless, some joint multi-telescope analysis is supported by ctools.
+
+   GammaLib, however, is a universal framework with a core that is completely
+   independent of any telescope.
+   Plugins are used to interface GammaLib with the data and response files of
+   specific telescopes.
+   For every new instrument that shall be supported a new plugin needs to be
+   developed.
+   So far, plugins exists for CTA (and Imaging Air Cherenkov Telescopes in
+   general), Fermi/LAT, and COMPTEL.
+   Some support for integration of any arbitrary multi-wavelength data
+   exists.
  
  
 .. _faq_upgrade:
  
 .. topic:: I want to upgrade ctools, do I have to upgrade GammaLib?
  
-  For the moment yes.
+   For the moment yes.
  
-  The GammaLib interface is still not fully stabilised, hence ctools is
-  continuously adapted to match the interface evolution
-  (see the :ref:`sec_download` section for a correspondance of versions).
-  We plan however to put the GammaLib interface under change control.
-  ctools should then become more independent from GammaLib.
+   The GammaLib interface is still not fully stabilised, hence ctools is
+   continuously adapted to match the interface evolution
+   (see the :ref:`sec_download` section for a correspondance of versions).
+   We plan however to put the GammaLib interface under change control.
+   ctools should then become more independent from GammaLib.
  
  
 .. _faq_analysis:
  
 .. topic:: Should I used binned or unbinned analysis?
  
-  This depends on the amount of data you want to analyse and to some extent
-  on the question you want to answer with your analysis.
-  For an unbinned analysis, the computation time increases about linearly
-  with the number of events and hence with the duration of the observation,
-  while for binned analysis the computation time depends only on the number
-  of bins that is used.
-  Consequently, for short observation times (below 30 hours), unbinned
-  analysis is faster, while for longer times it is advantageous to use
-  a binned analysis.
-  If you go to very low energies, either make sure that you have enough
-  energy bins in a binned analysis to sample properly the strong drop in the
-  effective area towards small energies, or better, use unbinned analysis.
-  If you'd like to fit a Gaussian line to your data you may also prefer
-  unbinned over binned analysis, as the fine sampling required to resolve
-  the line may require a prohibitive large number of energy bins for a binned
-  analysis.
+   This depends on the amount of data you want to analyse and to some extent
+   on the question you want to answer with your analysis.
+   For an unbinned analysis, the computation time increases about linearly
+   with the number of events and hence with the duration of the observation,
+   while for binned analysis the computation time depends only on the number
+   of bins that is used.
+   Consequently, for short observation times (below 30 hours), unbinned
+   analysis is faster, while for longer times it is advantageous to use
+   a binned analysis.
+   If you go to very low energies, either make sure that you have enough
+   energy bins in a binned analysis to sample properly the strong drop in the
+   effective area towards small energies, or better, use unbinned analysis.
+   If you'd like to fit a Gaussian line to your data you may also prefer
+   unbinned over binned analysis, as the fine sampling required to resolve
+   the line may require a prohibitive large number of energy bins for a binned
+   analysis.
  
  
 .. _faq_precision:
  
 .. topic:: How precise are ctools?
  
-  The ctools and gammalib codes have a numerical accuracy of better than 1%.
-  This means that if you use ctools to determine for example the flux 
-  received from a source or the spectral points of an SED, the relative 
-  precision of the flux or the spectral points is better than 1%.
-  The same is true for spatial parameters, such as source position or
-  source extension.
-  For many cases the actual numerical precision is in fact much better
-  than 1%, but in any case, it should never be worse.
-  Note, however, that this does not imply that source parameters can be
-  determined with CTA with an accuracy of 1%. The accuracy depends in the
-  end on the precision to which the instrument response function is known,
-  which should be more in the 10% range.
+   The ctools and gammalib codes have a numerical accuracy of better than 1%.
+   This means that if you use ctools to determine for example the flux
+   received from a source or the spectral points of an SED, the relative
+   precision of the flux or the spectral points is better than 1%.
+   The same is true for spatial parameters, such as source position or
+   source extension.
+   For many cases the actual numerical precision is in fact much better
+   than 1%, but in any case, it should never be worse.
+   Note, however, that this does not imply that source parameters can be
+   determined with CTA with an accuracy of 1%. The accuracy depends in the
+   end on the precision to which the instrument response function is known,
+   which should be more in the 10% range.
+
+
+.. _faq_python_logging:
+
+.. topic:: How to get a ctools log file when running the tool from Python?
+
+   By default, tools and scripts run from Python will not generate a log file.
+   The reason for this is that Python scripts are often used to build ctools
+   analysis pipelines and workflows, and one generally does not want that such
+   a script pollutes the workspace with log files. You can however instruct a
+   ctool or cscript to generate a log file by invoking the ``logFileOpen()``
+   method before running the tool, for example
+
+   .. code-block:: python
+
+      >>> import ctools
+      >>> sim = ctools.ctobssim()
+      >>> sim.logFileOpen()
+      >>> sim.run()
+
@@ -48,7 +48,7 @@ Glossary
    .. math::
       E_{\rm disp}(E'| p, E) =
       \frac{\sum_i E_{\rm disp,i}(E'| p, E) \times A_{\rm eff,i}(p, E) \times \tau_i}
-           {\sum_i E_{\rm disp,i}(E'| p, E) \times \tau_i}
+           {\sum_i A_{\rm eff,i}(p, E) \times \tau_i}
  
    where
    :math:`E_{\rm disp,i}(E'| p, E)` is the energy dispersion for observation :math:`i`,
@@ -381,7 +381,7 @@
      "data": {
       "image/png": "iVBORw0KGgoAAAANSUhEUgAAAXwAAAERCAYAAAB4jRxOAAAABHNCSVQICAgIfAhkiAAAAAlwSFlz\nAAALEgAACxIB0t1+/AAAGP1JREFUeJzt3XuwpHV95/H3Z2TBoFGjm0ACMuAapEK56yULXnbLVoyg\n7ooxbgnEjeIaLU0R92KJVZidmaSKdXPbNaImZsnEuDWOVxRiKNFIa1F4YUXAIAPjjWEWZ4wbXHXX\nRTJ+949+DtO0feb0OX0/z/tVNUX3093P93sezvn2r3/Pr79PqgpJ0ua3Zd4JSJJmw4IvSS1hwZek\nlrDgS1JLWPAlqSUs+JLUEhZ8SWoJC74ktcRR09hpkgC/AzwMuKGq3j2NOJKk0U1rhH8ucALwQ2D/\nlGJIktZhpIKf5PIkB5PcMrD9nCR7ktyR5OK+hx4HXF9VrwdeO8F8JUkbNOoIfydwdv+GJFuAy5rt\npwPnJzmteXg/cE9z++8nkKckaUwjFfyquo7DBXzFGcDeqrqzqu4DdtObygH4EHBOkrcAn55UspKk\njRvnpO0JwF199/fTexOgqn4AvPJIL05im05J2oCqykZeN85J22EB11XEt23bxrXXXktVLcy/bdu2\nzT0HczKnNuZlTkf+d+2117Jt27YxSvZ4I/z9wEl9908E7l7PDrZv3z5GeElqj06nQ6fTYceOHRve\nx3pG+OGBo/obgMcm2ZrkaOA84Mr1BN++fTvdbnc9L5GkVup2u2MPkkddlrkLuB44Ncm+JBdW1SHg\nIuAa4FZgd1Xdtp7g27dvp9PprDPl6Vq0fMCcRmVOo1vEvMzpyDqdztgFP1XzOXeapLZt23b/xxRJ\n0uq63S7dbpcdO3ZQGzxpO9eCP6/YkrSskmy44Ns8TZJaYq4F35O2kjSaSZy0dUpHkpaIUzqSpDU5\npSNJS8ApHUlqGad0JElrckpHkpaAUzqS1DJO6UiS1mTBl6SWsOBLUkt40laSloAnbSWpZTxpK0la\nkwVfklrCgi9JLWHBl6SWsOBLUku4LFOSloDLMiWpZVyWKUlakwVfklrCgi9JLXHUvBNYBPv27WPX\nrl0zi3fmmWfyzGc+c2bxJAmmVPCTPAP4HeBW4D1V9elpxJmUd77zT7n00i5btjx96rGqDnDKKe/j\nK1+5ceqxJKnftEb4BXwPOAbYP6UYE1MFVc/h0KHfmkG0G6l65QziSNIDjTSHn+TyJAeT3DKw/Zwk\ne5LckeTile1V9emqej7wRuC3J5uyJGkjRj1puxM4u39Dki3AZc3204Hzk5w28LrvAEePm6QkaXwj\nTelU1XVJtg5sPgPYW1V3AiTZDZwL7Enyy/TeCB5O701BkjRn48zhnwDc1Xd/P703AarqCuCKtXbQ\n/zXhTqdDp9MZIx1J2ny63e7EWtCMU/CHfbV3Xb0Sxu0LIUmb3eBgeMeOHRve1zhfvNoPnNR3/0Tg\n7vXswOZpkjSaSTRPW0/BDw8c1d8APDbJ1iRHA+cBV46VjSRpakZdlrkLuB44Ncm+JBdW1SHgIuAa\nel+w2l1Vt60n+Pbt2523l6QRdDqdsUf4o67SuWCV7VcDV4+VgSRpJrwAiiQtAS+AMiGXXPJbXHrp\n0cBsWis85jGv5KtftZeOpPVb2gugOMKXpNE4wp8QR/iSlsXSjvAlSbPjlI4kLQGndCbEKR1Jy8Ip\nHUnSmrym7Rzceedekg29QW/Iccdt5cCBb8wsnqTFNNeCv9JaoW3tFQ4d+j7rbCw6loMHZ/fmImk6\nJtEm2Tl8Zj+HD09mlgUfwqIca0njcQ5fkrQmC74ktYTr8CVpCbgOf0Kcw5e0LJzDlyStyYIvSS1h\nwZeklrDgS1JLWPAlqSVclilJS8BlmRPiskxJy8JlmZKkNVnwJaklLPitcAxJZvLv+ONPnvcPK2kV\nXgClFe5lVucM7L0vLa6pjfCTHJvkfyR53rRiSJJGN80pnYuB905x/5KkdRip4Ce5PMnBJLcMbD8n\nyZ4kdyS5uG/7WcCXgW8BfsaXpAUw6gh/J3B2/4YkW4DLmu2nA+cnOa15+JnAmcAFwCsnk6okaRwj\nnbStquuSbB3YfAawt6ruBEiyGzgX2FNVb2q2/Rrw7QnmK0naoHFW6ZwA3NV3fz+9N4H7VdVfHGkH\n/V8T7nQ6dDqdMdKRpM2n2+1OrAXNOAV/2Nz8utb+jdsXQpI2u8HB8I4dOza8r3FW6ewHTuq7fyJw\n93p2YPM0SRrNTJunJTkZuKqqHt/cfxBwO3AW8E3g88D5VXXbiPuzedrMZIbxbNQmTdPUm6cl2QVc\nD5yaZF+SC6vqEHARcA1wK7B71GK/whH+ZmQbB2kabI88IY7wlzfWovwOSbOytO2RHeFL0mgc4U+I\nI/zljbUov0PSrDjCl6RNzhH+hDjCX95Yi/I7JM3K0o7wJUmz45SOJC0Bp3QmxCmd5Y21KL9D0qw4\npSNJWpMFX5Jawjl8SVoCzuFPiHP4yxtrUX6HpFkZZw5/nH740pz1GrXNynHHbeXAgW/MLJ40aRZ8\nLbF7meUnpYMHZ/fmIk2Dc/iStAScw58Q5/CNNWq8RfmdVXu5Dl+StCYLviS1hAVfklrCgi9JLWHB\nl6SWcFmmJC0Bl2VOiMsyjTWaB9P7stf0+a1ercbWCtJMzO6bvX6rV9PgHL4ktYQFX5JawoIvSS0x\nlTn8JKcBrwMeBXyyqv54GnEkSaObygi/qvZU1WuAlwBPm0YMSdL6jFTwk1ye5GCSWwa2n5NkT5I7\nklw88Ni/BP4S+KvJpStJ2qhRR/g7gbP7NyTZAlzWbD8dOL+ZygGgqq6qqucDL51QrpKkMYw0h19V\n1yXZOrD5DGBvVd0JkGQ3cC6wJ8kzgBcBxwAfnWC+kqQNGuek7QnAXX3399N7E6CqPgV8aq0d9H9N\nuNPp0Ol0xkhHkjafbrc7sRY04xT8YV8FXNfXEMftCyFJm93gYHjHjh0b3tc4q3T2Ayf13T8RuHs9\nO7B5mrSaY0gyk3/HH3/yvH9YjWCmzdOSnAxcVVWPb+4/CLgdOAv4JvB54Pyqum3E/dk8bWY2a0Oz\n2V/TdnP+bF6rd5lM/Zq2SXYB1wOnJtmX5MKqOgRcBFwD3ArsHrXYr3CEL0mjsT3yhDjCN9bixXOE\nr+GmPsKfFkf4kjQaR/gT4gjfWIsXzxG+hnOEL0mbnCP8CXGEb6zFi+cIX8Mt7QhfkjQ7TulI0hJw\nSmdCnNIx1uLFc0pHwzmlI0lakwVfklrCOXxJWgLO4U+Ic/jGWrx4zuFrOOfwJUlrsuBLUktY8CWp\nJTxpK0lLwJO2E+JJW2MtXjxP2mo4T9pKktZkwZeklrDgS1JLWPAlqSWOmmfw7du30+l06HQ680xD\narljSDZ0DnBDjjtuKwcOfGNm8TaLbrc79qpGV+ngKh1jLWK8zRqrF29R/vaXkat0JElrsuBLUktY\n8CWpJSz4ktQSU1ulk+Rc4PnATwJ/VlUfn1YsSdLaplbwq+ojwEeSPAL4PcCCL0lzNPKUTpLLkxxM\ncsvA9nOS7ElyR5KLh7z0TcDbxk1UkjSe9czh7wTO7t+QZAtwWbP9dOD8JKf1Pf5m4K+q6qYJ5CpJ\nGsPIBb+qrgPuGdh8BrC3qu6sqvuA3cC5AEkuAs4CXpzkVRPKV5K0QePO4Z8A3NV3fz+9NwGq6q3A\nW4/04v5m/rZYkKQfN4mWCivGLfjDvt478nemx716iyRtdoOD4R07dmx4X+Ouw98PnNR3/0Tg7lFf\n7CUOJWk0M7/EYZKTgauq6vHN/QcBt9Obq/8m8Hng/Kq6bYR92TxtZjZrIy6bpy1frF68RfnbX0Yz\naZ6WZBdwPXBqkn1JLqyqQ8BFwDXArcDuUYr9Ckf4kjQaL2I+IY7wjbV48TZrrF68RfnbX0ZL2x7Z\nEb4kjcYR/oQ4wjfW4sXbrLF68Rblb38ZLe0IX5I0O07pSNIScEpnQpzSMdbixdussXrxFuVvfxk5\npSNJWpNTOpK0BJzSmRCndIy1ePE2a6xevEX5219GTulIktbklI4kLQGndCbEKR1jLV68zRqrF29R\n/vaXkVM6kqQ1WfAlqSUs+JLUEp60lTRjx5BkJv+OP/7kef+wE+NJ2wnxpK2xFi/eZo0163ib7wSx\nJ20lSWuy4EtSS1jwJaklLPiS1BKu0pGkJeAqnQlxlY6xFi/eZo0163iu0unnlI4ktYQFX5JawoIv\nSS1hwZeklrDgS1JLTKXgJzklyX9L8r5p7F+StH5TKfhV9fWqeuU09i1J2piRCn6Sy5McTHLLwPZz\nkuxJckeSi6eToiRpEkYd4e8Ezu7fkGQLcFmz/XTg/CSnDbxuQ18OkCRN3kgFv6quA+4Z2HwGsLeq\n7qyq+4DdwLkASR6Z5B3AExz5S9JiOGqM154A3NV3fz+9NwGq6u+A16y1g/6+EJ1Oh06nM0Y6krT5\ndLvdifUcG6fgD5uuWXfTCgu9JK1upUZOovCPU/D3Ayf13T8RuHs9Oxi385sktcVK4d+xY8eG97Ge\nZZnhgaP6G4DHJtma5GjgPODK9QS3PbIkjWZm7ZGT7AI6wKOAg8C2qtqZ5LnAf6X3xnF5Vb155MC2\nR55BrBWbtdXu5m7ruzljzTqe7ZH7jTSlU1UXrLL9auDqjQSG3gjfOXxJ03MMyWxWhx933FYOHPjG\n1PY/iTl8L4CCI3xjLWK8zRpr1vE236cJL4AiSVqT17SVpCXgNW0nxCkdYy1evM0aa9bxnNLp55SO\nJLWEUzqStASc0pkQp3SMtXjxNmusWcdzSqefUzqS1BJO6UjSEnBKZ0Kc0jHW4sXbrLFmHc8pnX5O\n6UhSS1jwJaklLPiS1BKetJWkJeBJ2wnxpK2xFi/eZo0163ietO3nlI4ktYQFX5JawoIvSS1hwZek\nlrDgS1JLuCxTkpaAyzInxGWZxlq8eJs11qzjuSyzn1M6ktQSFnxJagkLviS1hAVfklriqGnsNMmx\nwNuBe4FPVdWuacSRJI1uWiP8FwHvr6pXAy+YUowp6c47gSG6805giO68ExiiO+8EhujOO4FVdOed\nwBDdeScwRHfeCUzUSAU/yeVJDia5ZWD7OUn2JLkjycV9D50I3NXcPjShXGekO+8EhujOO4EhuvNO\nYIjuvBMYojvvBFbRnXcCQ3TnncAQ3XknMFGjjvB3Amf3b0iyBbis2X46cH6S05qH76JX9KG3EFaS\nNGcjFfyqug64Z2DzGcDeqrqzqu4DdgPnNo9dAbw4yduAqyaVrCRp40b+pm2SrcBVVfWPm/u/Apxd\nVa9q7r8UOKOqfnPE/S3G12wlacls9Ju246zSGRZw5CK+0YQlSRszziqd/cBJffdPBO4eLx1J0rSs\np+CHB47qbwAem2RrkqOB84ArJ5mcJGlyRl2WuQu4Hjg1yb4kF1bVIeAi4BrgVmB3Vd02vVQlSeMY\ndZXOBVX1c1V1TFWdVFU7m+1XV9Xjqurnq+rNR9pHkt9NcluSm5J8MMnDVnneamv7pyLJi5P8TZJD\nSZ50hOd9I8nNSb6Y5PMLktPMjlWSn0pyTZLbk3wsycNXed6hJDc2x+nDU8rliD93kqOT7E6yN8ln\nkpw0bD8zzullSb7VHJsbk7xiBjkN/f7MwHP+qDlONyV5wrxzSvKMJN/pO05vmkFOJyb5ZJIvJ/lS\nkqELT2Z5rEbJaUPHqqpm8g94NrCluf1m4D8Nec4W4CvAVuAfADcBp005r8cBPw98EnjSEZ73NeCn\nZnSs1sxp1scK+M/AG5rbFwNvXuV5353ysVnz5wZeA7y9uf0Sep8+553Ty4A/msXvT1/MfwY8Abhl\nlcefC3y0uX0m8NkFyOkZwJUzPk7HA09obj8UuH3I/7+ZHqsRc1r3sZpZ87Sq+kRV/ai5+1kOfzGr\n35HW9k8rr9urai9rf0EszKjZ3Ig5zfpYnQu8q7n9LuCFqzxv2quvRvm5+3P9AHDWAuQEM/4SYg3/\n/ky/c4G/aJ77OeDhSY6bc04w++N0oKpuam5/H7gNOGHgaTM9ViPmBOs8VvPqlvkK4Ooh20/gcEsG\n6K0EGvZDzkMBH0tyQ5Jfn3cyzP5Y/UxVHYTeLyPw06s875gkn09yfZJpvAGN8nPf/5zqnWv6TpJH\nTiGX9eQE8KJmOuB9SYYNeGZtMO//yWL8vT2lmRL8aJJfmGXgJCfT+wTyuYGH5nasjpATrPNYTbRb\nZpKPA/3veivXF7ukqq5qnnMJcF8N76A51tr+cfIawdOq6kCSnwY+nuS2ZrQyr5wmfqyOkNN65lFP\nao7TKcAnk9xSVV8fJ6/BNIdsG/y5B58z7evcjZLTlcCuqrovyavpfQKZ9iePtUzl721MXwC2VtX/\nTfJc4MPAqbMInOSh9D4Rvq4ZVT/g4SEvmfqxWiOndR+riRb8qvqlIz2e5GXA84BnrfKUqaztXyuv\nEfdxoPnv3ya5gt7H+A0X/AnkNPFjdaScmhNtx1XVwSTHA99aZR8rx+nrSbrAE4FJFvxRfu67gEcD\ndyd5EPCwqlprGmGqOQ3E/1N650TmbT+947Ri7t+l6S9qVXV1krcneWRV/d004yY5il5hfXdVfWTI\nU2Z+rNbKaSPHamZTOknOAd4AvKCq7l3lafNe2z90PizJsc07LUkeAjwH+Jt55sTsj9WVwMub2y8D\nfuwXMMkjmlxI8g+BpwFfnnAeo/zcVzU5Avwreie/p2nNnJo3yRXnMvnjsprB78/0uxL4NYAkTwG+\nszJtN6+c+ufFk5xBr/3LVIt948+AL1fVW1Z5fB7H6og5behYTfNM88AZ5b3AncCNzb+VVRQ/C/xl\n3/POoXdGei/wxhnk9UJ6I8IfAN8Erh7MCziF3sqLLwJfmnZeo+Q062MFPBL4RBPv48Ajmu1PBt7Z\n3H4qcEtznG4GXj6lXH7s5wZ2AP+iuX0M8L7m8c8CJ8/g92itnC6lN0j4IvDXwKkzyGkXvVHovcA+\n4ELg1cCr+p5zGb0VRjdzhFVqs8oJ+I2+43Q9cOYMcno6vTbuK3/jNzb/P+d2rEbJaSPHauTmaZKk\n5eY1bSWpJSz4ktQSFnxJagkLviS1hAVfklrCgi9JLWHB18Qk+d6E9nN1knuSDH556eQkn02vRfN7\nmm8irjz2uvSuq0ySnUm+lsNtmjf8jehJSrItyf4k25O8vMnti0nuTa/19o1JLl3ltQ9N8u0kxw5s\nvyrJC5Nc0LTu/VCz/f7jIa1wHb4mJsl3q2rodQ7WuZ9nAscCr66qF/Rtfy/wgap6f5J3ADdV1Z80\n7RNuBJ5YVT9KspNe29grxs1lIK8tdbjj60Zevw34XlX94cD2rwFPrjXaPzQ//4er6j3N/UfQ+7LX\no6vqh0nOAn6jql7UfCP801X15I3mq83HEb6mKslJST7RdIn8+EqXyCSPSe/iJDcn+Z3+TwdVdS0w\n2CgKej2YPtjc7m/R/CzgCwPF+Md+t5sR9uVJrk3ylSQX9T32q0k+14yy35EkzfbvJfn9JF+k15nw\neeldyOeGJG9JcmV67kjyqOY1aUbbo3bofECrgSQPaT6lfDbJF5I8v3loN3B+3+t+hV6P9h8O7rCq\n/g+wPzO4qImWhwVf03YZ8OdV9QR6X6t/a7P9LcB/qap/Qq8x1RE/ajbF9J6+ot7fgvjp9DoH9vu9\nvimdd/dtfxzwS/QuYrEtyYOSnEbvQilPq6onAT8CfrV5/kOAz1TVE5sYfwycXVX/lKZFdPU+Jr8b\nWJlCeTa9Tx8b7QHzH+m103gKvY6af9j06PkocGYOX23sPOA9R9jPF4B/vsEctAlZ8DVtT+VwUXo3\nveK8sv0Dze1hrbIHHak97c8Cfzvw2Our6klV9cSq+td92z9aVX9fVf8LOEivHfRZwJOAG5qR/LPo\n9U+CXj+TDzW3TwO+WlX7mvv9xXYnsBLnFc39jXoOcEmTy7XA0fTaTv+QXtF/UZKfAX6BXl+e1XwL\n+Lkx8tAmM9H2yNIQgyP3YSP5Na/aU1Xfbrpxrsyj97en/QHw4BHz6e/Ueoje30CAd1XVJUOe/4M6\nfKJr1S6PVbU/vRbSz6TXOvuCEfNZzQtr+HUEdgOvp3eO40NrnFN4ML1jIwGO8DVZw4rh9Ryed34p\nh68h8Bngxc3t81bZ1+D+rqXX7hge2KL5NuCxI+SyWr5/Dbw4vYvbrFyw/dEDzwHYA5ySwxdFf8nA\n/i4H/jvw3r43iY34GPC6+5N84Dz8J4DT6XVNPNJ0DvQuhjGrNt5aAhZ8TdJPJNmX5K7mv/8W+E3g\nwiQ30ZsXXylk/w749832fwT875WdJPk08F7gWc1+Vi7M8sbmNXfQa9d8ebP9anoXdO73u31z+Df2\nL+HsUwBVdRu9q3pdk+Rm4Bp600T3P6d53v8DXktzqUvgu/150+uZ/hDgz9c8UkPy6PPbwLFJbkny\nJWBbXw4/Aq4AfrKqrl9jv0/lyFM+ahmXZWoukvxEVf2guf0S4Lyq+uUx9vdB4A1V9dVJ5bhKnIc0\nK2BI8jbgjmouUJHkF4E/qKrBN5+V124Dvl9VfzCl3J4NvLZZlvmLwGuq6t9MI5aWkyN8zcuTm6Wa\nNwOvAf7DmPt7I4dH5dP0682nhluBhwF/ApDkYuD9TR6r+X7z+u2TTirJBfRWPq2sDHokfZ8MJHCE\nL0mt4QhfklrCgi9JLWHBl6SWsOBLUktY8CWpJf4/YSiW8RnJDJkAAAAASUVORK5CYII=\n",
       "text/plain": [
-       "<matplotlib.figure.Figure at 0x1067bc490>"
+       "<matplotlib.figure.Figure at 0x10f3d3ad0>"
       ]
      },
      "metadata": {},
@@ -491,8 +491,8 @@
       "  RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)\n",
       "  DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)\n",
       " Number of spectral par's ..: 3\n",
-      "  Prefactor ................: 5.71641985530777e-16 +/- 6.16044729438793e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)\n",
-      "  Index ....................: -2.47207574641491 +/- 0.00792255648868446 [-0,-5]  (free,scale=-1,gradient)\n",
+      "  Prefactor ................: 5.71641983396841e-16 +/- 6.16044728001869e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)\n",
+      "  Index ....................: -2.47207578184696 +/- 0.00792255637026554 [-0,-5]  (free,scale=-1,gradient)\n",
       "  PivotEnergy ..............: 300000 [10000,1000000000] MeV (fixed,scale=1000000,gradient)\n",
       " Number of temporal par's ..: 1\n",
       "  Normalization ............: 1 (relative value) (fixed,scale=1,gradient)\n",
@@ -504,8 +504,8 @@
       " Model type ................: \"PowerLaw\" * \"Constant\"\n",
       " Number of parameters ......: 4\n",
       " Number of spectral par's ..: 3\n",
-      "  Prefactor ................: 0.999546835049722 +/- 0.00722086200687532 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)\n",
-      "  Index ....................: -0.000149670672999089 +/- 0.00255125105704583 [-5,5]  (free,scale=1,gradient)\n",
+      "  Prefactor ................: 0.999547413672001 +/- 0.00722086618569711 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)\n",
+      "  Index ....................: -0.000149454940530402 +/- 0.00255125105744512 [-5,5]  (free,scale=1,gradient)\n",
       "  PivotEnergy ..............: 1000000 [10000,1000000000] MeV (fixed,scale=1000000,gradient)\n",
       " Number of temporal par's ..: 1\n",
       "  Normalization ............: 1 (relative value) (fixed,scale=1,gradient)\n"
@@ -568,11 +568,11 @@
       " Model components ..........: \"PointSource\" * \"PowerLaw\" * \"Constant\"\n",
       " Number of parameters ......: 6\n",
       " Number of spatial par's ...: 2\n",
-      "  RA .......................: 83.6321512928169 +/- 0.000642709898034108 [-360,360] deg (free,scale=1)\n",
-      "  DEC ......................: 22.0153650383811 +/- 0.000605599763935102 [-90,90] deg (free,scale=1)\n",
+      "  RA .......................: 83.6321513539243 +/- 0.000642709906923956 [-360,360] deg (free,scale=1)\n",
+      "  DEC ......................: 22.015365038759 +/- 0.000605599773766818 [-90,90] deg (free,scale=1)\n",
       " Number of spectral par's ..: 3\n",
-      "  Prefactor ................: 5.71414829573802e-16 +/- 6.15917758147358e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)\n",
-      "  Index ....................: -2.47211135009306 +/- 0.0079230681070739 [-0,-5]  (free,scale=-1,gradient)\n",
+      "  Prefactor ................: 5.71414829301837e-16 +/- 6.15917760942954e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)\n",
+      "  Index ....................: -2.47211138483201 +/- 0.0079230679574118 [-0,-5]  (free,scale=-1,gradient)\n",
       "  PivotEnergy ..............: 300000 [10000,1000000000] MeV (fixed,scale=1000000,gradient)\n",
       " Number of temporal par's ..: 1\n",
       "  Normalization ............: 1 (relative value) (fixed,scale=1,gradient)\n",
@@ -584,8 +584,8 @@
       " Model type ................: \"PowerLaw\" * \"Constant\"\n",
       " Number of parameters ......: 4\n",
       " Number of spectral par's ..: 3\n",
-      "  Prefactor ................: 0.999542788067004 +/- 0.00722079542969056 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)\n",
-      "  Index ....................: -0.00014887248036908 +/- 0.00255123898184119 [-5,5]  (free,scale=1,gradient)\n",
+      "  Prefactor ................: 0.999543391635431 +/- 0.0072207997895289 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)\n",
+      "  Index ....................: -0.000148647508899144 +/- 0.0025512389825989 [-5,5]  (free,scale=1,gradient)\n",
       "  PivotEnergy ..............: 1000000 [10000,1000000000] MeV (fixed,scale=1000000,gradient)\n",
       " Number of temporal par's ..: 1\n",
       "  Normalization ............: 1 (relative value) (fixed,scale=1,gradient)\n"
@@ -615,7 +615,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "4.2173620963\n"
+      "4.21736054635\n"
      ]
     }
    ],
@@ -633,11 +633,32 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "cell_type": "markdown",
    "metadata": {},
+   "source": [
+    "## Generating a log file\n",
+    "\n",
+    "By default, tools and scripts run from Python will not generate a log file. The reason for this is that Python scripts are often used to build ctools analysis pipelines and workflows, and one generally does not want that such a script pollutes the workspace with log files. You can however instruct a ctool or cscript to generate a log file as follows:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "metadata": {
+    "scrolled": true
+   },
    "outputs": [],
-   "source": []
+   "source": [
+    "like.logFileOpen()\n",
+    "like.run()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This creates a log file named ``ctlike.log`` in your local work space that you can visualise using any editor."
+   ]
   }
  ],
  "metadata": {
@@ -103,7 +103,7 @@ example
  
 .. code-block:: bash
  
-  $ ctobssim seed=41
+   $ ctobssim seed=41
  
 will run :ref:`ctobssim` with a seed value of 41. Multiple hidden parameters
 specified on the command line need to be separated by a white space. In the
@@ -116,3 +116,32 @@ values of queried parameters, e.g.
    >>> sim = ctools.ctobssim()
    >>> sim["seed"] = 41
    ...
+
+
+Log files
+---------
+
+Each ctool and cscript will produce a log file that is written in the working
+directory. The log file is in ASCII file format and can be read by any editor.
+By default, the name of the ASCII file is the name of the tool or script,
+suffixed by ``.log``. You can change the log file name using the hidden
+``logfile`` parameter, for example
+
+.. code-block:: bash
+
+   $ ctobssim logfile=my_first_simulation.log
+
+When calling a ctool or cscript from Python, no log file will be written by
+default. The reason for this is that Python scripts are often used to build
+ctools analysis pipelines and workflows, and one generally does not want that
+such a script pollutes the workspace with log files. You can however instruct
+a ctool or cscript to generate a log file by invoking the ``logFileOpen()``
+method before running the tool, for example
+
+.. code-block:: python
+
+   >>> import ctools
+   >>> sim = ctools.ctobssim()
+   ...
+   >>> sim.logFileOpen()
+   >>> sim.run()
@@ -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