From c55875e78d0b866a22f4ad79063a9e7c559d7f8e Mon Sep 17 00:00:00 2001 From: eschnett Date: Thu, 17 May 2012 02:54:13 +0000 Subject: Describe OPTIONS and TAGS in schedule.ccl git-svn-id: http://svn.cactuscode.org/flesh/trunk@4825 17b73243-c579-4c4c-a9d2-2d5706c11dac --- doc/UsersGuide.pdf | Bin 789718 -> 792860 bytes doc/UsersGuide/Appendices.tex | 47 +++++++++++++++++++++++++++++++++++ doc/UsersGuide/ApplicationThorns.tex | 33 ++++++++++++++++++++++++ 3 files changed, 80 insertions(+) (limited to 'doc') diff --git a/doc/UsersGuide.pdf b/doc/UsersGuide.pdf index 82438953..89b02c09 100644 Binary files a/doc/UsersGuide.pdf and b/doc/UsersGuide.pdf differ 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: + 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} -- cgit v1.2.3