Adding Carsten's suggestions

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

2 files changed, 183 insertions, 62 deletions

diff --git a/doc/UsersGuide/FunctionReference.tex b/doc/UsersGuide/FunctionReference.tex
index c191fa7f..59adfd4d 100644
--- a/doc/UsersGuide/FunctionReference.tex
+++ b/doc/UsersGuide/FunctionReference.tex
@@ -251,11 +251,20 @@ available from C, not all are currently available from Fortran.
   [\pageref{nProcs}] 
   Get the total number of processors used
 
+\item[CCTK\_OutputGH] 
+  [\pageref{OutputGH}] 
+
+\item[CCTK\_OutputVar] 
+  [\pageref{OutputVar}] 
+
+\item[CCTK\_OutputVarAs] 
+  [\pageref{OutputVarAs}] 
+
 \item[CCTK\_OutputVarAsByMethod] 
   [\pageref{OutputVarAsByMethod}] 
 
-\item[CCTK\_OutputGH] 
-  [\pageref{OutputGH}] 
+\item[CCTK\_OutputVarByMethod] 
+  [\pageref{OutputVarByMethod}] 
 
 \item[CCTK\_ParallelInit] 
   [\pageref{ParallelInit}] 
@@ -906,28 +915,6 @@ the Cactus scheduler via a thorn's {\tt schedule.ccl} file.
 
 
 % CommOverloadables.c
-\begin{CCTKFunc}{CCTK\_Exit}{Exit the code cleanly}
-\label{Exit}
-\subroutine{int}{integer}{istat}
-\argument{cGH *}{CCTK\_POINTER}{cctkGH}
-\argument{int}{integer}{value}
-\showargs
-\begin{params}
-\parameter{cctkGH}{pointer to CCTK grid hierarchy}
-\parameter{value}{error code}
-\end{params}
-\begin{discussion}
-\end{discussion}
-\begin{examples}
-\begin{tabular}{@{}p{3cm}cp{11cm}}
-\end{tabular}
-\end{examples}
-\begin{errorcodes}
-\end{errorcodes}
-\end{CCTKFunc}
-
-
-% CommOverloadables.c
 \begin{CCTKFunc}{CCTK\_Equals}{Check for string equality}
 \label{Equals}
 \function{int}{integer}{istat}
@@ -952,32 +939,21 @@ and zero if they differ.
 \end{errorcodes}
 \end{CCTKFunc}
 
-
-
-%%%%%
-% FFF
-%%%%%
-
-\begin{CCTKFunc}{CCTK\_FortranString}{Changes a C string into a Fortran string}
-\label{FortranString}
-\subroutine{int}{integer}{nchar}
-\argument{const char *}{character*(*)}{strout}
-\argument{const char *}{CCTK\_STRING}{strin}
+% CommOverloadables.c
+\begin{CCTKFunc}{CCTK\_Exit}{Exit the code cleanly}
+\label{Exit}
+\subroutine{int}{integer}{istat}
+\argument{cGH *}{CCTK\_POINTER}{cctkGH}
+\argument{int}{integer}{value}
 \showargs
 \begin{params}
-\parameter{nchar}{The number of characters in the C string, not counting the null terminator}
-\parameter{strout}{The fortran string which on output contains the C string as the first nchar characters}
-\parameter{strin}{The (pointer to the) C string containing the null terminator}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\parameter{value}{error code}
 \end{params}
 \begin{discussion}
-String or keyword parameters in Cactus are passed into Fortran routines as 
-pointers to C strings. This means that they cannot be directly used as Fortran
-strings. This routine allows a Fortran string to be created from such a C string. Note that the Fortran string must be defined to have at least the same expected length as the C string. This routine is only callable from Fortran.
 \end{discussion}
 \begin{examples}
 \begin{tabular}{@{}p{3cm}cp{11cm}}
-\hfill {\bf Fortran} && \\
-\\
 \end{tabular}
 \end{examples}
 \begin{errorcodes}
@@ -986,6 +962,12 @@ strings. This routine allows a Fortran string to be created from such a C string
 
 
 
+
+%%%%%
+% FFF
+%%%%%
+
+
 % Groups.c
 \begin{CCTKFunc}{CCTK\_FirstVarIndex}{Given a group name returns the first variable index in the group}
 \label{FirstVarIndex}
@@ -1038,6 +1020,33 @@ strings. This routine allows a Fortran string to be created from such a C string
 \end{CCTKFunc}
 
 
+\begin{CCTKFunc}{CCTK\_FortranString}{Changes a C string into a Fortran string}
+\label{FortranString}
+\subroutine{int}{integer}{nchar}
+\argument{const char *}{character*(*)}{strout}
+\argument{const char *}{CCTK\_STRING}{strin}
+\showargs
+\begin{params}
+\parameter{nchar}{The number of characters in the C string, not counting the null terminator}
+\parameter{strout}{The fortran string which on output contains the C string as the first nchar characters}
+\parameter{strin}{The (pointer to the) C string containing the null terminator}
+\end{params}
+\begin{discussion}
+String or keyword parameters in Cactus are passed into Fortran routines as 
+pointers to C strings. This means that they cannot be directly used as Fortran
+strings. This routine allows a Fortran string to be created from such a C string. Note that the Fortran string must be defined to have at least the same expected length as the C string. This routine is only callable from Fortran.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf Fortran} && \\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
 
 
 % Groups.c
@@ -1697,6 +1706,36 @@ The group name should be given in the form {\t <implementation>::<group>}
 
 
 % IOOverloadables.h
+\begin{CCTKFunc}{CCTK\_OutputVarAs}{}
+\label{OutputVarAs}
+\subroutine{int}{}{istat}
+\argument{cGH *}{}{cctkGH}
+\argument{const char *}{character*(*)}{variable}
+\argument{const char *}{character*(*)}{alias}
+\showargs
+\begin{params}
+\parameter{istat}{return flag}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\parameter{variable}{full name of variable to output}
+\parameter{alias}{name to base output file on}
+\end{params}
+\begin{discussion}
+Output a variable {\t variable} looping over all registered methods. 
+The output should take place if at all possible,
+if the appropriate file exists the data is appended, otherwise a new
+file is created. Uses {\t alias} as the name of the variable for the purpose
+of constructing a filename.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+% IOOverloadables.h
 \begin{CCTKFunc}{CCTK\_OutputVarAsByMethod}{}
 \label{OutputVarAsByMethod}
 \subroutine{int}{}{istat}
@@ -1706,9 +1745,72 @@ The group name should be given in the form {\t <implementation>::<group>}
 \argument{const char *}{character*(*)}{alias}
 \showargs
 \begin{params}
+\parameter{istat}{return flag}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\parameter{variable}{full name of variable to output}
+\parameter{method}{method to use for output}
+\parameter{alias}{name to base output file on}
+\end{params}
+\begin{discussion}
+Output a variable {\t variable} using the method {\t method} if it is 
+registered. Uses {\t alias} as the name of the variable for the purpose
+of constructing a filename. The output should take place if at all possible,
+if the appropriate file exists the data is appended, otherwise a new
+file is created.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% IOOverloadables.h
+\begin{CCTKFunc}{CCTK\_OutputVarByMethod}{}
+\label{OutputVarAsMethod}
+\subroutine{int}{}{istat}
+\argument{cGH *}{}{cctkGH}
+\argument{const char *}{character*(*)}{variable}
+\argument{const char *}{character*(*)}{method}
+\showargs
+\begin{params}
+\parameter{istat}{return flag}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\parameter{variable}{full name of variable to output}
+\parameter{method}{method to use for output}
+\end{params}
+\begin{discussion}
+Output a variable {\t variable} using the method {\t method} if it is 
+registered. The output should take place if at all possible,
+if the appropriate file exists the data is appended, otherwise a new
+file is created.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% IOOverloadables.h
+\begin{CCTKFunc}{CCTK\_OutputVar}{}
+\label{OutputVar}
+\subroutine{int}{}{istat}
+\argument{cGH *}{}{cctkGH}
+\argument{const char *}{character*(*)}{variable}
+\showargs
+\begin{params}
+\parameter{istat}{return flag}
 \parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\parameter{variable}{full name of variable to output}
 \end{params}
 \begin{discussion}
+Output a variable {\t variable} looping over all registered methods. 
+The output should take place if at all possible,
+if the appropriate file exists the data is appended, otherwise a new
+file is created.
 \end{discussion}
 \begin{examples}
 \begin{tabular}{@{}p{3cm}cp{11cm}}
diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex
index eda5422b..c1210165 100644
--- a/doc/UsersGuide/ThornWriters.tex
+++ b/doc/UsersGuide/ThornWriters.tex
@@ -428,29 +428,38 @@ changes the access level for any parameter defined in the file from that point o
 To access {\tt restricted} parameters from another implementation, a line
 containing {\tt shares: <name>} declares that all parameters mentioned in
 the file from now until the next access specification originate in 
-implementation {\tt <name>}.  
+implementation {\tt <name>}. Each of these parameters must be qualified by the initial token {\tt USES} or {\tt EXTENDS}, where
+\begin{Lentry}
+\item[{\tt USES}] indicates that the parameters range remains unchanged.
+\item[{\tt EXTENDS}] indicates that the parameters range is going to be extended.
+\end{Lentry}
 
 In contrast to parameter declarations in other access blocks, the default
 value must be omitted - it is impossible to set the default value of any
 parameter not originating in this thorn.
 For example, the following block adds possible values to the keyword
-{\tt initial\_data} originally defined in the implementation {\tt einstein}.
+{\tt initial\_data} originally defined in the implementation {\tt einstein}, 
+and uses the real parameter {\tt speed}.
 
 \begin{verbatim}
-
 shares:einstein
 
-KEYWORD initial_data ""
+EXTENDS KEYWORD initial_data ""
 {
   "bl_bh"         :: "Brill Lindquist black holes"
   "misner_bh"     :: "Misner black holes"
   "schwarzschild" :: "One Schwarzschild black hole"
 }
 
+USES CCTK_REAL speed ""
+{
+}
+
 \end{verbatim}
 
 Note that you must compile at least one thorn which implements {\tt einstein}.
 
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -1360,7 +1369,9 @@ the global grid.
 \item {\tt cctk\_bbox} 
       An array of 2*{\tt cctk\_dim} integers 
       which indicate whether the boundaries are internal boundaries
-      (e.g. between processors), or physical boundaries.
+      (e.g. between processors), or physical boundaries. A value of 1 indicates
+      a physical (outer) boundary at the edge of the computational grid, 
+      and 0 indicates an internal boundary.
 \end{itemize}
 
 The following variable is needed for grid refinement methods
@@ -1994,43 +2005,51 @@ file is created.
 A reduction operation can be defined as an operation on variables
 distributed  across multiple processor resulting in a single number.
 Typical reduction operations are: sum, minimum/maximum value, boolean
-operations. A typical applications is e.g. the maximum reduction on
-a processor local error estimates, therefor making the previous
-processor local error known to all processors. 
+operations. A typical application is, for example, 
+finding the maximum reduction from processor local error estimates, 
+therefor making the previous processor local error known to all processors. 
 
 The exchange of
 information across processors needs the functionality of a
-communication layer eg. PUGH. For this reason, the
+communication layer eg. {\tt CactusPUGH/PUGH}. For this reason, the
 reduction operation itself is not part of the flesh, instead Cactus (again)
 provides a registration mechanism for thorns to register routines they 
 provide as reduction operators. The different operators are
-identified by their name and a unique number, called a {\em handle}.
+identified by their name and/or a unique number, called a {\em handle}.
 
 The registration mechanism gives the advantage of a common
 interface while hiding the individual communication calls in the
 layer.
 
-In Cactus, reduction operators can be applied to gridfunctions, grid
-scalars and distributed arrays, as well as local variables/arrays. 
+In Cactus, reduction operators can in principle be applied to 
+grid functions, arrays and scalars, as well as to local arrays. Note that 
+different implementations of reduction operators may be limited in 
+the objects they can be applied to.
 There is a fundamental difference between the reduction operation on
 grid functions and quantities as arrays.
 
+\vskip .25cm
 
 {\bf Obtaining the reduction handle}
+
 Before calling the routine which performs the reduction operation,
 the handle, which indentifies the operation must be derived from its
 registered name.
 
 \begin{verbatim}
 
-int CCTK_GetReductionHandle(const char *reduction_name);
+int CCTK_ReductionHandle(const char *reduction_name);
 
-call CCTK_ReductionHandle(int reduction_handle, character reduction_name)
+integer       reduction_handle
+character*(*) reduction_name
+call CCTK_ReductionHandle(reduction_handle, reduction_name)
 
 
 int CCTK_GetReductionArrayHandle(const char *reduction_name);
 
-call CCTK_ReductionArrayHandle(int reduction_handle, character reduction_name)
+integer       reduction_handle
+character*(*) reduction_name
+call CCTK_ReductionArrayHandle(reduction_handle, reduction_name)
 
 \end{verbatim}
 
@@ -2044,12 +2063,12 @@ contain the handle value after the call. In C this value is the
 function value.
 \item[{\tt reduction\_name}] 
 is the name under which the operator has
-been registered by the providind thorn. Currently only PUGH is
-providing reduction operations.
+been registered by the providing thorn. The only thorn in the standard
+Computational Toolkit release which provides reduction operators is
+{\tt CactusPUGH/PUGHReduce}.
 \item[{\bf error checking}] 
 negative handle value indicates failure to
-identify the correct operator. Possible causes: misspelled operator
-name, operator not registered properly.
+identify the correct operator. 
 \end{Lentry}
 
 Get a integer handle corresponding to a given reduction operator.