Andreas Specovius / ctools

Commit 259ecb2c0a3817c5fea9b0f0f8a26a8070a11e8f

Authored by Jürgen Knödlseder
1 parent f837d81c

Update documentation for release 1.3

Inline Side-by-side
Showing 12 changed files with 235 additions and 41 deletions
Makefile.am
  View file @259ecb2
... ... @@ -58,6 +58,8 @@ uninstall-local: $(DOXYGEN_UNINSTALL_DATA_TARGETS)
58 58 # Files to be removed in build directory
59 59 clean-local:
60 60 rm -rf $(top_builddir)/.DS_Store
  61 + rm -rf $(top_builddir)/doc/html
  62 + rm -rf $(top_builddir)/doc/man
61 63  
62 64 #
63 65 # Additional rules
... ...
doc/source/develop/profiling/index.rst
  View file @259ecb2
... ... @@ -7,7 +7,7 @@ Profiling of the ctools can be done by various tools. Here we describe how ctool
7 7 profiled using valgrind.
8 8  
9 9 .. toctree::
10   - :maxdepth: 2
  10 + :maxdepth: 1
11 11  
12 12 install
13 13 usage
... ...
doc/source/develop/releasing/create.rst
  View file @259ecb2
... ... @@ -58,7 +58,7 @@ questions about the changes you did.
58 58 Have interfaces changed since last release? (y/n): y
59 59 Libtool version changed to '3:0:0'
60 60  
61   -Then you have to commit all changes and push then into the git repository.
  61 +Then you have to commit all changes and push them into the git repository.
62 62  
63 63 .. code-block:: bash
64 64  
... ...
doc/source/develop/releasing/devel.rst 0 → 100644
  View file @259ecb2
  1 +.. _dev_releasing_merge:
  2 +
  3 +Incrementing the development version
  4 +====================================
  5 +
  6 +As last step you have to increment the version number to the next
  7 +development release number. Before doing that you should make sure that you
  8 +have merged the released software version into the devel branch. You do this
  9 +by typing:
  10 +
  11 +.. code-block:: bash
  12 +
  13 + $ git checkout devel
  14 + $ git merge master
  15 +
  16 +Now you launch again the release manager to update the version number:
  17 +
  18 +.. code-block:: bash
  19 +
  20 + $ dev/release.py
  21 + ctools release manager
  22 + ======================
  23 +
  24 + [1] Make a new release
  25 + [2] Set the package version in current branch
  26 + [3] Set the libtool version in current branch
  27 + [4] Commit changes in current branch
  28 + [5] Create tarball from current branch
  29 + [6] Check tarball
  30 + [q] Quit
  31 + Enter your choice:
  32 +
  33 +Select ``2`` and enter the new version number:
  34 +
  35 +.. code-block:: bash
  36 +
  37 + Current ctools version is '1.2.0'. Please enter new ctools version: 1.3.0.dev1
  38 + Change version to '1.3.0.dev1'? (y/n): y
  39 + ctools version changed to '1.3.0.dev1'
  40 +
  41 + [1] Make a new release
  42 + [2] Set the package version in current branch
  43 + [3] Set the libtool version in current branch
  44 + [4] Commit changes in current branch
  45 + [5] Create tarball from current branch
  46 + [6] Check tarball
  47 + [q] Quit
  48 + Enter your choice:
  49 +
  50 +Now commit the changes by chosing ``4``:
  51 +
  52 +.. code-block:: bash
  53 +
  54 + The following files have been changed:
  55 + M README.md
  56 + M configure.ac
  57 + M ctools.pc.in
  58 + M doc/Doxyfile
  59 + M doc/source/conf.py
  60 + M sonar-project.properties
  61 + Commit all changes? (y/n): y
  62 + Please enter a commit message: Update to release version 1.3.0.dev1
  63 + [devel d38bbdc] Update to release version 1.3.0.dev1
  64 + 6 files changed, 8 insertions(+), 8 deletions(-)
  65 +
  66 + [1] Make a new release
  67 + [2] Set the package version in current branch
  68 + [3] Set the libtool version in current branch
  69 + [4] Commit changes in current branch
  70 + [5] Create tarball from current branch
  71 + [6] Check tarball
  72 + [q] Quit
  73 + Enter your choice:
  74 +
  75 +Quit the release manager by chosing ``q`` and push the modifications into
  76 +the repository:
  77 +
  78 +.. code-block:: bash
  79 +
  80 + $ git push origin
  81 +
  82 +Congratulations, you are done!
... ...
doc/source/develop/releasing/index.rst
  View file @259ecb2
... ... @@ -6,9 +6,18 @@ Creating a new ctools release
6 6 To create a new ctools release you have to go through the following steps:
7 7  
8 8 .. toctree::
9   - :maxdepth: 2
  9 + :maxdepth: 1
10 10  
11 11 create
12 12 pipeline
13 13 tag
14 14 merge
  15 + devel
  16 +
  17 +.. important::
  18 + Before releasing the software please make sure that you have
  19 +
  20 + * added unit tests for all new code
  21 + * added a page about the software changes to the release history
  22 + * updated the User documentation if necessary
  23 +
... ...
doc/source/develop/releasing/merge.rst
  View file @259ecb2
... ... @@ -2,3 +2,13 @@
2 2  
3 3 Merge release branch into master branch
4 4 =======================================
  5 +
  6 +The master branch should always contain the last release of the ctools
  7 +package. You therefore have to merge now the release branch into the master
  8 +branch by typing:
  9 +
  10 +.. code-block:: bash
  11 +
  12 + $ git checkout master
  13 + $ git merge release
  14 + $ git push origin
... ...
doc/source/develop/releasing/pipeline.png 0 → 100644
View file @259ecb2

475 KB
doc/source/develop/releasing/pipeline.rst
  View file @259ecb2
... ... @@ -3,4 +3,16 @@
3 3 Launch the release pipeline
4 4 ===========================
5 5  
  6 +Now you should connect to
  7 +`Jenkins <https://cta-jenkins.irap.omp.eu>`_
  8 +and launch the ctools release pipeline by clicking on the dedicated
  9 +button:
6 10  
  11 +.. figure:: pipeline.png
  12 + :width: 600px
  13 + :align: center
  14 +
  15 + *ctools release pipeline*
  16 +
  17 +In case that any errors occur during running the release pipeline, you should
  18 +fix the errors and rerun the pipeline until it terminates with success.
... ...
doc/source/develop/releasing/tag.rst
  View file @259ecb2
... ... @@ -2,3 +2,17 @@
2 2  
3 3 Tag the release
4 4 ===============
  5 +
  6 +Now you should tag the software with the current release number. You do this
  7 +by typing:
  8 +
  9 +.. code-block:: bash
  10 +
  11 + $ git tag -a ctools-1.2.0 -m "ctools release 1.2.0"
  12 +
  13 +You push the tag to the repository by typing:
  14 +
  15 +.. code-block:: bash
  16 +
  17 + $ git push origin --tags
  18 +
... ...
doc/source/users/release_history/1.3.rst 0 → 100644
  View file @259ecb2
  1 +.. _1.3:
  2 +
  3 +ctools 1.3 release (7 June 2017)
  4 +================================
  5 +
  6 +Overview
  7 +--------
  8 +
  9 +ctools 1.3 is a major release that adds significant functionality.
  10 +
  11 +In particular, this release provides:
  12 +
  13 +* :ref:`ctphase` for phasing events
  14 +* :ref:`ctprob` for event probabilities
  15 +* :ref:`csebins` for an automatic computation of an optimal energy binning
  16 +
  17 +Bug fixes
  18 +---------
  19 +
  20 +* [`2121 <https://cta-redmine.irap.omp.eu/issues/2121>`_] -
  21 + Correct covariance matrix computation in ctbutterfly
  22 +* [`2114 <https://cta-redmine.irap.omp.eu/issues/2114>`_] -
  23 + Add missing ``*.i`` SWIG file into release tarball
  24 +* Use correct ROOT histograms in :ref:`csroot2caldb`
  25 +* [`1987 <https://cta-redmine.irap.omp.eu/issues/1987>`_] -
  26 + Copy cscripts into bin directory instead of creating a symbolic links
  27 +* [`1983 <https://cta-redmine.irap.omp.eu/issues/1983>`_] -
  28 + Raise exception instead of exiting with return code in Python tests
  29 +* Support of map cubes lying outside RoI in ctobssim
  30 +* [`1975 <https://cta-redmine.irap.omp.eu/issues/1975>`_] -
  31 + Consider RoI in :ref:`ctskymap` and use numerical integration for IRF
  32 +* [`1370 <https://cta-redmine.irap.omp.eu/issues/1370>`_] -
  33 + Set local language to english
  34 +
  35 +
  36 +Improvements
  37 +------------
  38 +
  39 +* [`1996 <https://cta-redmine.irap.omp.eu/issues/1996>`_] -
  40 + Add ``phase`` parameter to :ref:`ctselect`
  41 +* [`1989 <https://cta-redmine.irap.omp.eu/issues/1989>`_] -
  42 + Implement regression scheme in :ref:`cssens` and remove ``num_avg`` parameter
  43 +* [`1985 <https://cta-redmine.irap.omp.eu/issues/1985>`_] -
  44 + If code originates from Git, always compile the Python bindings
  45 +* [`1978 <https://cta-redmine.irap.omp.eu/issues/1978>`_] -
  46 + Support energy boundary FITS file in ctmapcube
  47 +* [`1863 <https://cta-redmine.irap.omp.eu/issues/1863>`_] -
  48 + :ref:`ctlike` stores covariance matrix in either CSV or FITS format
  49 +* [`1862 <https://cta-redmine.irap.omp.eu/issues/1862>`_] -
  50 + Implement Gaussian error propagation in :ref:`ctbutterfly`
  51 +* [`1483 <https://cta-redmine.irap.omp.eu/issues/1483>`_] -
  52 + :ref:`ctobssim` adds Monte Carlo identifiers to simulated events
  53 +* Enhance logfile output of :ref:`csroot2caldb` script
  54 +* Set default ``deadc`` value to 0.98 (CTA has <2% deadtime)
  55 +
  56 +New features
  57 +------------
  58 +
  59 +* [`1991 <https://cta-redmine.irap.omp.eu/issues/1991>`_] -
  60 + Add :ref:`ctprob` tool
  61 +* [`1982 <https://cta-redmine.irap.omp.eu/issues/1982>`_] -
  62 + Add :ref:`ctphase` tool
  63 +* [`1976 <https://cta-redmine.irap.omp.eu/issues/1976>`_] -
  64 + Add :ref:`csebins` script
... ...
doc/source/users/release_history/index.rst
  View file @259ecb2
... ... @@ -8,6 +8,7 @@ Major releases:
8 8 .. toctree::
9 9 :maxdepth: 1
10 10  
  11 + ctools 1.3 <1.3>
11 12 ctools 1.2 <1.2>
12 13 ctools 1.1 <1.1>
13 14 ctools 1.0 <1.0>
... ...
doc/source/users/tutorials/1dc/first_fitting.rst
  View file @259ecb2
... ... @@ -48,44 +48,44 @@ converged properly, as illustrated in the example below:
48 48  
49 49 .. code-block:: bash
50 50  
51   - 2017-06-01T10:55:30: +=================================+
52   - 2017-06-01T10:55:30: | Maximum likelihood optimisation |
53   - 2017-06-01T10:55:30: +=================================+
54   - 2017-06-01T10:55:44: >Iteration 0: -logL=242348.647, Lambda=1.0e-03
55   - 2017-06-01T10:55:58: >Iteration 1: -logL=222180.556, Lambda=1.0e-03, delta=20168.091, step=1.0e+00, max(|grad|)=50061.839794 [Index:13]
56   - 2017-06-01T10:56:11: >Iteration 2: -logL=218667.504, Lambda=1.0e-04, delta=3513.051, step=1.0e+00, max(|grad|)=-11303.423190 [RA:6]
57   - 2017-06-01T10:56:24: >Iteration 3: -logL=217668.566, Lambda=1.0e-05, delta=998.938, step=1.0e+00, max(|grad|)=-9596.810651 [RA:6]
58   - 2017-06-01T10:56:38: >Iteration 4: -logL=217500.656, Lambda=1.0e-06, delta=167.910, step=1.0e+00, max(|grad|)=-6620.600218 [RA:6]
59   - 2017-06-01T10:56:52: >Iteration 5: -logL=217460.888, Lambda=1.0e-07, delta=39.769, step=1.0e+00, max(|grad|)=-4306.170420 [RA:6]
60   - 2017-06-01T10:57:05: >Iteration 6: -logL=217441.548, Lambda=1.0e-08, delta=19.339, step=1.0e+00, max(|grad|)=3170.609703 [RA:0]
61   - 2017-06-01T10:57:20: >Iteration 7: -logL=217432.039, Lambda=1.0e-09, delta=9.510, step=1.0e+00, max(|grad|)=2239.034002 [RA:0]
62   - 2017-06-01T10:57:34: >Iteration 8: -logL=217427.577, Lambda=1.0e-10, delta=4.461, step=1.0e+00, max(|grad|)=1582.498191 [RA:0]
63   - 2017-06-01T10:57:48: >Iteration 9: -logL=217425.390, Lambda=1.0e-11, delta=2.188, step=1.0e+00, max(|grad|)=1162.116922 [RA:0]
64   - 2017-06-01T10:58:03: >Iteration 10: -logL=217424.221, Lambda=1.0e-12, delta=1.169, step=1.0e+00, max(|grad|)=815.765881 [RA:0]
65   - 2017-06-01T10:58:17: >Iteration 11: -logL=217423.683, Lambda=1.0e-13, delta=0.538, step=1.0e+00, max(|grad|)=542.812704 [RA:0]
66   - 2017-06-01T10:58:31: >Iteration 12: -logL=217423.482, Lambda=1.0e-14, delta=0.200, step=1.0e+00, max(|grad|)=288.286783 [RA:0]
67   - 2017-06-01T10:58:45: >Iteration 13: -logL=217423.422, Lambda=1.0e-15, delta=0.060, step=1.0e+00, max(|grad|)=221.413071 [RA:0]
68   - 2017-06-01T10:59:00: >Iteration 14: -logL=217423.378, Lambda=1.0e-16, delta=0.044, step=1.0e+00, max(|grad|)=226.131427 [RA:0]
69   - 2017-06-01T10:59:17: >Iteration 15: -logL=217423.330, Lambda=1.0e-17, delta=0.048, step=1.0e+00, max(|grad|)=180.270743 [RA:0]
70   - 2017-06-01T10:59:32: >Iteration 16: -logL=217423.309, Lambda=1.0e-18, delta=0.020, step=1.0e+00, max(|grad|)=104.148460 [RA:0]
71   - 2017-06-01T10:59:46: >Iteration 17: -logL=217423.303, Lambda=1.0e-19, delta=0.007, step=1.0e+00, max(|grad|)=63.327107 [RA:0]
72   - 2017-06-01T11:00:00: >Iteration 18: -logL=217423.298, Lambda=1.0e-20, delta=0.004, step=1.0e+00, max(|grad|)=42.005734 [RA:0]
73   - 2017-06-01T11:00:14:
74   - 2017-06-01T11:00:14: +=========================================+
75   - 2017-06-01T11:00:14: | Maximum likelihood optimisation results |
76   - 2017-06-01T11:00:14: +=========================================+
77   - 2017-06-01T11:00:14: === GOptimizerLM ===
78   - 2017-06-01T11:00:14: Optimized function value ..: 217423.298
79   - 2017-06-01T11:00:14: Absolute precision ........: 0.005
80   - 2017-06-01T11:00:14: Acceptable value decrease .: 2
81   - 2017-06-01T11:00:14: Optimization status .......: converged
82   - 2017-06-01T11:00:14: Number of parameters ......: 16
83   - 2017-06-01T11:00:14: Number of free parameters .: 10
84   - 2017-06-01T11:00:14: Number of iterations ......: 18
85   - 2017-06-01T11:00:14: Lambda ....................: 1e-21
86   - 2017-06-01T11:00:14: Maximum log likelihood ....: -217423.298
87   - 2017-06-01T11:00:14: Observed events (Nobs) ...: 2204717.000
88   - 2017-06-01T11:00:14: Predicted events (Npred) ..: 2204716.997 (Nobs - Npred = 0.00283915968611836)
  51 + 2017-06-06T23:54:05: +=================================+
  52 + 2017-06-06T23:54:05: | Maximum likelihood optimisation |
  53 + 2017-06-06T23:54:05: +=================================+
  54 + 2017-06-06T23:54:18: >Iteration 0: -logL=242350.348, Lambda=1.0e-03
  55 + 2017-06-06T23:54:31: >Iteration 1: -logL=222183.040, Lambda=1.0e-03, delta=20167.308, step=1.0e+00, max(|grad|)=50064.145481 [Index:13]
  56 + 2017-06-06T23:54:44: >Iteration 2: -logL=218671.485, Lambda=1.0e-04, delta=3511.555, step=1.0e+00, max(|grad|)=-11302.678938 [RA:6]
  57 + 2017-06-06T23:54:57: >Iteration 3: -logL=217673.527, Lambda=1.0e-05, delta=997.958, step=1.0e+00, max(|grad|)=-9593.644236 [RA:6]
  58 + 2017-06-06T23:55:10: >Iteration 4: -logL=217505.751, Lambda=1.0e-06, delta=167.776, step=1.0e+00, max(|grad|)=-6625.379605 [RA:6]
  59 + 2017-06-06T23:55:23: >Iteration 5: -logL=217465.972, Lambda=1.0e-07, delta=39.779, step=1.0e+00, max(|grad|)=-4315.893743 [RA:6]
  60 + 2017-06-06T23:55:37: >Iteration 6: -logL=217446.648, Lambda=1.0e-08, delta=19.324, step=1.0e+00, max(|grad|)=3158.486974 [RA:0]
  61 + 2017-06-06T23:55:50: >Iteration 7: -logL=217437.175, Lambda=1.0e-09, delta=9.473, step=1.0e+00, max(|grad|)=2234.551298 [RA:0]
  62 + 2017-06-06T23:56:03: >Iteration 8: -logL=217432.730, Lambda=1.0e-10, delta=4.445, step=1.0e+00, max(|grad|)=1578.966812 [RA:0]
  63 + 2017-06-06T23:56:17: >Iteration 9: -logL=217430.542, Lambda=1.0e-11, delta=2.187, step=1.0e+00, max(|grad|)=1164.679821 [RA:0]
  64 + 2017-06-06T23:56:31: >Iteration 10: -logL=217429.374, Lambda=1.0e-12, delta=1.168, step=1.0e+00, max(|grad|)=816.726019 [RA:0]
  65 + 2017-06-06T23:56:44: >Iteration 11: -logL=217428.835, Lambda=1.0e-13, delta=0.539, step=1.0e+00, max(|grad|)=543.038385 [RA:0]
  66 + 2017-06-06T23:56:58: >Iteration 12: -logL=217428.635, Lambda=1.0e-14, delta=0.201, step=1.0e+00, max(|grad|)=290.465021 [RA:0]
  67 + 2017-06-06T23:57:12: >Iteration 13: -logL=217428.574, Lambda=1.0e-15, delta=0.061, step=1.0e+00, max(|grad|)=223.932827 [RA:0]
  68 + 2017-06-06T23:57:25: >Iteration 14: -logL=217428.528, Lambda=1.0e-16, delta=0.046, step=1.0e+00, max(|grad|)=228.672746 [RA:0]
  69 + 2017-06-06T23:57:38: >Iteration 15: -logL=217428.480, Lambda=1.0e-17, delta=0.049, step=1.0e+00, max(|grad|)=179.805198 [RA:0]
  70 + 2017-06-06T23:57:52: >Iteration 16: -logL=217428.459, Lambda=1.0e-18, delta=0.021, step=1.0e+00, max(|grad|)=103.278218 [RA:0]
  71 + 2017-06-06T23:58:05: >Iteration 17: -logL=217428.452, Lambda=1.0e-19, delta=0.006, step=1.0e+00, max(|grad|)=62.896707 [RA:0]
  72 + 2017-06-06T23:58:18: >Iteration 18: -logL=217428.448, Lambda=1.0e-20, delta=0.004, step=1.0e+00, max(|grad|)=41.622300 [RA:0]
  73 + 2017-06-06T23:58:31:
  74 + 2017-06-06T23:58:31: +=========================================+
  75 + 2017-06-06T23:58:31: | Maximum likelihood optimisation results |
  76 + 2017-06-06T23:58:31: +=========================================+
  77 + 2017-06-06T23:58:31: === GOptimizerLM ===
  78 + 2017-06-06T23:58:31: Optimized function value ..: 217428.448
  79 + 2017-06-06T23:58:31: Absolute precision ........: 0.005
  80 + 2017-06-06T23:58:31: Acceptable value decrease .: 2
  81 + 2017-06-06T23:58:31: Optimization status .......: converged
  82 + 2017-06-06T23:58:31: Number of parameters ......: 16
  83 + 2017-06-06T23:58:31: Number of free parameters .: 10
  84 + 2017-06-06T23:58:31: Number of iterations ......: 18
  85 + 2017-06-06T23:58:31: Lambda ....................: 1e-21
  86 + 2017-06-06T23:58:31: Maximum log likelihood ....: -217428.448
  87 + 2017-06-06T23:58:31: Observed events (Nobs) ...: 2204717.000
  88 + 2017-06-06T23:58:31: Predicted events (Npred) ..: 2204716.997 (Nobs - Npred = 0.00284357415512204)
89 89  
90 90 You may also convert the fitted model positions into a `ds9 <http://ds9.si.edu>`_
91 91 region file using the :ref:`csmodelinfo` script so that you can overlay the
... ...