diff --git a/doc/source/download.rst b/doc/source/download.rst index 226ea21..1a8b7dd 100644 --- a/doc/source/download.rst +++ b/doc/source/download.rst @@ -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 `_. +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 `_ - `gammalib `_ - Mac OS X package + * - `0.10.0 `_ + - `0.11.0 `_ + - `ctools-0.10.0-macosx10.3.dmg `_ * - `0.9.0 `_ - `0.10.0 `_ - `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 `_ on your system to build the diff --git a/doc/source/issues.rst b/doc/source/issues.rst index 21552e8..b1643d2 100644 --- a/doc/source/issues.rst +++ b/doc/source/issues.rst @@ -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 `_. **Installation issues** - :ref:`Certificate problem when cloning from Git ` +- :ref:`Python module does not work ` - :ref:`Python unit test fails on El Capitan ` +- :ref:`Installing on Solaris ` +- :ref:`Installing on 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 ` - :ref:`Elliptical Gaussian model fit converges slowly ` +.. _installation_issues: Installation issues ^^^^^^^^^^^^^^^^^^^ @@ -38,6 +44,30 @@ 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 `_ + tool. These wrapper files are shipped with a ctools release, but if + you use the code from git you need `swig `_ + 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 `_, + but if the wrappers don't exist you need `swig `_. + If the ``Python.h`` header file does not exist then install the Python + development package. + .. _issue_elcapitan: .. topic:: Python unit test fails on El Capitan @@ -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 ^^^^^^^^^^^^^^^ diff --git a/doc/source/user_manual/getting.rst b/doc/source/user_manual/getting.rst index a44fe30..7597113 100644 --- a/doc/source/user_manual/getting.rst +++ b/doc/source/user_manual/getting.rst @@ -1,3 +1,5 @@ +.. _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 `_. +.. _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'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 `_ 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 `_. +If you cannot solve your problems, please create an issue on the +ctools tracker +`here `_. diff --git a/doc/source/user_manual/introduction.rst b/doc/source/user_manual/introduction.rst index c0874a4..cec202d 100644 --- a/doc/source/user_manual/introduction.rst +++ b/doc/source/user_manual/introduction.rst @@ -1,18 +1,53 @@ +.. _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.