Proofreading, fixing missing commas, grammar, and typos in Utilities and Infrastructure

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

2 files changed, 105 insertions, 107 deletions

diff --git a/doc/UsersGuide/Infrastructure.tex b/doc/UsersGuide/Infrastructure.tex
index ec39aedd..fb48a8fb 100644
--- a/doc/UsersGuide/Infrastructure.tex
+++ b/doc/UsersGuide/Infrastructure.tex
@@ -23,7 +23,7 @@
  \item{} The cGH structure --- what it is and how to use it
  \item{} Extending the cGH structure
  \item{} Querying group and variable information
- \item{} Providing an IO layer
+ \item{} Providing an I/O layer
  \item{} Providing a communication layer
  \item{} Providing a reduction operator
  \item{} Providing an interpolation operator
@@ -35,24 +35,24 @@
 
 \section{Overloading and Registration}
 
-The Flesh defines a core API which guarantees the presence of a set of
-functions.  Although the Flesh guarantees the presence of these functions,
-they can be provided by thorns.  Thorns do this either by the \textit{overloading}
+The flesh defines a core API which guarantees the presence of a set of
+functions.  Although the flesh guarantees the presence of these functions,
+they can be provided by thorns.  Thorns do this by either the \textit{overloading}
 or the \textit{registration} of functions.
 
 \subsection{Overloading}
 
 Some functions can only be provided by one thorn.  The first thorn to
 \textit{overload} this function succeeds, and any later attempt to overload
-the function fails.  For each overloadable function there is a function
+the function fails.  For each overloadable function, there is a function
 with a name something like {\tt CCTK\_Overload...} which is passed the
 function pointer.
 
 \subsection{Registration}
 
 Some functions may be provided by several thorns.  The thorns \textit{register}
-their function with the Flesh, and when the Flesh-provided function is called,
-the Flesh calls all the registered functions.
+their function with the flesh, and when the flesh-provided function is called,
+the flesh calls all the registered functions.
 
 \section{GH Extensions}
 
@@ -61,10 +61,10 @@ that is required to be associated with a particular GH by a thorn.
 
 Each GH extension is given a unique handle.
 
-\section{IO Methods}
+\section{I/O Methods}
 
-An IO method is a distinct way to output data.  Each IO method has a unique name,
-and the Flesh-provided IO functions operate on all registered IO methods.
+An I/O method is a distinct way to output data.  Each I/O method has a unique name,
+and the flesh-provided I/O functions operate on all registered I/O methods.
 
 \chapter{GH Extensions}
 
@@ -114,7 +114,7 @@ the schedule tree.
    \hline
   \end{tabular}
 
-\chapter{Overloadable and Registerable Functions in IO}
+\chapter{Overloadable and Registerable Functions in I/O}
 
  \begin{tabular}{|l|l|}
    \hline {\bf Function} & {\bf Default}   \\
@@ -125,20 +125,20 @@ the schedule tree.
 
 \chapter{Drivers}
 
-The Flesh knows nothing about memory allocation for grid variables, or about how
-to communicate data when synchronisation is called for.  It knows nothing about
+The flesh does not know about memory allocation for grid variables, about how
+to communicate data when synchronisation is called for, or about
 multiple patches or adaptive mesh refinement.  All this is the job of a driver.
 
 This chapter describes how to add a driver to your code.
 
 \section{Anatomy}
 
-A driver consists of a Startup routine which creates a GH extension and
+A driver consists of a Startup routine which creates a GH extension, 
 registers its associated functions, and overloads the communication functions.
-It may optionally register interpolation, reduction, and IO methods.
+It may optionally register interpolation, reduction, and I/O methods.
 
 A driver may also overload the default Initialisation and Evolution routines,
-although a simple unigrid evolver is supplied in the Flesh.
+although a simple unigrid evolver is supplied in the flesh.
 
 \section{Startup}
 
@@ -177,14 +177,14 @@ describe in general, but one simple example might be
 
 struct SimpleExtension
 {
-  /* The data assocatiated with each variable */
+  /* The data associated with each variable */
   /* data[var][timelevel][ijk]                */
   void ***data
 } ;
 
 \end{verbatim}
 
-with a {\tt SetupGH} routine like.
+with a {\tt SetupGH} routine like
 
 \begin{verbatim}
 
@@ -220,16 +220,16 @@ struct SimpleExtension *SimpleSetupGH(tFleshConfig *config, int conv_level, cGH
 
 \end{verbatim}
 
-Basically all this example is doing is preparing a data array for use.  The
-function can query the Flesh for information on every variable.  Note that
+Basically, what this example is doing is preparing a data array for use.  The
+function can query the flesh for information on every variable.  Note that
 scalars should always have memory actually assigned to them.
 
-An {\tt InitGH} function isn't strictly necessary, and in this case it could
+An {\tt InitGH} function isn't strictly necessary, and in this case, it could
 just be a dummy function.
 
-The {\tt ScheduleTraverseGH} function needs to fill out the cGH data and
+The {\tt ScheduleTraverseGH} function needs to fill out the cGH data, and
 then call {\tt CCTK\_ScheduleTraverse} to have the functions scheduled at
-that point executed on the grid.
+that point executed on the grid
 
 \begin{verbatim}
 
@@ -342,7 +342,7 @@ int SimpleCallFunction(void *function,
 The return code of the function signifies whether or not the function
 synchronised the groups in this functions synchronisation list of not.
 
-The Flesh will synchronise them if the function returns false.
+The flesh will synchronise them if the function returns false.
 
 Providing this function is probably the easiest way to do multi-patch or
 AMR drivers.
@@ -399,7 +399,7 @@ size of the grid function or array group in a particular direction.
 
 \subsection{En/Disable Group Comm}
 
-These are the communication analogues to the storage functions.  Basically
+These are the communication analogues to the storage functions.  Basically,
 they flag that communication is to be done on that group or not, and may
 initialise data structures for the communication.
 
@@ -407,27 +407,27 @@ initialise data structures for the communication.
 \chapter{I/O Methods}
 \label{chap:io_methods}
 %
-The Flesh by itself does not provide output for grid variables or other data.
-Instead it provides a mechanism for thorns to register their own
+The flesh by itself does not provide output for grid variables or other data.
+Instead, it provides a mechanism for thorns to register their own
 routines as I/O methods, and to invoke these I/O methods by either the
-Flesh scheduler or by other thorn routines.
+flesh scheduler or by other thorn routines.
 
-This chapter explains how to implement I/O your own methods and register
-them with the Flesh.
+This chapter explains how to implement your own I/O methods and register
+them with the flesh.
 %
 \section{I/O Method Registration}
 %
-All I/O methods have to be registered with the Flesh before they can be used.
+All I/O methods have to be registered with the flesh before they can be used.
 
-The Flesh I/O registration API provides a routine {\t CCTK\_RegisterIOMethod()}
+The flesh I/O registration API provides a routine {\t CCTK\_RegisterIOMethod()}
 to create a handle for a new I/O method which is identified by its name
 (this name must be unique for all I/O methods).
 With such a handle, a thorn can then register a set of functions (using the
-{\t CCTK\_RegisterIOMethod*()} routines from the Flesh) for doing
+{\t CCTK\_RegisterIOMethod*()} routines from the flesh) for doing
 periodic, triggered, and/or unconditional output.
 
-The following example shows how a thorn would register an I/O method
-{\tt SimpleIO} with routines to provide all these different types of output.
+The following example shows how a thorn would register an I/O method,
+{\tt SimpleIO}, with routines to provide all these different types of output.
 %
 \begin{verbatim}
   void SimpleIO_Startup (void)
@@ -448,9 +448,9 @@ The following example shows how a thorn would register an I/O method
 %
 \section{Periodic Output of Grid Variables}
 %
-The Flesh scheduler will automatically call {\t CCTK\_OutputGH()} at every
+The flesh scheduler will automatically call {\t CCTK\_OutputGH()} at every
 iteration after the {\tt CCTK\_ANALYSIS} time bin. This function loops over all
-I/O methods and calls their routines registered as {\t OutputGH()} (see also
+I/O methods and calls their routines registered as {\t OutputGH()} (see also Section
 \ref{subsec:schedule_ccl}).
 %
 \begin{alltt}
@@ -458,10 +458,10 @@ I/O methods and calls their routines registered as {\t OutputGH()} (see also
 \end{alltt}
 %
 The {\t OutputGH()} routine itself should loop over all variables living on the
-\texttt{\var{GH}} grid hierarchy, and do all necessary output if requested
+\texttt{GH} grid hierarchy, and do all necessary output if requested
 (this is usually determined by I/O parameter settings).
 
-As its return code it should pass back the number of variables which were output
+As its return code, it should pass back the number of variables which were output
 at the current iteration, or zero if no output was done by this I/O method.
 %
 %
@@ -470,12 +470,12 @@ at the current iteration, or zero if no output was done by this I/O method.
 Besides the periodic output at every so many iterations using {\t OutputGH()},
 analysis and output of grid variables can also be done via triggers. For this,
 a {\t TimeToOutput()} routine is registered with an I/O method.
-This routine will be called by the Flesh scheduler at every iteration before
+This routine will be called by the flesh scheduler at every iteration before
 {\tt CCTK\_ANALYSIS} with the triggering variable(s) as defined in the schedule
-block for all {\tt CCTK\_ANALYSIS} routines (see \ref{scheduling:schedule_block}).
+block for all {\tt CCTK\_ANALYSIS} routines (see Section \ref{scheduling:schedule_block}).
 
 If the {\t TimeToOutput()} routine decides that it is now time to do output, the
-Flesh scheduler will invoke the corresponding analysis routine and also request
+flesh scheduler will invoke the corresponding analysis routine and also request
 output of the triggering variable(s) using {\t TriggerOutput()}.
 %
 \begin{alltt}
@@ -496,9 +496,9 @@ otherwise.
 \section{Unconditional Output of Grid Variables}
 
 An I/O method's {\t OutputVarAs()} routine is supposed to do output for a
-specific grid variable if ever possible. It will be invoked by the Flesh I/O API
+specific grid variable if ever possible. It will be invoked by the flesh I/O API
 routines {\t CCTK\_OutputVar*()} for unconditional, non-triggered output of
-grid variables (see also \ref{sec:io}).
+grid variables (see also Section \ref{sec:io}).
 
 A function registered as an \texttt{OutputVarAs()} routine has the following
 prototype:
@@ -523,8 +523,8 @@ was done successfully, or a negative error code otherwise.
 \label{chap:cp_recovery_methods}
 
 Like for I/O methods, checkpointing/recovery functionality must be implemented
-by thorns. The Flesh only provides specific time bins at which the scheduler
-will call thorns' routines in order to perform checkpointing and/or recovery.
+by thorns. The flesh only provides specific time bins at which the scheduler
+will call thorns' routines, in order to perform checkpointing and/or recovery.
 
 This chapter explains how to implement checkpointing and recovery methods
 in your thorn.  For further information, see the documentation for thorn
@@ -536,19 +536,19 @@ Thorns register their checkpointing routines at {\t CCTK\_CPINITIAL} and/or
 {\t CCTK\_CHECKPOINT} and/or {\t CCTK\_TERMINATE}. These time bins are
 scheduled right after all initial data has been set up, after every
 evolution timestep, and after the last time step of a simulation,
-respectively. (See \ref{subsec:schedule_ccl} for a description of all timebins).
+respectively. (See Section \ref{subsec:schedule_ccl} for a description of all timebins).
 Depending on
 parameter settings, the checkpoint routines decide whether to write an initial
 data checkpoint, and when to write an evolution checkpoint.
 
-Each checkpoint routine should save all information to persistent storage which
+Each checkpoint routine should save all information to persistent storage, which
 is necessary to restart the simulation at a later time from exactly the same
 state. Such information would include
 %
 \begin{itemize}
   \item the current settings of all parameters
   \item the contents of all grid variables which have global storage assigned
-    and are not tagged with {\tt checkpoint="no"} (see also section \ref{subsec:Appendix.interface-variables} on page \pageref{subsec:Appendix.interface-variables} for a list of possible tags)\\
+    and are not tagged with {\tt checkpoint="no"} (see also Section \ref{subsec:Appendix.interface-variables} on page \pageref{subsec:Appendix.interface-variables} for a list of possible tags)\\
     Note that grid variables should be synced before writing them to disk.
   \item other relevant information such as the current iteration number and
     physical time, the number of processors, etc.
@@ -557,7 +557,7 @@ state. Such information would include
 
 \section{Recovery Invocation}
 
-Recovering from a checkpoint is a two-phase operation for which the Flesh
+Recovering from a checkpoint is a two-phase operation for which the flesh
 provides distinct timebins for recovery routines to be scheduled at:
 %
 \begin{Lentry}
@@ -566,33 +566,33 @@ provides distinct timebins for recovery routines to be scheduled at:
     settings, the recovery routines should decide whether recovery was
     requested, and if so, restore all parameters from the checkpoint file and
     overwrite those which aren't steerable.\\
-    The Flesh loops over all registered recovery routines to find out
-    whether recovery was requested. Each recovery routine should therefore
+    The flesh loops over all registered recovery routines to find out
+    whether recovery was requested. Each recovery routine should, therefore,
     return a positive integer value for successful parameter recovery (causing
     a shortcut of the loop over all registered recovery routines),
     zero for no recovery, or a negative value to flag an error.\\
-    If recovery was requested but no routine could successfully recover
-    parameters, the Flesh will abort the run with an error message.
-    If no routine recovered any parameters, i.e., if all parameter
+    If recovery was requested, but no routine could successfully recover
+    parameters, the flesh will abort the run with an error message.
+    If no routine recovered any parameters, i.e. if all parameter
     recovery routines returned zero, then this indicates that this run
     is not a recovery run.\\
     If parameter recovery was performed successfully, the scheduler will set the
-    {\tt recovered} flag which --- in combination with the setting of the {\tt
-    Cactus::recovery\_mode} parameter --- decides whether any thorn routine
+    {\tt recovered} flag which---in combination with the setting of the {\tt
+    Cactus::recovery\_mode} parameter---decides whether any thorn routine
     scheduled for {\t CCTK\_INITIAL} and {\t CCTK\_POSTINITIAL} will be called.
-    The default is to not execute these initial time bins during recovery
+    The default is to not execute these initial time bins during recovery, 
     because the initial data will be set up from the checkpoint file during the
     following {\t CCTK\_RECOVER\_VARIABLES} time bin.
   \item[{\t CCTK\_RECOVER\_VARIABLES}]
     Recovery routines scheduled for this time bin are responsible for restoring
     the contents of all grid variables with storage assigned from the
     checkpoint.\\
-    Depending on the setting of {\tt Cactus::recovery\_mode} they should also
+    Depending on the setting of {\tt Cactus::recovery\_mode}, they should also
     decide how to treat errors in recovering individual grid variables. Strict
     recovery (which is the default) requires all variables to be restored
-    successfully (and will stop the code if not) whereas a relaxed mode
-    could e.g. allow for grid variables which are not found in the checkpoint
-    file to be gracefully ignored during recovery.
+    successfully (and will stop the code if not), whereas a relaxed mode
+    could, e.g. allow for grid variables, which are not found in the checkpoint
+    file, to be gracefully ignored during recovery.
 \end{Lentry}
 
 
@@ -600,12 +600,12 @@ provides distinct timebins for recovery routines to be scheduled at:
 \chapter{Clocks for Timing}
 \label{chap:clocks}
 
-To add a Cactus clock you need to write several functions to provide the
+To add a Cactus clock, you need to write several functions to provide the
 timer functionality (see Section \ref{sec:timers}), and then register these
-functions with the Flesh as a named clock.
+functions with the flesh as a named clock.
 
 The function pointers are placed in function pointer fields of a 
-\texttt{cClockFuncs} sturcture.  The fields of this structure are are:
+\texttt{cClockFuncs} structure.  The fields of this structure are are:
 
 \begin{Lentry}
 
@@ -663,7 +663,7 @@ of two calls to the timer, in seconds.  For example, it could reflect
 that the clock saves the time value internally as an integer value 
 representing milliseconds.
 
-To name and register the clock with the Flesh, call the function
+To name and register the clock with the flesh, call the function
 \begin{alltt}
 	CCTK_ClockRegister( "\var{my_clock_name}", &\var{clock_func} ).
 \end{alltt}
diff --git a/doc/UsersGuide/UtilityRoutines.tex b/doc/UsersGuide/UtilityRoutines.tex
index b5de3b5a..fb685d8f 100644
--- a/doc/UsersGuide/UtilityRoutines.tex
+++ b/doc/UsersGuide/UtilityRoutines.tex
@@ -32,7 +32,7 @@ general overview of programming with these utility routines.
 \section{Motivation}
 
 Cactus functions may need to pass information through a generic
-interface.  In the past we have used various ad hoc means to do this,
+interface.  In the past, we have used various ad hoc means to do this,
 and we often had trouble passing "extra" information that wasn't
 anticipated in the original design.  For example, for periodic output
 of grid variables,
@@ -75,7 +75,7 @@ character `{\tt /}' reserved for future expansion.%%%
 	 }%%%
 
 Values are 1-dimensional arrays of any of the usual Cactus data types
-described in section~\ref{sect-ThornWriting/DataTypes}.
+described in Section~\ref{sect-ThornWriting/DataTypes}.
 A string can be stored by treating it as a 1-dimensional array of
 \verb|CCTK_CHAR| (there's an example of this below).
 
@@ -144,9 +144,9 @@ Util_TableGetInt(handle, &two_value, "two");    /* sets two_value = 2 */
 Util_TableGetReal(handle, &pi_value, "pi");     /* sets pi_value = 3.14 */
 \end{verbatim}
 
-Actually, you shouldn't write code like this --- in the real world
+Actually, you shouldn't write code like this---in the real world
 errors sometimes happen, and it's much better to catch them close to
-their point of occurrence rather than silently produce garbage results
+their point of occurrence, rather than silently produce garbage results
 or crash your program.  So, the \emph{right} thing to do is to always
 check for errors.  To allow this, all the table routines return a status,
 which is zero or positive for a successful return, but negative if
@@ -200,8 +200,7 @@ also store 1-dimensional arrays of numbers (or characters or pointers).%%%
 	 you pass in, so it's somewhat inefficient to store a large array
 	 (e.g.~a grid function) this way.  If this is a problem, consider
 	 storing a \texttt{CCTK\_POINTER} (pointing to the array) in the table
-	 instead.  (Of course, this requires that you ensure that the pointed-to
-	 data is still valid whenever that \texttt{CCTK\_POINTER} is used.)
+	 instead.  (Of course, this requires that you ensure that the array still exists whenever that \texttt{CCTK\_POINTER} is used.)
 	 }%%%
 
 For example (continuing the previous example):
@@ -223,7 +222,7 @@ As you can see, a table entry remembers the length of any array
 value that has been stored in it.%%%
 \footnote{%%%
 	 In fact, actually \emph{all} table values are
-	 arrays --- setting or getting a single value is
+	 arrays---setting or getting a single value is
 	 just the special case where the array length is 1.
 	 }%%%
 {}
@@ -279,7 +278,7 @@ There are also convenience routines for the common case of setting
 values in a table based on a string.
 
 For example, the following code sets up exactly the same table as the
-example in section \ref{Tables_Simple_Example}:
+example in Section \ref{Tables_Simple_Example}:
 
 \begin{verbatim}
 #include <util_Table.h>
@@ -300,7 +299,7 @@ case insensitive flag set (to match Cactus parameter file semantics),
 then (assuming no errors occurred) calls \verb|Util_TableSetFromString()|
 to set values in the table.
 
-For example the following code sets up a table (with the case insensitive flag
+For example, the following code sets up a table (with the case insensitive flag
 set) with four entries: an integer number ({\tt two}), a real number ({\tt
 pi}), a string ({\tt buffer}), and an integer array with three elements ({\tt
 array}):
@@ -319,8 +318,8 @@ if (handle < 0)
 Note that this code passes a single string to
 \verb|Util_TableCreateFromString()|%%%
 \footnote{C automatically concatenates
-adjacent character string constants separated only by whitespace.}
-{} which then gets parsed into key/value pairs, with the key separated from its
+adjacent character string constants separated only by whitespace.}, 
+which then gets parsed into key/value pairs, with the key separated from its
 corresponding value by an equals sign.
 
 Values for numbers are converted into integers ({\tt CCTK\_INT}) if possible
@@ -336,10 +335,10 @@ of the same type (either all integer or all real).
 \section{Table Iterators}
 \label{sect-UtilityRoutines/tables/table-iterators}
 
-In the examples up to now, the code which wanted to get values from
-the table knew what the keys were.  It's also useful to be able to
+In the examples up to now, the code, which wanted to get values from
+the table, knew what the keys were.  It's also useful to be able to
 write generic code which can operate on a table without knowing the
-keys.  ``Table iterators'' (``iterators'' for short) are used for this.
+keys.  ``Table iterators'' (``iterators'', for short) are used for this.
 
 An iterator is an abstraction of a pointer to a particular table entry.
 Iterators are analogous to the \verb|DIR *| pointers used by the POSIX
@@ -348,10 +347,10 @@ functions, to Perl hash tables' \verb|each()|, \verb|keys()|,
 and \verb|values()|, and to the C++ Standard Template Library's
 forward iterators.
 
-At any time the entries in a table may be considered to be in some
+At any time, the entries in a table may be considered to be in some
 arbitrary (implementation-defined) order; an iterator may be used to
 walk through some or all of the table entries in this order.  This
-order is guaranteed to remain unchanged for any given table so long
+order is guaranteed to remain unchanged for any given table, so long
 as no changes are made to that table, \ie{} so long as no
 \verb|Util_TableSet*()|, \verb|Util_TableSet*Array()|,
 \verb|Util_TableSetGeneric()|, \verb|Util_TableSetGenericArray()|,
@@ -382,24 +381,25 @@ using an iterator to print out all the entries in a table.
 
 \section{Multithreading and Multiprocessor Issues}
 
-{\bf At the moment, the table functions are \emph{not} thread-safe
-in a multithreaded environment!}  However, this should change in
-the not-too-distant future: then all the table functions will default
-to being thread-safe.  That is, user code will be able call these
-functions concurrently from multiple threads, with the table functions
-automatically doing any necessary locking.%%%
-\footnote{%%%
-	 For the implementation, this means that we will need a
-	 reader/writer lock for each table and for each iterator:
-	 any number of threads will be able to concurrently read
-	 the data structure, but any write will require exclusive
-	 access.
-	 }%%%
-{}  (We may add a flags-word bit to suppress this for maximum
-performance if you know you won't be making concurrent calls from
-multiple threads.)
-
-Note that tables and iterators will still be process-wide, i.e. all
+At the moment, the table functions are \emph{not} thread-safe
+in a multithreaded environment. 
+%% However, this should change in
+%%the not-too-distant future: then all the table functions will default
+%to being thread-safe.  That is, user code will be able call these
+%%functions concurrently from multiple threads, with the table functions
+%%automatically doing any necessary locking.%%%
+%%\footnote{%%%
+%	 For the implementation, this means that we will need a
+%	 reader/writer lock for each table and for each iterator:
+%	 any number of threads will be able to concurrently read
+%	 the data structure, but any write will require exclusive
+%	 access.
+%	 }%%%
+%{}  (We may add a flags-word bit to suppress this for maximum
+%performance if you know you won't be making concurrent calls from
+%multiple threads.)
+
+Note that tables and iterators are process-wide, i.e. all
 threads see the same tables and iterators (think of them as like the
 Unix current working directory, with the various routines which modify
 the table or change iterators acting like a Unix \verb|chdir()| system
@@ -411,18 +411,16 @@ In a multiprocessor environment, tables are always processor-local.
 
 \section{Metadata about All Tables}
 
-We have decided that tables do not \emph{themselves} have names or other
-attributes.  However, at some time in the future we may add some special
+Tables do not \emph{themselves} have names or other
+attributes.  However, we may add some special
 ``system tables'' to be used by Cactus itself to store this sort of
-information for those cases where it's needed.
-
-For example, at some time in the future we may add support for a
+information for those cases where it's needed. For example, we may add support for a
 ``checkpoint me'' bit in a table's flags word, so that if you want a
 table to be checkpointed, you just need to set this bit.
-In this case the table will probably get a system generated name in
+In this case, the table will probably get a system generated name in
 the checkpoint dump file.  But if you want the table to have some
 other name in the dump file, then you need to tell the checkpointing
-code that by setting an appropriate entry in a checkpoint table.
+code that, by setting an appropriate entry in a checkpoint table.
 (You would find the checkpoint table by looking in a special
 ``master system table'' that records handles of other interesting tables.)