parameters and par file

Luigi Tibaldo
1 parent 27ab7347
Showing 3 changed files with 51 additions and 11 deletions
doc/source/users/reference_manual/index.rst
doc/source/users/reference_manual/usage.rst
doc/source/users/user_manual/introduction.rst
@@ -4,10 +4,12 @@ Reference Manual
 ================
  
 This manual provides reference information for all ctools and csripts.
-General information on ctools usage can be found `here <usage.html>`__.
+General information on ctools usage can be found `here
+<../user_manual/introduction.html>`_. The description of user parameters in the reference
+manual is documented `here <usage.html>`__.
  
-Below you find links to the command line reference for the tools and scripts
-that are available.
+
+Below you find links to the command line reference for all available tools and scripts.
  
 ctools
 ------
-Basic ctools parameter usage
-============================
+Description of ctools parameters in the reference manual
+=====================================
+
+For a generic introduction to ctools and user parameters see `here <../user_manual/introduction.html>`__.
  
 Automatic parameters
 --------------------
@@ -36,7 +38,7 @@ Examples
  
 .. note::
  
-  To set hidden parameters at runtime, specify them explicitly at 
+  You can set hidden parameters at runtime by specifying them explicitly on 
   the command line; for example:
  
   ``ctobssim start_time=900``
@@ -5,7 +5,17 @@ Introduction
  
 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, 
+Telescope.
+
+In this User Manual you will now learn how to use the ctools package.
+If you encounter any problems, please read the :ref:`sec_help` section.
+And you should read the :ref:`sec_develop` section if you would like to
+contribute to the ctools developments.
+
+Running ctools
+---------------
+
+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:
@@ -53,7 +63,33 @@ command line or used as Python classes, as illustrated below:
   >>> import cscripts
   >>> pull = cscripts.cspull()
  
-In this User Manual you will now learn how to use the ctools package.
-If you encounter any problems, please read the :ref:`sec_help` section.
-And you should read the :ref:`sec_develop` section if you would like to
-contribute to the ctools developments.
+User parameters and parameter files
+-----------------------------
+
+Each ctool and cscript has a defined list of user parameters. You can
+find a complete description `here
+<../reference_manual/reference.html>`_.
+
+User parameters are stored in
+par files. A ctools installation comprises a set of default par files
+stored at ``$CTOOLS/syspfiles``. When you run a tool/script the latest
+parameter values will be stored in a copy of the file at
+``$HOME/pfiles`` (e.g., ``ctlike`` will save there a file called ``ctlike.par`` ).
+
+When a tool/script is executed again, it will look for a par file
+first in ``$HOME/pfiles``, and propose you to use the latest values
+stored there. If no par file is found there, it will use the default
+in ``$CTOOLS/syspfiles``.
+
+If you update your ctools installation you may get an error such as
+
+.. code-block:: bash
+		
+	*** ERROR encounterted in the execution of ctlike. Run aborted ...
+	*** ERROR in GApplicationPars::load(GFilename&,
+	std::vector<std::string>&): Invalid command line parameter
+	encountered (invalid parameter name "XX"): XX=2
+
+Remove the stale file ``ctlike.par`` from ``$HOME/pfiles`` and run
+again to solve the issue.
+