diff options
| -rw-r--r-- | doc/UsersGuide/Appendices.tex | 385 | ||||
| -rw-r--r-- | doc/UsersGuide/RunningCactus.tex | 76 | ||||
| -rw-r--r-- | doc/UsersGuide/ThornWriters.tex | 417 | ||||
| -rw-r--r-- | doc/UsersGuide/UsersGuide.tex | 2 |
4 files changed, 466 insertions, 414 deletions
diff --git a/doc/UsersGuide/Appendices.tex b/doc/UsersGuide/Appendices.tex index 9b968d40..69733fa0 100644 --- a/doc/UsersGuide/Appendices.tex +++ b/doc/UsersGuide/Appendices.tex @@ -24,16 +24,17 @@ Cactus Users' Guide and the Cactus Reference Manual. \begin{Lentry} +\item[alias function] \item[API] - Applications Programming Interface, the externally visible interface + \textit{Applications Programming Interface}, the externally visible + interface provided by some software component. (An API usually consists of a set of subroutine/function calls, but may also include data passed - via Cactus key-value tables, grid arrays, or other means.) For - example, the Reference Manual documents most of the Cactus Flesh - APIs. + via Cactus key-value tables, grid arrays, or other means.) + The Reference Manual documents most of the Cactus Flesh APIs. \item[arrangement] - A collection of thorns, normally stored in the Cactus - \verb|arrangements| directory. + A collection of thorns, normally stored in a subdirectory of the Cactus + \verb|arrangements| directory. See Section~\ref{sec:arrangements}. \item[autoconf] A GNU program which builds a configuration script which can be used to make a Makefile. @@ -42,7 +43,7 @@ Cactus Users' Guide and the Cactus Reference Manual. contain boundary data, e.g.\ Dirichlet or Von Neumann data. (See also \textit{symmetry zone}, \textit{ghost zone}.) \item[Cactus] - A green fleshy plant with lots of thorns, usually painful if + A green fleshy plant with lots of thorns, usually inflicting pain if touched. \item[CCTK] \textit{Cactus Computational Tool Kit} (The Cactus Flesh and computational @@ -50,6 +51,7 @@ Cactus Users' Guide and the Cactus Reference Manual. \item[CCL] The \textit{Cactus Configuration Language}, this is the language that the thorn configuration files are written in. + See Section~\ref{sec:Appendix.ccl}. \item[configuration] The combination of a set of thorns, and all the Cactus configure options which affect what binary will be produced when compiling @@ -60,27 +62,35 @@ Cactus Users' Guide and the Cactus Reference Manual. configuration (these flags change what binary is produced), but the Cactus \verb|SILENT| and \verb|WARN| configure options aren't part of a configuration (they don't change what binary will be produced). + See Section~\ref{sec:configurations}. \item[checkout] - Get a copy of the code or thorns from CVS. + Get a copy of source code from CVS. \item[checkpointing] - Save the entire state of a run to file so that it can be restarted - at a later time. + Save the entire state of a Cactus run to a file so that the run can be + restarted at a later time. + See Sections~\ref{sec:checkpointing}, \ref{chap:cp_recovery_methods}. +\item[computational grid] \item[convergence] Important, but often neglected. \item[CST] This stands for \textit{Cactus Specification Tool}, which is the set of Perl - scripts which parse the thorns' configuration files (those that have a - \texttt{.ccl} extension). + scripts which parse the thorns' \texttt{.ccl} files. \item[CVS] - The \textit{Concurrent Versions System} is the favoured - distribution system for Cactus and can be downloaded from your - favorite GNU site. + The \textit{Concurrent Versions System} is the favoured code + distribution system for Cactus. See Sections~\ref{sec:checkout}, + \ref{sec:Appendix.cvs}. \item[driver] - A thorn which creates and handles grid hierarchies. + A special kind of thorn which creates and handle grid hierarchies. +%Drivers are responsible for memory management for grid variables, and for all parallel operations, in response to requests from the scheduler. + See Section~\ref{sec:parallelisation}. +\item[evolution] \item[Flesh] The routines which hold all the thorns together, this is what you get if you check out Cactus from our CVS repository. -\item[friend] +\item[friend] Interfaces that are \textit{friends} share their collective + set of protected grid variables. + See Section~\ref{subsec:interface_ccl}. \ref{sec:Appendix.interface}. +\item[function aliasing] \item[GA] Shorthand for a \textit{grid array}. \item[GF] @@ -92,15 +102,19 @@ Cactus Users' Guide and the Cactus Reference Manual. enable inter-processor communication of data from processor boundaries. In single processor runs there are no ghost zones. Ghost zones should not be confused with symmetry or boundary zones. + See Section~\ref{sec:ghost_size}. +\item[grid] + Short for \textit{computational grid}. \item[grid array] - A \textit{grid variable} whose global size need not be that of the computational - grid; instead, the size is declared explicitly in an \verb|interface.ccl| - file. (See also \textit{local array}.) + A \textit{grid variable} whose global size need not be that of the + computational grid; instead, the size is declared explicitly in an + \verb|interface.ccl| file. \item[grid function] A \textit{grid variable} whose global size is the size of the computational grid. (See also \textit{local array}.) \item[grid hierarchy] A computational grid, and the grid variables associated with it. +\item[grid point] \item[grid scalar] A \textit{grid variable} which has zero indices, i.e.\ it's just a number on each processor. @@ -110,45 +124,62 @@ Cactus Users' Guide and the Cactus Reference Manual. interface; implicitly implies it is related to the computational grid rather than being an internal variable of the thorn or one of its routines. \textit{grid scalar}, \textit{grid function}, and \textit{grid - array} are all examples of \textit{grid variables}. + array} are all examples of \textit{grid variables}. + See Section~\ref{chap:cactus_variables}. \item[GNATS] The GNU program we use for reporting and tracking bugs, comments and suggestions. +\item[GNU] + \textit{GNU's Not Unix}: a freely-distributable code project. + See \url{http://www.gnu.org/}. \item[GV] Shorthand for a \textit{grid variable} \item[handle] - A signed integer value $>= 0$. Many Cactus routines return or accept - a handle to represent a dynamic data or code object. Handles for the + A signed integer value $>= 0$ passed by many Cactus routines and + used to represent a dynamic data or code object. Handles for the same object class should not be trusted to comprise a consecutive sequence of integer values. \item[HDF5] \textit{Hierarchical Data Format} version~5, an API, subroutine library, and - file format for storing multidimensional data. An HDF5 file can + file format for storing structured data. An HDF5 file can store both data (for example Cactus grid variables), and meta data (data describing the other data, for example Cactus coordinate systems). + See Section~\ref{subsec:hdf5}, also \url{http://hdf.ncsa.uiuc.edu/HDF5/}. \item[implementation] - Defines the interface that a thorn presents to the outside world. - See Section~\ref{sec:im}. -\item[inherit] + Defines the interface that a thorn presents to the rest of a Cactus program. + See Section~\ref{sec:implementations}. +\item[inherit] A thorn that \textit{inherits} from another implementation + can access all the other implementation's public variables. + See Section~\ref{subsec:interface_ccl}. \ref{sec:Appendix.interface}. +\item[interface] \item[interpolation] - Given $N$ \textit{grid arrays} and $C$ interpolation points (in the + Given $N$ grid arrays and $C$ interpolation points (in the grid array coordinate space), return $M$ values on each requested processor at each interpolation point. (See also \textit{local interpolation}) \item[local array] - An array that is declared in normal code, as opposed to a \textit{grid - array} that is declared in an \verb|interface.ccl|. Cactus knows - nothing about local arrays. + An array that is declared in thorn code but not declared in + the thorn's \verb|interface.ccl|, as opposed to a \textit{grid + array}. \item[local interpolation] Given $N$ arrays on the current processor with a given coordinate system, and $C$ interpolation points (in the array coordinate space) return $M$ values at each interpolation point. (See also \textit{interpolation}) +\item[Makefile] + The default input file for \texttt{make} (or \texttt{gmake}). Includes + rules for building targets. +\item[make] A system for building software. It uses rules involving + dependencies of one part of software on another, and information of what + has changed since the last build, to determine what parts need to be + built. \item[MPI] \textit{Message Passing Interface}, an API and software library for sending messages between processors in a multiprocessor system. + See Sections~\ref{subsec:Compilation-Available_Options}, + \ref{subsubsec:Compiling-MPI}. \item[mutual recursion] See \textit{recursion, mutual}. \item[NUL character] @@ -185,32 +216,60 @@ Cactus Users' Guide and the Cactus Reference Manual. For further information, see the section ``Null pointers'' in the (excellent) {\tt comp.lang.c FAQ}, available online at \url{http://www.eskimo.com/~scs/C-faq/top.html}. +\item[parallelisation] \item[parameter] A variable which remains unchanged throughout the execution of a Cactus executable. Parameters all have default values which can be changed in a parameter file. \item[processor topology] \item[PUGH] - The default parallel driver for Cactus which uses MPI. + The default driver thorn for Cactus which uses MPI. + See Section~\ref{sec:required_software}. \item[PVM] - \textit{Parallel Virtual Machine}, provides interprocessor - communication. + \textit{Parallel Virtual Machine}, provides interprocessor communication. + See Section~\ref{sec:required_software}. \item[recursion, mutual] See \textit{mutual recursion}. \item[reduction] Given $N$ grid variables return $M$ output values on each requested processor. +\item[schedule] +\item[schedule bin] +\item[schedule group] +\item[shares] An implementation may \textit{share} restricted parameters + with another implementation. + See Section~\ref{subsec:param_ccl}. \ref{sec:Appendix.param}. +\item[staggering] + See Section~\ref{sec:staggering}. \item[symmetry zone] A symmetry zone is a set of points added to the edge of a grid to contain data which is obtained, by some symmetry operation, from another part of the grid. (See also \textit{boundary zone}, \textit{ghost zone}.) +\item[synchronisation] \item[TAGS] + See Section~\ref{sec:Appendix.tags}. \item[target] + A \textit{make target} is the name of a set of rules for + \texttt{make} (or \texttt{gmake}). When the target is included in the + command line for \texttt{make} the rules are executed, usually to + build some software. +\item[test suite] + See Sections~\ref{sec:testing}, \ref{sec:adding_test_suite}. \item[thorn] - A collection of subroutines with a definite interface and purpose. + A collection of subroutines defining a Cactus interface. + See Chapters~\ref{chap:thorn_concepts}, \ref{chap:thorn_anatomy}. +\item[ThornList] +\item[time bin] +\item[time level] +\item[timer] +\item[trigger] +\item[unigrid] \item[WMPI] \textit{Win32 Message Passing Interface}. + See Sections~\ref{subsec:Compilation-Available_Options}, + \ref{subsubsec:Compiling-MPI}. +\item[wrapper] \end{Lentry} @@ -219,10 +278,9 @@ Cactus Users' Guide and the Cactus Reference Manual. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Configuration file syntax} -\label{sec:cofisy} +\label{sec:Appendix.ccl} \section{General Concepts} -\label{sec:geco} Each thorn is configured by three compulsory and one optional files in the top level thorn directory: @@ -242,7 +300,7 @@ case insensitive. % course be enclosed in []). \section{interface.ccl} -\label{sec:in} +\label{sec:Appendix.interface} The interface configuration file consists of \begin{itemize} @@ -254,15 +312,15 @@ thorns, and which include files are provided by this thorn \item a series of blocks listing the thorn's global variables. \end{itemize} (For a more extensive discussion of Cactus variables see Chapter -\ref{chap:cava}.) +\ref{chap:cactus_variables}.) \subsection{Header block} The header block has the form: -\begin{verbatim} -implements: <implementation> -inherits: <implementation>, <implementation> -friend: <implementation>, <implementation> -\end{verbatim} +\begin{alltt} +implements: <\var{implementation}> +inherits: <\var{implementation}>, <\var{implementation}> +friend: <\var{implementation}>, <\var{implementation}> +\end{alltt} where \begin{itemize} \item{} The implementation name must be unique among all thorns, except @@ -283,13 +341,13 @@ where \subsection{Include files} The include file section has the form: -\begin{verbatim} -USES INCLUDE [SOURCE|HEADER]: <file_name> -INCLUDE[S] [SOURCE|HEADER]: <file_to_include> in <file_name> -\end{verbatim} +\begin{alltt} +USES INCLUDE [SOURCE|HEADER]: <\var{file_name}> +INCLUDE[S] [SOURCE|HEADER]: <\var{file_to_include}> in <\var{file_name}> +\end{alltt} The former is used when a thorn wishes to use an include file from another thorn. The latter indicates that this thorn adds the code in -\verb|<file_to_include>| to the include file \verb|<file_name>|. If +\texttt{<\var{file\_to\_include}>} to the include file \texttt{<\var{file\_name}>}. If the include file is described as \verb|SOURCE|, the included code is only executed if the providing thorn is active. Both default to \verb|HEADER|. @@ -297,42 +355,42 @@ Both default to \verb|HEADER|. \subsection{Function aliasing} If any aliased function is to be used or provided by the thorn then the prototype must be declared with the form: -\begin{verbatim} -<return_type> FUNCTION <alias>(<arg1_type> <intent1> [ARRAY] <arg1>, ...) -\end{verbatim} -The \verb|<return_type>| must be either \verb|void|, \verb|CCTK_INT| +\begin{alltt} +<\var{return_type}> FUNCTION <\var{alias}>(<\var{arg1_type}> <\var{intent1}> [ARRAY] <\var{arg1}>, ...) +\end{alltt} +The \texttt{<\var{return\_type}>} must be either \verb|void|, \verb|CCTK_INT| or \verb|CCTK_REAL|. The keyword \verb|SUBROUTINE| is equivalent to -\verb|void FUNCTION|. The name of the aliased function \verb|<alias>| +\verb|void FUNCTION|. The name of the aliased function \texttt{<\var{alias}>} must contain at least one uppercase and one lowercase letter and follow the C standard for function names. The type of each argument, -\verb|<arg*_type>| must be a \verb|CCTK| type in +\texttt{<\var{arg*\_type}>} must be a \verb|CCTK| type in \verb|INT,REAL,STRING,POINTER|. The intent of each argument, -\verb|<intent*>| must be either \verb|IN| or \verb|OUT|. An argument +\texttt{<\var{intent*}>} must be either \verb|IN| or \verb|OUT|. An argument should only be modified if it is declared to have intent \verb|OUT|. If the argument is an array then the prefix \verb|ARRAY| should also be given. -If the argument \verb|<arg*>| is a function pointer then the argument +If the argument \texttt{<\var{arg*}>} is a function pointer then the argument itself (which will preceded by the return type) should be -\begin{verbatim} -CCTK_FPOINTER <function_arg1>(<arg1_type> <intent1> <arg1>, ...) -\end{verbatim} +\begin{alltt} +CCTK_FPOINTER <\var{function_arg1}>(<\var{arg1_type}> <\var{intent1}> <\var{arg1}>, ...) +\end{alltt} Function pointers may not be nested. If an aliased function is to be used then the block -\begin{verbatim} -USES FUNCTION <alias> -\end{verbatim} +\begin{alltt} +USES FUNCTION <\var{alias}> +\end{alltt} is required. If a function is provided then the block -\begin{verbatim} -PROVIDES FUNCTION <alias> WITH <provider> LANGUAGE <providing_language> -\end{verbatim} -is required. As with the alias name, \verb|<provider>| must contain at +\begin{alltt} +PROVIDES FUNCTION <\var{alias}> WITH <\var{provider}> LANGUAGE <\var{providing_language}> +\end{alltt} +is required. As with the alias name, \texttt{<\var{provider}>} must contain at least one uppercase and one lowercase letter and follow the C standard for function names. Currently the only supported values of -\verb|<providing_language>| are \verb|C| and \verb|Fortran|. +\texttt{<\var{providing\_language}>} are \verb|C| and \verb|Fortran|. \subsection{Variable blocks} @@ -342,37 +400,37 @@ Storage assignment, communication assignment, and ghostzone synchronization take place for groups only. The thorn's variables are defined by: -{\t -\begin{verbatim} -[<access>:] - -<data_type> <group_name>[[<number>]] [TYPE=<group_type>] [DIM=<dim>] -[TIMELEVELS=<num>] -[SIZE=<size in each direction>] [DISTRIB=<distribution_type>] -[GHOSTSIZE=<ghostsize>] [STAGGER=<stagger-specification>] -[TAGS=<string>] ["<group_description>"] -[{ - [ <variable_name>[,]<variable_name> - <variable_name> ] -} ["<group_description>"] ] -\end{verbatim}} + +\begin{alltt} +[<\var{access}>:] + +<\var{data_type}> <\var{group_name}>[[<\var{number}>]] [TYPE=<\var{group_type}>] [DIM=<\var{dim}>] +[TIMELEVELS=<\var{num}>] +[SIZE=<\var{size in each direction}>] [DISTRIB=<\var{distribution_type}>] +[GHOSTSIZE=<\var{ghostsize}>] [STAGGER=<\var{stagger-specification}>] +[TAGS=<\var{string}>] ["<\var{group_description}>"] +[\{ + [ <\var{variable_name}>[,]<\var{variable_name}> + <\var{variable_name}> ] +\} ["<\var{group_description}>"] ] +\end{alltt} % -(The options {\t TYPE}, {\t DIM}, etc.\ following {\t <group\_name>} +(The options {\t TYPE}, {\t DIM}, etc.\ following {\t <\var{group\_name}>} must all appear on one line.) Note that the beginning brace (\{) must sit on a line by itself; the ending brace (\}) must be preceded by a carriage return. % \begin{itemize} -\item{} {\t access} defines which thorns can use the following - groups of variables. {\t access} can be either +\item{} {\t \var{access}} defines which thorns can use the following + groups of variables. {\t \var{access}} can be either {\t public}, {\t protected} or {\t private}. -\item{} {\t data\_type} defines the data type of the variables in the +\item{} {\t \var{data\_type}} defines the data type of the variables in the group. Supported data types are {\t CHAR}, {\t BYTE}, {\t INT}, {\t REAL} and {\t COMPLEX}. -\item{} {\t group\_name} must be an alphanumeric name (which may also +\item{} {\t \var{group\_name}} must be an alphanumeric name (which may also contain underscores) which is unique across group and variable names within the scope of the thorn. A group name is compulsory. -\item{} {\t [number]}, if present, indicates that this is a \emph{vector} +\item{} {\t [\var{number}]}, if present, indicates that this is a \emph{vector} group. Such a group does not have named variables (so the \{\} block should not be present) but instead appears as a one-dimensional array of grid variables. The first index in the array is the member-index, @@ -425,7 +483,7 @@ The process of sharing code among thorns using include files is discussed in Section~\ref{sec:includefiles}. \section{param.ccl} -\label{sec:pa} +\label{sec:Appendix.param} The parameter configuration file consists of a list of \textit{parameter object specification items} (OSIs) giving the type and @@ -435,14 +493,14 @@ parameter. (For a more extensive discussion of Cactus parameters see Chapter \ref{chap:capa}.) \subsection{Parameter data scoping items} -{\tt -\begin{verbatim} -<access>: -\end{verbatim} -} -The key word {\t access} designates that all parameter object specification + +\begin{alltt} +<\var{access}>: +\end{alltt} + +The key word {\t \var{access}} designates that all parameter object specification items up to the next parameter data scoping item are in the same -protection or scoping class. {\tt access} can take the values: +protection or scoping class. {\tt \var{access}} can take the values: \begin{Lentry} \item[{\tt global}] all thorns have access to global parameters \item[{\tt restricted}] other thorns can have access to these @@ -458,53 +516,46 @@ on this line.) \subsection{Parameter object specification items} -\label{sec:paobspit} -{\t -\begin{verbatim} -[EXTENDS|USES] <parameter_type> <parameter name>[[<integer>]] "<parameter description>" -[AS <alias>] [STEERABLE=<NEVER|ALWAYS|RECOVER>] -[ACCUMULATOR=<expression>] [ACCUMULATOR-BASE=<parameter-name>] -{ - <PARAMETER_VALUES> -} <default value> -\end{verbatim} -} -Where the options {\t AS}, {\t STEERABLE}, etc. following {\t <parameter\_description>} +\begin{alltt} +[EXTENDS|USES] <\var{parameter_type}> <\var{parameter name}>[[<\var{integer}>]] "<\var{parameter description}>" +[AS <\var{alias}>] [STEERABLE=<NEVER|ALWAYS|RECOVER>] +[ACCUMULATOR=<\var{expression}>] [ACCUMULATOR-BASE=<\var{parameter-name}>] +\{ + <\var{PARAMETER_VALUES}> +\} <\var{default value}> +\end{alltt} +where the options {\t AS}, {\t STEERABLE}, etc. following {\t <\var{parameter\_description}>} must all appear on one line. Note that the beginning brace ({\t\{}) must sit on a line by itself; the ending brace ({\t\}}) must be preceded by a carriage return. \begin{itemize} -\item{} Allowed {\t parameter\_type}s are +\item{} Allowed {\t \var{parameter\_type}}s are \begin{Lentry} - \item[{\t INT}] The specification of {\t parameter\_value}s takes + \item[{\t INT}] The specification of \var{parameter\_value}s takes the form of any number of comma-separated blocks of the form: -{\t -\begin{verbatim} -[<low-range>][:[<high-range>][:[<step>]]][::"<range description>"] -\end{verbatim} -} -Where an empty field, or a {\t *} in the place of {\tt low-range} or -{\t high-range} indicates $-\infty$ and $\infty$ respectively. The -default value for {\t step} is 1. A number by itself denotes that +\begin{alltt} +[<\var{low-range}>][:[<\var{high-range}>][:[<\var{step}>]]][::"<\var{range description}>"] +\end{alltt} +where an empty field, or a {\t *} in the place of \var{low-range} or +\var{high-range} indicates $-\infty$ and $\infty$ respectively. The +default value for \var{step} is 1. A number by itself denotes that this number is the only acceptable value. \item[{\t REAL}] The range specification is the same as integers, - except that here, no {\t step} implies a continuum of + except that here, no \var{step} implies a continuum of values. Note that numeric constants should be expressed as in C (e.g.\ {\t 1e-10}). Note also that one can use the Cactus types such as {\t CCTK\_REAL4} to specify the precision of the parameter. \item[{\t KEYWORD}] Each entry in the list of acceptable values for a keyword has the form -{\t -\begin{verbatim} -"<keyword value>", "<keyword value>" :: "<description>" -\end{verbatim} -} +\begin{alltt} +"<\var{keyword value}>", "<\var{keyword value}>" :: "<\var{description}>" +\end{alltt} \item[{\t STRING}] Allowed values for strings should be specified using regular expressions. To allow any string, the regular expression {\tt ".*"} should be used. - \item[{\t BOOLEAN}] No {\t PARAMETER\_VALUES} should be specified for a boolean + \item[{\t BOOLEAN}] No \var{PARAMETER\_VALUES} should be specified for a boolean parameter. The default value for a boolean can be \begin{itemize} \item{} True: {\t 1}, {\t yes}, {\t y}, {\t t}, {\t true} @@ -512,7 +563,7 @@ as {\t CCTK\_REAL4} to specify the precision of the parameter. \end{itemize} \end{Lentry} -\item{} The {\t parameter name} must be unique within the scope of the thorn. +\item{} The \var{parameter name} must be unique within the scope of the thorn. \item{} A thorn can declare that it {\t EXTENDS} a parameter of another thorn. This allows it to declare additional acceptable values. @@ -522,13 +573,13 @@ another thorn. This allows it to declare additional acceptable values. \item{} If the thorn wants to simply use a parameter from another thorn, without declaring additional values, use {\t USES} instead. -\item{} {\tt [integer]}, if present, specifies that this is an {\tt +\item{} {\tt [\var{integer}]}, if present, specifies that this is an {\tt array} parameter. (Note that the notation used above for the parameter specification breaks down here, there must be square brackets around the given integer). The parameter is then a one-dimensional array of values of the specified type. -\item{} {\t alias} allows a parameter to appear as a different name in +\item{} \var{alias} allows a parameter to appear as a different name in this thorn than its original name in another thorn. The name as seen in the parameter file is unchanged. \item{} {\t STEERABLE} specifies when a parameter value may be @@ -552,7 +603,7 @@ instead. \end{itemize} \section{schedule.ccl} -\label{sec:sc} +\label{sec:Appendix.schedule} (A more extensive discussion of Cactus scheduling is provided in Chapter \ref{chap:scheduling}.) A schedule configuration file consists of @@ -574,10 +625,9 @@ instead. \textit{Assignment statements}, currently only assign storage. These lines have the form: -{\t -\begin{verbatim}[STORAGE: <group>[timelevels], <group>[timelevels]] -\end{verbatim} -} +\begin{alltt} +[STORAGE: <\var{group}>[\var{timelevels}], <\var{group}>[\var{timelevels}]] +\end{alltt} If the thorn is active, storage will be allocated for the given groups for the duration of program execution (unless storage is explicitly @@ -597,36 +647,37 @@ block). \subsection{Schedule Blocks} Each \textit{schedule block} in the file {\t schedule.ccl} must have the syntax: -{\t -\begin{verbatim}schedule [GROUP] <function name|group name> AT|IN <time> \ - [BEFORE|AFTER <function name>] [WHILE <variable>] [AS <alias>] -{ - [LANG: <language>] - [STORAGE: <group>[timelevels],<group>[timelevels]...] - [TRIGGER: <group>,<group>...] - [SYNCHRONISE: <group>,<group>...] - [OPTIONS: <option>,<option>...] -} "Description of function" -\end{verbatim} -} + +\begin{alltt} +schedule [GROUP] <\var{function name}|\var{group name}> AT|IN <\var{time}> \verb|\| + [BEFORE|AFTER <\var{function name}>] [WHILE <\var{variable}>] [AS <\var{alias}>] +\{ + [LANG: <\var{language}>] + [STORAGE: <\var{group}>[\var{timelevels}],<\var{group}>[\var{timelevels}]...] + [TRIGGER: <\var{group}>,<\var{group}>...] + [SYNCHRONISE: <\var{group}>,<\var{group}>...] + [OPTIONS: <\var{option}>,<\var{option}>...] +\} "\var{Description of function}" +\end{alltt} + \begin{Lentry} \item[{\tt GROUP}] Schedule a schedule group with the same options as a schedule function. The schedule group will be created if it doesn't exist. - \item[{\tt <function name|group name>}] The name of a function or a + \item[{\tt <\var{function name}|\var{group name}>}] The name of a function or a schedule group to be scheduled. Function and schedule group names are case sensitive - \item[{\tt <group>}] A group of grid variables. Variable groups + \item[{\tt <\var{group}>}] A group of grid variables. Variable groups inherited from other thorns may be used, but they must then be fully qualified with the implementation name. \item[{\tt AT}] Functions can be scheduled to run at the Cactus schedule bins, for example {\tt CCTK\_EVOL}, {\tt CCTK\_STARTUP}. A complete list and description of these is provided in - Appendix~\ref{sec:scbi}. The initial letters {\tt CCTK\_} are - optional. Grid variables cannot be used in the {\tt CCTK\_STARTUP} - and {\tt CCTK\_SHUTDOWN} timebins. + Appendix~\ref{sec:Appendix.schedule_bins}. The initial letters + {\tt CCTK\_} are optional. Grid variables cannot be used in the + {\tt CCTK\_STARTUP} and {\tt CCTK\_SHUTDOWN} timebins. \item[{\tt IN}] Schedules a function or schedule group to run in a schedule group rather than in a Cactus timebin. @@ -694,14 +745,13 @@ Any schedule block or assignment statements can be optionally surrounded by conditional {\t if-elseif-else} constructs using the parameter data base. These can be nested, and have the general form: -{\t -\begin{verbatim} -if (CCTK_Equals(<parameter>,<string>)) -{ - [<assignments>] - [<schedule blocks>] -}\end{verbatim} -} + +\begin{alltt} +if (CCTK_Equals(<\var{parameter}>,<\var{string}>)) +\{ + [<\var{assignments}>] + [<\var{schedule blocks}>] +\}\end{alltt} Such conditionals are evaluated only at program startup and are used to pick between different static schedule options. For dynamic @@ -712,13 +762,13 @@ Conditional constructs cannot be used inside a schedule block. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{configuration.ccl} -\label{sec:configuration.ccl} +\label{sec:Appendix.configuration.ccl} A configuration options file has the form: -\begin{verbatim} -Requires Thorns: <list of thorns> -\end{verbatim} +\begin{alltt} +Requires Thorns: <\var{list of thorns}> +\end{alltt} The \verb|Requires Thorns| configuration option has as its argument a case sensitive, space-separated list of thorn names (without the name @@ -743,7 +793,7 @@ in order to call routines, you should use rather function aliasing. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Schedule bins} -\label{sec:scbi} +\label{sec:Appendix.schedule_bins} Using the {\tt schedule.ccl} files, thorn functions can be scheduled to run in the different timebins which are executed by the Cactus Flesh. This chapter @@ -906,7 +956,6 @@ indicate whether an error occurred. You should return 0. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Flesh parameters} -\label{sec:ccpa} The Flesh parameters are defined in the file {\tt src/param.ccl}. @@ -992,6 +1041,7 @@ Terminate on next iteration ? [{\tt no}] %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Using GNATS} +\label{sec:Appendix.gnats} GNATS is a freely redistributable set of tools for tracking bug reports. It allows users to categorize their problem report and submit them to the GNATS. The bug tracker will assign appropriate maintainers @@ -1043,14 +1093,13 @@ our web site. These commands are compiled to submit Cactus problem reports in your shell and from within Emacs, respectively. -\label{sec:usgn} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Using CVS} -\label{sec:uscv} +\label{sec:Appendix.cvs} CVS is a version control system, which allows you to keep old versions of files (usually source code), log of when, and why changes occurred, and who made them, etc. @@ -1388,14 +1437,13 @@ home directory which provides menus to pick arrangements and thorns from. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Using Tags} -\label{sec:usta} +\label{sec:Appendix.tags} Finding your way around in the Cactus structure can be pretty difficult to handle. To make life easier there is support for \textit{tags}, which lets you browse the code easily from within Emacs/XEmacs or {\tt vi}. A tags database can be generated with {\tt gmake}: \section{Tags with Emacs} -\label{sec:tawiem} The command {\tt gmake TAGS} will create a database for a routine reference table to be used within Emacs. This database can be accessed within @@ -1434,7 +1482,6 @@ The key strokes to use when you want to browse in read-only mode are: \end{enumerate} \section{Tags with {\tt vi}} -\label{sec:tawivi} The commands available are highly dependent upon the version of {\tt vi}, but the following is a selection of commands which may work. diff --git a/doc/UsersGuide/RunningCactus.tex b/doc/UsersGuide/RunningCactus.tex index eb941021..f7239de9 100644 --- a/doc/UsersGuide/RunningCactus.tex +++ b/doc/UsersGuide/RunningCactus.tex @@ -22,7 +22,7 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Required software} -\label{sec:reqo} +\label{sec:required_software} In general, Cactus \emph{requires} the following set of software to function in single processor mode. Please refer to the architecture section @@ -91,8 +91,8 @@ it is useful to install \item[{\tt ctags/etags}] These programs enable you browse through the calling structure of a program by help of a function call database. Navigating the Flesh and arrangements becomes very easy. Emacs and - {\tt vi} both support this method. See \ref{sec:usta} for a short guide - to ``tags''. + {\tt vi} both support this method. See \ref{sec:Appendix.tags} for a short + guide to tags. \end{Lentry} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -112,7 +112,8 @@ be found at \begin{Lentry} \item[\textbf{SGI}] 32 or 64 bit running Irix. \item[\textbf{Cray T3E}] -\item[\textbf{Compaq Alpha}] Compaq operating system and Linux. Single processor +\item[\textbf{Compaq Alpha}] Compaq operating system and Linux. + Single processor mode and MPI supported. The Alphas need to have the GNU C/C++ compilers installed. \item[\textbf{IA32}] running Linux or Windows 2000/NT. Single @@ -158,7 +159,7 @@ The following machines are only partially supported %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Checkout procedure} -\label{sec:chpr} +\label{sec:checkout} Cactus is distributed, extended, and maintained using the free CVS software (\textit{Concurrent Versions System}: \url{http://www.cvshome.org}). @@ -169,9 +170,9 @@ main CVS site, and from a growing number of user sites, we provide a script, described below, on our web site for checking out the Flesh and thorns. The Cactus web site also provides a form interface for direct download. -CVS experts who want to use raw CVS commands are directed to Appendix~\ref{sec:uscv} -for full instructions. For CVS novices, we also summarize in this -appendix basic CVS commands. +CVS experts who want to use raw CVS commands are directed to +Appendix~\ref{sec:Appendix.cvs} for full instructions. For CVS novices, +we also summarize in this appendix basic CVS commands. The space required for an installation depends on the arrangements and thorns used. The Flesh on its own requires less than 5 MB. @@ -184,11 +185,11 @@ from the web site at The script takes as an argument the name of a file containing a \textit{ThornList}, that is a list of thorns with the syntax -{\tt -\begin{verbatim} -<arrangement name>/<thorn name> -\end{verbatim} -} + +\begin{alltt} +<\var{arrangement name}>/<\var{thorn name}> +\end{alltt} + If no filename is given, only the Flesh is checked out. Optional directives in the ThornList indicate which CVS repository to fetch thorns from. The default is to take the thorns from the same repository as @@ -241,7 +242,7 @@ scratch/cactus\_configs Cactus/configs/}) to the Cactus directory, if your filesystem supports soft links. \end{itemize} -Configurations are described in detail in section \ref{sec:coaco}. +Configurations are described in detail in section \ref{sec:configurations}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -254,7 +255,7 @@ system published under the GNU license. We have set up a web interface at of problem reports. A description of the GNATS categories which we use is provided in the appendix -\ref{sec:usgn}. +\ref{sec:Appendix.gnats}. % OK, there is NO emacs at the moment, because the GNATS setup is really stupid % and sendpr handles like c.... besides the fact, that the user has to go @@ -299,7 +300,7 @@ will compile the code. The first time it generates a compile %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Creating a configuration} -\label{sec:coaco} +\label{sec:configurations} At its simplest, this is done by {\tt gmake <config>}\footnote % @@ -354,7 +355,7 @@ configuration file or the command line will overwrite completely the default values. \subsection{Available options} -\label{Compilation-Available_Options} +\label{subsec:Compilation-Available_Options} There is a plethora of available options. @@ -370,7 +371,7 @@ is automatically created, and the users prompted for any changes. \item [{\tt THORNLIST}] Name of file containing a list of thorns with the syntax {\tt <arrangement name>/<thorn name>}, lines beginning with -{\tt \#} or {\tt !} are ignored. +\verb|#| or {\tt !} are ignored. \item [{\tt THORNLIST\_DIR}] Location of directory containing {\tt THORNLIST}. This defaults to the current working directory. @@ -438,14 +439,14 @@ Whether error messages and debug information in the compiled C and C++ files should point to the original source file or to an internal file created by Cactus. The only options available are {\tt yes} and {\tt no}, the default is {\tt yes}. Set this to {\tt no} if your compiler -reports error messages about unrecognised {\tt #} directives. +reports error messages about unrecognised \verb|#| directives. \item [{\tt F\_LINE\_DIRECTIVES}] Whether error messages and debug information in the compiled Fortran files should point to the original source file or to an internal file created by Cactus. The only options available are {\tt yes} and {\tt no}, the default is {\tt yes}. Set this to {\tt no} if your compiler -reports error messages about unrecognised {\tt #} directives. +reports error messages about unrecognised \verb|#| directives. \item [{\tt DEBUG}] * Specifies what type of debug mode should be used, @@ -547,7 +548,7 @@ values will be valid on all architectures. \item{Extra packages} Compiling with extra packages is described fully in -Section \ref{sec:cowiexpa}, +Section \ref{subsec:cowiexpa}, which should be consulted for the full range of configuration options. \begin{Lentry} @@ -584,10 +585,11 @@ commands that it is executing. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Compiling with extra packages} -\label{sec:cowiexpa} +\label{subsec:cowiexpa} \subsubsection{MPI: Message Passing Interface} +\label{subsubsec:Compiling-MPI} The \textit{Message Passing Interface} (MPI) provides inter-processor communication. It can either be implemented natively on a machine @@ -691,6 +693,7 @@ Note that the searches for libraries etc. mentioned above use the locations given in the files in {\tt lib/make/extras/MPI}. \subsubsection{HDF5: Hierarchical Data Format version 5} +\label{subsec:hdf5} To compile with HDF5 (\url{http://hdf.ncsa.uiuc.edu/whatishdf5.html}), the configure options are @@ -910,7 +913,7 @@ by configure and the {\tt ThornList} file remain. \item [{\tt gmake <config>-rebuild}] rebuilds a configuration (reruns the CST). \item [{\tt gmake <config>-testsuite}] runs the test programs associated with - each thorn in the configuration. See section \ref{sec:te} for information about the + each thorn in the configuration. See section \ref{sec:testing} for information about the testsuite mechanism. \item [{\tt gmake <config>-thornlist}] regenerates the {\tt ThornList} for a configuration. @@ -943,15 +946,15 @@ you will be shown a list of all the thorns in your arrangement directory, and asked if you with to edit them. You can regenerate this list at anytime by typing -\begin{verbatim} -gmake <config>-thornlist -\end{verbatim} +\begin{alltt} +gmake <\var{config}>-thornlist +\end{alltt} or you can edit it using -\begin{verbatim} -gmake <config>-editthorns -\end{verbatim} +\begin{alltt} +gmake <\var{config}>-editthorns +\end{alltt} Instead of using the editor to specify the thorns you want to have compiled, you can \emph{edit} the {\tt ThornList} outside @@ -1026,10 +1029,10 @@ the Cactus root directory. % (usually \texttt{Cactus}). information and creating template files. \item [{\tt gmake TAGS}] creates an Emacs style TAGS file. See section - \ref{sec:usta} for using tags within Cactus. + \ref{sec:Appendix.tags} for using tags within Cactus. \item [{\tt gmake tags}] creates a {\tt vi} style tags file. See section - \ref{sec:usta} for using tags within Cactus. + \ref{sec:Appendix.tags} for using tags within Cactus. \item [{\tt gmake UsersGuide}] runs LaTeX to produce a copy of the Users' Guide. @@ -1044,7 +1047,7 @@ configuration found in user's \texttt{configs} subdirectory. \section{Testing} -\label{sec:te} +\label{sec:testing} Some thorns come with a testsuite, consisting of example parameter files and the output files generated by running these. To run the testsuite @@ -1318,34 +1321,27 @@ As the program runs, the normal output provides the following information: shows whether the activation was successful, and if successful gives the thorn's implementation. For example -{\tt \begin{verbatim} Activating thorn idscalarwave...Success -> active implementation idscalarwave \end{verbatim} -} \item [Failed parameters] If any of the parameters in the parameter file does not belong to any of the active thorns, or if the parameter value is not in the allowed range, an error is registered. For example, if the parameter is not recognised -{\tt \begin{verbatim} Unknown parameter time::ddtfac \end{verbatim} -} or if the parameter value is not in the allowed range -{\tt \begin{verbatim} Unable to set keyword CartGrid3D::type - ByMouth not in any active range \end{verbatim} -} \item [Scheduling information] A complete list of all scheduled routines is given, in the order that they will be executed. For example -{\tt \begin{verbatim} ---------------------------------------------------------------------- Startup routines @@ -1377,7 +1373,6 @@ order that they will be executed. For example enddo ---------------------------------------------------------------------- \end{verbatim} -} \item [Thorn banners] Any banners registered from the thorns are displayed. @@ -1404,6 +1399,7 @@ directory from which the executable is run. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Checkpointing/Recovery} +\label{sec:checkpointing} Checkpointing is defined as saving the current state of a run (parameter settings, contents of grid variables, and other relevant information) to a file. diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex index 1464990a..9f5a9940 100644 --- a/doc/UsersGuide/ThornWriters.tex +++ b/doc/UsersGuide/ThornWriters.tex @@ -38,6 +38,7 @@ you may use to gain extra functionality. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Thorn concepts} +\label{chap:thorn_concepts} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -62,6 +63,7 @@ for arrangement documentation. Arrangement names which start with a %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Arrangements} +\label{sec:arrangements} Thorns are grouped into \textit{arrangements}. This is a logical grouping of thorns which is purely for organisational purposes. For example, @@ -84,7 +86,7 @@ belonging to the arrangement. \section{Implementations} -\label{sec:im} +\label{sec:implementations} One of the key concepts for thorns is the concept of the \textit{implementation}. Relationships among thorns are all based upon relationships among the @@ -113,25 +115,25 @@ the other thorns. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Anatomy of a thorn} -\label{sec:anofath} +\label{chap:thorn_anatomy} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Thorns} -\label{sec:th} A thorn consists of a subdirectory of an arrangement containing four administrative files: \begin{Lentry} \item[{\tt interface.ccl}] the Cactus interface, which defines the grid -functions, variables, etc. See \ref{sec:in}. +functions, variables, etc. See \ref{sec:Appendix.interface}. \item[{\tt param.ccl}] the parameters introduced by this thorn, and the parameters needed from other thorns. See -\ref{sec:pa}. +\ref{sec:Appendix.param}. \item[{\tt schedule.ccl}] scheduling information for routines called by +the Flesh. See \ref{sec:Appendix.schedule}. \item[{\tt configuration.ccl}] configuration options for the thorn. See -\ref{sec:configuration.ccl}. +\ref{sec:Appendix.configuration.ccl}. \end{Lentry} Thorns can also contain @@ -143,7 +145,7 @@ Thorns can also contain \item a {\tt doc} directory for documentation \item a {\tt par} directory for example parameter files \item a {\tt test} subdirectory may also be added, to hold the thorn's - test suite. See \ref{sec:adatesu} for details. + test suite. See \ref{sec:adding_test_suite} for details. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -173,8 +175,8 @@ These are: \begin{Lentry} \item [{\tt interface.ccl}] -This defines the \textit{implementation} (Section~\ref{sec:im}) the thorn -provides, and the variables the thorn needs, along with their +This defines the \textit{implementation} (Section~\ref{sec:implementations}) +the thorn provides, and the variables the thorn needs, along with their visibility to other implementations. \item [{\tt param.ccl}] @@ -201,6 +203,7 @@ non-blank character of a line in a CCL file is a backslash following line is treated as a continuation of the current line. \subsection{The {\tt interface.ccl} file} +\label{subsec:interface_ccl} The {\tt interface.ccl} file is used to declare @@ -213,10 +216,10 @@ The {\tt interface.ccl} file is used to declare The implementation is declared by a single line at the top of the file -\begin{verbatim} -implements: <name> -\end{verbatim} -where {\tt <name>} can be any combination of alphanumeric +\begin{alltt} +implements: <\var{name}> +\end{alltt} +Where {\tt <\var{name}>} can be any combination of alphanumeric characters and underscores, and is case independent. There are three different access levels available for variables @@ -235,30 +238,30 @@ Corresponding to the first two access levels there are two relationship statements that can be used to get variables from other thorns. \begin{Lentry} -\item [{\tt Inherits: <name>}] -This gets all {\tt Public} variables from implementation {\tt <name>}, and all -variables that {\tt <name>} has in turn inherited. +\item [{\tt Inherits: <\var{name}>}] +This gets all {\tt Public} variables from implementation {\tt <\var{name}>}, and all +variables that {\tt <\var{name}>} has in turn inherited. An implementation may inherit from any number of other implementations. -\item [{\tt Friend: <name>}] -This gets all {\tt Protected} variables from implementation {\tt <name>}, but, +\item [{\tt Friend: <\var{name}>}] +This gets all {\tt Protected} variables from implementation {\tt <\var{name}>}, but, unlike {\tt inherits}, it is symmetric and also defines a transitive relation by pushing its own implementation's {\tt Protected} variables onto implementation -{\tt <name>}. This keyword is used to define a group of implementations which +\var{name}. This keyword is used to define a group of implementations which all end up with the same {\tt Protected} variables. \end{Lentry} So, for example, an {\tt interface.ccl} starting -\begin{verbatim} +\begin{alltt} implements: wavetoy inherits: grid friend: wave_extract -\end{verbatim} +\end{alltt} declares that the thorn provides an implementation called {\tt wavetoy}, gets all the {\tt public} variables declared by an implementation called {\tt grid}, and shares all {\tt protected} variables with {\tt wave\_extract} and its friends. -Cactus variables, described in Chapter~\ref{chap:cava}, are placed +Cactus variables, described in Chapter~\ref{chap:cactus_variables}, are placed in groups with homogeneous attributes, where the attributes describe properties such as the data type, group type, dimension, ghostsize, number of timelevels, type of staggering and @@ -293,6 +296,7 @@ changes the access level for any group defined in the file from that point on. All variables seen by any one thorn must have distinct names. \subsection{The {\tt param.ccl} file} +\label{subsec:param_ccl} Users control the operation of thorns via parameters given in a file at runtime. The {\tt param.ccl} file @@ -394,9 +398,9 @@ specification of the form {\tt global:} or {\tt restricted:} (or changes the access level for any parameter defined in the file from that point on. To access {\tt restricted} parameters from another implementation, a line -containing {\tt shares: <name>} declares that all parameters mentioned in +containing {\tt shares: <\var{name}>} declares that all parameters mentioned in the file from now until the next access specification originate in -implementation {\tt <name>}. (Note that only one implementation can be +implementation {\tt <\var{name}>}. (Note that only one implementation can be specified on each {\tt shares:} line.) 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. @@ -439,18 +443,20 @@ conditions they should be run. The specification of routine scheduling is via a schedule block which consists of lines of the form -\begin{verbatim} -schedule <name> at <time bin> [other options] -{ +\begin{alltt} +schedule <\var{name}> at <\var{time bin}> [\var{other options}] +\{ LANG: <FORTRAN|C> - STORAGE: [group list with timelevels] - TRIGGERS: [group list] - SYNC: [group list] -} "A description" -\end{verbatim} -where {\tt <name>} is the name of the routine, and {\tt <time bin>} is the -name of a schedule bins (the {\tt CCTK\_} prefix is optional). A list of -the most useful schedule bins for application thorns is given here, a complete and more descriptive list is provided in Appendix~\ref{sec:scbi}: + STORAGE: [\var{group list with timelevels}] + TRIGGERS: [\var{group list}] + SYNC: [\var{group list}] +\} "\var{A description}" +\end{alltt} +where {\tt <\var{name}>} is the name of the routine, and +{\tt <\var{time bin}>} is the name of a schedule bins (the {\tt CCTK\_} +prefix is optional). A list of the most useful schedule bins for application +thorns is given here, a complete and more descriptive list is provided in +Appendix~\ref{sec:Appendix.schedule_bins}: \begin{Lentry} @@ -485,10 +491,10 @@ For analysing data. \end{Lentry} -The {\tt other options} allow finer grained control of the scheduling. It is +The \var{other options} allow finer grained control of the scheduling. It is possible to state that the routine must run {\tt BEFORE} or {\tt AFTER} another routine. It is also possible to schedule the routine under an -alias name by using {\tt AS <alias\_name>}. +alias name by using {\tt AS <\var{alias\_name}>}. \begin{Lentry} @@ -504,7 +510,8 @@ storage status reverts to its previous status after the routine returns. The format of the {\tt STORAGE} statement includes specifying the number of timelevels of each group for which storage should be activated. -{\tt STORAGE: <group1>[timelevels1], <group2>[timelevels2]} +{\tt STORAGE: <\var{group1}>[\var{timelevels1}], +<\var{group2}>[\var{timelevels2}]} This number can range from one to the maximum number of timelevels for the group as specified in the group definition in its {\tt interface.ccl} file. If this maximum number is one, the timelevel specification can be omitted from the {\tt STORAGE} statement. @@ -527,8 +534,8 @@ refinement. \end{Lentry} -Besides schedule blocks it's possible to embed C style {\tt -if/else} statements in the {\tt schedule.ccl} file. These can be used to +Besides schedule blocks it's possible to embed C style {\tt if/else} +statements in the {\tt schedule.ccl} file. These can be used to schedule things based upon the value of a parameter. \vskip .5cm @@ -596,11 +603,9 @@ schedule WaveToyC_Evolution AS WaveToy_Evolution AT evol SYNC: scalarfield } "Evolution of 3D wave equation" \end{verbatim} - The thorn {\tt IDScalarWave} schedules the routine {\tt WaveBinary} after the alias {\tt WaveToy\_Evolution}. It is scheduled independently of the C or Fortran routine name. - \begin{verbatim} schedule WaveBinary AT evol AFTER WaveToy_Evolution { @@ -610,7 +615,6 @@ schedule WaveBinary AT evol AFTER WaveToy_Evolution \end{verbatim} \subsubsection{Storage Outside of Schedule Blocks} - The keyword {\tt STORAGE} can also be used outside of the schedule blocks to indicate that storage for these groups should be switched on at the start of the run. Note that the storage is only allocated in @@ -630,12 +634,12 @@ it provides to or requires from other thorns. Currently there is only one option evaluated from a thorn's {\tt configuration.ccl} file: -\begin{verbatim} -Requires Thorns: <list of thorns> -\end{verbatim} +\begin{alltt} +Requires Thorns: <\var{list of thorns}> +\end{alltt} -where {\tt <list of thorns>} is a space-separated list of thorns which this -thorn requires in order to be compiled and to be activated at runtime. +where {\tt <\var{list of thorns}>} is a space-separated list of thorns which +this thorn requires in order to be compiled and to be activated at runtime. Thorns must be given by their exact names, without the arrangement name. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -756,18 +760,24 @@ and has a working directory of {\tt <config>/build/<thorn\_name>} . %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Cactus Variables} -\label{chap:cava} +\label{chap:cactus_variables} + +A \textit{grid variable} is Cactus program variable passed among thorns, +(or routines belonging to the same thorn interface), +by way of calls to the Flesh. +They are the only variables known to Cactus. +Such variables represent values of functions on the computational grid, +and are therefore often called \textit{grid functions}. -Cactus variables are sorted into \textit{groups}. All variables in a group -are of the same type, and have -the same attributes, and most Cactus operations act on a group as a whole. +In the Cactus context, grid variables are often referred +to simply as \textit{variables}. Cactus variables are used instead of local variables for a number of reasons: \begin{itemize} \item Cactus variables can be made visible to other thorns, allowing -thorns to communicate and share data, -\item Cactus variables can be distributed and communicated - among processors, allowing parallel computation, + thorns to communicate and share data, +\item Cactus variables can be distributed and communicated + among processors, allowing parallel computation, \item A database of Cactus variables, and their attributes, is held by the Flesh, and this information is used by thorns, for example for obtaining a list of variables for checkpointing, @@ -776,18 +786,23 @@ thorns to communicate and share data, and their attributes. \end{itemize} -The specification for a group declaration -(fully described in Appendix~\ref{sec:in}) is, +Cactus variables are collected into \textit{groups}. All variables in a +group are of the same data type, and have the same attributes. Most Cactus +operations act on a group as a whole. A group must be declared in its +thorn's \texttt{interface.ccl} file. -\begin{verbatim} -<data_type> <group_name> [TYPE=<group_type>] [DIM=<dim>] [TIMELEVELS=<num>] \ - [SIZE=<size in each direction>] [DISTRIB=<distribution_type>] \ - [GHOSTSIZE=<ghostsize>] [STAGGER=<stagger-specification>] -[{ - [ <variable_name>[,]<variable_name> - <variable_name> ] -} ["<group_description>"] ] -\end{verbatim} +The specification for a group declaration +(fully described in Appendix~\ref{sec:Appendix.interface}) is, + +\begin{alltt} +<\var{data_type}> <\var{group_name}> [TYPE=<\var{group_type}>] [DIM=<\var{dim}>] [TIMELEVELS=<\var{num}>] + [SIZE=<\var{size in each direction}>] [DISTRIB=<\var{distribution_type}>] + [GHOSTSIZE=<\var{ghostsize}>] [STAGGER=<\var{stagger-specification}>] +[\{ + [ <\var{variable_name}>[,]<\var{variable_name}> + <\var{variable_name}> ] +\} ["<\var{group_description}>"] ] +\end{alltt} Currently, the names of groups and variables must be distinct. @@ -795,9 +810,9 @@ Currently, the names of groups and variables must be distinct. \section{Data Type} -Cactus supports integer, real, complex and character variables, in +Cactus supports integer, real, complex and character variable types, in various different sizes. (Sizes in the following refer to the number of -bytes the type takes). +bytes occupied by the a variable of the type). \begin{Lentry} \item[INTEGER] @@ -815,7 +830,7 @@ This is a 1 byte data type. Normally a thorn should use the default types --- {\tt CCTK\_INT}, {\tt CCTK\_REAL}, {\tt CCTK\_COMPLEX} --- rather than explicitly setting the size, as this gives maximum portability. Also, the defaults can be changed at configuration time (see -\ref{Compilation-Available_Options}), and this allows people to compile the +\ref{subsec:Compilation-Available_Options}), and this allows people to compile the code with different precisions to test for roundoff effects, or to run more quickly with a lower accuracy. @@ -920,6 +935,7 @@ responsible for assigning the size on each processor. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Ghost Size} +\label{sec:ghost_size} Cactus is based upon a \textit{distributed computing} paradigm. That is, the problem domain is split into blocks, each of which is assigned to @@ -976,6 +992,7 @@ ghostzones as your stencil size requires. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Staggering} +\label{sec:staggering} The staggering of a gridfunction or array describes the \emph{physical} placement of that gridfunction relative to the supporting grid @@ -997,7 +1014,7 @@ used. The type of staggering applied to a gridfunction can be specified in the {\tt interface.ccl} file by the attribute {\tt stagger} (see -\ref{sec:in}). Cactus supports three kinds of staggering +\ref{sec:Appendix.interface}). Cactus supports three kinds of staggering per dimension. The physical location of a gridfunction is shifted relative to the default position by adding the following values to the stagger attribute: @@ -1040,7 +1057,13 @@ provides a set of querying APIs. \subsection{Group Information} -Fundamental information about grid functions (e.g.\ local grid size and location, number of ghostzones) is passed through the argument list of scheduled routines (see~\ref{sec:cava2}). To obtain similar information from non-scheduled routines, or for general grid variables, a set of functions are provided, the last two letters of which specify whether the information is requested using a group name ({\tt GN}) or index ({\tt GI}), or a variable name ({\tt VN}) or index ({\tt VI}). +Fundamental information about grid functions (e.g.\ local grid size and +location, number of ghostzones) is passed through the argument list of +scheduled routines (see~\ref{sec:cactus_variables_c}). To obtain similar information +from non-scheduled routines, or for general grid variables, a set of +functions are provided, the last two letters of which specify whether +the information is requested using a group name ({\tt GN}) or index +({\tt GI}), or a variable name ({\tt VN}) or index ({\tt VI}). \begin{itemize} @@ -1086,15 +1109,15 @@ then the Flesh validates these values against the ranges the thorn writers have specified to be valid. Once validated, parameter values are fixed, and cannot be changed (unless the parameter is specified to be \textit{steerable}, see below). For a detailed discussion of the {\tt param.ccl} syntax see -Appendix \ref{sec:pa}. +Appendix \ref{sec:Appendix.param}. The full specification for a parameter declaration is -\begin{verbatim} -[EXTENDS|USES] <parameter_type>[[<size>]] <parameter name> "<parameter description>" -{ - <PARAMETER_RANGES> -} <default value> -\end{verbatim} +\begin{alltt} +[EXTENDS|USES] <\var{parameter_type}>[[<\var{size}>]] <\var{parameter name}> "<\var{parameter description}>" +\{ + <\var{PARAMETER_RANGES}> +\} <\var{default value}> +\end{alltt} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1119,14 +1142,14 @@ of range is determined by the type of parameter. The range specification is of the form -\begin{verbatim} +\begin{alltt} -lower:upper:stride +\var{lower}:\var{upper}:\var{stride} -\end{verbatim} +\end{alltt} -where \textit{lower} and \textit{upper} specify the lower and upper allowed -range, and \textit{stride} allows numbers to be be missed out. e.g.\ +where \var{lower} and \var{upper} specify the lower and upper allowed +range, and \var{stride} allows numbers to be be missed out. e.g.\ \begin{verbatim} 1:21:2 \end{verbatim} @@ -1139,10 +1162,10 @@ infinity, and the default stride is one. \subsection{Real} The range specification is of the form -\begin{verbatim} -lower:upper -\end{verbatim} -where \textit{lower} and \textit{upper} specify the lower and upper allowed +\begin{alltt} +\var{lower}:\var{upper} +\end{alltt} +where \var{lower} and \var{upper} specify the lower and upper allowed range. A missing end of range (or a `{\t *}') implies negative or positive infinity. The above is inclusive of the endpoints. A `{\tt (}' (or `{\tt )}') before (or after) the lower (or upper) range specifies an open @@ -1194,34 +1217,34 @@ determines if the specifications are inconsistent, but does allow the user to schedule a routine with respect to another routine which may not exist. For a detailed discussion of the {\t schedule.ccl} syntax see -Appendix~\ref{sec:sc}. +Appendix~\ref{sec:Appendix.schedule}. A usual simple specification for a schedule declaration is -\begin{verbatim}schedule <function name> AT <schedule bin> -{ - LANG: <language> - [STORAGE: <group>,<group>...] -} "Description of function" -\end{verbatim} +\begin{alltt}schedule <\var{function name}> AT <\var{schedule bin}> +\{ + LANG: <\var{language}> + [STORAGE: <\var{group}>,<\var{group}>...] +\} "\var{Description of function}" +\end{alltt} The full specification for a schedule declaration is -\begin{verbatim}schedule [GROUP] <function|schedule group name> AT|IN <schedule bin|group name> \ - [BEFORE|AFTER <item>] [WHILE <variable>] [AS <alias>] -{ - LANG: <language> - [STORAGE: <group>,<group>...] - [TRIGGER: <group>,<group>...] - [SYNC: <group>,<group>...] - [OPTIONS: <option>,<option>...] -} "Description of function or schedule group" -\end{verbatim} +\begin{alltt}schedule [GROUP] <function|\var{schedule group name}> AT|IN <\var{schedule bin}|\var{group name}> + [BEFORE|AFTER <\var{item}>] [WHILE <\var{variable}>] [AS <\var{alias}>] +\{ + LANG: <\var{language}> + [STORAGE: <\var{group}>,<\var{group}>...] + [TRIGGER: <\var{group}>,<\var{group}>...] + [SYNC: <\var{group}>,<\var{group}>...] + [OPTIONS: <\var{option}>,<\var{option}>...] +\} "\var{Description of function or schedule group}" +\end{alltt} This full schedule specification consists of a mandatory part, a set of options, and the main body limited by braces, referred to as the -\textit{schedule block}. +\texttt{schedule block}. Each schedule item is scheduled either {\tt AT} a particular -\textit{scheduling bin}, or {\tt IN} a schedule \textit{group}. +\var{scheduling bin}, or {\tt IN} a schedule \var{group}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1414,7 +1437,7 @@ A Cactus macro {\tt CCTK\_ARGUMENTS} is defined for each thorn to contain: \begin{itemize} \item General information about the grid hierarchy, for example - the number of grid points used. See Section \ref{sec:cava2} for a + the number of grid points used. See Section \ref{sec:cactus_variables_c} for a complete list. \item All the grid variables defined in the thorn's {\tt interface.ccl} \item All the grid variables required from other thorns as requested by @@ -1463,7 +1486,7 @@ provides a mechanism for converting a string parameter to a Fortran string. For example, if {\tt operator} is a Cactus string parameter holding the name of a reduction operator whose handle you need to find, you cannot pass it directly into the subroutine {\tt CCTK\_ReductionHandle} which is expecting a Fortran string. Instead, the following is needed: -{\tt + \begin{verbatim} character*200 fortran_operator CCTK_INT fortran_operator_len @@ -1472,7 +1495,6 @@ a Fortran string. Instead, the following is needed: call CCTK_FortranString(fortran_operator_len,operator,fortran_operator) call CCTK_ReductionHandle(handle,fortran_operator(1:fortran_operator_len)) \end{verbatim} -} @@ -1544,11 +1566,10 @@ Fortran 90 modules should be included in a thorn's {\tt make.code.deps} file routines which use them. This is especially important for parallel building. For example, if a routine in {\tt MyRoutine.F} uses a module in {\tt MyModule.F} add the line: -{\tt + \begin{verbatim} $(SYS_OBJD)/MyRoutine.F.o: $(SYS_OBJD)/MyModule.F.o \end{verbatim} -} \subsubsection{The {\tt MOD} function} @@ -1585,7 +1606,7 @@ A Cactus macro {\tt CCTK\_ARGUMENTS} is defined for each thorn to contain \begin{itemize} \item General information about the grid hierarchy, for example the -number of grid points on the processor. See Section \ref{sec:cava2} +number of grid points on the processor. See Section \ref{sec:cactus_variables_c} for a complete list. \item All the grid variables defined in the thorn's {\tt interface.ccl} \item All the grid variables required from other thorns as requested by @@ -1684,7 +1705,7 @@ Here, {\tt CCTK\_GFINDEX3D(cctkGH,i,j,k)]} expands to \end{verbatim} \subsection{Cactus Variables} -\label{sec:cava2} +\label{sec:cactus_variables_c} The Cactus variables which are passed through the macro {\tt CCTK\_ARGUMENTS} are @@ -1881,14 +1902,14 @@ treat this case in a easy way is explained below. } \end{figure} When a thorn programmer uses staggered gridpoints, he has to be aware -of this gridpoint anomaly. This can be done most easily by using the {\tt -CCTK\_LSSH(<dir\_staggertype>,<direction>)} macro. For a given staggertype -and direction, this 2d array returns the local number of gridpoints, -including ghostzones and the necessary change for the staggering on -the outermost processor. +of this gridpoint anomaly. This can be done most easily by using the +{\tt CCTK\_LSSH(<\var{dir\_staggertype}>,<\var{direction}>)} macro. +For a given staggertype and direction, this 2d array returns the local +number of gridpoints, including ghostzones and the necessary change +for the staggering on the outermost processor. \begin{Lentry} -\item[{\tt CCTL\_LSSH(<dir\_staggertype>,<direction>)}] +\item[{\tt CCTL\_LSSH(<\var{dir\_staggertype}>,<\var{direction}>)}] for a given staggertype and a direction this macro returns the number of processor local gridpoints, including ghostzones. @@ -1905,18 +1926,18 @@ ranging from $1 \ldots$.} Several functions exist to derive the staggertype for a given group and for a certain direction. \begin{Lentry} -\item[{\tt int CCTK\_GroupStaggerIndexGI(int group\_index)}] %returns the +\item[{\tt int CCTK\_GroupStaggerIndexGI(int \var{group\_index})}] %returns the %\textit{staggerindex} for a given group index. -\item[{\tt call CCTK\_GroupStaggerIndexGI(int staggerindex, int -group\_index)}] returns the \textit{staggerindex} for a given group index. +\item[{\tt call CCTK\_GroupStaggerIndexGI(int \var{staggerindex}, int +\var{group\_index})}] returns the \var{staggerindex} for a given group index. \end{Lentry} \vskip .45cm \begin{Lentry} -\item[{\tt int CCTK\_GroupStaggerIndexGN(char *group\_name)}] %returns the +\item[{\tt int CCTK\_GroupStaggerIndexGN(char *\var{group\_name})}] %returns the %\textit{staggerindex} for a given group name. -\item[{\tt call CCTK\_GroupStaggerIndexGN(int staggerindex, char *group\_name)}] returns the -\textit{staggerindex} for a given group name. \vskip .25cm +\item[{\tt call CCTK\_GroupStaggerIndexGN(int \var{staggerindex}, char *\var{group\_name})}] returns the +\var{staggerindex} for a given group name. \vskip .25cm \end{Lentry} \vskip .45cm @@ -1924,7 +1945,9 @@ group\_index)}] returns the \textit{staggerindex} for a given group index. %\item[{\tt int CCTK\_GroupStaggerIndexVI(int variable\_index)}] %returns the %%\textit{staggerindex} for a given variable index. %\item[{\tt call CCTK\_GroupStaggerIndexVI(int staggerindex, int variable\_index)}] returns the + %\textit{staggerindex} for a given variable index. + %\end{Lentry} %\vskip .45cm % @@ -1932,33 +1955,34 @@ group\_index)}] returns the \textit{staggerindex} for a given group index. %\item[{\tt int CCTK\_GroupStaggerIndexVN(char *variable\_name)}] %returns the %%\textit{staggerindex} for a given variable name. %\item[{\tt call CCTK\_GroupStaggerIndexVN(int staggerindex, char *variable\_name)}] returns the + %\textit{staggerindex} for a given variable name. %\end{Lentry} %\vskip .45cm \begin{Lentry} -\item[{\tt int CCTK\_StaggerIndex(char *stagger\_string)}] %return the \textit{ +\item[{\tt int CCTK\_StaggerIndex(char *\var{stagger\_string})}] %return the \textit{ %staggerindex} for a given stagger string. -\item[{\tt call CCTK\_StaggerIndex(int staggerindex, char *stagger\_string)}] return the \textit{staggerindex} for a given stagger string. +\item[{\tt call CCTK\_StaggerIndex(int \var{staggerindex}, char *\var{stagger\_string})}] return the \var{staggerindex} for a given stagger string. \end{Lentry} \vskip .45cm \begin{Lentry} -\item[{\tt int CCTK\_DirStaggerIndex(int direction, char *stagger\_string)}] +\item[{\tt int CCTK\_DirStaggerIndex(int \var{direction}, char *\var{stagger\_string})}] %returns the \textit{directional staggerindex} for a given direction and %stagger string. -\item[{\tt call CCTK\_DirStaggerIndex(int dir\_staggerindex, int direction, char *stagger\_string)}] -returns the \textit{directional staggerindex} for a given direction and +\item[{\tt call CCTK\_DirStaggerIndex(int \var{dir\_staggerindex}, int \var{direction}, char *\var{stagger\_string})}] +returns the \var{directional staggerindex} for a given direction and stagger string. \end{Lentry} \vskip .45cm \begin{Lentry} -\item[{\tt int CCTK\_DirStaggerIndexI(int direction, char *stagger\_type)}] +\item[{\tt int CCTK\_DirStaggerIndexI(int \var{direction}, char *\var{stagger\_type})}] %returns the \textit{directional staggerindex} for a given direction and %staggerindex. -\item[{\tt call CCTK\_DirStaggerIndexI(int dir\_direction, char *stagger\_type)}] -returns the \textit{directional staggerindex} for a given direction and +\item[{\tt call CCTK\_DirStaggerIndexI(int \var{dir\_direction}, char *\var{stagger\_type})}] +returns the \var{directional staggerindex} for a given direction and staggerindex. \end{Lentry} @@ -1966,7 +1990,7 @@ staggerindex. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Parallelisation} -\label{seap} +\label{sec:parallelisation} The Flesh itself does not actually set up grid variables. This is done by a \textit{driver} thorn. To allow the distribution of @@ -2003,7 +2027,7 @@ is a parallel unigrid driver. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Coordinates} -\label{sec:coordinates} +\label{sec:CactusAPI.coordinates} The Flesh provides utility routines for registering and querying coordinate information. The Flesh does not provide any coordinates @@ -2031,9 +2055,10 @@ Following conventions for coordinate system and coordinate names provides a means for other thorns to use the physical properties of coordinate systems, without being tied to a particular thorn. -A registered coordinate system can be referred to by both its name and -an associated handle. Passing such an integer handle instead of the -name string may be necessary for calling C routines from Fortran. +A registered coordinate system can be referred to by either its name or +an associated integer known as a \textit{handle}. Passing a handle instead +of the name string may be necessary for calling C routines from Fortran. + \subsection{Registering Coordinates and Coordinate Properties} @@ -2209,18 +2234,18 @@ this call returns the {\tt addresses} or the minimum and maximum values. For example, the range of the {\tt y} coordinate of the {\tt cart3d} coordinate system can be found using -{\tt -CCTK\_REAL lower, upper;\\ -int ierr;\\ -ierr = CCTK\_CoordRange(cctkGH, \&lower, \&upper, -1, "y", "cart3d"); -} +\begin{verbatim} +CCTK_REAL lower, upper; +int ierr; +ierr = CCTK_CoordRange(cctkGH, &lower, &upper, -1, "y", "cart3d"); +\end{verbatim} or alternatively, using the direction -{\tt -CCTK\_REAL lower, upper;\\ -int ierr;\\ -ierr = CCTK\_CoordRange(cctkGH, \&lower, \&upper, 2, NULL, "cart3d"); -} +\begin{verbatim} +CCTK_REAL lower, upper; +int ierr; +ierr = CCTK_CoordRange(cctkGH, &lower, &upper, 2, NULL, "cart3d"); +\end{verbatim} \item[{\tt CCTK\_CoordLocalRange}] @@ -2230,17 +2255,18 @@ grid hierarchy. WARNING: This utility only currently works for regular cartesian grids. For example, the local processor range of the {\tt y} coordinate of the {\tt cart3d} coordinate system can be found using -{\tt -CCTK\_REAL lower, upper;\\ -int ierr;\\ -ierr = CCTK\_CoordLocalRange(cctkGH, \&lower, \&upper, -1, "y", "cart3d");} +\begin{verbatim} +CCTK_REAL lower, upper; +int ierr; +ierr = CCTK_CoordLocalRange(cctkGH, &lower, &upper, -1, "y", "cart3d"); +\end{verbatim} or alternatively, using the direction -{\tt -CCTK\_REAL lower, upper;\\ -int ierr;\\ -ierr = CCTK\_CoordLocalRange(cctkGH, \&lower, \&upper, 2, NULL, "cart3d"); -} +\begin{verbatim} +CCTK_REAL lower, upper; +int ierr; +ierr = CCTK_CoordLocalRange(cctkGH, &lower, &upper, 2, NULL, "cart3d"); +\end{verbatim} \item[{\tt CCTK\_CoordRangePhysIndex}] @@ -2285,7 +2311,7 @@ the following function calls: \begin{description} -\item {\tt CCTK\_OutputGH (const cGH *GH)} +\item {\tt CCTK\_OutputGH (const cGH *\var{GH})} This call loops over all registered IO methods, calling the routine that each method has registered for {\t OutputGH}. The expected @@ -2295,37 +2321,37 @@ routines (that is, not all methods will supply routines to output all different types of variables) and if the method decides it is an appropriate time to output. -\item {\tt CCTK\_OutputVar (const cGH *GH, const char *varname)} +\item {\tt CCTK\_OutputVar (const cGH *\var{GH}, const char *\var{varname})} -Output a variable {\t varname} looping over all registered IO methods. +Output a variable \var{varname} looping over all registered IO methods. The output should take place if at all possible. If output goes into a file and the appropriate file exists the data is appended, otherwise a new file is created. -\item {\tt CCTK\_OutputVarAs (const cGH *GH, const char *varname, const char *alias)} +\item {\tt CCTK\_OutputVarAs (const cGH *\var{GH}, const char *\var{varname}, const char *\var{alias})} -Output a variable {\t varname} looping over all registered IO methods. +Output a variable \var{varname} looping over all registered IO methods. The output should take place if at all possible. If output goes into a file and the appropriate file exists the data is appended, otherwise -a new file is created. Uses {\t alias} as the name of the variable +a new file is created. Uses \var{alias} as the name of the variable for the purpose of constructing a filename. -\item {\tt CCTK\_OutputVarByMethod (const cGH *GH, const char *varname, const char *methodname)} +\item {\tt CCTK\_OutputVarByMethod (const cGH *\var{GH}, const char *\var{varname}, const char *\var{methodname})} -Output a variable {\t varname} using the IO method {\t methodname} if +Output a variable \var{varname} using the IO method \var{methodname} if it is registered. The output should take place if at all possible. If output goes into a file and the appropriate file exists the data is appended, otherwise a new file is created. -\item {\tt CCTK\_OutputVarAsByMethod (const cGH *GH, - const char *varname, - const char *methodname,\\ - const char *alias)} +\item {\tt CCTK\_OutputVarAsByMethod (const cGH *\var{GH}, + const char *\var{varname}, + const char *\var{methodname},\\ + const char *\var{alias})} -Output a variable {\t varname} using the IO method {\t methodname} if +Output a variable \var{varname} using the IO method \var{methodname} if it is registered. The output should take place if at all possible. If output goes into a file and the appropriate file exists the data is -appended, otherwise a new file is created. Uses {\t alias} as the +appended, otherwise a new file is created. Uses \var{alias} as the name of the variable for the purpose of constructing a filename. \end{description} @@ -2653,7 +2679,6 @@ variable across multiple processors. The result of the reduction operation can be placed on the specified processor or on all processors. -{\t \begin{verbatim} int CCTK_ReduceLocScalar (const cGH *GH, int processor, @@ -2670,7 +2695,6 @@ call CCTK_ReduceLocScalar(integer returnvalue, out_scalar, integer data_type) \end{verbatim} -} \begin{Lentry} \item[{\tt returnvalue}] the return value of the operation. A negative value indicates a failure to perform the reduction. A zero @@ -2700,7 +2724,6 @@ communicating. Use the values as specified in \ref{sec:datyansi}. reduce a 1d array on all processors to a 1d array. This reduction is carried out element by element. The arrays need to have the same size on all processors. -{\t \begin{verbatim} int CCTK_ReduceLocArrayToArray1D( const cGH *GH, int processor, @@ -2719,7 +2742,6 @@ call CCTK_ReduceLocArrayToArray1D( integer returnvalue integer xsize, integer data_type) \end{verbatim} -} \begin{Lentry} \item[{\tt returnvalue}] the return value of the operation. A @@ -2747,7 +2769,6 @@ communicating. Use the values as specified in \ref{sec:datyansi}. \vskip 0.24cm {\bf Reduction of 2d arrays} Use these routines to reduce a 2d array, element by element. The arrays need to have the same size on all processors. -{\t \begin{verbatim} int CCTK_ReduceLocArrayToArray2D( const cGH *GH, int processor, @@ -2769,7 +2790,6 @@ call CCTK_ReduceLocArrayToArray2D( integer returnvalue integer ysize, integer data_type) \end{verbatim} -} \begin{Lentry} \item[{\tt returnvalue}] the return value of the operation. A @@ -2799,7 +2819,6 @@ communicating. Use the values as specified in \ref{sec:datyansi}. \vskip 0.24cm {\bf Reduction of 3d arrays} Use these routines to reduce a 3d array, element by element. The arrays need to have the same size on all processors. -{\t \begin{verbatim} int CCTK_ReduceLocArrayToArray3D(const cGH *GH, int processor, @@ -2822,7 +2841,6 @@ call CCTK_ReduceLocArrayToArray3D(integer returnvalue integer zsize, integer data_type) \end{verbatim} -} \begin{Lentry} \item[{\tt returnvalue}] the return value of the operation. A @@ -2916,7 +2934,7 @@ with ``{\tt //}''), should only be used in C++ source code). The Flesh and the Cactus thorns use the {\tt grdoc} Code Documenting -System\\(\texttt{http://jean-luc.aei.mpg.de/Codes/grdoc/}) to document +System\\(\url{http://jean-luc.aei.mpg.de/Codes/grdoc/}) to document source code. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -3091,7 +3109,7 @@ copyright details, and a synopsis of what the thorn does. The LaTeX file {\tt doc/documentation.tex} is included in Thorn Guides built by the Cactus make system. (e.g.\ by {\tt gmake -$<$config$>$-ThornGuide}). Ideally this file should contain complete +$<$\var{config}$>$-ThornGuide}). Ideally this file should contain complete (and \textit{up-to-date}) details about the thorn, exactly what is relevant is for the authors to decide, but remember that the Cactus make system automatically parses the thorn CCL files to include @@ -3141,11 +3159,9 @@ documentation: included using a relative link, so that updates to the style file are applied to all thorns. -{\tt \begin{verbatim} \usepackage{../../../../doc/latex/cactus} \end{verbatim} -} \item Aside from the {\tt date}, {\tt author}, and {\tt title} fields, all of the documentation to be included in a Thorn Guide should be @@ -3169,7 +3185,6 @@ and Graphics figures should be included using the {\tt includegraphics} command (not {\tt epsffig}), with no file extension specified. For example, -{\tt \begin{verbatim} \begin{figure}[ht] \begin{center} @@ -3179,7 +3194,6 @@ and \label{MyArrangement_MyThorn_MyLabel} \end{figure} \end{verbatim} -} \item All {\bf labels}, {\bf citations}, {\bf references}, and {\bf graphic images} names should conform to the following guidelines: @@ -3192,7 +3206,6 @@ and bibitem} command, for example, a bibliography section should look like: -{\tt \begin{verbatim} \begin{thebibliography}{9} \bibitem{MyArrangement_MyThorn_Author99} @@ -3200,14 +3213,13 @@ and 1--16. \url{http://www.nowhere.com/}} \end{thebibliography} \end{verbatim} -} \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Adding a test suite} -\label{sec:adatesu} +\label{sec:adding_test_suite} To add a test suite to your thorn, devise a series of parameter files which use as many aspects of your thorn as possible. @@ -3222,7 +3234,7 @@ in your thorn. Document carefully any situations or architectures in which your test suite does not give the correct answers. -For details on running the test suites, see Section~\ref{sec:te}. +For details on running the test suites, see Section~\ref{sec:testing}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -3356,18 +3368,16 @@ CactusTest/TestTimers}. The first action for any timer is to create it, using {\t CCTK\_TimerCreate}. This can be performed at any time, as long as it precedes using the timer: -{\tt + \begin{verbatim} #include "cctk_Timers.h" ierr = CCTK_TimerCreate(`TimeMyStuff`); \end{verbatim} -} {\bf Instrumenting a section of code} Code sections are instrumented using the Start, Stop and Reset functions. These functions are applied to the chosen timer using all the registered clocks. -{\tt \begin{verbatim} #include "cctk_Timers.h" ierr = CCTK_TimerStart(`TimeMyStuff`); @@ -3375,14 +3385,12 @@ ierr = CCTK_TimerStart(`TimeMyStuff`); y = CalculateNewValue(y); ierr = CCTK_TimerStop(`TimeMyStuff`); \end{verbatim} -} {\bf Accessing the timer results} This is a little bit cumbersome at the moment, since the timer data can be of different types. -{\tt \begin{verbatim} #include "cctk_Timers.h" cTimerData *info; @@ -3416,7 +3424,6 @@ for (i = 0; i < info->n_vals; i++) } ierr = CCTK_TimerDestroyData(info); \end{verbatim} -} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -3434,9 +3441,9 @@ Any thorn which uses the include file must declare this in its {\tt interface.ccl} with the line -\begin{verbatim} -USES INCLUDE [SOURCE|HEADER]: <file_name> -\end{verbatim} +\begin{alltt} +USES INCLUDE [SOURCE|HEADER]: <\var{file_name}> +\end{alltt} (If the optional \verb![SOURCE|HEADER]! is omitted, \verb|HEADER| is assumed. Note that this can be dangerous, as included \emph{source} @@ -3446,9 +3453,9 @@ inactive}. Thus it is recommended to always include the optional \verb![SOURCE|HEADER]! specification.) Any thorn which wishes to add to this include file, declares in its own {\tt interface.ccl} -\begin{verbatim} -INCLUDE [SOURCE|HEADER]: <file_to_include> in <file_name> -\end{verbatim} +\begin{alltt} +INCLUDE [SOURCE|HEADER]: <\var{file_to_include}> in <\var{file_name}> +\end{alltt} \subsubsection{Example} @@ -4016,10 +4023,10 @@ Data Type & Size (bytes) & Variable Type & Fortran Equivalent\\ In addition Cactus provides three generic numeric data types which map onto the compilers' native data types used to represent integer, real, and complex values. The size for these generic types can be chosen at configuration time -(see \ref{Compilation-Available_Options}). This is to allow the code to be -easily run at different precisions. Note that the effectiveness of running the -code at a lower or higher precision depends crucially on all thorns being used -making consistent use of the these generic data types: +(see \ref{subsec:Compilation-Available_Options}). This is to allow the code to +be run easily at different precisions. Note that the effectiveness of running +the code at a lower or higher precision depends crucially on all thorns being +used making consistent use of the these generic data types: \begin{center} \begin{tabular}{|l|l|l|l|} diff --git a/doc/UsersGuide/UsersGuide.tex b/doc/UsersGuide/UsersGuide.tex index cab70f1c..60c13f14 100644 --- a/doc/UsersGuide/UsersGuide.tex +++ b/doc/UsersGuide/UsersGuide.tex @@ -24,6 +24,8 @@ urlcolor=blue ]{hyperref} +\usepackage{alltt} +\newcommand{ \var }[1]{\textsl{\texttt{#1}}} % This must come after most of the other \usepackages, because we % might want to pass options to them |