Adding more description for parameter setting

git-svn-id: http://svn.cactuscode.org/flesh/trunk@2043 17b73243-c579-4c4c-a9d2-2d5706c11dac

1 files changed, 76 insertions, 24 deletions

diff --git a/doc/UsersGuide/RunningCactus.tex b/doc/UsersGuide/RunningCactus.tex
index 6c8ec3df..05229f89 100644
--- a/doc/UsersGuide/RunningCactus.tex
+++ b/doc/UsersGuide/RunningCactus.tex
@@ -147,7 +147,11 @@ The space required for an installation depends on the arrangements and
 thorns used. The flesh on its own requires less than 5 MB.
 
 The script for checking out the flesh and thorns, {\tt GetCactus} is available 
-from the website at {\tt http://www.cactuscode.org/Download/GetCactus}. The 
+from the website at 
+
+{\tt http://www.cactuscode.org/Download/GetCactus}
+
+The 
 script takes as an argument the name of a file containing a {\it ThornList},
 that is a list of thorns with the syntax 
 {\tt
@@ -516,11 +520,9 @@ communication. It can either be implemented natively on a machine
 such as {\tt MPICH}, {\tt LAM}, {WMPI}, or {PACX}.  
 
 To compile with MPI, the configure option is
-\newline
-\newline
+
 {\tt MPI = <MPI\_TYPE>}
-\newline
-\newline
+
 where {\tt <MPI\_TYPE>} can take the values (entries followed by * 
 may be specified on the configuration command line):
 
@@ -615,11 +617,9 @@ locations given in the files in {\tt lib/make/extras/MPI}.
 
 To compile with HDF5 ({\tt http://hdf.ncsa.uiuc.edu/whatishdf5.html}),
 the configure options are
-\newline
-\newline
+
 {\tt HDF5 = YES [HDF5\_DIR = <dir>] [LIBZ\_DIR = <dir>]}
-\newline
-\newline
+
 If HDF5\_DIR is not given the configuration process will search for an
 installed HDF5 package in some standard places (defined in
 {\tt lib/make/extras/HDF5}). If the found HDF5 library was compiled with
@@ -882,10 +882,8 @@ Note that with more modern versions of gmake, it is sufficient to pass the norma
 Some thorns come with a testsuite, consisting of example parameter files
 and the output files generated by running these. To run the testsuites
 for the thorns you have compiled use
-\newline
 
 {\tt gmake <configuration>-testsuite}
-\newline
 
 These testsuites serve the dual purpose of
 
@@ -911,8 +909,6 @@ screen output and environment variables.
 \label{sec:coliop}
 
 The cactus executable accepts numerous command line arguments:
-\newline
-
 {\tt
 \begin{tabular}{|l|l|}
 \hline
@@ -940,7 +936,6 @@ Short Version & Long Version \\
 \hline
 \end{tabular}
 }
-\newline
 
 \begin{Lentry}
 \item [{\tt -O} or {\tt -describe-all-parameters}]
@@ -987,13 +982,25 @@ The parameter file is used to control the behaviour of the code at runtime.
 It is of a text file with lines which are either comments, denoted
 by a `\#', or parameter statements. A parameter statement consists 
 of one or more parameter names, followed by
-and `=', followed by the value(s) for this (these) parameter(s).
+and `=', followed by the value(s) for this (these) parameter(s). 
+Note that all string parameters are case insensitive.
 
-The name of a parameter consists of:
+The {\tt first parameter} in any parameter file should be {\tt ActiveThorns}.
+This is a special parameter  which tells the 
+code which {\em thorns} are to be activated.  Only parameters from active 
+thorns can be set  (and only those routines {\it scheduled} by active thorns 
+are run).  By default all thorns are inactive. For example, the first 
+entry in a parameter file which is using just the two thorns 
+{\tt CactusPUGH/PUGH} and {\tt CactusBase/CartGrid3D} should be
 
+{\tt ActiveThorns = ``PUGH CartGrid3D''}
+
+Parameters following the {\tt ActiveThorns} parameter all have names
+whose syntax depends on the scope of the parameter:
 \begin{Lentry}
 \item [{\tt Global parameters}]
-Just name of the parameter itself.
+Just the name of the parameter itself. Global parameters are avoided, and 
+there are none in the Flesh and Cactus Toolkits. 
 \item [{\tt Restricted parameters}]
 The name of the {\em implementation} which defined the parameter, two colons,
 and the name of the parameter --- e.g. {\tt driver::global\_nx}.
@@ -1002,17 +1009,62 @@ The name of the {\em thorn} which defined the parameter, two colons,
 and the name of the parameter --- e.g. {\tt wavetoyF77::amplitude}.
 \end{Lentry}
 
-In addition there is a parameter {\tt ActiveThorns} which tells the code
-which {\em thorns} are to be activated.  Only parameters from active thorns can
-be set  (and only those routines {\it scheduled} by active thorns are run).  
-By default all thorns are inactive.  {\bf This should be the first
-parameter in your parameter file.}
-\newline
+This notation is not strictly enforced currently in the code. It is 
+sufficient to specify the first part of the parameter name using either
+the implementation name, or the thorn name. However, it is suggested 
+that the convention above is followed.
+
+The Cactus Flesh performs checks for consistency and range of parameters,
+the severity of these checks is controlled by the command line argument
+{\tt -parameter-level} which can take the following values
+\begin{Lentry}
+\item[{\tt relaxed}] Cactus will issue a level 0 warning (that is the
+default behaviour will be to terminate) if
+\begin{itemize}
+\item{} The specified parameter value is outside of the allowed range.
+\end{itemize}
+
+\item [{\tt normal}] 
+This is the default, and provides the same warnings as the 
+{\tt relaxed} level, with in addition a level 0 warning issued for
+\begin{itemize}
+\item{} An implementation and/or thorn {\tt foo} is active, but the 
+	parameter {\tt foo::bar} was not defined.
+\item{} The parameter {\tt foo::bar} was successfully set for both an 
+	active implementation {\tt foo} not implemented by a thorn {\tt foo}, 
+	and to a thorn {\tt foo}.
+\end{itemize}
+
+\item [{\tt strict}]
+This provides the same warnings as the {\tt normal} level, with in 
+addition a level 0 warning issued for
+\begin{itemize}
+\item{} The parameter {\tt foo::bar} is specified in the parameter file,		but no implementation or thorn with the name {\tt bar} is active.
+\end{itemize}
+\end{Lentry}
+
+Notes:
 
-Note that you can obtain lists of the parameters associated with
+\begin{itemize}
+
+\item{} You can obtain lists of the parameters associated with
 each thorn using the command line options {\tt -o} and {\tt -O}
 (Section~\ref{sec:coliop}).
 
+\item{} The parameter file is read {\it sequentially} from top to bottom,
+	this means that if you set the value of a parameter twice in 
+	the parameter file, the second value will be used. (This is 
+	why the {\tt ActiveThorns} parameter is always first in the file).
+
+\item{} Some parameters are {\it steerable} and can be changed during 
+	the execution of a code using parameter steering interfaces 
+	(for example, thorn {\tt CactusConnect/HTTPD}, or using a 
+	parameter file when recovering from a checkpoint file. 
+
+\item{} For examples of parameter files, look in the {\par} directory
+	of thorns.
+
+\end{itemize}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%