From c18829b41a005d04115d5d63a11d7e9f27867b37 Mon Sep 17 00:00:00 2001 From: Jürgen Knödlseder Date: Fri, 3 Jul 2020 15:02:06 +0200 Subject: [PATCH] Prepare documentation for release --- doc/source/_templates/index.html | 2 +- doc/source/about.rst | 9 +++++---- doc/source/admin/install_source.rst | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------------------------------------------ doc/source/users/reference_manual/csspec.rst | 2 +- doc/source/users/reference_manual/csviscube.rst | 1 + doc/source/users/tutorials/1dc/getting_data.rst | 87 ++++++--------------------------------------------------------------------------------- 6 files changed, 70 insertions(+), 141 deletions(-) diff --git a/doc/source/_templates/index.html b/doc/source/_templates/index.html index e94a241..5c8cb62 100755 --- a/doc/source/_templates/index.html +++ b/doc/source/_templates/index.html @@ -19,7 +19,7 @@ Besides CTA, GammaLib supports also the analysis of Fermi/LAT and COMPTEL data, and extensions to support further gamma-ray instruments are planned. An interface to virtual observatory ressources does also exist. By making use of the GammaLib multi-instrument capabilities, ctools supports the joint analysis -of CTA, H.E.S.S., MAGIC, VERITAS, Fermi/LAT and COMPTEL data. +of CTA, H.E.S.S., MAGIC, VERITAS, Fermi/LAT, INTEGRAL/SPI and COMPTEL data. {%endtrans%}

{%trans%} ctools are developed by a team of enthousiastic gamma-ray diff --git a/doc/source/about.rst b/doc/source/about.rst index d9488e1..dde2b0a 100755 --- a/doc/source/about.rst +++ b/doc/source/about.rst @@ -15,12 +15,13 @@ Creation of shell or Python scripts and pipelines is supported as well. ctools are based on GammaLib, a versatile toolbox for the scientific analysis of astronomical gamma-ray data. -Besides CTA, GammaLib supports also the analysis of Fermi/LAT and COMPTEL -data, and extensions to support further gamma-ray instruments are planned. +Besides CTA, GammaLib supports also the analysis of Fermi/LAT, INTEGRAL/SPI +and COMPTEL data, and extensions to support further gamma-ray instruments are +planned. An interface to virtual observatory ressources does also exist. By making use of the GammaLib multi-instrument capabilities, ctools -supports the joint analysis of CTA, H.E.S.S., MAGIC, VERITAS, Fermi/LAT and -COMPTEL data. +supports the joint analysis of CTA, H.E.S.S., MAGIC, VERITAS, Fermi/LAT, +INTEGRAL/SPI and COMPTEL data. ctools are developed by a team of enthousiastic gamma-ray astronomers with support from engineers. We regularily organise diff --git a/doc/source/admin/install_source.rst b/doc/source/admin/install_source.rst index b35f262..cde6c81 100755 --- a/doc/source/admin/install_source.rst +++ b/doc/source/admin/install_source.rst @@ -17,7 +17,7 @@ The procedure for building and installing ctools is modeled on GNU software distributions. You will need the following to build the software: -- About 25 MB of free disk space. +- About 50 MB of free disk space. - An ANSI C++ compiler. ctools builds well using GNU g++ or clang. @@ -42,7 +42,7 @@ section and continue with the :ref:`sec_building_ctools` section. You will need the following to build the GammaLib: -- About 200 MB of free disk space. +- About 300 MB of free disk space. - An ANSI C++ compiler. We recommend building GammaLib with the GNU g++ or the clang compilers. @@ -66,7 +66,7 @@ in an appropriate location (for example ``$HOME/builds``), and type .. code-block:: bash - $ tar xvfz gammalib-1.2.0.tar.gz + $ tar xvfz gammalib-1.7.0.tar.gz (the ``$`` symbol indicates the console prompt and is not part of the command that you should type in). @@ -76,25 +76,25 @@ typing .. code-block:: bash - $ cd gammalib-1.2.0 - $ ./configure - $ make - $ make check - $ make install + $ cd gammalib-1.7.0 + $ ./configure + $ make + $ make check + $ make install The last step may require system administator privileges. In this case, use .. code-block:: bash - $ sudo make install + $ sudo make install If you do not have system administrator privileges, change the install directory by typing for example .. code-block:: bash - $ ./configure --prefix=$HOME/gamma + $ ./configure --prefix=$HOME/gamma which then installs GammaLib in the ``gamma`` folder of your home directory. @@ -114,16 +114,16 @@ machine: .. code-block:: bash - export GAMMALIB=/usr/local/gamma - source $GAMMALIB/bin/gammalib-init.sh + export GAMMALIB=/usr/local/gamma + source $GAMMALIB/bin/gammalib-init.sh If you use C shell or a variant then add the following to your ``$HOME/.cshrc`` or ``$HOME/.tcshrc`` script: .. code-block:: csh - setenv GAMMALIB /usr/local/gamma - source $GAMMALIB/bin/gammalib-init.csh + setenv GAMMALIB /usr/local/gamma + source $GAMMALIB/bin/gammalib-init.csh .. _sec_building_ctools: @@ -136,7 +136,7 @@ an appropriate location (for example ``$HOME/builds``), and type .. code-block:: bash - $ tar xvfz ctools-1.2.0.tar.gz + $ tar xvfz ctools-1.7.0.tar.gz (the ``$`` symbol indicates the console prompt and is not part of the command that you should type in). @@ -145,9 +145,9 @@ Step in the directory and build the ctools by typing .. code-block:: bash - $ cd ctools-1.2.0 - $ ./configure - $ make + $ cd ctools-1.7.0 + $ ./configure + $ make at the operating system prompt. The ``./configure`` command customizes the Makefiles for the particular system, the ``make`` command compiles @@ -159,7 +159,7 @@ You can get the full list of configuration options by typing .. code-block:: bash - $ ./configure --help + $ ./configure --help Testing ctools @@ -170,7 +170,7 @@ make sure that ctools have been built correctly. For this, type .. code-block:: bash - $ make check + $ make check If you have automake version 1.13 or newer installed, you should see the following output at the end of the unit testing: @@ -181,7 +181,7 @@ following output at the end of the unit testing: PASS: test_python_cscripts.sh PASS: test_examples.py ============================================================================ - Testsuite summary for ctools 1.2.0 + Testsuite summary for ctools 1.7.0 ============================================================================ # TOTAL: 3 # PASS: 3 @@ -199,34 +199,36 @@ For older automake version, you should see *********************** * ctools unit testing * *********************** - Test ctobssim on command line: ..... ok - Test ctobssim from Python: ................................................. ok - Test ctselect on command line: ....... ok - Test ctselect from Python: ..... ok - Test ctbin on command line: ..... ok - Test ctbin from Python: ............................................. ok + Test ctobssim on command line: ...... ok + Test ctobssim from Python: ........................................... ok + Test ctselect on command line: ........ ok + Test ctselect from Python: .............................................................. ok + Test ctphase on command line: ...... ok + Test ctphase from Python: .............. ok ... PASS test_python_ctools.sh ************************* * cscripts unit testing * ************************* - Test cscaldb on command line: .. ok - Test cscaldb from Python: . ok - Test cslightcrv on command line: ............... ok - Test cslightcrv from Python: ................................................. ok - Test csmodelinfo on command line: ..... ok - Test csmodelinfo from Python: ..... ok + Test cscript base class: ............................................................................................................................... ok + Test ctobservation base class: ............................................. ok + Test ctlikelihood base class: ... ok + Test csbkgmodel on command line: ..... ok + Test csbkgmodel from Python: ........... ok + Test csbkgmodel pickeling: ...... ok ... PASS test_python_cscripts.sh ******************** * Examples testing * ******************** - Test generate_prod3_irfs.py: .. ok Test make_pointings.py: ....... ok - Test make_spectrum.py: .. ok - Test make_ts_distributions.py: .. ok + Test show_butterfly.py: .. ok + Test show_irf.py: .. ok + Test show_lightcurve.py: .. ok + Test show_model.py: ... ok + Test show_obs.py: ... ok ... PASS test_examples.py ================== @@ -239,9 +241,9 @@ versions, but there it is written in log files that you can find in the .. code-block:: bash - test_python_ctools.sh.log - test_python_cscripts.sh.log - test_examples.py.log + test_python_ctools.sh.log + test_python_cscripts.sh.log + test_examples.py.log 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 @@ -256,7 +258,7 @@ Now you are ready to install the ctools by typing .. code-block:: bash - $ make install + $ make install If the destination directory is owned by ``root`` (which is normally the case when using the default), administrator privileges are needed for @@ -264,7 +266,7 @@ installation. In this case, type .. code-block:: bash - $ sudo make install + $ sudo make install By default, the install directory is set to ``/usr/local/gamma``. To change the install directory (for example in case that you do not @@ -273,7 +275,7 @@ can be given, for example: .. code-block:: bash - $ ./configure --prefix=$HOME/gamma + $ ./configure --prefix=$HOME/gamma Setting up the ctools environment @@ -288,16 +290,16 @@ on a Linux machine: .. code-block:: bash - export CTOOLS=/usr/local/gamma - source $CTOOLS/bin/ctools-init.sh + export CTOOLS=/usr/local/gamma + source $CTOOLS/bin/ctools-init.sh If you use C shell or a variant then add the following to your ``$HOME/.cshrc`` or ``$HOME/.tcshrc`` script: .. code-block:: csh - setenv CTOOLS /usr/local/gamma - source $CTOOLS/bin/ctools-init.csh + setenv CTOOLS /usr/local/gamma + source $CTOOLS/bin/ctools-init.csh Checking your setup @@ -309,17 +311,17 @@ As a quick check that your setup is okay you can run ``csinfo check``: .. code-block:: bash - $ csinfo check + $ csinfo check - Gammalib / ctools setup check: + Gammalib / ctools setup check: - GAMMALIB environment variable ... ok - CTOOLS environment variable ... ok - gammalib Python import .......... ok - ctools Python import .......... ok - cscripts Python import .......... ok + GAMMALIB environment variable ... ok + CTOOLS environment variable ... ok + gammalib Python import .......... ok + ctools Python import .......... ok + cscripts Python import .......... ok - ===> Your Gammalib / ctools setup is OK. + ===> Your Gammalib / ctools setup is OK. If the setup is not okay, run the ``csinfo info`` command to print detailed information about your setup. There's also a ``csinfo list`` diff --git a/doc/source/users/reference_manual/csspec.rst b/doc/source/users/reference_manual/csspec.rst index f094ef0..2557e8d 100755 --- a/doc/source/users/reference_manual/csspec.rst +++ b/doc/source/users/reference_manual/csspec.rst @@ -158,7 +158,7 @@ General parameters ``(dll_sigmax = 5.0) [real]`` Maximum number of standard deviations for log-like profiles. The final number of bins generated in the likelihood profile will be: - 2*(dll_sigmax/dll_sigstep) + 1 + ``2*(dll_sigmax/dll_sigstep) + 1`` ensuring that the central flux will always be evaluated. ``(dll_freenodes = no) [boolean]`` diff --git a/doc/source/users/reference_manual/csviscube.rst b/doc/source/users/reference_manual/csviscube.rst index 83565bd..303a46f 100755 --- a/doc/source/users/reference_manual/csviscube.rst +++ b/doc/source/users/reference_manual/csviscube.rst @@ -15,6 +15,7 @@ that a given position on the sky is observable under a given zenith angle by an IACT array during a given time period. For the moment, the script takes into account: + - a Sun constraint, specified as a minimum zenith angle of the Sun (hidden parameter ``sunzenith``). If the Sun is higher in the sky than this zenith angle the corresponding times are excluded diff --git a/doc/source/users/tutorials/1dc/getting_data.rst b/doc/source/users/tutorials/1dc/getting_data.rst index eb210ab..050a4e3 100755 --- a/doc/source/users/tutorials/1dc/getting_data.rst +++ b/doc/source/users/tutorials/1dc/getting_data.rst @@ -3,89 +3,14 @@ Getting the data ================ -The +The data for the :ref:`first CTA Data Challenge ` -data are available on the -`CTA ownCloud server `_. -Only CTA Consortium members are entitled to access the data. -You need your usual CTA credentials to download the data. +are only available to members of the CTA Consortium. +Instructions for CTA Consortium of how to download the data can be found +`here `_ +(access to the instructions are restricted). -The release contains simulated data for the Galactic Plane Survey, the -Galactic Centre Survey, the Extragalactic Survey and the AGN monitoring program, -:ref:`instrument response functions (IRFs) `, and the -:ref:`model definition files ` -that were used for the simulation. - -The data were split into the separate files that can be downloaded -by clicking on the following links: - -* `Galactic Plane Survey `_ (8.3 GB) -* `Galactic Centre Survey `_ (4.4 GB) -* `Extragalactic Survey `_ (2.5 GB) -* `AGN monitoring program `_ (4.7 GB) -* `Instrument Response Functions `_ (1.2 MB) -* `Sky and background models `_ (0.9 GB) - -You can also download the files using the ``wget`` tool from the command -line by typing: - -.. code-block:: bash - - $ wget https://owncloud.cta-observatory.org/remote.php/webdav/1dc/gps.tar.gz --user= --ask-password - $ wget https://owncloud.cta-observatory.org/remote.php/webdav/1dc/gc.tar.gz --user= --ask-password - $ wget https://owncloud.cta-observatory.org/remote.php/webdav/1dc/egal.tar.gz --user= --ask-password - $ wget https://owncloud.cta-observatory.org/remote.php/webdav/1dc/agn.wobble.tar.gz --user= --ask-password - $ wget https://owncloud.cta-observatory.org/remote.php/webdav/1dc/caldb.tar.gz --user= --ask-password - $ wget https://owncloud.cta-observatory.org/remote.php/webdav/1dc/models.tar.gz --user= --ask-password - -.. warning:: - ```` needs to be replaced by your CTA user name. - Don't type the ``$`` symbol. It indicates that a command should be typed - on the command line of your terminal. - -.. note:: - You may need to add the ``--no-check-certificate`` option to download the - files using ``wget``. - -.. note:: - In case you encounter the following error message - - .. code-block:: bash - - HTTP request sent, awaiting response... 401 Unauthorized - Authentication selected: Basic realm="ownCloud" - Reusing existing connection to owncloud.cta-observatory.org:443. - HTTP request sent, awaiting response... 404 Not Found - 2017-06-06 14:43:33 ERROR 404: Not Found. - - or any other problems with the download, please contact - sstober@cta-observatory.org. - -To make sure that you have the relevant files you may check the MD5 checksums -after downloading by typing for example - -.. code-block:: bash - - $ md5 gps.tar.gz - -on Mac OS X or - -.. code-block:: bash - - $ md5sum gps.tar.gz - -on Linux. Below the expected results: - -.. code-block:: bash - - gps.tar.gz c7129c71e911920f82273270c9d7c818 - gc.tar.gz 07aa46bb2d67cd64fa4685078643b043 - egal.tar.gz 4ea5f2ff8312b700dcc133a89d9fd096 - agn.wobble.tar.gz df8fc4f9de22ac36a86023ccbfd0cf89 - caldb.tar.gz ce718128e1b2fe19c4b8dc79b688d113 - models.tar.gz 87662cf53a2988522f485cad984d8810 - -Now uncompress the files at any place by typing +Once downloaded, uncompress the files at any place by typing .. code-block:: bash -- libgit2 0.21.4