Merge branch 'master' into devel

Jürgen Knödlseder
2 parents 29d94075 b01d505b
Showing 18 changed files with 216 additions and 146 deletions
README
ctools.pc.in
doc/source/_templates/index.html
doc/source/_themes/sphinx13/layout.html
doc/source/about.rst
doc/source/contents.rst
doc/source/download.rst
doc/source/help.rst
doc/source/issues.rst
doc/source/reference_manual/cscaldb.rst
doc/source/reference_manual/cslightcrv.rst
doc/source/reference_manual/cspull.rst
doc/source/reference_manual/cssens.rst
doc/source/reference_manual/cstsdist.rst
doc/source/reference_manual/ctbin.rst
doc/source/reference_manual/ctmodel.rst
doc/source/user_manual/getting.rst
doc/source/user_manual/introduction.rst
 ctools information
 ==================
-Version:             0.10.0 (28 October 2015)
+Version:             0.10.0 (31 October 2015)
 Author:              Juergen Knodlseder (jurgen.knodlseder@irap.omp.eu)
 GammaLib dependency: 0.11.0
@@ -6,9 +6,9 @@ includedir=${prefix}/include
 Name: ctools
 Description: CTA science analysis tools
 URL: http://cta.irap.omp.eu/ctools
-Version: 0.9.0
+Version: 0.10.0
 Requires: 
-Requires.private: gammalib >= 0.10.0
+Requires.private: gammalib >= 0.11.0
 Conflicts: 
 Cflags: -I${includedir}/ctools @OPENMP_CXXFLAGS@
 Libs: -L${libdir} -lctools
@@ -25,6 +25,12 @@ By making use of the GammaLib multi-instrument capabilities, ctools
 supports the joint analysis of CTA (or any IACT providing data in the
 CTA format), Fermi/LAT and COMPTEL data. {%endtrans%}</p>
+<p>{%trans%} ctools are developed by a team of enthousiastic gamma-ray
+astronomers with support from engineers. We regularily organise
+<a href=https://cta-redmine.irap.omp.eu/projects/ctools/wiki/Coding_sprints>coding sprints</a>
+where key developers but also newcomers meet to discuss the developments 
+and next steps, and advance with the coding of the software. {%endtrans%}</p>
+
 <p>{%trans%} ctools is free software distributed under the
 <a href="http://www.gnu.org/licenses/gpl.html">GNU GPL license version 3</a> {%endtrans%}</p>
@@ -52,5 +58,6 @@ CTA format), Fermi/LAT and COMPTEL data. {%endtrans%}&lt;/p&gt;
 <h2 style="margin-bottom: 0">{%trans%}Links{%endtrans%}</h2>
 <ul>
-	<li><a href="https://cta-redmine.irap.omp.eu/projects/ctools">Developer's pages</a>{% endblock %}</li>
+	<li><a href="https://cta-redmine.irap.omp.eu/projects/ctools">Developer's pages</a></li>
+	<li><a href="https://www.openhub.net/p/ctools_">ctools on Open HUB</a>{% endblock %}</li>
 </ul>
@@ -68,15 +68,15 @@
 <div class="pageheader">
   <ul>
     <li><a href="{{ pathto('about') }}">About</a></li>
-    <li><a href="{{ pathto('index') }}">Home</a></li>
     <li><a href="{{ pathto('download') }}">Download</a></li>
     <li><a href="{{ pathto('contents') }}">Documentation</a></li>
     <li><a href="{{ pathto('develop') }}">Develop</a></li>
+    <li><a href="{{ pathto('help') }}">Help</a></li>
   </ul>
   <div>
     <a href="{{ pathto('index') }}">
       <div class=banner_part>
-      <img src="{{ pathto('_static/logo.png', 1) }}" height="64" alt="SPHINX" />
+      <img src="{{ pathto('_static/logo.png', 1) }}" height="64" alt="ctools" />
       </div>
 	  <div class=banner_part></div>
 	  <div class=banner_part></div>
@@ -27,6 +27,12 @@ By making use of the GammaLib multi-instrument capabilities, ctools
 supports the joint analysis of CTA (or any IACT providing data in the 
 CTA format), Fermi/LAT and COMPTEL data.
+ctools are developed by a team of enthousiastic gamma-ray astronomers with
+support from engineers. We regularily organise
+`coding sprints <https://cta-redmine.irap.omp.eu/projects/ctools/wiki/Coding_sprints>`_
+where key developers but also newcomers meet to discuss the developments 
+and next steps, and advance with the coding of the software.
+
 Acknowledging or citing ctools
 ------------------------------
@@ -15,4 +15,5 @@ Documentation
    reference_manual/index
    faq
    issues
-   develop
 \ No newline at end of file
+   develop
+   help
 \ No newline at end of file
@@ -13,14 +13,7 @@ bugs.
 Releases
 --------
-The latest ctools release is ``ctools-0.9.0`` (22 May 2015).
-
-.. note::
-
-   The cscripts in the Mac OS X binary package ctools-0.9.0-macosx10.3.dmg 
-   were not working. If you encounter a problem please download the updated
-   binary package
-   `ctools-0.9.1-macosx10.3.dmg <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-0.9.1-macosx10.3.dmg>`_.
+The latest ctools release is ``ctools-0.10.0`` (1 November 2015).
 Below a table of ctools releases. Please note that at this stage of the
 project there is a strict link between the ctools and gammalib versions.
@@ -35,6 +28,9 @@ gammalib.
    * - `ctools <http://cta.irap.omp.eu/ctools/releases/ctools/ChangeLog>`_
      - `gammalib <http://cta.irap.omp.eu/ctools/releases/gammalib/ChangeLog>`_
      - Mac OS X package
+   * - `0.10.0 <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-0.10.0.tar.gz>`_
+     - `0.11.0 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-0.11.0.tar.gz>`_
+     - `ctools-0.10.0-macosx10.3.dmg <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-0.10.0-macosx10.3.dmg>`_
    * - `0.9.0 <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-0.9.0.tar.gz>`_
      - `0.10.0 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-0.10.0.tar.gz>`_
      - `ctools-0.9.1-macosx10.3.dmg <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-0.9.1-macosx10.3.dmg>`_
@@ -132,6 +128,9 @@ the following command sequence (the code will be installed into the
    $ export CTOOLS=/usr/local/gamma
    $ source $CTOOLS/bin/ctools-init.sh
+Please read the :ref:`sec_getting` section if you need more information on
+how to install ctools.
+
 .. note::
   You need `swig <http://www.swig.org/>`_ on your system to build the
+.. _help:
+
+Getting Help
+============
+
+Any questions, bug reports, or suggested enhancements related to
+ctools should be submitted via the
+`issue tracker <https://cta-redmine.irap.omp.eu/projects/ctools/issues/new>`_
+or the
+`mailing list <mailto:ctools@irap.omp.eu>`_.
 \ No newline at end of file
@@ -3,12 +3,17 @@
 Known issues
 ------------
-Below you will find a list of known issues.
+Below you will find a list of known ctools issues. You may also check the
+list of
+`known GammaLib issues <http://cta.irap.omp.eu/gammalib/doc/html/issues.html>`_.
 **Installation issues**
 - :ref:`Certificate problem when cloning from Git <issue_ssl>`
-- :ref:`Python unit test fail on El Capitan <issue_elcapitan>`
+- :ref:`Python module does not work <issue_python>`
+- :ref:`Python unit test fails on El Capitan <issue_elcapitan>`
+- :ref:`Installing on Solaris <issue_solaris>`
+- :ref:`Installing on OpenSolaris <issue_opensolaris>`
 **Analysis issues**
@@ -21,6 +26,7 @@ Below you will find a list of known issues.
 - :ref:`Shell model is biased when width is comparable to angular resolution <issue_shell>`
 - :ref:`Elliptical Gaussian model fit converges slowly <issue_egauss>`
+.. _installation_issues:
 Installation issues
 ^^^^^^^^^^^^^^^^^^^
@@ -38,9 +44,33 @@ Installation issues
        export GIT_SSL_NO_VERIFY=true
+.. _issue_python:
+
+.. topic:: Python module does not work
+
+   ctools include a Python module that is built from so called wrapper 
+   files that are autogenerated using the `swig <http://www.swig.org/>`_
+   tool. These wrapper files are shipped with a ctools release, but if
+   you use the code from git you need `swig <http://www.swig.org/>`_
+   to generate the wrapper files during the build step. In any case,
+   to compile the Python module ctools need the ``Python.h`` header file
+   which may not necessarily be installed on your system. Check the output
+   of ``./configure`` to examine the configuration that ctools has
+   detected. You may see the following::
+
+   * Python                       (yes)
+   * Python.h                     (yes)
+   * swig                         (yes)
+   * Python wrappers              (yes)
+
+   Recall, if the wrappers exist you do not need `swig <http://www.swig.org/>`_,
+   but if the wrappers don't exist you need `swig <http://www.swig.org/>`_.
+   If the ``Python.h`` header file does not exist then install the Python
+   development package.
+
 .. _issue_elcapitan:
-.. topic:: Python unit test fail on El Capitan
+.. topic:: Python unit test fails on El Capitan
     On Mac OS X 10.11 (El Capitan) the Python unit tests fail when ctools 
     are not installed due to the way the ``DYLD_LIBRARY_PATH`` environment
@@ -48,6 +78,38 @@ Installation issues
     workaround is to install the ctools before running the unit test using 
     ``make check``.
+.. _issue_solaris:
+
+.. topic:: Installing on Solaris
+
+    Although ctools build on Solaris using the Sun compiler, there are
+    problems with global symbols in shared libraries and exception catching,
+    which prevents the FITS interface to work correctly. ctools have however
+    been built and tested successfully using the GNU compiler, and this is
+    the only build method that is currently supported. Problems have also
+    been encountered when compiling cfitsio versions more recent than 3.250.
+    The problems have been reported to the cfitsio developer team, and are
+    likely to be solved in the future. For the time being, it is recommended
+    to use cfitsio version 3.250 on Solaris.
+
+.. _issue_opensolaris:
+
+.. topic:: Installing on OpenSolaris
+
+   On OpenSolaris, the same problems concerning the SunStudio compiler
+   occur as for Solaris, and also here, the GNU compiler is the recommended
+   tool to build ctools. Also here, cfitsio version 3.250 is the recommended
+   library as more recent version feature relocation problems. ctools have
+   been tested using gcc 4.3.2 on OpenSolaris 2009.06. Make sure to create
+   the symbolic links
+
+   .. code-block:: csh
+
+      $ ln -s /usr/bin/gcc4.3.2 /usr/bin/gcc
+      $ ln -s /usr/bin/g++4.3.2 /usr/bin/g++
+
+   which are not there by default. This avoids warnings during compilation.
+
 Analysis issues
 ^^^^^^^^^^^^^^^
-.. _cscaldb:

cscaldb
=======

Dumps available instrument response functions.


Synopsis
--------

This scripts dumps all instrument response functions that are available
in the calidation database into a log file.


General parameters
------------------

None
 	 	 

Standard parameters
-------------------

``(chatter = 2) [integer]``
    Verbosity of the executable:
     chatter = 0: no information will be logged
     
     chatter = 1: only errors will be logged
     
     chatter = 2: errors and actions will be logged
     
     chatter = 3: report about the task execution
     
     chatter = 4: detailed report about the task execution
 	 	 
``(clobber = yes) [boolean]``
    Specifies whether an existing output counts cube should be overwritten.
 	 	 
``(debug = no) [boolean]``
    Enables debug mode. In debug mode the executable will dump any log file output to the console.
 	 	 
``(mode = ql) [string]``
    Mode of automatic parameters (default is "ql", i.e. "query and learn").


Related tools
-------------

None
 \ No newline at end of file
+.. _cscaldb:

cscaldb
=======

Dumps all available instrument response functions into log fil.


Synopsis
--------

This scripts dumps all instrument response functions that are available
in the calibration database into the log file. If you want the information
on the screen, add the ``debug=yes`` parameter.


General parameters
------------------

None
 	 	 

Standard parameters
-------------------

``(chatter = 2) [integer]``
    Verbosity of the executable:
     chatter = 0: no information will be logged
     
     chatter = 1: only errors will be logged
     
     chatter = 2: errors and actions will be logged
     
     chatter = 3: report about the task execution
     
     chatter = 4: detailed report about the task execution
 	 	 
``(clobber = yes) [boolean]``
    Specifies whether an existing output counts cube should be overwritten.
 	 	 
``(debug = no) [boolean]``
    Enables debug mode. In debug mode the executable will dump any log file output to the console.
 	 	 
``(mode = ql) [string]``
    Mode of automatic parameters (default is "ql", i.e. "query and learn").


Related tools
-------------

None
 \ No newline at end of file
@@ -9,7 +9,16 @@ Computes a lightcurve for a given source.
 Synopsis
 --------
-Computes a lightcurve for a given source.
+Computes a lightcurve by performing a maximum likekihood fit in a series of 
+time bins. The time bins can be either specified in an ASCII file, as an
+interval divided into equally sized time bins, or can be taken from the Good 
+Time Intervals of the observation(s). The format of the ASCII file is one
+row per time bin, each specifying the start of stop value of the bin, separated
+by a whitespace. The times are given in Modified Julian Days (MJD). 
+cslightcrv writes the fitted model parameters and their statistical errors 
+in a FITS file. In addition, it computes for each time bin the statistical 
+significance of the detection, expressed by the Test Statistics, and the 
+upper flux limit.
 General parameters
@@ -9,11 +9,11 @@ Generates pull distribution for all model parameters.
 Synopsis
 --------
-Generates pull distributions for all parameters in a model.
-The pull is defined by the fitted value minus the simulated true value,
-devided by the statistical uncertainty.
-For unbiased parameter estimates, the pull distribution should follow a
-Gaussian centred on 0 and a sigma parameter of 1.
+Generates pull distributions for all parameters in a model. The pull is
+defined by the fitted value minus the simulated true value, devided by
+the statistical uncertainty. For unbiased parameter estimates, the pull
+distribution should follow a Gaussian centred on 0 and a sigma parameter
+of 1.
 General parameters
@@ -11,10 +11,10 @@ Synopsis
 Computes the CTA sensitivity for a number of energy bins using :doc:`ctlike`.
 Crab spectra are fitted in narrow energy bins to simulated data, and the
-flux level is determined that leads to a particular significance.
-The significance is estimated using the Test Statistic value.
-The simplified assumption is made that the significance (in Gaussian
-sigma) is the square root of the Test Statistic.
+flux level is determined that leads to a particular significance. The
+significance is estimated using the Test Statistic value. The simplified
+assumption is made that the significance (in Gaussian sigma) is the square
+root of the Test Statistic.
 General parameters
@@ -9,8 +9,8 @@ Generates the TS distribution for a particular model.
 Synopsis
 --------
-Generates the Test Statistics (TS) distribution for a particular model based on
-Monte-Carlo simulations.
+Generates the Test Statistics (TS) distribution for a particular model
+based on Monte-Carlo simulations.
 General parameters
@@ -10,9 +10,8 @@ Synopsis
 --------
 This tool computes the counts cube for use in a binned maximum likelihood
-analysis.
-The counts cubes are 3-dimensional data cubes spanned by Right Ascension or
-Galactic longitude, Declination or Galactic latitude, and energy.
+analysis. The counts cubes are 3-dimensional data cubes spanned by Right
+Ascension or Galactic longitude, Declination or Galactic latitude, and energy.
 The energy binning may be either linear, logarithmic, or custom defined.
 If an observation definition XML file containing several observations is 
 provided on input, the tool will stack all data into a single counts cube.
@@ -9,9 +9,9 @@ Computes model counts cube.
 Synopsis
 --------
-This tool computes a model counts cube based on an XML model.
-The counts cube is a 3-dimensional data cube spanned by Right Ascension or
-Galactic longitude, Declination or Galactic latitude, and energy.
+This tool computes a model counts cube based on an XML model. The counts
+cube is a 3-dimensional data cube spanned by Right Ascension or Galactic
+longitude, Declination or Galactic latitude, and energy.
 General parameters
+.. _sec_getting:
+
 Getting the ctools
 ==================
@@ -25,6 +27,8 @@ software:
 No system administrator privileges are needed to install ctools.
+.. _sec_installing_gammalib:
+
 Installing gammalib
 -------------------
@@ -59,7 +63,7 @@ in an appropriate location (for example ``$HOME/builds``), and type
 .. code-block:: bash
-  $ tar xvfz gammalib-0.10.0.tar.gz
+  $ tar xvfz gammalib-0.11.0.tar.gz
 (the ``$`` symbol indicates the console prompt and is not part of the
 command that you should type in).
@@ -69,7 +73,7 @@ typing
 .. code-block:: bash
-  $ cd gammalib-0.10.0
+  $ cd gammalib-0.11.0
   $ ./configure
   $ make
   $ make check
@@ -91,6 +95,8 @@ which then installs GammaLib in the ``gamma`` folder of your home
 directory.
+.. _sec_setup_gammalib:
+
 Setting up the GammaLib environment
 -----------------------------------
@@ -127,7 +133,7 @@ an appropriate location (for example ``$HOME/builds``), and type
 .. code-block:: bash
-  $ tar xvfz ctools-0.9.0.tar.gz
+  $ tar xvfz ctools-0.10.0.tar.gz
 (the ``$`` symbol indicates the console prompt and is not part of the
 command that you should type in).
@@ -136,7 +142,7 @@ Step in the directory and build the ctools by typing
 .. code-block:: bash
-  $ cd ctools-0.9.0
+  $ cd ctools-0.10.0
   $ ./configure
   $ make
@@ -153,6 +159,8 @@ You can get the full list of configuration options by typing
   $ ./configure --help
+.. _sec_testing_ctools:
+
 Testing ctools
 --------------
@@ -173,7 +181,7 @@ following output at the end of the unit testing:
   PASS: test_python.py
   make[4]: Nothing to be done for `all'.
   ============================================================================
-  Testsuite summary for ctools 0.9.0
+  Testsuite summary for ctools 0.10.0
   ============================================================================
   # TOTAL: 3
   # PASS:  3
@@ -204,6 +212,7 @@ For older automake version, you should see
   Test ctcubemask: .. ok
   Test ctbutterfly: .. ok
   Test ctulimit: .. ok
+  Test cterror: .. ok
   PASS: test_ctools.sh
   *****************
@@ -237,6 +246,7 @@ For older automake version, you should see
   Test ctcubemask functionality: ... ok
   Test ctbutterfly functionality: ... ok
   Test ctulimit functionality: ... ok
+  Test cterror functionality: ... ok
   Test unbinned pipeline with FITS file saving: .... ok
   Test unbinned in-memory pipeline: .... ok
   PASS: test_python.py
@@ -254,14 +264,17 @@ versions, but there it is written in log files that you can find in the
   test_cscripts.sh.log
   test_python.py.log
-If you do not see the same output, but a failure message, please report 
-this to the ctools developer team.
+If you do not see the same output, but a failure message, please check
+first the :ref:`issues` section. If you cannot fix the problem, please
+create an issue on the ctools tracker
+`here <https://cta-redmine.irap.omp.eu/projects/ctools>`_.
+.. _sec_installing_ctools:
 Installing ctools
 -----------------
-The ctools are installed by typing
+Now you are ready to install the ctools by typing
 .. code-block:: bash
@@ -284,13 +297,14 @@ can be given, for example:
   $ ./configure --prefix=$HOME/gamma
+.. _sec_setup_ctools:
 Setting up the ctools environment
 ---------------------------------
 You have to configure ctools by setting up some environment variables. This
 will be done automatically by an initialisation script that is found in the
-``bin`` directory of the directory into which ctools has been installed. 
+``bin`` directory of the ctools installation. 
 Assuming that you have installed ctools into ``/usr/local/gamma`` you need
 to add the following to your ``$HOME/.bashrc`` or ``$HOME/.profile`` script
 on a Linux machine:
@@ -308,13 +322,14 @@ If you use C shell or a variant then add the following to your
   setenv CTOOLS /usr/local/gamma
   source $CTOOLS/bin/ctools-init.csh
+.. _sec_check_ctools_setup:
 Checking your setup
 -------------------
 Now you should be ready to get started using Gammalib and ctools.
-As a quick check that your setup is OK, you can run ``csinfo check``:
+As a quick check that your setup is okay you can run ``csinfo check``:
 .. code-block:: bash
@@ -329,7 +344,7 @@ As a quick check that your setup is OK, you can run ``csinfo check``:
      ===> Your Gammalib / ctools setup is OK.
-If the setup is not OK, run the ``csinfo info`` command to print
+If the setup is not okay, run the ``csinfo info`` command to print
 detailed information about your setup.
 There's also a ``csinfo list`` command to quickly list the available tools:
@@ -345,89 +360,16 @@ There&#39;s also a ``csinfo list`` command to quickly list the available tools:
      csinfo info    Print Gammalib / ctools setup info
+.. _sec_known_problems:
+
 Known problems
 --------------
-GammaLib unit tests fail
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Some users have reported failure of a large fraction of the GammaLib unit
-tests after after typing ``make check``. In all cases, this was related to
-not finding the ``libcfitsio`` library. To solve the issue, locate the 
-directory where the shared ``libcfitsio`` library resides and then type
-
-.. code-block:: bash
-
-  export LD_LIBRARY_PATH=/directory/to/lib:$LD_LIBRARY_PATH
-
-on Unix based systems or
-
-.. code-block:: bash
-
-  export DYLD_LIBRARY_PATH=/directory/to/lib:$DYLD_LIBRARY_PATH
-
-on Mac OS X (``/directory/to/lib`` should be replaced by the correct
-library path on your system).
-
-
-Python support
-~~~~~~~~~~~~~~
-
-ctools comes with Python wrappers so that all classes can be directly 
-used from Python. To compile-in Python support, ctools needs the 
-``Python.h`` header file, which on many distributions is not installed
-by default. To make ``Python.h`` available, install the Python developer
-package in your distribution. Otherwise you will not be able to use ctools
-from Python.
-
-GammaLib and ctools release bundles come with Python wrapper files, but 
-these wrapper files will be deleted once you type ``make clean``. Wrapper
-files will be built automatically when needed, but this required
-`swig <http://www.swig.org/>`_ installed on your system. In that case,
-please make sure that you swig version 2.0.4 or newer.
-
-
-Mac OS X
-~~~~~~~~
-
-The Python development package is not installed by default on Mac OS X,
-and consequently, the ``Python.h`` header file is missing that is needed
-to compile in the Python bindings. The configure script recognises this
-fact and adjust the build procedure accordingly, but you will not be able
-to use ctools as a Python module. So better install the Python development
-package before installing ctools.
-
-It was also reported that adding of 
-``export MACOSX_DEPLOYMENT_TARGET=10.6`` to the ``.bashrc`` file was
-necessary one some Mac OS X 10.6 installations to make ctools compile.
-
-
-Solaris
-~~~~~~~
-
-Although ctools builds on Solaris using the Sun compiler, there are problems
-with global symbols in shared libraries and exception catching, which prevents
-the FITS interface to work correctly. ctools has however been built and tested
-successfully using the GNU compiler, and this is the only build method that
-is currently supported. Problems have also been encountered when compiling
-cfitsio versions more recent than 3.250. The problems have been reported to
-the cfitsio developer team, and are likely to be solved in the future. For 
-the time being, it is recommended to use cfitsio version 3.250 on Solaris.
-
-
-OpenSolaris
-~~~~~~~~~~~
-
-On OpenSolaris, the same problems concerning the SunStudio compiler occur
-as for Solaris, and also here, the GNU compiler is the recommended tool to
-build ctools. Also here, cfitsio version 3.250 is the recommended library as
-more recent version feature relocation problems. ctools has been tested 
-using gcc 4.3.2 on OpenSolaris 2009.06. Make sure to create the symbolic 
-links
-
-.. code-block:: csh
-
-  $ ln -s /usr/bin/gcc4.3.2 /usr/bin/gcc
-  $ ln -s /usr/bin/g++4.3.2 /usr/bin/g++
-
-which are not there by default to avoid excess warnings during compilation.
 \ No newline at end of file
+In case you encounter problem, please check the list of known
+:ref:`installation_issues`.
+If you encounter problems during the GammaLib installation, please
+check the list of
+`known GammaLib issues <http://cta.irap.omp.eu/gammalib/doc/html/issues.html>`_.
+If you cannot solve your problems, please create an issue on the
+ctools tracker
+`here <https://cta-redmine.irap.omp.eu/projects/ctools>`_.
+.. _sec_introduction:
+
 Introduction
 ============
-ctools is a highly modular collection of utilities for processing
-and analysing CTA reconstructed event data in the FITS (Flexible
-Image Transport System) data format. Each utility presents itself
-as a FTOOL (see http://heasarc.gsfc.nasa.gov/ftools/) and performs
-a single simple task such as event binning, event selection or model
-fitting. Individual utilities can easily be chained together in
-scripts to achieve more complex operations, either by using the command
-line interface, or by using the Python scripting language. The ctools
-user interface is controlled by standard IRAF-style parameter files.
-Software is written in C++ to provide portability across most computer
-systems. The data format dependencies between hardware platforms are
-isolated through the cfitsio library package from HEASARC 
-(http://heasarc.gsfc.nasa.gov/fitsio/).
-
-This User Manual describes the use of the ctools software.
 \ No newline at end of file
+ctools is a software package developed for the scientific analysis of 
+Cherenkov Telescope Array (CTA) data or any other Imaging Air Cherenkov 
+Telescope. ctools comprises a set of ftools-like binary executables, 
+written in C++, with a command-line interface allowing for interactive
+step-wise data analysis. To start a ctool from the command line, simply 
+type the name of the ctool:
+
+.. code-block:: bash
+
+  $ ctobssim
+  RA of pointing (degrees) (0-360) [83.63] 
+
+The ctool will query all user parameters and execute. User parameters can
+also be specified as arguments separated by a whitespace to the ctool:
+
+.. code-block:: bash
+
+  $ ctobssim ra=83.63 dec=22.01 rad=5.0 tmin=0 tmax=1800 emin=0.1 emax=100.0 caldb=prod2 irf=South_50h inmodel=$CTOOLS/share/models/crab.xml outevents=events.fits
+
+ctools includes also a Python module that declares every ctool as a
+Python class. The following example illustrates the usage:
+
+.. code-block:: bash
+
+  $ python
+  >>> import ctools
+  >>> sim = ctools.ctobssim()
+  >>> sim["ra"]  = 83.63
+  >>> sim["dec"] = 22.01
+  >>> sim.execute()
+  Radius of FOV (degrees) (0-180) [5.0]
+
+ctools comprise also cscripts, which are Python scripts that have the same 
+user interface as the ctools binaries. cscripts can be started from the 
+command line or used as Python classes, as illustrated below:
+
+.. code-block:: bash
+
+  $ python
+  >>> import cscripts
+  >>> pull = cscripts.cspull()
+
+In this User Manual you will now learn how to install and use the ctools
+package.
+If you encounter any problems, please read the :ref:`issues` section.
+If you're desperate, you may need :ref:`help`.
+And you should read the :ref:`develop` section if you would like to 
+contribute to the ctools developments.