Describe OPTIONS and TAGS in schedule.ccl

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

3 files changed, 80 insertions, 0 deletions

diff --git a/doc/UsersGuide.pdf b/doc/UsersGuide.pdf
index 82438953..89b02c09 100644
--- a/doc/UsersGuide.pdf
+++ b/doc/UsersGuide.pdf
diff --git a/doc/UsersGuide/Appendices.tex b/doc/UsersGuide/Appendices.tex
index 111f54a3..9287274b 100644
--- a/doc/UsersGuide/Appendices.tex
+++ b/doc/UsersGuide/Appendices.tex
@@ -859,7 +859,11 @@ schedule [GROUP] <\var{function name}|\var{group name}> AT|IN <\var{time}> \verb
      [BEFORE|AFTER <\var{function name}>|(<\var{function name}> <\var{function name}> ...)] \verb|\|
 \{
   [LANG: <\var{language}>]
+  [OPTIONS:       <\var{option}>,<\var{option}>...]
+  [TAGS:          <\var{keyword=value}>,<\var{keyword=value}>...]
   [STORAGE:       <\var{group}>[\var{timelevels}],<\var{group}>[\var{timelevels}]...]
+  [READS:         <\var{group}>,<\var{group}>...]
+  [WRITES:        <\var{group}>,<\var{group}>...]
   [TRIGGER:       <\var{group}>,<\var{group}>...]
   [SYNCHRONISE:   <\var{group}>,<\var{group}>...]
   [OPTIONS:       <\var{option}>,<\var{option}>...]
@@ -913,6 +917,35 @@ schedule [GROUP] <\var{function name}|\var{group name}> AT|IN <\var{time}> \verb
   \item[{\tt LANG}] The code language for the function (either {\tt C} or {\tt
     FORTRAN}). No language should be specified for a schedule group.
 
+  \item[\texttt{OPTIONS}] Schedule options are used for mesh
+    refinement and multi-block simulations, and they determine
+    ``where'' a routine executes. Possible options are:
+    \begin{description}
+    \item[\texttt{meta}]
+    \item[\texttt{meta\_early}]
+    \item[\texttt{meta\_late}]
+    \item[\texttt{global}]
+    \item[\texttt{global\_early}]
+    \item[\texttt{global\_late}]
+    \item[\texttt{level}]
+    \item[\texttt{singlemap}]
+    \item[\texttt{local}] (default, may be omitted)
+    \end{description}
+    (Only one of these options may be used.)
+    These options can be combined with the following:
+    \begin{description}
+    \item[\texttt{loop\_meta}]
+    \item[\texttt{loop\_global}]
+    \item[\texttt{loop\_level}]
+    \item[\texttt{loop\_singlemap}]
+    \item[\texttt{loop\_local}]
+    \end{description}
+    (At most one of the \texttt{loop\_...} options may be used.)
+
+  \item[\texttt{TAGS}] Schedule tags. These tags must have the form
+    \texttt{keyword=value}, and must be in a syntax accepted by
+    \texttt{Util\_TableCreateFromString}.
+
   \item[{\tt STORAGE}] List of variable groups which should have storage
   switched on for the duration of the function or schedule group.
   Each group must specify how many timelevels to activate storage for,
@@ -925,6 +958,20 @@ schedule [GROUP] <\var{function name}|\var{group name}> AT|IN <\var{time}> \verb
   case 0 (zero) \var{timelevels} can be requested, which is equivalent to
   the {\tt STORAGE} statement being absent.
 
+\item[\texttt{READS}] \texttt{READS} is used to declare which grid
+  variables are read by the routine. This information is used e.g.\ to
+  determine which variables need to be copied between host and device
+  for OpenCL or CUDA kernel. This information can also be used to
+  ensure that all variables that are read have previously been written
+  by another routine.
+
+\item[\texttt{WRITES}] \texttt{WRITES} is used to declare which grid
+  variables are written by the routine. This information is used e.g.\ to
+  determine which variables need to be copied between host and device
+  for OpenCL or CUDA kernel. This information can also be used to
+  ensure that all variables that are read have previously been written
+  by another routine.
+
   \item[{\tt TRIGGER}] List of grid variables or groups to be used as
   triggers for causing an {\tt ANALYSIS} function or group to be
   executed.  Any schedule block for an analysis function or analysis
diff --git a/doc/UsersGuide/ApplicationThorns.tex b/doc/UsersGuide/ApplicationThorns.tex
index 59d93373..5b26d6a0 100644
--- a/doc/UsersGuide/ApplicationThorns.tex
+++ b/doc/UsersGuide/ApplicationThorns.tex
@@ -451,7 +451,11 @@ consists of lines of the form
 schedule <\var{name}> at <\var{time bin}> [\var{other options}]
 \{
   LANG:     <FORTRAN|C>
+  OPTIONS:  [\var{list of options}]
+  TAGS:     [\var{list of keyword=value definitions}]
   STORAGE:  [\var{group list with timelevels}]
+  READS:    [\var{group list}]
+  WRITES:   [\var{group list}]
   TRIGGERS: [\var{group list}]
   SYNC:     [\var{group list}]
 \} "\var{A description}"
@@ -509,6 +513,19 @@ which determines how to call it from the scheduler.
 C and Fortran linkage are possible here. C++ routines should be defined as
 \texttt{extern "C"} and registered as \texttt{LANG: C}.
 
+\item[\texttt{OPTIONS}] Schedule options are used for mesh refinement
+  and multi-block simulations, and they determine ``where'' a routine
+  executes. Often used schedule options are \texttt{local} (also the
+  default, may be omitted), \texttt{level}, or \texttt{global}.
+  Routines scheduled in \emph{local mode} can access individual grid
+  points, routines scheduled in \emph{level mode} are used e.g.\ to
+  select boundary conditions, and routines schedule in \emph{global
+    mode} are e.g.\ used to calculate reductions (norms).
+
+\item[\texttt{TAGS}] Schedule tags, e.g.\ \texttt{Device=1} to specify
+  that a routine executes on an OpenCL or CUDA device instead of on
+  the host.
+
 \item[\texttt{STORAGE}] The \texttt{STORAGE} keyword specifies any groups for
 which memory should be allocated for the duration of the routine.  The
 storage status reverts to its previous status after the routine
@@ -527,6 +544,20 @@ thorn, fully qualified parameter names of the form
 \var{timelevels} can be requested, which is equivalent to the {\tt STORAGE}
 statement being absent.
 
+\item[\texttt{READS}] \texttt{READS} is used to declare which grid
+  variables are read by the routine. This information is used e.g.\ to
+  determine which variables need to be copied between host and device
+  for OpenCL or CUDA kernel. This information can also be used to
+  ensure that all variables that are read have previously been written
+  by another routine.
+
+\item[\texttt{WRITES}] \texttt{WRITES} is used to declare which grid
+  variables are written by the routine. This information is used e.g.\ to
+  determine which variables need to be copied between host and device
+  for OpenCL or CUDA kernel. This information can also be used to
+  ensure that all variables that are read have previously been written
+  by another routine.
+
 \item[\texttt{TRIGGERS}] \texttt{TRIGGERS} is used when the routine is
 registered at \texttt{ANALYSIS}.  This is a special time bin; a routine
 registered here will only be called if one of the variables from a
@@ -543,6 +574,8 @@ functions \texttt{CCTK\_SyncGroup()} or \texttt{CCTK\_SyncGroupsI()}
 keyword in the \texttt{schedule.ccl} is the preferred method, since it
 provides the flesh with more information about the behaviour of your code.
 
+
+
 \end{Lentry}
 
 Besides schedule blocks, it's possible to embed C style \texttt{if/else}