Put in more refs/labels, esp. in and to Chapter A

and cases of CCTK functions explained in the Reference Manual

Removed a bad character (probably added by me)

Expanded upon overview of parameters in B5;
Added a section "Steerable" (note: also needs sections on "Accumulator")

Changed "gridfunction" -> "grid function" throughout.

Regularised use of verbatim environment, esp in B8.1

Corrected statement about arguments of CCTK_CoordRange

Core use of alltt environment in B8.4 (fixed a small typo)


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

1 files changed, 74 insertions, 49 deletions

diff --git a/doc/UsersGuide/RunningCactus.tex b/doc/UsersGuide/RunningCactus.tex
index 113c5809..4a9aba35 100644
--- a/doc/UsersGuide/RunningCactus.tex
+++ b/doc/UsersGuide/RunningCactus.tex
@@ -891,8 +891,8 @@ by configure and the {\tt ThornList} file remain.
 \item [{\tt gmake <config>-rebuild}] rebuilds a configuration (reruns the CST).
 
 \item [{\tt gmake <config>-testsuite}] runs the test programs associated with
- each thorn in the configuration. See section \ref{sec:testing} for information about the
- testsuite mechanism.
+ each thorn in the configuration. See section \ref{sec:testing} for information
+ about the test suite mechanism.
 
 \item [{\tt gmake <config>-thornlist}] regenerates the {\tt ThornList} for a configuration.
 
@@ -1027,13 +1027,13 @@ configuration found in user's \texttt{configs} subdirectory.
 \section{Testing}
 \label{sec:testing}
 
-Some thorns come with a testsuite, consisting of example parameter files
-and the output files generated by running these. To run the testsuite
+Some thorns come with a test suite, consisting of example parameter files
+and the output files generated by running these. To run the test suite
 for the thorns you have compiled use
 
 {\tt gmake <configuration>-testsuite}
 
-These testsuite serve the dual purpose of
+These test suite serve the dual purpose of
 
 \begin{Lentry}
 \item [Regression testing]
@@ -1050,15 +1050,15 @@ is also of use when trying to get Cactus to work on a new architecture.
 \chapter{Running Cactus}
 
 Cactus executables always run from a parameter file (which may be a
-physical file or taken from standard input), which specifies which
+specified as a command line argument taken from standard input), which
+specifies which
 thorns to use and sets the values of any parameters which are different
-from the default values. Any accepted filename can be used for the name
-of the parameter file, although standard convention is to use the file
+from the default values. There is no restriction on the name 
+of the parameter file, although it is conventional to use the file
 extension {\tt .par}.  Optional command line arguments can be used
 to customise runtime behaviour, and to provide information about the
 thorns used in the executable. The general syntax for running Cactus from
-a physical parameter file is
-then
+a parameter file is then
 
 {\tt ./cactus\_<config> <parameter file> [command line options]}
 
@@ -1072,9 +1072,9 @@ file syntax, understanding screen output, environment variables, and
 creating thorn documentation.
 
 \section{Command Line Options}
-\label{sec:coliop}
+\label{sec:command_line_options}
 
-The cactus executable accepts numerous command line arguments:
+The Cactus executable accepts numerous command line arguments:
 
 {\tt
 \begin{tabular}{|l|l|}
@@ -1155,26 +1155,35 @@ the standard outputs from processors other than processor 0 are discarded.
 \item [{\tt -i} or {\tt -ignore-next}]
 Ignore the next argument on the command line.
 \item [{\tt -parameter-level=<level>}]
-Set the level of parameter checking to be used, either {\tt strict}, {\tt normal} (the default), or {\tt relaxed}. See Section~\ref{sec:pafisy}.
+Set the level of parameter checking to be used, either {\tt strict}, {\tt normal} (the default), or {\tt relaxed}. See Section~\ref{sec:Parameter_File}.
 \end{Lentry}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Parameter File Syntax}
-\label{sec:pafisy}
-
-The parameter file is used to control the behaviour of the code at runtime.
-It is a text file with lines which are either comments, denoted
-by a `{\tt \#}' or `{\tt !}', or parameter statements. A parameter statement
+\label{sec:Parameter_File}
+
+A \textit{parameter file} ( or \textit{par file}) is used to control the
+behaviour of a Cactus executable.  It specifies initial values for parameters
+as defined in the various thorns' {\tt param.ccl} files
+(see Chapter~\ref{chap:Cactus_parameters}).
+The name of a parameter file is often given the suffix {\tt .par}, but
+this is not mandatory.
+
+A parameter file is a text file whose lines are either comments
+or parameter statements. 
+Comments are blank lines or lines that begin with either
+`{\tt \#}' or `{\tt !}'. 
+A parameter statement
 consists of one or more parameter names, followed by
 an `{\tt =}', followed by the value(s) for this (these) parameter(s).
 Note that all string parameters are case insensitive.
 
-The {\tt first parameter} in any parameter file should be {\tt ActiveThorns}.
-This is a special parameter  which tells the
-code which \textit{thorns} are to be activated.  Only parameters from active
-thorns can be set  (and only those routines \textit{scheduled} by active thorns
+The first parameter statement in any parameter file should set {\tt ActiveThorns},
+which is a special parameter that tells the
+program which \textit{thorns} are to be activated.  Only parameters from active
+thorns can be set (and only those routines \textit{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
@@ -1182,14 +1191,17 @@ entry in a parameter file which is using just the two thorns
 {\tt ActiveThorns = "PUGH CartGrid3D"}
 
 Parameters following the {\tt ActiveThorns} parameter all have names
-whose syntax depends on the scope of the parameter:
+whose syntax depends on the scope
+(see Section~\ref{sec:Cactus_parameters.scope})
+of the parameter:
 \begin{Lentry}
 \item [{\tt Global parameters}]
-Just the name of the parameter itself. Global parameters are avoided, and
+Just the name of the parameter itself. Global parameters are to be avoided;
 there are none in the Flesh and Cactus Toolkits.
 \item [{\tt Restricted parameters}]
-The name of the \textit{implementation} which defined the parameter, two colons,
-and the name of the parameter --- e.g. {\tt driver::global\_nx}.
+The name of the \textit{implementation} which defined the parameter, followed
+by two colons,
+then the name of the parameter --- e.g. {\tt driver::global\_nx}.
 \item [{\tt Private parameters}]
 The name of the \textit{thorn} which defined the parameter, two colons,
 and the name of the parameter --- e.g. {\tt wavetoyF77::amplitude}.
@@ -1197,8 +1209,8 @@ and the name of the parameter --- e.g. {\tt wavetoyF77::amplitude}.
 
 This notation is not currently strictly enforced 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 implementation name, or the thorn name. However, we recommend
+that the above convention be followed.
 
 The Cactus Flesh performs checks for consistency and range of parameters.
 The severity of these checks is controlled by the command line argument
@@ -1236,16 +1248,16 @@ Notes:
 
 \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}).
+(Section~\ref{sec:command_line_options}).
 
-\item{} The parameter file is read \textit{sequentially} from top to bottom,
+\item{} The parameter file is read \emph{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 \textit{steerable} and can be changed during
-        the execution of a code using parameter steering interfaces
-        (for example, thorn {\tt CactusConnect/HTTPD}, or using a
+        the execution of a Cactus program 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 {\tt par} directory
@@ -1256,14 +1268,14 @@ each thorn using the command line options {\tt -o} and {\tt -O}
 \section{Thorn Documentation}
 \label{sec:thdo}
 
-The Cactus make system provides a mechanism for generating a
+The Cactus make system provides a mechanism for generating a 
 \textit{Thorn Guide} containing separate chapters for each thorn and
 arrangement in your configuration. The documentation provided for an
 individual thorn obviously depends on what the thorn authors added,
 but the Thorn Guide is a good place to first look for special
 instructions on how to run and interpret the output from a Thorn.
 Details about parameters, grid variables and scheduling are
-automatically included in from a thorns {\tt CCL} files into the Thorn
+automatically included in from a thorns CCL files into the Thorn
 Guide. To construct a Thorn Guide for the configuration {\tt
 $<$config$>$} use
 
@@ -1273,7 +1285,8 @@ or to make a Thorn Guide for all the thorns in the {\tt arrangements} directory
 
 {\tt gmake $<$config$>$}.
 
-
+See Section~\ref{sec:Adding_documentation} for a guide to adding 
+documentation to your own thorns.
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -1295,7 +1308,9 @@ As the program runs, the normal output provides the following information:
 \begin{Lentry}
 
 \item [Active thorns]
-        A report is made as each of the thorns in the {\tt ActiveThorns} parameters from the parameter file is attempted to be activated. This report
+        A report is made as each of the thorns in the {\tt ActiveThorns}
+parameters from the parameter file (see Section~\ref{sec:Parameter_File})
+is attempted to be activated. This report
 shows whether the activation was successful, and if successful gives the
 thorn's implementation. For example
 
@@ -1304,11 +1319,13 @@ Activating thorn idscalarwave...Success -> active implementation idscalarwave
 \end{verbatim}
 
 \item [Failed parameters]
-         If any of the parameters in the parameter file does not belong to any of the active thorns, or if the parameter value is not in the allowed range, an
-error is registered. For example, if the parameter is not recognised
+         If any of the parameters in the parameter file does not belong to any
+of the active thorns, or if the parameter value is not in the allowed range
+(see Section~\ref{sec:Parameters.Types_and_Ranges}),
+an error is registered. For example, if the parameter is not recognised
 
 \begin{verbatim}
-Unknown parameter time::ddtfac�
+Unknown parameter time::ddtfac
 \end{verbatim}
 or if the parameter value is not in the allowed range
 
@@ -1317,8 +1334,8 @@ Unable to set keyword CartGrid3D::type - ByMouth not in any active range
 \end{verbatim}
 
 \item [Scheduling information]
-        A complete list of all scheduled routines is given, in the
-order that they will be executed. For example
+        The scheduled routines (see Section~\ref{chap:scheduling}),
+are listed, in the order that they will be executed. For example
 
 \begin{verbatim}
 ----------------------------------------------------------------------
@@ -1359,20 +1376,23 @@ order that they will be executed. For example
 
 
 \section{Output}
-Output methods in Cactus are all provided by thorns. Any number of output
-methods can be used for each run. The behaviour of the output thorns in the
+Output methods in Cactus are all provided by thorns.
+Any number of output methods can be used for each run.
+The behaviour of the output thorns in the
 standard arrangements are described in those thorns' documentation.
 
 In general, these thorns decide what to output by parsing a string parameter
 containing the names of those grid variables, or groups of variables, for which
 output is required. The names should be fully qualified with the
-{\tt implementation} and {\tt group} or {\tt variable} names.
+implementation and group or variable names.
 
 There is usually a parameter for each method to denote how often, in evolution
 iterations, this output should be performed.  There is also usually a parameter
 to define the directory in which the output should be placed, defaulting to the
 directory from which the executable is run.
 
+See Chapter~\ref{chap:io_methods} for details on creating your own IO method.
+
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -1384,12 +1404,17 @@ settings, contents of grid variables, and other relevant information) to a file.
 At a later time, this run can then be restarted from that state by recovering
 all the data from the checkpoint file.
 
-Checkpointing/recovery methods in Cactus are provided by thorns.
+Checkpointing/recovery methods in Cactus are provided by thorns. 
+
+In general, these thorns decide how often to generate a checkpoint.
+They also register their recovery routines with the Flesh; the recovery
+routines are then called during initialization to perform the recovery of
+parameters and grid variables
+if requested in the parameter file.
+% SW Where can we read about how to request this in the parameter file?
 
-In general, these thorns decide how often to generate a checkpoint. They also
-register their recovery routines with the Flesh which then get called during
-initialization to perform the recovery of parameters and grid variables if
-requested in the parameter file.
+See Chapter~\ref{chap:cp_recovery_methods} for details of how to create
+your own checkpointing and recovery methods.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%