Document the schedule options "loop-local", "loop-singlemap",

"loop-level", "loop-global", and "loop-meta".


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

2 files changed, 61 insertions, 15 deletions

diff --git a/doc/UsersGuide/Appendices.tex b/doc/UsersGuide/Appendices.tex
index fd45185c..fdc7d359 100644
--- a/doc/UsersGuide/Appendices.tex
+++ b/doc/UsersGuide/Appendices.tex
@@ -752,22 +752,71 @@ schedule [GROUP] <\var{function name}|\var{group name}> AT|IN <\var{time}> \verb
 
 \label{app:allopts}
 
+Cactus understands the following options.  These options are
+interpreted by the driver, not by Cactus.  The current set of options
+is useful for Berger-Oliger mesh refinement which has subcycling in
+time, and for multi-patch simulations in which the domain is split
+into several distinct patches.  Given this, the meanings of the
+options below is only tentative, and their exact meaning needs to be
+obtained from the driver documentation.  The standard driver PUGH
+ignores all options.
+
+Option names are case-insensitive.  There can be several options given
+at the same time.
+
 \begin{Lentry}
+  
+\item[{\tt META}] This routine will only be called once, even if
+  several simulations are performed at the same time.  This can be
+  used, for example, to initialise external libraries, or to set up
+  data structures that live in global variables.
+  
+\item[{\tt GLOBAL}] This routine will only be called once on a grid
+  hierarchy, not for all subgrids making up the hierarchy.  This can
+  be used, for example, for analysis routines which use global
+  reduction or interpolation routines rather than the local subgrid
+  passed to them, and hence should only be called once.
+  
+\item[{\tt LEVEL}] This routine will only be called once on any
+  ``level'' of the grid hierarchy.  That is, it will only be called
+  once for any set of sub-grids which have the same
+  \texttt{cctk\_levfac} numbers.
+  
+\item[{\tt SINGLEMAP}] This routine will only be called once on any of
+  the ``patches'' that form a ``level'' of the grid hierarchy.
+  
+\item[{\tt LOCAL} (this is the default)] This routine will be called
+  on every ``component''.
+
+\end{Lentry}
 
-\item[{\tt GLOBAL}]
-This routine will only be called once on a grid hierarchy, not for all
-subgrids making up the hierarchy.  This can be used, for example, for
-analysis routines which use global reduction or interpolation routines
-rather than the local subgrid passed to them, and hence should only be
-called once.
+When the above options are used, it is often the case that a certain
+routine should e.g.\ be called at the time for a \texttt{GLOBAL}
+routine, but should actually loop overall ``components''.  The
+following set of options allows this:
 
-\item[{\tt LEVEL}]
-This routine will only be called once on any ``level'' of grid
-hierarchy.  I.e. it will only be called once for any set of sub-grids
-which have the same \texttt{cctk\_levfac} numbers.
+\begin{Lentry}
+  
+\item[{\tt LOOP-META}] Loop once.
+  
+\item[{\tt LOOP-GLOBAL}] Loop over all simulations.
+  
+\item[{\tt LOOP-LEVEL}] Loop over all ``levels''.
+  
+\item[{\tt LOOP-SINGLEMAP}] Loop over all ``patches''.
+  
+\item[{\tt LOOP-LOCAL}] Loop over all ``components''.
 
 \end{Lentry}
 
+For example, the specification
+\begin{alltt}
+  OPTIONS: global loop-local
+\end{alltt}
+schedules a routine at those time when a \texttt{GLOBAL} routine is
+scheduled, and then calls the routine in a loop over all
+``components''.
+
 
 \subsection{Conditional Statements}
 
diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex
index 6ca4389a..62a75a0c 100644
--- a/doc/UsersGuide/ThornWriters.tex
+++ b/doc/UsersGuide/ThornWriters.tex
@@ -1427,11 +1427,8 @@ if there is no group listed.)
 On exit from this item the ghost zones of the listed groups will be
 exchanged.
 \item[\texttt{OPTIONS}]
-This is for miscellaneous options.  The only currently supported
-option is {\tt GLOBAL} which tells the driver that this routine does
-not use a local grid, but instead uses global operations to process
-data;  such a routine should only be called once however many
-sub-grids the driver may have broken the problem into.
+This is for miscellaneous options.  The list of accepted options is
+given in appendix~\ref{app:allopts}.
 \end{Lentry}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%