diff options
Diffstat (limited to 'doc/UsersGuide')
| -rw-r--r-- | doc/UsersGuide/Appendices.tex | 444 | ||||
| -rw-r--r-- | doc/UsersGuide/Infrastructure.tex | 128 | ||||
| -rw-r--r-- | doc/UsersGuide/Preface.tex | 2 | ||||
| -rw-r--r-- | doc/UsersGuide/RunningCactus.tex | 355 | ||||
| -rw-r--r-- | doc/UsersGuide/ThornWriters.tex | 655 | ||||
| -rw-r--r-- | doc/UsersGuide/UtilityRoutines.tex | 70 |
6 files changed, 833 insertions, 821 deletions
diff --git a/doc/UsersGuide/Appendices.tex b/doc/UsersGuide/Appendices.tex index 028d0d99..0c584c89 100644 --- a/doc/UsersGuide/Appendices.tex +++ b/doc/UsersGuide/Appendices.tex @@ -13,7 +13,7 @@ \renewcommand{\thepage}{\Alph{part}\arabic{page}} Note that these appendices appear (identically) in both the -Cactus Users's Guide and the Cactus Reference Manual. +Cactus Users' Guide and the Cactus Reference Manual. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -24,33 +24,33 @@ Cactus Users's Guide and the Cactus Reference Manual. \begin{Lentry} -\item[{\tt API}] - Applications Programming Interface, the externally-visible interface +\item[API] + 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 + example, the Reference Manual documents most of the Cactus Flesh APIs. -\item[{\tt arrangement}] +\item[arrangement] A collection of thorns, normally stored in the Cactus \verb|arrangements| directory. -\item[{\tt autoconf}] +\item[autoconf] A GNU program which builds a configuration script which can be used to make a Makefile. -\item[{\tt boundary zone}] +\item[boundary zone] A boundary zone is a set of points added to the edge of a grid to contain boundary data, e.g.\ Dirichlet or Von Neumann data. (See - also {\it symmetry zone}, {\it ghost zone}.) -\item[{\tt Cactus}] + also \textit{symmetry zone}, \textit{ghost zone}.) +\item[Cactus] A green fleshy plant with lots of thorns, usually painful if touched. -\item[{\tt CCTK}] - Cactus Computational Tool Kit (The Cactus flesh and computational +\item[CCTK] + \textit{Cactus Computational Tool Kit} (The Cactus Flesh and computational thorns). -\item[{\tt CCL}] - The {\tt Cactus Configuration Language}, this is the language that +\item[CCL] + The \textit{Cactus Configuration Language}, this is the language that the thorn configuration files are written in. -\item[{\tt configuration}] +\item[configuration] The combination of a set of thorns, and all the Cactus configure options which affect what binary will be produced when compiling Cactus. For example, the choice of compilers (Cactus \verb|CC|, @@ -60,108 +60,108 @@ Cactus Users's 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). -\item[{\tt checkout}] +\item[checkout] Get a copy of the code or thorns from CVS. -\item[{\tt checkpointing}] +\item[checkpointing] Save the entire state of a run to file so that it can be restarted at a later time. -\item[{\tt convergence}] +\item[convergence] Important, but often neglected. -\item[{\tt CST}] - This stands for Cactus Specification Tool, which is the perl scripts - which parse the thorns' configuration files (those that have a +\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). -\item[{\tt CVS}] - The {\em ``Concurrent Versioning System''} is the favoured +\item[CVS] + The \textit{Concurrent Versions System} is the favoured distribution system for Cactus and can be downloaded from your favorite GNU site. -\item[{\tt driver}] - A thorn which creates and handles grid hierachies. -\item[{\tt flesh}] +\item[driver] + A thorn which creates and handles grid hierarchies. +\item[Flesh] The routines which hold all the thorns together, this is what you - get if you check out {\it Cactus} from our CVS repository. -\item[{\tt friend}] -\item[{\tt GA}] - Shorthand for a {\it grid array}. -\item[{\tt GF}] - Shorthand for a {\it grid function}. -\item[{\tt gmake}] - GNU version of make utility. -\item[{\tt ghostzone}] + get if you check out Cactus from our CVS repository. +\item[friend] +\item[GA] + Shorthand for a \textit{grid array}. +\item[GF] + Shorthand for a \textit{grid function}. +\item[gmake] + GNU version of the {\tt make} utility. +\item[ghostzone] A ghostzone is a set of points added for parallelisation purposes to 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. -\item[{\tt grid array}] - A {\it grid variable} whose global size need not be that of the computational +\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 {\it local array}.) -\item[{\tt grid function}] - A {\it grid variable} whose global size is the size of the - computational grid. (See also {\it local array}.) -\item[{\tt grid hierarchy}] + file. (See also \textit{local array}.) +\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[{\tt grid scalar}] - A {\it grid variable\/} which has zero indices, +\item[grid scalar] + A \textit{grid variable} which has zero indices, i.e.\ it's just a number on each processor. -\item[{\tt grid variable}] +\item[grid variable] Any variable which can be passed between thorns, or routines - belonging to the same thorn, but passed through the defined flesh + belonging to the same thorn, but passed through the defined Flesh interface; implicitly implies it is related to the computational grid rather than being an internal variable of the thorn or one of - its routines. {\it grid scalar}, {\it grid function}, and {\it grid - array} are all examples of {\it grid variables}. -\item[{\tt GNATS}] + its routines. \textit{grid scalar}, \textit{grid function}, and \textit{grid + array} are all examples of \textit{grid variables}. +\item[GNATS] The GNU program we use for reporting and tracking bugs, comments and suggestions. -\item[{\tt GV}] - Shorthand for a {\it grid variable} -\item[{\tt handle}] +\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 same object class should not be trusted to comprise a consecutive sequence of integer values. -\item[{\tt HDF5}] - Hierarchical Data Format version~5, an API, subroutine library, and - file format for storing multimdimensional data. An HDF5 file can - store both data (for example Cactus grid variables), and metadata +\item[HDF5] + \textit{Hierarchical Data Format} version~5, an API, subroutine library, and + file format for storing multidimensional 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). -\item[{\tt implementation}] +\item[implementation] Defines the interface that a thorn presents to the outside world. See Section~\ref{sec:im}. -\item[{\tt inherit}] -\item[{\tt interpolation}] - Given $N$ {\it grid arrays} and $C$ interpolation points (in the +\item[inherit] +\item[interpolation] + Given $N$ \textit{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 {\it local + processor at each interpolation point. (See also \textit{local interpolation}) -\item[{\tt local array}] - An array that is declared in normal code, as opposed to a {\it grid +\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. -\item[{\tt local interpolation}] +\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 {\it interpolation}) -\item[{\tt MPI}] - Message Passing Interface, an API and software library for sending + (See also \textit{interpolation}) +\item[MPI] + \textit{Message Passing Interface}, an API and software library for sending messages between processors in a multiprocessor system. -\item[{\tt mutual recursion}] - See {\it recursion, mutual}. -\item[{\tt NUL character}] +\item[mutual recursion] + See \textit{recursion, mutual}. +\item[NUL character] The C programming language uses a ``NUL character'' to terminate character strings. A NUL character has the integer value zero, but it's useful to write it as \verb|'\0'| to emphasize to human readers that this has type \verb|char| rather than \verb|int|. -\item[{\tt NULL pointer}] +\item[NULL pointer] C defines a ``NULL pointer'' which is guaranteed not to point to any object. You get a NULL pointer by converting the integer constant 0 to a pointer type, e.g.\ \verb|int* ptr = 0;|. Note that if you have an expression which has the value zero, but which isn't an - integer constant, converting this to a pointer type is {\em not\/} + integer constant, converting this to a pointer type is \emph{not} guaranteed to give a NULL pointer, e.g.: \begin{verbatim} int i = 0; @@ -171,39 +171,39 @@ int* ptr = i; /* ptr is NOT guaranteed to be a NULL pointer! */ Many programmers prefer to use the predefined macro \verb|NULL| (defined in \verb|<stdlib.h>| and \verb|<stdio.h>|) to create NULL pointers, e.g.\ \verb|int* ptr = NULL;|, to emphasize to - human readers that this is a NULL {\em pointer\/} rather than + human readers that this is a NULL \emph{pointer} rather than ``just'' the integer zero. - Note that it is explicitly {\em not\/} defined whether a NULL pointer - is represented by a bit pattern of all zero bits -- this varies from + Note that it is explicitly \emph{not} defined whether a NULL pointer + is represented by a bit pattern of all zero bits --- this varies from system to system, and there are real-world systems where NULL pointers - are in fact {\em not\/} represented this way. -\item[{\tt parameter}] + are in fact \emph{not} represented this way. +\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[{\tt processor topology}] -\item[{\tt PUGH}] +\item[processor topology] +\item[PUGH] The default parallel driver for Cactus which uses MPI. -\item[{\tt PVM}] - {\tt Parallel Virtual Machine}, provides interprocessor +\item[PVM] + \textit{Parallel Virtual Machine}, provides interprocessor communication. -\item[{\tt recursion, mutual}] - See {\it mutual recursion}. -\item[{\tt reduction}] +\item[recursion, mutual] + See \textit{mutual recursion}. +\item[reduction] Given $N$ grid variables return $M$ output values on each requested processor. -\item[{\tt symmetry zone}] +\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 {\it boundary zone}, - {\it ghost zone}.) -\item[{\tt TAGS}] -\item[{\tt target}] -\item[{\tt thorn}] + another part of the grid. (See also \textit{boundary zone}, + \textit{ghost zone}.) +\item[TAGS] +\item[target] +\item[thorn] A collection of subroutines with a definite interface and purpose. -\item[{\tt WMPI}] - Win32 Message Passing Interface. +\item[WMPI] + \textit{Win32 Message Passing Interface}. \end{Lentry} @@ -225,7 +225,7 @@ top level thorn directory: \item{} {\tt schedule.ccl} \item{} {\tt configuration.ccl} (optional) \end{itemize} -These files are written in the {\it Cactus Configuration Language} which is +These files are written in the \textit{Cactus Configuration Language} which is case insensitive. % A note on optional arguments and square brackets: If e.g.\ a variable or @@ -284,7 +284,7 @@ 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 the include file is described as \verb|SOURCE|, the included code is -only exectuted if the providing thorn is active. +only executed if the providing thorn is active. Both default to \verb|HEADER|. \subsection{Function aliasing} @@ -360,15 +360,15 @@ carriage return. groups of variables. {\t access} can be either {\t public}, {\t protected} or {\t private}. \item{} {\t data\_type} defines the data type of the variables in the -group. Supported data types are {\t CHAR}, {\t BYTE}, {\it INT}, {\t REAL} and +group. Supported data types are {\t CHAR}, {\t BYTE}, {\t INT}, {\t REAL} and {\t COMPLEX}. -\item{} {\t group\_name} must be an alpha-numeric name (which may also +\item{} {\t 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 {\bf vector} +\item{} {\t [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 mumber-index, +of grid variables. The first index in the array is the member-index, and any other indices are the normal spatial indices for a group of this type and dimension. The number can be any valid arithmetical expression consisting of integers or integer-valued parameters. @@ -421,9 +421,9 @@ discussed in Section~\ref{sec:includefiles}. \label{sec:pa} The parameter configuration file consists of a list of -{\it parameter object specification items} (OSIs) giving the type and +\textit{parameter object specification items} (OSIs) giving the type and range of the parameter separated by optional -{\it parameter data scoping items} (DSIs) which detail access to the +\textit{parameter data scoping items} (DSIs) which detail access to the parameter. (For a more extensive discussion of Cactus parameters see Chapter \ref{chap:capa}.) @@ -513,7 +513,7 @@ 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 {\bf +\item{} {\tt [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). @@ -527,11 +527,11 @@ instead. parameter file has been read, or on restarting from checkpoint. This option relaxes this restricting, specifying that the parameter may be changed at recovery time or at any time. -\item{} {\t ACCUMULATOR} specifies that this is an {\bf accumulator} +\item{} {\t ACCUMULATOR} specifies that this is an \textit{accumulator} parameter. Such parameters cannot be set directly, but are - set by other parameters who specify this one as an {\bf + set by other parameters who specify this one as an {\tt ACCUMULATOR-BASE}. The expression is a two parameter - arithemetical expression of $X$ and $y$. Setting the + arithmetical expression of $x$ and $y$. Setting the parameter consists of evaluating this expression successively, with $x$ being the current value of the parameter (at the first iteration this is the default value) @@ -539,7 +539,7 @@ instead. This procedure is repeated, starting from the default value of the parameter, each time one of the setting parameters changes. \item{} {\t ACCUMULATOR-BASE} specifies the name of an - {\bf ACCUMULATOR} parameter which this parameter sets. + {\tt ACCUMULATOR} parameter which this parameter sets. \end{itemize} \section{schedule.ccl} @@ -549,20 +549,20 @@ instead. \ref{chap:scheduling}.) A schedule configuration file consists of \begin{itemize} -\item{} {\it assignment statements} to switch on storage for +\item{} \textit{assignment statements} to switch on storage for grid variables for the entire duration of program execution -\item{} {\it schedule blocks} to schedule a subroutine from a thorn +\item{} \textit{schedule blocks} to schedule a subroutine from a thorn to be called at specific times during program execution in a given manner -\item {} {\it conditional statements} for both assignment statements and +\item {} \textit{conditional statements} for both assignment statements and schedule blocks to allow them to be processed depending on parameter values \end{itemize} \subsection{Assignment Statements} -{\it Assignment statements}, currently only assign storage. +\textit{Assignment statements}, currently only assign storage. These lines have the form: {\t @@ -587,7 +587,7 @@ block). \subsection{Schedule Blocks} -Each {\it schedule block} in the file {\t schedule.ccl} must have the syntax: +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>] @@ -619,10 +619,10 @@ Each {\it schedule block} in the file {\t schedule.ccl} must have the syntax: optional. Grid variables cannot be used in the {\tt CCTK\_STARTUP} and {\tt CCTK\_SHUTDOWN} timebins. - \item[{IN}] Schedules a function or schedule group to run in a + \item[{\tt IN}] Schedules a function or schedule group to run in a schedule group rather than in a Cactus timebin. - \item[{BEFORE/AFTER}] Takes either a function name, a function + \item[{\tt BEFORE/AFTER}] Takes either a function name, a function alias, or a schedule group name. If no function, alias or schedule group with this name is provided by an active thorn this directive is ignored. @@ -648,7 +648,7 @@ Each {\it schedule block} in the file {\t schedule.ccl} must have the syntax: \item[{\tt TRIGGER}] List of grid variables or groups to be used as triggers for causing an analysis function or analysis group to be executed. Any schedule block for an analysis function or analysis - group must contain a non-trivial TRIGGER line. + group must contain a nontrivial TRIGGER line. \item[{\tt SYNCHRONISE}] List of groups to be synchronised as soon as the function or schedule group is exited. @@ -696,7 +696,7 @@ if (CCTK_Equals(<parameter>,<string>)) Such conditionals are evaluated only at program startup and are used to pick between different static schedule options. For dynamic -scheduling the SCHEDULE WHILE construction should be used. +scheduling the {\tt SCHEDULE WHILE} construction should be used. Conditional constructs cannot be used inside a schedule block. @@ -711,7 +711,7 @@ A configuration options file has the form: Requires Thorns: <list of thorns> \end{verbatim} -The \verb|Requires Thorns| configuration option has as its argument a case-% +The \verb|Requires Thorns| configuration option has as its argument a case sensitive, space-separated list of thorn names (without the name of the arrangement there are located in). @@ -723,7 +723,7 @@ arrangement there are located in). \label{sec:scbi} 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 +in the different timebins which are executed by the Cactus Flesh. This chapter describes these standard timebins, and shows the flow of program execution through them. @@ -737,13 +737,13 @@ through them. variables cannot be used in routines scheduled here. \item[{\tt CCTK\_RECOVER\_PARAMETERS}] - Used by thorns with relevent IO methods as the point + Used by thorns with relevant IO methods as the point to read parameters when recovering from checkpoint files. \item[{\tt CCTK\_PARAMCHECK}] This timebin is for thorns to check the validity of parameter combinations. This bin is also executed before the - grid hierachy is made, so that routines scheduled here only + grid hierarchy is made, so that routines scheduled here only have access to the global grid size and the parameters. \item[{\tt CCTK\_BASEGRID}] @@ -758,7 +758,7 @@ through them. \item[{\tt CCTK\_POSTINITIAL}] \item[{\tt CCTK\_RECOVER\_VARIABLES}] - Used by thorns with relevent IO methods as the point + Used by thorns with relevant IO methods as the point to read in all the grid variables when recovering from checkpoint files. @@ -767,11 +767,11 @@ through them. to modify grid variables after recovery. \item[{\tt CCTK\_CPINITIAL}] - Used by thorns with relevent IO methods as the point to checkpoint + Used by thorns with relevant IO methods as the point to checkpoint initial data if required. \item[{\tt CCTK\_CHECKPOINT}] - Used by thorns with relevent IO methods as the point to checkpoint + Used by thorns with relevant IO methods as the point to checkpoint data during the iterative loop when required. \item[{\tt CCTK\_PRESTEP}] @@ -795,12 +795,12 @@ through them. \item[{\tt CCTK\_POSTRESTRICT}] This timebin is used only in mesh refinement settings. It is - ignored for unigrid runs. (With mesh refinemenets, boundary + ignored for unigrid runs. (With mesh refinements, boundary conditions might need to be applied after every ``restriction'' step.) \item[{\tt CCTK\_ANALYSIS}] - The analysis timebin is special, in that it is closely coupled + The {\tt ANALYSIS} timebin is special, in that it is closely coupled with output, and routines which are scheduled here are typically only executed if output of analysis variables is required. Routines which perform analysis should be independent of the main @@ -811,10 +811,10 @@ through them. \item[{\tt CCTK\_TERMINATE}] Called after the main iteration loop when Cactus terminates. Note that sometime in this timebin a driver thorn should be - destroying the grid hierachy and removing grid variables. + destroying the grid hierarchy and removing grid variables. \item[{\tt CCTK\_SHUTDOWN}] - Cactus final shutdown routines, after the grid hierachy has been + Cactus final shutdown routines, after the grid hierarchy has been destroyed. Grid variables are no longer available. \end{Lentry} @@ -826,7 +826,7 @@ through them. \chapter{Flesh parameters} \label{sec:ccpa} -The flesh parameters are defined in the file {\tt src/param.ccl}. +The Flesh parameters are defined in the file {\tt src/param.ccl}. \section{Private parameters} @@ -885,7 +885,7 @@ messages. [{\tt basic}] \begin{Lentry} -\item [{\tt cctk\_final\_time}] Final time for evolution, overriden by +\item [{\tt cctk\_final\_time}] Final time for evolution, overridden by {\tt cctk\_itlast} unless it is positive [{\tt -1.0}] \item[{\tt cctk\_initial\_time}] @@ -909,10 +909,10 @@ Terminate on next iteration ? [{\tt no}] %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\chapter{Using {\tt GNATS}} +\chapter{Using 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 bugtracker will assign appropriate maintainers +them to the GNATS. The bug tracker will assign appropriate maintainers to analyze and solve the problem. We are currently supporting a web based interface at \url{http://www.cactuscode.org} which lets you @@ -944,7 +944,7 @@ problem you are dealing with. out, for example, from an executable by typing {\tt cactus\_<config> -v}. \item[{\bf Environment}] Very important: specify the environment, -e.g.\ {\tt uname -a}, {\tt MPI}/non-{\tt MPI}, etc. +e.g.\ {\tt uname -a}, MPI/non-MPI, etc. \item[{\bf Description}] Describe your problem precisely, if you get a core dump, include the stack trace, give the minimal number of thorns, @@ -957,8 +957,8 @@ software related. \end{Lentry} We also provide the customized {\tt send-pr} and {\tt send-pr.el} programs at -our website. These commands are compiled to submit Cactus problem -reports in your shell and from within emacs, respectively. +our web site. These commands are compiled to submit Cactus problem +reports in your shell and from within Emacs, respectively. \label{sec:usgn} @@ -967,75 +967,75 @@ reports in your shell and from within emacs, respectively. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\chapter{Using {\tt CVS}} +\chapter{Using CVS} \label{sec:uscv} -{\tt CVS} is a version control system, which allows you to keep +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. -Unlike the simpler systems, {\tt CVS} does not just operate on one file at a +Unlike the simpler systems, CVS does not just operate on one file at a time or one directory at a time, but operates on hierarchical collections of directories consisting of -version controlled files. {\tt CVS} helps to manage +version controlled files. CVS helps to manage releases and to control the concurrent editing of source -files among multiple authors. {\tt CVS} can be obtained from +files among multiple authors. CVS can be obtained from \url{http://www.cyclic.com}. -A {\em CVS repository} located on a {\em server} may consist of an arbitrary -number of {\em modules}, which can be checked out (that is downloaded) -independently. The Cactus flesh and the Cactus -arrangements are organized as modules, their {\em CVS server} is {\tt cvs.cactuscode.org}. +A CVS \textit{repository} located on a \textit{server} may consist of an arbitrary +number of \textit{modules}, which can be checked out (that is downloaded) +independently. The Cactus Flesh and the Cactus +arrangements are organized as modules, their CVS \textit{server} is {\tt cvs.cactuscode.org}. \section{Essential CVS commands} \begin{Lentry} \item[{\bf cvs login}] -Logs into the repository. You will be prompted for a {\em -password}. This cvs command leaves a file {\tt .cvspass} in your -home directory. There is no need to login every time you issue a cvs +Logs into the repository. You will be prompted for a \textit{password}. +This CVS command leaves a file {\tt .cvspass} in your +home directory. There is no need to login every time you issue a CVS command, as long as this file exists. For a Cactus checkout, you have -to log into the CVS server, using the cvs option {\bf -d} to specify CVSROOT:\\ +to log into the CVS server, using the CVS option {\tt -d} to specify {\tt CVSROOT}:\\ {\tt cvs -d :pserver:cvs\_anon@cvs.cactuscode.org:/cactus login} -{\tt Note}: that there is no "logout" command: if you log in with +\emph{Note}: that there is no ``logout'' command: if you log in with administrative rights from an arbitrary account, you should be aware that the password file enables subsequent administrative logins from -that account. {\em Delete the file if necessary}. +that account. \emph{Delete the file if necessary}. -\item[{\bf cvs checkout} {\em modules} \ldots] +\item[{\bf cvs checkout} \textit{modules} \ldots] This command creates -your private copy of the source for {\em modules}. You can work +your private copy of the source for \textit{modules}. You can work with this copy without interfering with others' work. At least one subdirectory level is always created: it does not write all files into your current directory but creates a -directory. For Cactus, you need to either include the {\bf -d} options to -specify the CVSROOT directory and the CVS server, or specify them +directory. For Cactus, you need to either include the {\tt -d} options to +specify the {\tt CVSROOT} directory and the CVS server, or specify them with an environment variable (see below). Once you -have checked out the repository there is no need to include the {\bf +have checked out the repository there is no need to include the {\tt -d} option and its rather lengthy argument: the necessary information is contained in the local {\tt CVS/} directories. \item[{\bf cvs update}] -Execute this command from {\it within} your private +Execute this command from \emph{within} your private source directory when you wish to update your copies of source files from changes that other developers have made to the source in the repository. Merges are performed automatically when possible, a warning is issued if manual resolution is required for conflicting changes. If your local copy is several versions behind the actual repository copy, CVS -will {\em refetch} the whole file instead of applying multiple +will \emph{refetch} the whole file instead of applying multiple patches. \item[{\bf cvs add} {\tt file}] -Use this command to enroll new files in cvs records +Use this command to enroll new files in CVS records of your working directory. The files will be added -to the repository the next time you run `cvs -commit'. +to the repository the next time you run `{\tt cvs +commit}'. \item[{\bf cvs commit} {\tt file}] Use this command to add your local changes to the source to the repository and thereby making it publically available to checkouts and updates by other users. You cannot commit a -newly created file unless you have {\it added} it. +newly created file unless you have \emph{added} it. \item[{\bf cvs diff} {\tt file}] Show differences between a file in your working directory @@ -1054,7 +1054,7 @@ cvs diff -r 1.8 1.9 foobar.c Remove files from the source repository, pending a {\tt cvs commit} on the same files. -\item[{\bf cvs status} [file]] +\item[{\bf cvs status} {[}file{]}] This command returns the current status of your local copy relative to the repository: e.g.\ it indicates local modifications and possible updates. @@ -1086,92 +1086,92 @@ away, and only edit this version. \section{CVS Options} The CVS command line can include the following: \begin{Lentry} -\item[{\bf cvs options}] which apply to the overall cvs program +\item[{\bf cvs options}] which apply to the overall CVS program \item[{\bf a cvs command}] which defines a particular task carried out by -cvs -\item[{\bf command options}] to specify certain working modes for the cvs +CVS +\item[{\bf command options}] to specify certain working modes for the CVS command. \item[{\bf command arguments}] to specify which file to act on. \end{Lentry} -The options must be put {\em relative} to the {\it cvs command} as the -same option name can mean different things: {\em cvs options} go to the -{\em left} of the cvs command, {\em command options} go to the {\em right} -of the cvs command. Here is a list of essential {\em cvs options} +The options must be put \emph{relative} to the CVS \emph{command} as the +same option name can mean different things: CVS \emph{options} go to the +\emph{left} of the CVS command, \emph{command options} go to the \emph{right} +of the CVS command. Here is a list of essential CVS options: \begin{Lentry} -\item[{\bf -d} {\em cvs\_root\_directory}] -Use {\em cvs\_root\_directory} as the root directory pathname of +\item[{\bf -d} \textit{cvs\_root\_directory}] +Use \textit{cvs\_root\_directory} as the root directory pathname of the master source repository. Overrides -the setting of the {\em CVSROOT} environment variable. +the setting of the {\tt CVSROOT} environment variable. This value should be specified as an absolute pathname. In the Cactus checkout procedure, you specify the Cactus CVS server:\\ {\tt -d :pserver:cvs\_anon@cvs.cactuscode.org:/cactus/} -\item[{\bf -z} {\em compression-level}] +\item[{\bf -z} \textit{compression-level}] When transferring files across the network use {\tt gzip} -with compression level {\em compression-level} to compress and +with compression level \textit{compression-level} to compress and decompress data as it is transferred. -Requires the presence of the GNU gzip program in +Requires the presence of the GNU {\tt gzip} program in the current search path at both ends of the link. \item[{\bf -n}] -Do not change any file. Attempt to execute the {\em cvs command} but +Do not change any file. Attempt to execute the CVS \textit{command} but only to issue reports. Does not remove, update, etc. any files. Very effective for testing. \item[{\bf -v}] Displays version information of the installed CVS. -\item[{\bf -H} {\em cvs-command}] -Displays usage information about the specified cvs command. Without -cvs-command, a list of all available commands is returned. +\item[{\bf -H} \textit{cvs-command}] +Displays usage information about the specified CVS command. Without +\textit{cvs-command}, a list of all available commands is returned. \end{Lentry} -Here is a list of essential {\em command options} with the -commands they are used with. They go after the cvs command. For a more +Here is a list of essential command options with the +commands they are used with. They go after the CVS command. For a more complete list of all options, please refer to the manual page. \begin{Lentry} \item[{\bf -P}] Prune (remove) directories that are empty after being updated, on -{\bf checkout}, or {\bf update}. Normally, an empty directory +{\tt checkout}, or {\tt update}. Normally, an empty directory (one that is void of revision controlled files) is left alone. -Specifying {\bf -P} will cause these directories to be silently -removed from your checked-out sources. This does not remove +Specifying {\tt -P} will cause these directories to be silently +removed from the sources you have checked out. This does not remove the directory from the repository, only from your checked out copy. -\item[{\bf -m} {\em "Text"}] -Specify a logging message explaining changes, etc. on {\bf commit}, -{\bf import}. If you do not specify a message, your default editor +\item[{\bf -m} \textit{"Text"}] +Specify a logging message explaining changes, etc. on {\tt commit}, +{\tt import}. If you do not specify a message, your default editor is invoked to allow you to enter one. \item[\bf -d] -Use this option with the {\bf update} command to create any +Use this option with the {\tt update} command to create any directories if they are missing from your local copy. This is normally the case if another user has added files or directories to the -repository. By default the {\bf update} command only acts on files in +repository. By default the {\tt update} command only acts on files in your local copy. Note that omitting this option is a frequent cause of files missing during compilation. (You can change this -default behavior of cvs by putting a .cvsrc in your home directory -with the contents ``update -d''.) +default behavior of CVS by putting a {\tt .cvsrc} in your home directory +with the contents ``{\tt update -d}''.) \end{Lentry} \section{CVS Examples} -We list some sample CVS commands to treat the most typical Cactus4.0 +We list some sample CVS commands to treat the most typical Cactus 4.0 CVS situations. \begin{description} \item\textbf{Logging into the server}\newline {\tt cvs -d :pserver:cvs\_anon@cvs.cactuscode.org:/cactus -login} \\ You will be asked for the password for user {\em cvs\_anon}, which is {\tt anon}. +login} \\ You will be asked for the password for user \textit{cvs\_anon}, which is {\tt anon}. \item\textbf{Checking out the code}\newline {\tt cvs -d :pserver:cvs\_anon@cvs.cactuscode.org:/cactus checkout Cactus}\\ -check out a CVS module named "Cactus", in this case it checks out the +check out a CVS module named ``Cactus'', in this case it checks out the Cactus Computational Toolkit. A directory {\tt ./Cactus} is created if it doesn't already exist. If you perform a checkout on an already existing and locally modified copy of the module, CVS will try to merge the files @@ -1198,7 +1198,7 @@ To update a directory {\tt ./mysources}, type\\ \item\textbf{Committing a changed file}\newline To commit changes you have applied to your local copy, your file must be in sync with the repository: your changes must be done to the -latest version, otherwise CVS will instruct you to perform an {\bf +latest version, otherwise CVS will instruct you to perform an {\tt update} first. To commit changes made to a file {\tt ./foobar}, type\\ {\tt cvs commit -m "Reason for the change" ./foobar}\\ You may specify several files to commit. @@ -1211,7 +1211,7 @@ schedule the file for addition, then you commit it:\\ \item\textbf{Creating a new thorn}\newline -To add a new {\bf module} (e.g.\ an arrangement) to a Cactus repository we +To add a new \textit{module} (e.g.\ an arrangement) to a Cactus repository we first have to create a directory for you with the right permissions. Please contact {\tt cactus@cactuscode.org} providing the name of the requested module, and who should be able to commit changes to the module. @@ -1220,23 +1220,23 @@ To add the new module, change directory so that you are in the first directory that you want to commit to the repository. (e.g.\ if you want to commit a new arrangement called {\tt MyArrange} then change directory to {\tt MyArrange}). Then type\\ -{\tt cvs -d :pserver:}{\em your\_login}{\tt -@cvs.cactuscode.org:<repository name> } import {\em module\_name} {\tt start V1}\\ +{\tt cvs -d :pserver:}\textit{your\_login}{\tt +@cvs.cactuscode.org:<repository name> } import \textit{module\_name} {\tt start V1}\\ (where {\tt start} and {\tt V1} are the vendor and release tags, which you could change to something different). -To add a new {\bf directory} {\tt <new dir>} to an existing module (that you have write permissions for), either add the directory using\\ +To add a new \textit{directory} {\tt <new dir>} to an existing module (that you have write permissions for), either add the directory using\\ {\tt cvs add <new dir>}\\ and then recursing down adding all the new files and directories contained inside, or import the directory by changing directory to sit inside it, and then using\\ -{\tt cvs -d :pserver:}{\em your\_login}{\tt +{\tt cvs -d :pserver:}\textit{your\_login}{\tt @cvs.cactuscode.org:<repository\_name> } import {\tt <relative name> start V1}\\ -Where {\tt <relative name>} means the position of the directory within the module. (For example, if you have a module called {\em AMod} which contains a -directory {\em BMod}, and you want to add {\em CMod} inside {\em BMod}, then change directory to {\em BMod}, and use {\em AMod/BMod} for the {\em relative name}). +Where {\tt <relative name>} means the position of the directory within the module. (For example, if you have a module called \textit{AMod} which contains a +directory \textit{BMod}, and you want to add \textit{CMod} inside \textit{BMod}, then change directory to \textit{BMod}, and use \textit{AMod/BMod} for the \textit{relative name}). \end{description} -\section{Checking out flesh and thorns with CVS} +\section{Checking out Flesh and thorns with CVS} \begin{Lentry} \item[{\bf Login}] Prior to any CVS operation, you need to log into the Cactus @@ -1244,20 +1244,20 @@ directory {\em BMod}, and you want to add {\em CMod} inside {\em BMod}, then cha {\tt cvs -d :pserver:cvs\_anon@cvs.cactuscode.org:/cactus login } - You will be prompted for a password which is {\bf anon}. + You will be prompted for a password which is {\tt anon}. \item[{\bf Checkout}] To obtain a fresh copy of Cactus, move to a directory which does not contain a previously checked out version, and type {\t cvs -d :pserver:cvs\_anon@cvs.cactuscode.org:/cactus checkout Cactus } - The CVS checkout procedure will create a directory called {\bf + The CVS checkout procedure will create a directory called {\tt Cactus} and install the code inside this directory. From now on we - will reference all directory names relative to {\bf Cactus}. + will reference all directory names relative to {\tt Cactus}. \noindent If you want to compile Cactus with thorns, you now need to checkout - separately the required arrangement (or {\it arrangements}) - into the {\bf arrangements} directory. To see the + separately the required arrangement (or \textit{arrangements}) + into the {\tt arrangements} directory. To see the available Cactus arrangements and thorns type {\t cvs -d :pserver:cvs\_anon@cvs.cactuscode.org:/cactus checkout -s @@ -1277,7 +1277,7 @@ home directory which provides menus to pick arrangements and thorns from. \item[{\bf Update}] To update an existing Cactus checkout (to patch in - possible changes, etc.), do the following {\em within} the {\tt Cactus} directory. + possible changes, etc.), do the following \emph{within} the {\tt Cactus} directory. {\t cvs update } @@ -1293,7 +1293,7 @@ home directory which provides menus to pick arrangements and thorns from. \item[{\bf non-anonymous CVS}] If you have an account at the central repository ({\tt cvs.cactuscode.org}) and would like to perform any of the operation above - {\em non-anonymously}, replace {\tt cvs\_anon} by your login name + \emph{non-anonymously}, replace {\tt cvs\_anon} by your login name and provide the appropriate password during the CVS login process. Depending on your permissions, you may then make commits to Cactus or its arrangements. @@ -1305,19 +1305,19 @@ home directory which provides menus to pick arrangements and thorns from. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\chapter{Using TAGS} +\chapter{Using Tags} \label{sec:usta} Finding your way around in the Cactus structure can be pretty -difficult to handle. To make life easier there is support for TAGS, -which lets you browse the code easily from within Emacs/XEmacs or vi. -A TAGS database can be generated with gmake: +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} +\section{Tags with Emacs} \label{sec:tawiem} -{\tt gmake TAGS} will create a database for a routine reference +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 -emacs if you add either of the following lines to your {\tt .emacs} file:\\ +Emacs if you add either of the following lines to your {\tt .emacs} file:\\ {\tt (setq tags-file-name "CACTUS\_HOME/TAGS")} XOR \\ {\tt (setq tag-table-alist '(("CACTUS\_HOME" . "CACTUS\_HOME/TAGS")))}\\ where {\tt CACTUS\_HOME} is your Cactus directory.\\ @@ -1330,7 +1330,7 @@ functions or ``tags'': \item \textbf{ Alt*} will go back to the last matched tag \end{enumerate} If you add the following lines to your {\tt .emacs} file, the -files found with TAGS will opened in {\em read-only} mode: +files found with tags will opened in \emph{read-only} mode: \begin{verbatim} (defun find-tag-readonly (&rest a) (interactive) @@ -1345,25 +1345,25 @@ files found with TAGS will opened in {\em read-only} mode: (global-set-key [(control meta \.)] 'find-tag-readonly) (global-set-key [(control meta \,)] 'find-tag-readonly-next) \end{verbatim} -The Key strokes to use when you want to browse in read-only mode are: +The key strokes to use when you want to browse in read-only mode are: \begin{enumerate} \item{CTRL Alt.} will find a tag and open the file in read-only mode \item{CTRL Alt,} will find the next matching tag in read-only mode \end{enumerate} -\section{TAGS with vi} +\section{Tags with {\tt vi}} \label{sec:tawivi} -The commands available are highly dependent upon the version of {\bf vi}, but +The commands available are highly dependent upon the version of {\tt vi}, but the following is a selection of commands which may work. \begin{enumerate} \item \textbf{vi -t tag} -Start vi and position the cursor at the file and line where `tag' is defined. +Start {\tt vi} and position the cursor at the file and line where `tag' is defined. -\item \textbf{Control-]} +\item \textbf{Control-{]}} Find the tag under the cursor. \item \textbf{:ta tag} @@ -1382,10 +1382,10 @@ Return to previous location before jump to tag (not widely implemented). \vspace{1.1cm} -\textbf{Note: Currently some of the \texttt{CCTK\_FILEVERSION()} macros +\emph{Note: Currently some of the \texttt{CCTK\_FILEVERSION()} macros at the top of every source file don't have a trailing semicolon, which -confuses the \texttt{etags} and \texttt{ctags} programs, so TAGS does not find the first -subroutine in any file with this problem.} +confuses the \texttt{etags} and \texttt{ctags} programs, so tags does not +find the first subroutine in any file with this problem.} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% diff --git a/doc/UsersGuide/Infrastructure.tex b/doc/UsersGuide/Infrastructure.tex index 8821c851..460412bd 100644 --- a/doc/UsersGuide/Infrastructure.tex +++ b/doc/UsersGuide/Infrastructure.tex @@ -35,24 +35,24 @@ \section{Overloading and Registration} -The flesh defines a core API which guarantees the presence of a set of -functions. Although the flesh guarantees the presence of these functions, -they can be provided by thorns. Thorns do this either by the {\em overloading} -or the {\em registration} of functions. +The Flesh defines a core API which guarantees the presence of a set of +functions. Although the Flesh guarantees the presence of these functions, +they can be provided by thorns. Thorns do this either by the \textit{overloading} +or the \textit{registration} of functions. \subsection{Overloading} Some functions can only be provided by one thorn. The first thorn to -{\em overload} this function succeeds, and any later attempt to overload +\textit{overload} this function succeeds, and any later attempt to overload the function fails. For each overloadable function there is a function with a name something like {\tt CCTK\_Overload...} which is passed the function pointer. \subsection{Registration} -Some functions may be provided by several thorns. The thorns {\em register} -their function with the flesh, and when the flesh-provided function is called, -the flesh calls all the registered functions. +Some functions may be provided by several thorns. The thorns \textit{register} +their function with the Flesh, and when the Flesh-provided function is called, +the Flesh calls all the registered functions. \section{GH Extensions} @@ -64,7 +64,7 @@ Each GH extension is given a unique handle. \section{IO Methods} An IO method is a distinct way to output data. Each IO method has a unique name, -and the flesh-provided IO functions operate on all registered IO methods. +and the Flesh-provided IO functions operate on all registered IO methods. \chapter{GH Extensions} @@ -75,13 +75,13 @@ name of the extension. This returns a unique handle that identifies the extensi Associated with a GH extension are three functions \begin{Lentry} -\item[SetupGH] +\item[{\tt SetupGH}] this is used to actually create the data structure holding the extension. It is called when a new cGH is created. -\item[InitGH] +\item[{\tt InitGH}] this is used to initialise the extension. It is called after the scheduler has been initialised on the cGH. -\item[ScheduleTraverseGH] +\item[{\tt ScheduleTraverseGH}] this is called whenever the schedule tree is due to be traversed on the GH. It should initialise the data on the cGH and the call {\tt CCTK\_ScheduleTraverse} to traverse the schedule tree. @@ -124,7 +124,7 @@ the schedule tree. \chapter{Adding a Driver} -The flesh knows nothing about memory allocation for grid variables, or about how +The Flesh knows nothing about memory allocation for grid variables, or about how to communicate data when synchronisation is called for. It knows nothing about multiple patches or adaptive mesh refinement. All this is the job of a driver. @@ -135,7 +135,7 @@ registers its associated functions, and overloads the communication functions. It may optionally register interpolation, reduction, and IO methods. A driver may also overload the default Initialisation and Evolution routines, -although a simple unigrid evolver is supplied in the flesh. +although a simple unigrid evolver is supplied in the Flesh. \section{Startup} @@ -143,19 +143,19 @@ A driver consists of a GH extension, and the following overloaded functions. \begin{enumerate} -\item{} CCTK\_EnableGroupStorage -\item{} CCTK\_DisableGroupStorage -\item{} CCTK\_ArrayGroupSizeB -\item{} CCTK\_QueryGroupStorageB -\item{} CCTK\_SyncGroup -\item{} CCTK\_EnableGroupComm -\item{} CCTK\_DisableGroupComm -\item{} CCTK\_Barrier -\item{} CCTK\_OverloadParallelInit -\item{} CCTK\_OverloadExit -\item{} CCTK\_OverloadAbort -\item{} CCTK\_OverloadMyProc -\item{} CCTK\_OverloadnProcs +\item{} {\tt CCTK\_EnableGroupStorage} +\item{} {\tt CCTK\_DisableGroupStorage} +\item{} {\tt CCTK\_ArrayGroupSizeB} +\item{} {\tt CCTK\_QueryGroupStorageB} +\item{} {\tt CCTK\_SyncGroup} +\item{} {\tt CCTK\_EnableGroupComm} +\item{} {\tt CCTK\_DisableGroupComm} +\item{} {\tt CCTK\_Barrier} +\item{} {\tt CCTK\_OverloadParallelInit} +\item{} {\tt CCTK\_OverloadExit} +\item{} {\tt CCTK\_OverloadAbort} +\item{} {\tt CCTK\_OverloadMyProc} +\item{} {\tt CCTK\_OverloadnProcs} \end{enumerate} \section{The GH Extension} @@ -213,7 +213,7 @@ struct SimpleExtension *SimpleSetupGH(tFleshConfig *config, int conv_level, cGH \end{verbatim} Basically all this example is doing is preparing a data array for use. The -function can query the flesh for information on every variable. Note that +function can query the Flesh for information on every variable. Note that scalars should always have memory actually assigned to them. An {\tt InitGH} function isn't strictly necessary, and in this case it could just @@ -285,7 +285,7 @@ int SimpleScheduleTraversGH(cGH *GH, const char *where) \end{verbatim} The third argument to {\tt CCTK\_ScheduleTraverse} is actually a function -which will be called by the schedular when it wants to call a function +which will be called by the scheduler when it wants to call a function scheduled by a thorn. This function is given some information about the function to call, and is an alternative place where the cGH can be setup. @@ -334,7 +334,7 @@ int SimpleCallFunction(void *function, The return code of the function signifies whether or not the function synchronised the groups in this functions synchronisation list of not. -The flesh will synchronise them if the function returns false. +The Flesh will synchronise them if the function returns false. Providing this function is probably the easiest way to do multi-patch or AMR drivers. @@ -343,10 +343,10 @@ AMR drivers. These consist of \begin{enumerate} -\item{} CCTK\_EnableGroupStorage -\item{} CCTK\_DisableGroupStorage -\item{} CCTK\_QueryGroupStorageB -\item{} CCTK\_ArrayGroupSizeB +\item{} {\tt CCTK\_EnableGroupStorage} +\item{} {\tt CCTK\_DisableGroupStorage} +\item{} {\tt CCTK\_QueryGroupStorageB} +\item{} {\tt CCTK\_ArrayGroupSizeB} \end{enumerate} \subsection{En/Disable Group Storage} @@ -385,8 +385,8 @@ int SimpleEnableGroupStorage(cGH *GH, const char *groupname) The disable function is basically the reverse of the enable one. -The QueryGroupStorage function basically returns true or false if there is storage -for the group, and the ArrayGroupSize returns the size of the grid function or array +The {\tt QueryGroupStorage} function basically returns true or false if there is storage +for the group, and the {\tt ArrayGroupSize} returns the size of the grid function or array group in a particular direction. \subsection{En/Disable Group Comm} @@ -400,23 +400,23 @@ structures for the communication. \chapter{Adding an I/O Method} \label{chap:io_methods} % -The flesh does not implement output for grid variables and other data by itself. +The Flesh does not implement output for grid variables and other data by itself. Instead it provides a mechanism for thorns to register their own routines as I/O methods, and to invoke these I/O methods by either the -flesh scheduler or by other thorn routines. +Flesh scheduler or by other thorn routines. % \section{I/O Method Registration} % -All I/O methods have to be registered with the flesh before they can be used.\\ -The flesh I/O registration API provides a routine {\t CCTK\_RegisterIOMethod()} +All I/O methods have to be registered with the Flesh before they can be used.\\ +The Flesh I/O registration API provides a routine {\t CCTK\_RegisterIOMethod()} to create a handle for a new I/O method which is identified by its name (this name must be unique for all I/O methods). With such a handle, a thorn can then register a set of functions (using the -{\t CCTK\_RegisterIOMethod*()} routines from the flesh) for doing +{\t CCTK\_RegisterIOMethod*()} routines from the Flesh) for doing periodic, triggered, and/or unconditional output. -The following example shows how a thorn would register an I/O method {\it -"SimpleIO"} with routines to provide all these different types of output. +The following example shows how a thorn would register an I/O method +{\tt SimpleIO} with routines to provide all these different types of output. % \begin{verbatim} void SimpleIO_Startup (void) @@ -440,8 +440,8 @@ The following example shows how a thorn would register an I/O method {\it % \section{Periodic Output of Grid Variables} % -The flesh scheduler will automatically call {\t CCTK\_OutputGH()} at every -iteration after the CCTK\_ANALYSIS time bin. This function loops over all I/O +The Flesh scheduler will automatically call {\t CCTK\_OutputGH()} at every +iteration after the {\tt CCTK\_ANALYSIS} time bin. This function loops over all I/O methods and calls their routines registered as {\t OutputGH()} (see also \ref{subsec:schedule_ccl}). % @@ -450,7 +450,7 @@ methods and calls their routines registered as {\t OutputGH()} (see also \end{verbatim} % The {\t OutputGH()} routine itself should loop over all variables living on the -{\t GH} grid hierarchy, and do all neccessary output if requested (this is +{\t GH} grid hierarchy, and do all necessary output if requested (this is usually determined by I/O parameter settings). As its return code it should pass back the number of variables which were output @@ -462,12 +462,12 @@ at the current iteration, or zero if no output was done by this I/O method. Besides the periodic output at every so many iterations using {\t OutputGH()}, analysis and output of grid variables can also be done via triggers. For this, a {\t TimeToOutput()} routine is registered with an I/O method. -This routine will be called by the flesh scheduler at every iteration before -CCTK\_ANALYSIS with the triggering variable(s) as defined in the schedule -block for all CCTK\_ANALYSIS routines (see \ref{scheduling:schedule_block}). +This routine will be called by the Flesh scheduler at every iteration before +{\tt CCTK\_ANALYSIS} with the triggering variable(s) as defined in the schedule +block for all {\tt CCTK\_ANALYSIS} routines (see \ref{scheduling:schedule_block}). If the {\t TimeToOutput()} routine decides that it is now time to do output, the -flesh scheduler will invoke the corresponding analysis routine and also request +Flesh scheduler will invoke the corresponding analysis routine and also request output of the triggering variable(s) using {\t TriggerOutput()}. % \begin{verbatim} @@ -478,16 +478,16 @@ output of the triggering variable(s) using {\t TriggerOutput()}. Both routines get passed the index of a possible triggering grid variable. {\t TimeToOutput()} should return true (a non-zero value) if analysis and output -for {\it varindex} should take place at the current iteration, and false (zero) +for \textit{varindex} should take place at the current iteration, and false (zero) otherwise.\\ {\t TriggerOutput()} should return zero for successful output of variable -{\it varindex}, and a negative value in case of an error. +\textit{varindex}, and a negative value in case of an error. % % \section{Unconditional Output of Grid Variables} An I/O method's {\t OutputVarAs()} routine is supposed to do output for a -specific grid variable if ever possible. It will be invoked by the flesh I/O API +specific grid variable if ever possible. It will be invoked by the Flesh I/O API routines {\t CCTK\_OutputVar*()} for unconditional, non-triggered output of grid variables (see also \ref{sec:io}). @@ -498,11 +498,11 @@ prototype: int SimpleIO_OutputVarAs (const cGH *GH, const char *varname, const char *alias); \end{verbatim} % -The variable to output, {\it varname}, is given by its full name. -In addition to that, an {\it alias} string can be passed which then serves +The variable to output, \textit{varname}, is given by its full name. +In addition to that, an \textit{alias} string can be passed which then serves the purpose of constructing a unique name for the output file. -The {\t OutputVarAs()} routine should return zero if output for {\it varname} +The {\t OutputVarAs()} routine should return zero if output for \textit{varname} was done successfully, or a negative error code otherwise. @@ -511,20 +511,20 @@ was done successfully, or a negative error code otherwise. \label{chap:cp_recovery_methods} Like for I/O methods, checkpointing/recovery functionality must be implemented -by thorns. The flesh only provides specific time bins at which the scheduler +by thorns. The Flesh only provides specific time bins at which the scheduler will call thorns' routines in order to perform checkpointing and/or recovery. \section{Invocation of Checkpointing Routines} Thorns register their checkpointing routines at {\t CCTK\_CPINITIAL} and/or {\t CCTK\_CHECKPOINT}. These time bins are scheduled right after all initial -data has been set up and after every evolution timestep resp. (see +data has been set up and after every evolution timestep, respectively. (see \ref{subsec:schedule_ccl} for a description of all timebins). Depending on parameter settings, the checkpoint routines decide whether to write an initial data checkpoint, and when to write an evolution checkpoint. Each checkpoint routine should save all information to persistent storage which -is neccessary to restart the simulation at a later time from exactly the same +is necessary to restart the simulation at a later time from exactly the same state. Such information would include % \begin{itemize} @@ -538,7 +538,7 @@ state. Such information would include \section{Invocation of Recovery Routines} -Recovering from a checkpoint is a two-phase operation for which the flesh +Recovering from a checkpoint is a two-phase operation for which the Flesh provides distinct timebins for recovery routines to be scheduled at: % \begin{Lentry} @@ -547,13 +547,13 @@ provides distinct timebins for recovery routines to be scheduled at: settings, the recovery routines should decided whether recovery was requested, and if so, restore all parameters the checkpoint file and overwrite those which aren't steerable.\\ - The flesh scheduler loops over all registered recovery routines to find out + The Flesh scheduler loops over all registered recovery routines to find out whether recovery was requested. Each recovery routine should therefore return a positive integer value for successful parameter recovery (causing the scheduler to shortcut its loop over all registered recovery routines), zero for no recovery, or a negative value to flag an error.\\ If recovery was requested but no routine could successfully recover - parameters, the flesh will abort the run with an error message.\\ + parameters, the Flesh will abort the run with an error message.\\ If parameter recovery was performed successfully, the scheduler will set the {\tt recovered} flag which -- in combination with the setting of the {\tt Cactus::recovery\_mode} parameter -- decides whether any thorn routine @@ -569,7 +569,7 @@ provides distinct timebins for recovery routines to be scheduled at: decide how to treat errors in recovering individual grid variables. Strict recovery (which is the default) requires all variables to be restored successfully (and should stop the code if not) whereas a relaxed mode - could eg. allow for grid variables which are not found in the checkpoint + could e.g. allow for grid variables which are not found in the checkpoint file to be gracefully ignored during recovery. \end{Lentry} @@ -578,7 +578,7 @@ provides distinct timebins for recovery routines to be scheduled at: \chapter{Adding a timer} To add a Cactus timer you need to write several functions to provide the -timer functionality, and then register these functions with the flesh, with a name for the timer using {\t CCTK\_TimerRegister}. +timer functionality, and then register these functions with the Flesh, with a name for the timer using {\t CCTK\_TimerRegister}. The functions are registered using a structure {\t cTimerFuncs} which contains the function pointers. The required functions are: diff --git a/doc/UsersGuide/Preface.tex b/doc/UsersGuide/Preface.tex index 46228bb4..98f3c33d 100644 --- a/doc/UsersGuide/Preface.tex +++ b/doc/UsersGuide/Preface.tex @@ -59,7 +59,7 @@ This guide covers the following topics \item [{\bf Part~\ref{part:Infrastructure}: Infrastructure Thorn Writer's Guide.}] In this more advanced part, we talk about user supplied infrastructure routines such - as {\em additional output routines, drivers, etc.} [This part is not + as \textit{additional output routines, drivers, etc.} [This part is not yet complete, and is currently under construction.] \item [\bf Part~\ref{part:Appendices}: Appendices.] diff --git a/doc/UsersGuide/RunningCactus.tex b/doc/UsersGuide/RunningCactus.tex index 4319d76d..575a2414 100644 --- a/doc/UsersGuide/RunningCactus.tex +++ b/doc/UsersGuide/RunningCactus.tex @@ -24,26 +24,26 @@ \section{Required software} \label{sec:reqo} -In general, Cactus {\em requires} the following set of software to function +In general, Cactus \emph{requires} the following set of software to function in single processor mode. Please refer to the architecture section \ref{sec:suar} for architecture specific items. \begin{Lentry} -\item[{\tt Perl5.0}] Perl is used extensively during the Cactus +\item[Perl5.0] Perl is used extensively during the Cactus thorn configuration phase. Perl is available for nearly all operating systems known to man and can be obtained at \url{http://www.perl.org} -\item[{\tt GNU make}] The make - process works with the GNU make utility (referred to as {\bf gmake} +\item[GNU make] The make + process works with the GNU make utility (referred to as {\tt gmake} henceforth). While other make utilities may also work, this is not guaranteed. Gmake can be obtained from your favorite GNU site or from \url{http://www.gnu.org} -\item[{\tt C}] C compiler. For example, the GNU compiler. This +\item[C] C compiler. For example, the GNU compiler. This is available for most supported platforms. Platform specific compilers should also work. -\item[{\tt CPP}] C Pre-processor. For example, the GNU CPP. These are -normally provided on most platforms, and many C compilers have an option -to just run as a preprocessor. -\item[{\tt CVS}] The {\em ``Concurrent Versioning System''} is not needed +\item[CPP] C Preprocessor. For example, the GNU {\tt cpp}. These are + normally provided on most platforms, and many C compilers have an option + to just run as a preprocessor. +\item[CVS] The \textit{Concurrent Versions System} is not needed to run/compile Cactus, but you are strongly encourage to install this software to take advantage of the update procedures. It can be downloaded from your favorite GNU site. Tar files of each release are @@ -54,45 +54,45 @@ to just run as a preprocessor. To use Cactus, with the default driver\footnote{For help with unfamiliar terms, please consult the glossary, Appendix \ref{sec:glossary}.} ({\tt CactusPUGH/PUGH}) on multiple processors you also need: \begin{Lentry} -\item[{\tt MPI}] the {\it Message Passing Interface (MPI)} +\item[MPI] The \textit{Message Passing Interface} which provides inter-processor communication. -Supercomputing sites often supply a native {\tt MPI} implementation with +Supercomputing sites often supply a native MPI implementation with which Cactus is very likely to be compatible. Otherwise there are -various freely available ones available, e.g. the {\tt MPICH} -version of {\tt MPI} is available for various architectures and operating +various freely available ones available, e.g. the MPICH +version of MPI is available for various architectures and operating systems at \url{http://www-unix.mcs.anl.gov/mpi/}. \end{Lentry} \noindent If you are using any thorns containing routines -written in {\tt C++} you also need +written in C++ you also need \begin{Lentry} -\item[{\tt C++}] C++ compiler. For example, the GNU compiler. This +\item[C++] C++ compiler. For example, the GNU compiler. This is available for most supported platforms. Platform specific compilers should also work. Note that if a C++ compiler is available then the - {\em main} routine in the flesh is compiled with C++ to allow static + {\tt main} routine in the Flesh is compiled with C++ to allow static class initialisations. \end{Lentry} \noindent If you are using any thorns containing routines -written in {\tt FORTRAN} you also need +written in Fortran you also need \begin{Lentry} -\item[{\tt F90/F77}] For routines written in F77, either an F90 or an F77 - compiler can be used. For routines written in F90 a F90 compiler is - obviously - required. There is a very limited set of free F90 compilers available - for the different architectures. +\item[F90/F77] For routines written in Fortran 77, either an Fortran 90 or + a Fortran 77 compiler can be used. For routines written in Fortran 90 + a Fortran 90 compiler is obviously required. There is a very limited set of + free Fortran 90 compilers available for the different architectures. \end{Lentry} \noindent While not required for compiling or running Cactus, for thorn development it is useful to install \begin{Lentry} -\item[{\tt ctags/etags}] The program Tags enables 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 vi both support this method. See - \ref{sec:usta} for a short guide to ``tags''. +\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''. \end{Lentry} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -110,39 +110,39 @@ be found at \end{center} \begin{Lentry} -\item[{\bf SGI}] 32 or 64 bit running Irix. -\item[{\bf Cray T3E}] -\item[{\bf Compaq Alpha}] Compaq operating system and Linux. Single processor - mode and {\tt MPI} supported. The Alphas need to have the GNU {\tt C/C++} +\item[\textbf{SGI}] 32 or 64 bit running Irix. +\item[\textbf{Cray T3E}] +\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 -processor mode and MPI ({\tt MPICH} and {\tt LAM}) supported.\\On +processor mode and MPI (MPICH and LAM) supported.\\On Windows Cactus compiles with Cygwin. MPI -({\tt WMPI}, {\tt HPVM}, and {\tt MPIPro}) supported. Please read -doc/README.NT for details. +(WMPI, HPVM, and MPIPro) supported. Please read +{\tt doc/README.NT} for details. \item[\textbf{IA64}] running Linux. -\item[{\bf Macintosh PowerPC}] (MacOS X and Linux PPC) -\item[{\bf IBM SP2}] 32 or 64 bit running AIX. -\item[{\bf Hitachi SR8000-F1}] -\item[{\bf Sun} Solaris] -\item[{\bf Fujitsu}] +\item[\textbf{Macintosh PowerPC}] (MacOS X and Linux PPC) +\item[\textbf{IBM SP2}] 32 or 64 bit running AIX. +\item[\textbf{Hitachi SR8000-F1}] +\item[\textbf{Sun} Solaris] +\item[\textbf{Fujitsu}] \end{Lentry} %\begin{Lentry} %\item[{\bf SGI Origin 2000} running Irix] %\item[{\bf SGI} 32 or 64 bit running Irix] %\item[{\bf Cray T3E}] -%\item[{\bf Dec Alpha}] Dec operating system and Linux. Single processor -% mode and {\tt MPI} supported. The Decs need to have the GNU {\tt C/C++} +%\item[{\bf DEC Alpha}] Dec operating system and Linux. Single processor +% mode and MPI supported. The DECs need to have the GNU C/C++ % compilers installed %\item[{\bf Linux (ia32, ia64, ppc, alpha)}] There is a % free Linux F90 compiler available from \url{http://www.psrv.com} % -- the only free we know of; please note the comment about installing this in %the FAQ. -% Single processor mode and MPI ({\tt MPICH} and {\tt LAM}) supported. +% Single processor mode and MPI (MPICH and LAM) supported. %\item[{\bf Windows NT}] Compiles with Cygwin. Single processor mode and MPI ({\t %t WMPI}, -%{\tt HPVM}, and {\tt MPIPro}) supported. Please read doc/README.NT for details. +%{\tt HPVM}, and MPIPro) supported. Please read doc/README.NT for details. %\item[{\bf Macintosh PowerPC (MacOS X)}] %\item[{\bf IBM SP2}] %\item[{\bf Hitachi SR8000-F1}] @@ -151,8 +151,8 @@ doc/README.NT for details. The following machines are only partially supported \begin{Lentry} -\item[{\bf HP Exemplar}] -\item[{\bf NEC SX-5}] +\item[\textbf{HP Exemplar}] +\item[\textbf{NEC SX-5}] \end{Lentry} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -161,39 +161,39 @@ The following machines are only partially supported \label{sec:chpr} Cactus is distributed, extended, and maintained using the free CVS -software ({\it Concurrent Versioning System}: \url{http://www.cvshome.org}). +software (\textit{Concurrent Versions System}: \url{http://www.cvshome.org}). CVS allows many people to work on a large software project together without getting into a tangle. Since Cactus thorns are distributed from several repositories on the main CVS site, and from a growing number of user sites, we provide a -script, described below, on our website for checking out the flesh and thorns. -The Cactus website also provides a form interface for direct download. +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. The space required for an installation depends on the arrangements and -thorns used. The flesh on its own requires less than 5 MB. +thorns used. The Flesh on its own requires less than 5 MB. -The script for checking out the flesh and thorns, {\tt GetCactus}, is available -from the website at +The script for checking out the Flesh and thorns, {\tt GetCactus}, is available +from the web site at \url{http://www.cactuscode.org/Download/GetCactus} The -script takes as an argument the name of a file containing a {\it ThornList}, +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} } -If no filename is given, only the flesh is checked out. +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 -the flesh. A full description of ThornList syntax is provided in Appendix~\ref{chap:th}. -ThornLists for example applications are provided on the Cactus website. +the Flesh. A full description of ThornList syntax is provided in Appendix~\ref{chap:th}. +ThornLists for example applications are provided on the Cactus web site. The same script can be used to checkout additional thorns. @@ -207,7 +207,7 @@ following subdirectories: \begin{Lentry} -\item[{\tt CVS}] the CVS book-keeping directory, present in every subdirectory +\item[{\tt CVS}] the CVS bookkeeping directory, present in every subdirectory \item[{\tt doc}] Cactus documentation @@ -238,7 +238,7 @@ or \begin{itemize} \item{} soft link this directory ({\tt ln -s scratch/cactus\_configs Cactus/configs/}) to the Cactus directory, if your -file-system supports soft-links. +filesystem supports soft links. \end{itemize} Configurations are described in detail in section \ref{sec:coaco}. @@ -248,7 +248,7 @@ Configurations are described in detail in section \ref{sec:coaco}. \section{Getting help} \label{sec:gehe} -For tracking problem reports and bugs we use GNATS, which is a bugtracking +For tracking problem reports and bugs we use GNATS, which is a bug tracking system published under the GNU license. We have set up a web interface at \url{http://www.cactuscode.org} which allows easy submission and browsing of problem reports. @@ -258,7 +258,7 @@ A description of the GNATS categories which we use is provided in the appendix % 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 -% through a make-process which installs stuff somewhere on his HD. gerd. +% through a make process which installs stuff somewhere on his HD. gerd. % BUT, we could distribute our own, either copy cvsbug, or write a perl % version. Tom % \begin{itemize} @@ -281,14 +281,14 @@ the source files, and these different configurations coexist in the this can be useful: \begin{enumerate} -\item{}Different configurations can be for {\em different +\item{}Different configurations can be for \emph{different architectures}. You can keep executables for multiple architectures based on a single copy of source code, shared on a common file system. -\item{} You can compare different {\em compiler options, debug-modes}. +\item{} You can compare different \textit{compiler options, debug-modes}. You might want to compile different communication protocols - (e.g. {\tt MPI} or {\tt GLOBUS}) or leave them out all together. -\item{} You can have different configurations for {\em different thorn + (e.g. MPI or Globus) or leave them out all together. +\item{} You can have different configurations for \textit{different thorn collections} compiled into your executable. \end{enumerate} @@ -305,7 +305,7 @@ At its simplest, this is done by {\tt gmake <config>}\footnote % {A note on the Cactus make system --- if at any point it prompts you to enter something, the default value, which will be assumed if you -simply press enter, is shown in parantheses.} +simply press enter, is shown in parentheses.} % . This generates a configuration with the name {\tt config}, doing its best to @@ -360,7 +360,7 @@ There is a plethora of available options. \begin{itemize} -\item {\tt Compiled Thorns} +\item {Compiled Thorns} These specify the chosen set of thorns for compilation. If the thorn choice is not provided during configuration, a list containing all thorns in the {\tt arrangements} directory @@ -370,7 +370,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 -\# or ! are ignored. +{\tt \#} or {\tt !} are ignored. \item [{\tt THORNLIST\_DIR}] Location of directory containing {\tt THORNLIST}. This defaults to the current working directory. @@ -378,7 +378,7 @@ This defaults to the current working directory. \end{Lentry} -\item {\tt Compiler and tool specification} +\item {Compiler and tool specification} These are used to specify which compilers and other tools to use. Entries followed by * may be specified on the command line. @@ -387,16 +387,16 @@ by * may be specified on the command line. \item [{\tt CC}] * The C compiler. \item [{\tt CXX}] The C++ compiler. \item [{\tt F90}] * The Fortran 90 compiler. -\item [{\tt F77}] * The FORTRAN 77 compiler. +\item [{\tt F77}] * The Fortran 77 compiler. \item [{\tt CPP}] The preprocessor used to generate dependencies and to preprocess Fortran code. \item [{\tt LD}] * The linker. \item [{\tt AR}] The archiver used for generating libraries. \item [{\tt RANLIB}] The archive indexer to use. \item [{\tt MKDIR}] The program to use to create a directory. -\item [{\tt PERL}] The name of the perl executable. +\item [{\tt PERL}] The name of the Perl executable. \end{Lentry} -\item {\tt Compilation and tool flags} +\item {Compilation and tool flags} Flags which are passed to the compilers and the tools. @@ -411,14 +411,14 @@ Flags for the C++ compiler. * Flags for the Fortran 90 compiler. \item [{\tt F77FLAGS}] -* Flags for the FORTRAN 77 compiler. +* Flags for the Fortran 77 compiler. \item [{\tt CPPFLAGS}] Flags for the preprocessor (used to generate compilation dependencies and preprocess Fortran code). \item [{\tt MKDIRFLAGS}] - Flags for MKDIR so that no error is given if the directory exists. + Flags for {\tt MKDIR} so that no error is given if the directory exists. \item [{\tt LDFLAGS}] * Flags for the linker. @@ -448,11 +448,11 @@ Optimisation flags for the C++ compiler, their use depends on the type of optimisation being used. \item [{\tt F90\_OPTIMISE\_FLAGS}] -Optimisation flags for the FORTRAN 90 compiler, their use depends on the +Optimisation flags for the Fortran 90 compiler, their use depends on the type of optimisation being used. \item [{\tt F77\_OPTIMISE\_FLAGS}] -Optimisation flags for the FORTRAN 77 compiler, their use depends on the +Optimisation flags for the Fortran 77 compiler, their use depends on the type of optimisation being used. \item [{\tt C\_WARN\_FLAGS}] @@ -464,7 +464,7 @@ Warning flags for the C++ compiler, their use depends on the type of warnings used during compilation (\ref{sec:gmopfobuco}). \item [{\tt F90\_WARN\_FLAGS}] -Warning flags for the FORTRAN 90 compiler, their use depends on the type of +Warning flags for the Fortran 90 compiler, their use depends on the type of warnings used during compilation (\ref{sec:gmopfobuco}). \item [{\tt F77\_WARN\_FLAGS}] @@ -473,7 +473,7 @@ warnings used during compilation (\ref{sec:gmopfobuco}). \end{Lentry} -\item {\tt Architecture-specific flags} +\item {Architecture-specific flags} \begin{Lentry} \item [{\tt IRIX\_BITS=32|64}] For Irix SGI systems: whether to build a 32- or 64-bit configuration. @@ -483,7 +483,7 @@ warnings used during compilation (\ref{sec:gmopfobuco}). \item [{\tt AIX\_BITS=32|64}] For IBM SP systems: whether to build a 32- or 64-bit configuration. \end{Lentry} -\item {\tt Library flags} +\item {Library flags} Used to specify auxiliary libraries and directories to find them in. @@ -492,7 +492,7 @@ Used to specify auxiliary libraries and directories to find them in. \item [{\tt LIBDIRS}] Any other library directories. \end{Lentry} -\item {\tt Extra include directories} +\item {Extra include directories} \begin{Lentry} \item [{\tt SYS\_INC\_DIRS}] @@ -500,7 +500,7 @@ Used to specify any additional directories for system include files. \end{Lentry} -\item {\tt Precision options} +\item {Precision options} Used to specify the precision of the default real and integer data types, specified as the number of bytes the data takes up. Note that not all @@ -509,50 +509,50 @@ values will be valid on all architectures. \begin{Lentry} \item [{\tt REAL\_PRECISION}] -* Allowed values are 16, 8, 4. +* Allowed values are {\tt 16, 8, 4}. \item [{\tt INTEGER\_PRECISION}] -* Allowed values are 8, 4 and 2. +* Allowed values are {\tt 8, 4} and {\tt 2}. \end{Lentry} -\item {\tt Executable name} +\item {Executable name} \begin{Lentry} \item [{\tt EXEDIR}] The directory in which to place the executable. \item [{\tt EXE}] The name of the executable. \end{Lentry} -\item{\tt Extra packages} +\item{Extra packages} Compiling with extra packages is described fully in Section \ref{sec:cowiexpa}, which should be consulted for the full range of configuration options. \begin{Lentry} -\item [{\tt MPI} *] The {\tt MPI} package to use, if required. Supported values are +\item [{\tt MPI}] * The MPI package to use, if required. Supported values are {\tt CUSTOM}, {\tt NATIVE}, {\tt MPICH} or {\tt LAM}. \item [{\tt HDF5}] -Supported values are {\it yes, no}. A blank value is taken as {\it no}. +Supported values are {\tt yes, no}. A blank value is taken as {\tt no}. \item [{\tt LAPACK}] -Supported values are {\it yes, no}. A blank value is taken as {\it no}. +Supported values are {\tt yes, no}. A blank value is taken as {\tt no}. \item [{\tt PETSC}] -Supported values are {\it yes, no}. A blank value is taken as {\it no}. +Supported values are {\tt yes, no}. A blank value is taken as {\tt no}. \item [{\tt PTHREADS}] -Supported values are {\it yes}. +Supported values are {\tt yes}. \end{Lentry} -\item{\tt Miscellaneous} +\item{Miscellaneous} \begin{Lentry} -\item [{\tt PROMPT}] Setting this to 'no' turns off all prompts from the +\item [{\tt PROMPT}] Setting this to {\tt no} turns off all prompts from the make system. -\item [{\tt SILENT}] Setting this to 'no' instructs {\tt gmake} to print the +\item [{\tt SILENT}] Setting this to {\tt no} instructs {\tt gmake} to print the commands that it is executing. \end{Lentry} @@ -568,10 +568,10 @@ commands that it is executing. \subsubsection{MPI: Message Passing Interface} -{\tt MPI} (the {\it Message Passing Interface}) provides inter-processor +The \textit{Message Passing Interface} (MPI) provides inter-processor communication. It can either be implemented natively on a machine (this is usual on most supercomputers), or through a standard package -such as {\tt MPICH}, {\tt LAM}, {WMPI}, or {PACX}. +such as MPICH, LAM, WMPI, or PACX. To compile with MPI, the configure option is @@ -582,14 +582,14 @@ may be specified on the configuration command line): \begin{Lentry} -\item[{\tt CUSTOM}] For a custom {\tt MPI} configuration set the variables +\item[{\tt CUSTOM}] For a custom MPI configuration set the variables \begin{Lentry} - \item [{\tt MPI\_LIBS} *] libraries. - \item [{\tt MPI\_LIB\_DIRS} *] library directories. - \item [{\tt MPI\_INC\_DIRS} *] include file directories. + \item [{\tt MPI\_LIBS}] * libraries. + \item [{\tt MPI\_LIB\_DIRS}] * library directories. + \item [{\tt MPI\_INC\_DIRS}] * include file directories. \end{Lentry} -\item[{\tt NATIVE}] Use the native {\tt MPI} for this machine, as indicated in +\item[{\tt NATIVE}] Use the native MPI for this machine, as indicated in the {\tt known-architectures} directory ({\tt lib/make/known-architectures}). @@ -597,10 +597,10 @@ may be specified on the configuration command line): Use MPICH (\url{http://www-unix.mcs.anl.gov/mpi/mpich}). This is controlled by the options \begin{Lentry} - \item [{\tt MPICH\_ARCH} *] machine architecture. - \item [{\tt MPICH\_DIR} *] directory in which {\tt MPICH} is installed. + \item [{\tt MPICH\_ARCH}] * machine architecture. + \item [{\tt MPICH\_DIR} ] * directory in which MPICH is installed. If this option is not defined it will be searched for. - \item [{\tt MPICH\_DEVICE} *] the device used by {\tt MPICH}. If not + \item [{\tt MPICH\_DEVICE}] * the device used by MPICH. If not defined, the configuration process will search for this in a few defined places. Supported devices are currently {\tt ch\_p4}, {\tt ch\_shmem}, @@ -613,54 +613,54 @@ by the options If {\tt MPICH\_DEVICE} is chosen to be {\tt globus}, (\url{http://www.globus.org}), an additional variable must be set \begin{Lentry} - \item[{\tt GLOBUS\_LIB\_DIR} *] directory in which Globus libraries are installed. + \item[{\tt GLOBUS\_LIB\_DIR}] * directory in which Globus libraries are installed. \end{Lentry} If {\tt MPICH\_DEVICE} is chosen to be {\tt ch\_gm}, (\url{http://www.myri.com}), an additional variable must be set \begin{Lentry} - \item[{\tt MYRINET\_DIR} *] directory in which Myrinet libraries are installed. + \item[{\tt MYRINET\_DIR}] * directory in which Myrinet libraries are installed. \end{Lentry} \item[{\tt LAM}] -Use {\tt LAM} (Local Area Multicomputer, \url{http://www.lam-mpi.org/}). +Use {\tt LAM} (\textit{Local Area Multicomputer}, \url{http://www.lam-mpi.org/}). This is controlled by the variables \begin{Lentry} - \item[{\tt LAM\_DIR} *] directory in which {\tt LAM} is installed. This + \item[{\tt LAM\_DIR} ] * directory in which LAM is installed. This will be searched for in a few provided places if not given. \end{Lentry} if the {\tt LAM} installation splits libraries and include files into different directories, instead of setting {\tt LAM\_DIR} set the two variables \begin{Lentry} - \item[{\tt LAM\_LIB\_DIR} *] directory in which {\tt LAM} libraries are installed. - \item[{\tt LAM\_INC\_DIR} *] directory in which {\tt LAM} include files are installed. + \item[{\tt LAM\_LIB\_DIR}] * directory in which LAM libraries are installed. + \item[{\tt LAM\_INC\_DIR}] * directory in which LAM include files are installed. \end{Lentry} \item[{\tt WMPI}] -Use WMPI (Win32 Message Passing Interface, \url{http://dsg.dei.uc.pt/w32mpi/intro.html}). This is controlled by the variable +Use WMPI (\textit{Win32 Message Passing Interface}, \url{http://dsg.dei.uc.pt/w32mpi/intro.html}). This is controlled by the variable \begin{Lentry} - \item[{\tt WMPI\_DIR} *] directory in which {\tt WMPI} is installed. + \item[{\tt WMPI\_DIR}] * directory in which WMPI is installed. \end{Lentry} \item[{\tt HPVM}] -Use HPVM (High Performance Virtual Machine, +Use HPVM (\textit{High Performance Virtual Machine}, (\url{http://www-csag.ucsd.edu/projects/hpvm.html}). This is controlled by the variable \begin{Lentry} - \item[{\tt HPVM\_DIR} *] directory in which {\tt HPVM} is installed. + \item[{\tt HPVM\_DIR}] * directory in which HPVM is installed. \end{Lentry} \item[{\tt MPIPro}] Use MPIPro (\url{http://www.mpi-softtech.com/}). \item[{\tt PACX}] -Use the PACX Metacomputing package (PArallel Computer eXtension,\\ +Use the PACX Metacomputing package (\textit{PArallel Computer eXtension},\\ \url{http://www.hlrs.de/structure/organisation/par/projects/pacx-mpi/}). This is controlled by the variables \begin{Lentry} - \item[{\tt PACX\_DIR} *] directory in which {\tt PACX} is installed. + \item[{\tt PACX\_DIR}] * directory in which PACX is installed. If this option is not defined it will be searched for. - \item[{\tt PACX\_MPI} *] the MPI package {\tt PACX} uses for node-local + \item[{\tt PACX\_MPI}] * the MPI package PACX uses for node-local communication. This can be any of the above MPI packages. \end{Lentry} @@ -676,17 +676,17 @@ the configure options are {\tt HDF5 = yes/no [HDF5\_DIR = <dir>] [LIBZ\_DIR = <dir>] [LIBSZ\_DIR = <dir>]} -If HDF5\_DIR is not given the configuration process will search for an +If {\tt HDF5\_DIR} is not given the configuration process will search for an installed HDF5 package in some standard places (defined in {\tt lib/make/extras/HDF5}). If the found HDF5 library was built with the external deflate I/O filter, the configuration process also searches for the {\tt libz} library and adds it to the linker flags. You may also point directly to the location of -{\tt libz.a} by setting LIBZ\_DIR. -If the found HDF5 library was built with the external szlib I/O filter, +{\tt libz.a} by setting {\tt LIBZ\_DIR}. +If the found HDF5 library was built with the external {\tt szlib} I/O filter, the configuration process also searches for the {\tt szlib} library and adds it to the linker flags. You may also point directly to the location of -{\tt libsz.a} by setting LIBSZ\_DIR. +{\tt libsz.a} by setting {\tt LIBSZ\_DIR}. \subsubsection{LAPACK: Linear Algebra PACKage} @@ -703,10 +703,10 @@ LAPACK = yes | no | <blank> \end{verbatim} If {\t LAPACK\_DIR} is not given the configuration process will search for a -LAPACK library {\it liblapack.[\{a,so\}]} in some standard places (defined in -{\tt lib/make/extras/LAPACK}). If {\t LAPACK\_DIR} is set to {\it no} the +LAPACK library {\tt liblapack.[\{a,so\}]} in some standard places (defined in +{\tt lib/make/extras/LAPACK}). If {\t LAPACK\_DIR} is set to {\tt no} the LAPACK library path is assumed to be installed in a standard system location -(eg. {\i /usr/lib/}) and thus the library path will not be added to the linker's +(e.g. {\tt /usr/lib/}) and thus the library path will not be added to the linker's command line. Because LAPACK doesn't come as a standardized system installation, there are @@ -738,16 +738,16 @@ architecture-specific libraries as required by a PETSc configuration (usually PETSc needs the LAPACK library). -\subsubsection{PTHREADS: POSIX threads} +\subsubsection{Pthreads: POSIX threads} To enable multithreading support within Cactus using POSIX threads the configure option is {\tt PTHREADS = yes} -The configuration process will check if a re-entrant C library is available +The configuration process will check if a reentrant C library is available and adds it to the linker flags. It will also search for the system's Pthreads -library (either libpthread or libpthreads) and set preprocessor +library (either {\tt libpthread} or {\tt libpthreads}) and set preprocessor defines necessary for compiling multithreaded code. @@ -788,7 +788,7 @@ In addition the following files may be informative: \begin{Lentry} \item [{\tt fortran\_name.pl}] -A perl script used to determine how the Fortran compiler names subroutines. +A Perl script used to determine how the Fortran compiler names subroutines. This is used to make some C routines callable from Fortran, and Fortran routines callable from C. @@ -797,22 +797,22 @@ Initially empty. Can be edited to add extra architecture specific dependencies needed to generate the executable. \item [{\tt make.config.rule}] -Make rules for generating object files from source files. +The {\tt make} rules for generating object files from source files. \end{Lentry} -Finally, autoconf generates the following files. +Finally, {\tt autoconf} generates the following files. \begin{Lentry} \item [{\tt config.log}] -A log of the autoconf process. +A log of the {\tt autoconf} process. \item [{\tt config.status}] A script which may be used to regenerate the configuration. \item [{\tt config.cache}] -An internal file used by autoconf. +An internal file used by {\tt autoconf}. \end{Lentry} @@ -830,7 +830,7 @@ A file containing information about the configuration. generated by the CST from the \texttt{.ccl} files. \item [{\tt scratch}] -A scratch directory which is used to accomodate Fortran 90 modules. +A scratch directory which is used to accommodate Fortran 90 modules. \end{Lentry} @@ -843,7 +843,7 @@ Once you have created a new configuration, the command {\tt gmake <configuration name>} \\ \\ will build an executable, prompting you along the way for the -thorns which should be included. There is a range of gmake +thorns which should be included. There is a range of {\tt gmake} targets and options which are detailed in the following sections. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -852,7 +852,7 @@ targets and options which are detailed in the following sections. A target for {\tt gmake} can be naively thought of as an argument that tells it which of several things listed in the {\tt Makefile} it -is to do. The command {\tt gmake help} lists all gmake targets: +is to do. The command {\tt gmake help} lists all {\tt gmake} targets: % colon clarifies that all (config) targets are listed here \begin{Lentry} @@ -872,7 +872,7 @@ is to do. The command {\tt gmake help} lists all gmake targets: \item [{\tt gmake <config>-config}] creates a new configuration or reconfigures an old one. -\item [{\tt gmake <config>-cvsupdate}] update the Flesh and Thorns for a configuration using CVS +\item [{\tt gmake <config>-cvsupdate}] updates the Flesh and thorns for a configuration using CVS \item [{\tt gmake <config>-delete}] deletes a configuration ({\tt rm -r configs/<config>}). @@ -882,9 +882,9 @@ is to do. The command {\tt gmake help} lists all gmake targets: \item [{\tt gmake <config>-realclean}] removes from a configuration all object and dependency files, as well as files generated from the -CST (stands for Cactus Specification Tool, which is the perl scripts +CST (stands for \textit{Cactus Specification Tool}, which is the set of Perl scripts which parse the thorn configuration files). Only the files generated -by configure and the ThornList file remain. +by configure and the {\tt ThornList} file remain. \item [{\tt gmake <config>-rebuild}] rebuilds a configuration (reruns the CST). @@ -892,7 +892,7 @@ by configure and the ThornList file remain. each thorn in the configuration. See section \ref{sec:te} for information about the testsuite mechanism. -\item [{\tt gmake <config>-thornlist}] regenerates the ThornList for a configuration. +\item [{\tt gmake <config>-thornlist}] regenerates the {\tt ThornList} for a configuration. \item [{\tt gmake <config>-utils [UTILS$=$<list>]}] builds all utility programs provided by the thorns of a configuration. Individual utilities can be selected by giving their names in the {\tt UTILS} variable. @@ -901,7 +901,7 @@ in this configuration. \item[{\tt gmake <config>-configinfo}] displays the options used to build the configuration. -\item[{\tt gmake <config>-cvsupdate}] updates the Flesh and this configuration's Thorns from the CVS repositories. +\item[{\tt gmake <config>-cvsupdate}] updates the Flesh and this configuration's thorns from the CVS repositories. \end{Lentry} @@ -913,7 +913,8 @@ in this configuration. Cactus will try to compile all thorns listed in {\tt configs/<config>/ThornList}. The {\tt ThornList} file is simply a list of the form -{\t <arrangement>/<thorn>}. All text after a \# or ! sign +{\tt <arrangement>/<thorn>}. All text after a pound sign `{\tt \#}' or +exclamation mark `{\tt !}' on a line is treated as a comment and ignored. The first time that you compile a configuration, if you did not specify a ThornList already during configuration, @@ -932,17 +933,17 @@ gmake <config>-editthorns \end{verbatim} Instead of using the editor to specify the thorns you want to - have compiled, you can {\em edit} the {\em ThornList} outside + have compiled, you can \emph{edit} the {\tt ThornList} outside the make process. It is located in {\tt configs/<config>/ThornList}, where {\tt <config>} refers to the name of your configuration. - The directory, {\tt ./configs}, exists {\em - after} the very first make phase for the first configuration. + The directory, {\tt ./configs}, exists \emph{ after} the very first + make phase for the first configuration. \subsection{Notes and Caveats} \begin{itemize} \item{} If during the build you see the error ``{\tt missing separator}'' you are probably not using GNU make. -\item{} {\em The EDITOR environment variable}. You may not be aware of +\item{} \textit{The EDITOR environment variable}. You may not be aware of this, but this thing very often exists and may be set by default to something scary like {\tt vi}. If you don't know how to use {\tt vi} or wish to @@ -950,11 +951,11 @@ Instead of using the editor to specify the thorns you want to (To exit {\tt vi} type {\tt <ESC> :q!}) \end{itemize} -\subsection{gmake options for building configurations} +\subsection{{\tt gmake} options for building configurations} \label{sec:gmopfobuco} -An {\it option} for gmake can be thought of as an argument which tells -it how it should make a {\tt target}. Note that the final result is always +An \textit{option} for {\tt gmake} can be thought of as an argument which tells +it how it should make a \textit{target}. Note that the final result is always the same. \begin{Lentry} @@ -987,27 +988,27 @@ arrangements and thorns. For example it can checkout all the thorns in any thornlist file found in the \texttt{thornlists} subdirectory of the Cactus root directory. % (usually \texttt{Cactus}). -\item [{\tt gmake cvsdiff}] differences between checked out version of Cactus and that in the CVS repositories. +\item [{\tt gmake cvsdiff}] shows differences between checked out version of Cactus and that in the CVS repositories. -\item [{\tt gmake cvsstatus}] status of checked out version of Cactus, reporting which files have been modified or need updating. +\item [{\tt gmake cvsstatus}] shows status of checked out version of Cactus, reporting which files have been modified or need updating. -\item [{\tt gmake cvsupdate}] update Flesh and all Thorns from CVS repositories. +\item [{\tt gmake cvsupdate}] updates Flesh and all thorns from CVS repositories. \item [{\tt gmake default}] creates a new configuration with a default name. -\item [{\tt gmake distclean}] delete your {\tt configs} directory and hence all your configurations. +\item [{\tt gmake distclean}] deletes your {\tt configs} directory and hence all your configurations. \item [{\tt gmake downsize}] removes non-essential files as documents - and testsuites to allow for minimal installation size. + and test suites to allow for minimal installation size. \item [{\tt gmake newthorn}] creates a new thorn, prompting for the necessary 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:usta} 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:usta} for using tags within Cactus. \item [{\tt gmake UsersGuide}] runs LaTeX to produce a copy of the Users' Guide. @@ -1025,16 +1026,16 @@ configuration found in user's \texttt{configs} subdirectory. \label{sec:te} Some thorns come with a testsuite, consisting of example parameter files -and the output files generated by running these. To run the testsuites +and the output files generated by running these. To run the testsuite for the thorns you have compiled use {\tt gmake <configuration>-testsuite} -These testsuites serve the dual purpose of +These testsuite serve the dual purpose of \begin{Lentry} \item [Regression testing] -i.e. making sure that changes to the thorn or the flesh don't affect the +i.e. making sure that changes to the thorn or the Flesh don't affect the output from a known parameter file. \item [Portability testing] i.e. checking that the results are independent of the architecture --- this @@ -1048,12 +1049,12 @@ is also of use when trying to get Cactus to work on a new architecture. Cactus executables always run from a parameter file (which may be a physical file or taken from standard input), which specifies which -Thorns to use and set the values of any parameters which are different +thorns to use and sets the values of any parameters which are different from the default values. Any accepted filename can be used for the name of the parameter file, although standard convention is to use the file extension {\tt .par}. Optional command line arguments can be used to customise runtime behaviour, and to provide information about the -Thorns used in the executable. The general syntax for running Cactus from +thorns used in the executable. The general syntax for running Cactus from a physical parameter file is then @@ -1126,7 +1127,7 @@ Produces version information of the code. %Runs the code far enough to check the consistency of the parameters. If %given a numeric argument it will attempt to simulate being on that number %of processors. [To be implemented.] -\item [{\tt -W<level>} or {\tt -waring-level=<level>}] +\item [{\tt -W<level>} or {\tt -warning-level=<level>}] Sets the warning level of the code. All warning messages are given a level --- the lower the level the greater the severity. This parameter controls the level of messages to be seen, with all warnings of level $\le$ {\tt <level>} @@ -1163,20 +1164,20 @@ Set the level of parameter checking to be used, either {\tt strict}, {\tt normal The parameter file is used to control the behaviour of the code at runtime. It is a text file with lines which are either comments, denoted -by a `\#' or `!', or parameter statements. A parameter statement consists -of one or more parameter names, followed by -an `=', followed by the value(s) for this (these) parameter(s). +by a `{\tt \#}' or `{\tt !}', or parameter statements. A parameter statement +consists of one or more parameter names, followed by +an `{\tt =}', followed by the value(s) for this (these) parameter(s). Note that all string parameters are case insensitive. The {\tt first parameter} in any parameter file should be {\tt ActiveThorns}. This is a special parameter which tells the -code which {\em thorns} are to be activated. Only parameters from active -thorns can be set (and only those routines {\it scheduled} by active thorns +code which \textit{thorns} are to be activated. Only parameters from active +thorns can be set (and only those routines \textit{scheduled} by active thorns are run). By default all thorns are inactive. For example, the first entry in a parameter file which is using just the two thorns {\tt CactusPUGH/PUGH} and {\tt CactusBase/CartGrid3D} should be -{\tt ActiveThorns = ``PUGH CartGrid3D''} +{\tt ActiveThorns = "PUGH CartGrid3D"} Parameters following the {\tt ActiveThorns} parameter all have names whose syntax depends on the scope of the parameter: @@ -1185,20 +1186,20 @@ whose syntax depends on the scope of the parameter: Just the name of the parameter itself. Global parameters are avoided, and there are none in the Flesh and Cactus Toolkits. \item [{\tt Restricted parameters}] -The name of the {\em implementation} which defined the parameter, two colons, +The name of the \textit{implementation} which defined the parameter, two colons, and the name of the parameter --- e.g. {\tt driver::global\_nx}. \item [{\tt Private parameters}] -The name of the {\em thorn} which defined the parameter, two colons, +The name of the \textit{thorn} which defined the parameter, two colons, and the name of the parameter --- e.g. {\tt wavetoyF77::amplitude}. \end{Lentry} -This notation is not strictly enforced currently in the code. It is +This notation is not currently strictly enforced in the code. It is sufficient to specify the first part of the parameter name using either the implementation name, or the thorn name. However, it is suggested that the convention above is followed. -The Cactus Flesh performs checks for consistency and range of parameters, -the severity of these checks is controlled by the command line argument +The Cactus Flesh performs checks for consistency and range of parameters. +The severity of these checks is controlled by the command line argument {\tt -parameter-level} which can take the following values \begin{Lentry} \item[{\tt relaxed}] Cactus will issue a level 0 warning (that is the @@ -1235,12 +1236,12 @@ Notes: each thorn using the command line options {\tt -o} and {\tt -O} (Section~\ref{sec:coliop}). -\item{} The parameter file is read {\it sequentially} from top to bottom, +\item{} The parameter file is read \textit{sequentially} from top to bottom, this means that if you set the value of a parameter twice in the parameter file, the second value will be used. (This is why the {\tt ActiveThorns} parameter is always first in the file). -\item{} Some parameters are {\it steerable} and can be changed during +\item{} Some parameters are \textit{steerable} and can be changed during the execution of a code using parameter steering interfaces (for example, thorn {\tt CactusConnect/HTTPD}, or using a parameter file when recovering from a checkpoint file. @@ -1253,9 +1254,9 @@ each thorn using the command line options {\tt -o} and {\tt -O} \section{Thorn Documentation} \label{sec:thdo} -The Cactus make system provides a mechanism for generating a {\it -Thorn Guide} containing separate chapters for each thorn and -arrangement in your configuration. The provided documentation for an +The Cactus make system provides a mechanism for generating a +\textit{Thorn Guide} containing separate chapters for each thorn and +arrangement in your configuration. The documentation provided for an individual thorn obviously depends on what the thorn authors added, but the Thorn Guide is a good place to first look for special instructions on how to run and interpret the output from a Thorn. @@ -1285,7 +1286,7 @@ or to make a Thorn Guide for all the thorns in the {\tt arrangements} directory As your Cactus executable runs, standard output and standard error are usually written to the screen. Standard output provides you with information about the run, and standard error reports warnings -and errors from the flesh and thorns. +and errors from the Flesh and thorns. As the program runs, the normal output provides the following information: @@ -1370,8 +1371,8 @@ standard arrangements are described in those thorns' documentation. In general, these thorns decide what to output by parsing a string parameter containing the names of those grid variables, or groups of variables, for which -output is required. The names should be fully qualified with the {\tt -implementation} and {\tt group} or {\tt variable} names. +output is required. The names should be fully qualified with the +{\tt implementation} and {\tt group} or {\tt variable} names. There is usually a parameter for each method to denote how often, in evolution iterations, this output should be performed. There is also usually a parameter @@ -1391,7 +1392,7 @@ all the data from the checkpoint file. Checkpointing/recovery methods in Cactus are provided by thorns. In general, these thorns decide how often to generate a checkpoint. They also -register their recovery routines with the flesh which then get called during +register their recovery routines with the Flesh which then get called during initialization to perform the recovery of parameters and grid variables if requested in the parameter file. diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex index 9bb81075..58ddb4b8 100644 --- a/doc/UsersGuide/ThornWriters.tex +++ b/doc/UsersGuide/ThornWriters.tex @@ -11,7 +11,7 @@ % @author Jonathan Thornburg <jthorn@aei.mpg.de> % @desc Revise section "Interpolation Operators" to cover the % new interpolation API (when we will have multiple APIs -% coexisting, eg CCTK_InterpLocalUniform() and +% coexisting, e.g. CCTK_InterpLocalUniform() and % CCTK_InterpLocalNonUniform()) % @endhistory % @@*/ @@ -43,27 +43,27 @@ you may use to gain extra functionality. \section{Thorns} -A thorn is the basic working module within Cactus. All user-supplied +A thorn is the basic working module within Cactus. All user supplied code goes into thorns, which are, by and large, independent of each other. -Thorns communicate with each other via calls to the flesh API, plus, more +Thorns communicate with each other via calls to the Flesh API, plus, more rarely, custom APIs of other thorns. -The connection from a thorn to the flesh or to other thorns is specified in +The connection from a thorn to the Flesh or to other thorns is specified in configuration files which are parsed at compile time and used to generate -glue code which encapsulates the external appearence of a thorn. +glue code which encapsulates the external appearance of a thorn. Thorn names must be (case independently) unique, must start with a letter, can only contain letters, numbers or underscores, and must contain 27 characters or less. In addition, a thorn cannot have the name {\t doc}, this is reserved for arrangement documentation. Arrangement names which start with a -`\#', or finish with `\~{}' or `.bak' will be ignored. +`{\t \#}', or finish with `{\t \~{}}' or `{\t .bak}' will be ignored. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Arrangements} -Thorns are grouped into {\em arrangements}. This is a logical grouping of +Thorns are grouped into \textit{arrangements}. This is a logical grouping of thorns which is purely for organisational purposes. For example, you might wish to keep all your initial data thorns in one arrangement, and all your evolution thorns in another arrangement, or you may want @@ -75,7 +75,7 @@ Cactus directory. Arrangement names must be (case independently) unique, must start with a letter, and can only contain letters, numbers or underscores. Arrangement names which start with a -`\#', or finish with `\~{}' or `.bak' will be ignored. +`{\t \#}', or finish with `{\t \~{}}' or `{\t .bak}' will be ignored. Inside an arrangement directory there are directories for each thorn belonging to the arrangement. @@ -86,25 +86,25 @@ belonging to the arrangement. \label{sec:im} -One of the key concepts for thorns is the concept of the {\bf implementation}. +One of the key concepts for thorns is the concept of the \textit{implementation}. Relationships among thorns are all based upon relationships among the -{\bf implementations} they provide. +implementations they provide. In principle it should be possible to swap one thorn providing an implementation with another thorn providing that implementation, without affecting any other thorn. -An {\bf implementation} defines a group of variables and parameters which +An implementation defines a group of variables and parameters which are used to implement some functionality. For example the thorn -{\tt CactusPUGH/PUGH} provides the implementation {\it driver}. This +{\tt CactusPUGH/PUGH} provides the implementation {\tt driver}. This implementation is responsible for providing memory for grid variables and for communication. Another thorn can also implement {\tt driver}, -and both thorns can be compiled in {\em at the same time}. +and both thorns can be compiled in \emph{at the same time}. At runtime, the user can decide which thorn providing {\tt driver} is used. No other thorn should be affected by this choice. When a thorn decides it needs access to a variable or a parameter provided by another thorn, it defines a relationship between itself and the other thorn's -{\bf implementation}, not explicitly with the other {\bf thorn}. +\emph{implementation}, not explicitly with the other \emph{thorn}. This allows the transparent replacement, at compile or runtime, of one thorn with another thorn providing the same functionality as seen by the other thorns. @@ -124,7 +124,7 @@ 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 +\item[{\tt interface.ccl}] the Cactus interface, which defines the grid functions, variables, etc. See \ref{sec:in}. \item[{\tt param.ccl}] the parameters introduced by this thorn, and the parameters needed from other thorns. See @@ -132,7 +132,7 @@ parameters needed from other thorns. See \item[{\tt schedule.ccl}] scheduling information for routines called by \item[{\tt configuration.ccl}] configuration options for the thorn. See \ref{sec:co}. -the flesh. See \ref{sec:sc}. +the Flesh. See \ref{sec:sc}. \end{Lentry} Thorns can also contain @@ -144,7 +144,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 - testsuite. See \ref{sec:adatesu} for details. + test suite. See \ref{sec:adatesu} for details. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -152,29 +152,29 @@ Thorns can also contain \section{Creating a thorn} -To simplify the creation of a thorn, a make target {\tt +To simplify the creation of a thorn, a {\tt make} target {\tt gmake newthorn} has been provided. When this is run: \begin{enumerate} \item{} You will be prompted for the name of the new thorn. -\item{} You will be prompted for the name of the arrangement you would -like to include your thorn in. Either enter a new arrangement name or pick -one from the list of available arrangements that are shown. +\item{} You will be prompted for the name of the arrangement in which you +would like to include your thorn. Either enter a new arrangement name or +pick one from the list of available arrangements that are shown. \end{enumerate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Configuring your thorn} -The interaction of a thorn with the flesh and other thorns is controlled -by various configuration files. +The interaction of a thorn with the Flesh and other thorns is controlled +by certain configuration files. -These consist of: +These are: \begin{Lentry} \item [{\tt interface.ccl}] -This defines the {\bf implementation} (Section~\ref{sec:im}) the thorn +This defines the \textit{implementation} (Section~\ref{sec:im}) the thorn provides, and the variables the thorn needs, along with their visibility to other implementations. @@ -183,7 +183,7 @@ This defines the parameters that are used to control the thorn, along with their visibility to other implementations. \item [{\tt schedule.ccl}] -This defines which functions from the thorn are called and when they are +This defines which functions are called from the thorn and when they are called. It also handles memory and communication assignment for grid variables. \item [{\tt configuration.ccl}] @@ -193,12 +193,15 @@ This file is optional for a thorn. If it exists it contains configuration option \subsection{General syntax of CCL files} -{\bf Cactus Configuration Language} (CCL) files are simple text files +\textit{Cactus Configuration Language} (CCL) files are simple text files used to define configuration information for a thorn. CCL files are -case independent, and may contain comments introduced by the `\#' character, -which indicates that the rest of the line is a comment. If the last non-blank character of a line in a CCL file is a backslash {\tt $\backslash$}, the following line is treated as a continuation of the current line. +case independent, and may contain comments introduced by the hash `{\tt \#}' +character, which indicates that the rest of the line is a comment. If the last +non-blank character of a line in a CCL file is a backslash +`{\tt $\backslash$}', the +following line is treated as a continuation of the current line. -\subsection{The {\tt interface.ccl}} +\subsection{The {\tt interface.ccl} file} The {\tt interface.ccl} file is used to declare @@ -216,6 +219,7 @@ implements: <name> \end{verbatim} Where {\tt <name>} can be any combination of alphanumeric characters and underscores, and is case independent. + There are three different access levels available for variables \begin{Lentry} @@ -239,8 +243,8 @@ 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, unlike {\tt inherits}, it is symmetric and also defines a transitive relation by -pushing its own implementations {\tt Protected} variables onto implementation -{\tt <name>}. This keyword is used define to a group of implementations which +pushing its own implementation's {\tt Protected} variables onto implementation +{\tt <name>}. This keyword is used to define a group of implementations which all end up with the same {\tt Protected} variables. \end{Lentry} @@ -250,14 +254,15 @@ implements: wavetoy inherits: grid friend: wave_extract \end{verbatim} -declares that the thorn provides an implementation called `wavetoy', gets -all the {\tt public} variables declared by an implementation called `grid', and -shares all {\tt protected} variables with {\tt wave\_extract} and its friends. +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:cava}, are placed in groups with homogeneous attributes, where the attributes describe properties such as the data type, group type, -dimenension, ghostsize, number of timelevels, type of staggering and +dimension, ghostsize, number of timelevels, type of staggering and distribution. For example, a group, called {\tt realfields} of 5 real grid @@ -288,10 +293,10 @@ 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}} +\subsection{The {\tt param.ccl} file} Users control the operation of thorns via parameters given in a file -at runtime. The {\tt param.ccl} +at runtime. The {\tt param.ccl} file is used to specify the parameters used to control an individual thorn, and to specify the values these parameters are allowed to take. When the code is run it reads a parameter file and sets the parameters if they fall @@ -321,8 +326,8 @@ A distinct string with only a few known allowed values. \item [{\tt STRING}] An arbitrary string, which must conform to a given regular expression. \item [{\tt BOOLEAN}] -A boolean type which can take values 1, `t', `true', `yes' or -0, `f', `false', `no'. +A boolean type which can take values {\t 1}, {\t t}, {\t true}, {\t yes} or +{\t 0}, {\t f}, {\t false}, {\t no}. \end{Lentry} \item the parameter name @@ -335,13 +340,13 @@ A boolean type which can take values 1, `t', `true', `yes' or each element is specified with square brackets and is 0-based. The size must be an integer. -\item a {\tt description} of the parameter +\item a description of the parameter \item an allowed value block -- This consists of a brace delimited -block of lines\footnote{The beginning brace (\{) must sit on a line by -itself; the ending brace (\}) must be preceded by a carriage return.} +block of lines\footnote{The beginning brace ({\t \{}) must sit on a line by +itself; the ending brace ({\t \}}) must be preceded by a carriage return.} describing the allowed values of the parameter. Each range may have a -description associated with it by placing a :: on the line and putting +description associated with it by placing a {\t ::} on the line and putting the description afterwards. \item the default value -- @@ -351,8 +356,8 @@ This must be one of the allowed values. For the numeric types {\tt INT} and {\tt REAL}, a range consists of a string of the -forms lower-bound:upper-bound:step where a missing number or a * denotes -anything (i.e.\ infinite bounds or an infinitesimal step). +form lower-bound:upper-bound:step, where a missing number or an asterisk +`{\t *}' denotes anything (i.e.\ infinite bounds or an infinitesimal step). For example \begin{verbatim} @@ -381,10 +386,10 @@ REAL Length[2] "Length in each direction" } 1.0 \end{verbatim} -defines a REAL parameter, a BOOLEAN parameter, a KEYWORD and an array -of REAL parameters. +defines a {\tt REAL} parameter, a {\tt BOOLEAN} parameter, a {\tt KEYWORD} +and an array of {\tt REAL} parameters. -By default all parameters are {\tt private}, to change this an access +By default all parameters are {\tt private}; to change this, an access specification of the form {\tt global:} or {\tt restricted:} (or {\tt private:} to change it back) may be placed on a line by itself. This changes the access level for any parameter defined in the file from that point on. @@ -404,7 +409,7 @@ value must be omitted --- it is impossible to set the default value of any parameter not originating in this thorn. For example, the following block adds possible values to the keyword {\tt initial\_data} originally defined in the implementation {\tt einstein}, -and uses the real parameter {\tt speed}. +and uses the {\tt REAL} parameter {\tt speed}. \begin{verbatim} shares:einstein @@ -426,7 +431,7 @@ Note that you must compile at least one thorn which implements {\tt einstein}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{The {\tt schedule.ccl}} +\subsection{The {\tt schedule.ccl} file} \label{subsec:schedule_ccl} By default no routine of a thorn will be run. The {\tt schedule.ccl} file defines those that should be run and when and under which @@ -451,7 +456,7 @@ the most useful schedule bins for application thorns is given here, a complete a \begin{Lentry} \item [{\tt CCTK\_STARTUP}] -For routines run before the grid hierachy is set up, for example function +For routines run before the grid hierarchy is set up, for example function registration. \item [{\tt CCTK\_PARAMCHECK}] @@ -513,7 +518,7 @@ the variables from a group in {\tt TRIGGERS} is due for output. \item[{\tt SYNC}] The keyword {\tt SYNC} specifies groups of variables which should be synchronised (that is, their ghostzones should be exchanged between -processors) on exit from the routine. Specifying synchonisation of +processors) on exit from the routine. Specifying synchronisation of grid variables in {\tt schedule.ccl} is an alternative to calling the function {\tt CCTK\_SyncGroup()} from inside a routine. Using the {\tt SYNC} keyword in the {\tt schedule.ccl} is the preferred method, since it @@ -523,16 +528,16 @@ refinement. \end{Lentry} -As well as schedule blocks it's possible to embed C style {\tt -if/else} statements in the schedule.ccl. 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 {\bf Example I:} If the parameter {\tt evolve\_hydro} is positively set, the Fortran -routine {\tt hydro\_predictor} is scheduled to run in the {\em -evolution} loop, after the routine {\tt metric\_predictor} and before +routine {\tt hydro\_predictor} is scheduled to run in the \textit{evolution} +loop, after the routine {\tt metric\_predictor} and before {\tt metric\_corrector}. The routine names {\tt metric\_predictor} and {\tt metric\_corrector} may either be real routine names from the same or a different thorn, or they may be {\tt aliased} routine names (see the @@ -565,7 +570,7 @@ interface is available. The thorns {\tt WaveToy77} and {\tt WaveToyC} each provide a routine to evolve the 3D wave equation: {\tt WaveToyF77\_Evolution} and {\tt WaveToyC\_Evolution}. The routine names have to be different, so -that both thorns can be compiled at the same time, their functionlity +that both thorns can be compiled at the same time, their functionality is identical though. Either one of them can then be activated at run time in the parameter file via {\tt ActiveThorns}. @@ -594,7 +599,7 @@ schedule WaveToyC_Evolution AS WaveToy_Evolution AT evol \end{verbatim} The thorn {\tt IDScalarWave} schedules the routine {\tt WaveBinary} -after the alias {\em WaveToy\_Evolution}. It is scheduled independently of +after the alias {\tt WaveToy\_Evolution}. It is scheduled independently of the C or Fortran routine name. \begin{verbatim} @@ -648,12 +653,12 @@ to designate coding language. The following extensions can be handled: \hline Extension & Coding Language \\ \hline -{\t .F} & Fortran90 fixed form \\ -{\t .f} & (no preprocessing) Fortran90 fixed form\\ -{\t .F90} & Fortran90 free form\\ -{\t .f90} & (no preprocessing) Fortran90 free form\\ -{\t .F77} & Fortran77 \\ -{\t .f77} & (no preprocessing) Fortran77\\ +{\t .F} & Fortran 90 fixed form \\ +{\t .f} & (no preprocessing) Fortran 90 fixed form\\ +{\t .F90} & Fortran 90 free form\\ +{\t .f90} & (no preprocessing) Fortran 90 free form\\ +{\t .F77} & Fortran 77 \\ +{\t .f77} & (no preprocessing) Fortran 77\\ {\t .c} & C \\ {\t .cc} or {\t .C} & C++ \\ \hline @@ -665,7 +670,7 @@ The following restrictions apply to file names: \item For portability across all operating systems, the base names for any particular extension should not depend on the operating system being case sensitive (e.g.\ having {\tt MyFile.c} and - {\tt MYFILE.f77} is alright, but {\tt MyFile.c} and {\tt MYFILE.c} could cause problems). + {\tt MYFILE.f77} is allright, but {\tt MyFile.c} and {\tt MYFILE.c} could cause problems). \item Currently all source files in different subroutines within a thorn must have distinct names. We hope to relax this in future. Different thorns can have files with the same names. @@ -725,7 +730,7 @@ The makefile is passed the following variables \item [{\tt \$(THORN)}] the thorn name -\item [{\tt \$(SCRATCH\_BUILD)}] the scratch directory where Fortran90 module +\item [{\tt \$(SCRATCH\_BUILD)}] the scratch directory where Fortran 90 module files should end up if they need to be seen by other thorns. \item [{\tt \$(NAME)}] the name of the library to be built @@ -737,15 +742,15 @@ and has a working directory of {\tt <config>/build/<thorn\_name>} . \subsection{Other makefile variables} \begin{itemize} -\item CC -\item CXX -\item F90 -\item F77 -\item CFLAGS -\item CXXFLAGS -\item F90FLAGS -\item F77FLAGS -\item LD +\item {\tt CC} +\item {\tt CXX} +\item {\tt F90} +\item {\tt F77} +\item {\tt CFLAGS} +\item {\tt CXXFLAGS} +\item {\tt F90FLAGS} +\item {\tt F77FLAGS} +\item {\tt LD} \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -754,13 +759,13 @@ and has a working directory of {\tt <config>/build/<thorn\_name>} . \chapter{Cactus Variables} \label{chap:cava} -Cactus variables are sorted into {\tt groups}. All variables in a group +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. Cactus variables are used instead of local variables for a number of reasons: \begin{itemize} -\item Cactus variables can be made visable to other thorns, allowing +\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, @@ -797,42 +802,45 @@ bytes the type takes). \begin{Lentry} \item[INTEGER] -CCTK\_INT, CCTK\_INT1, CCTK\_INT2, CCTK\_INT4, CCTK\_INT8. -(CCTK\_INT defaults to being CCTK\_INT4). +{\tt CCTK\_INT}, {\tt CCTK\_INT1}, {\tt CCTK\_INT2}, {\tt CCTK\_INT4}, {\tt CCTK\_INT8}. +({\tt CCTK\_INT} defaults to being {\tt CCTK\_INT4}). \item[REAL] -CCTK\_REAL, CCTK\_REAL4, CCTK\_REAL8, CCTK\_REAL16. (CCTK\_REAL defaults to being CCTK\_REAL8). +{\tt CCTK\_REAL}, {\tt CCTK\_REAL4}, {\tt CCTK\_REAL8}, {\tt CCTK\_REAL16}. ({\tt CCTK\_REAL} defaults to being {\tt CCTK\_REAL8}). \item[COMPLEX] -CCTK\_COMPLEX, CCTK\_COMPLEX8, CCTK\_COMPLEX16, CCTK\_COMPLEX32. -(CCTK\_COMPLEX defaults to being CCTK\_COMPLEX16). +{\tt CCTK\_COMPLEX}, {\tt CCTK\_COMPLEX8}, {\tt CCTK\_COMPLEX16}, {\tt CCTK\_COMPLEX32}. +({\tt CCTK\_COMPLEX} defaults to being {\tt CCTK\_COMPLEX16}). \item[BYTE] This is a 1 byte data type. \end{Lentry} Normally a thorn should use the default types --- -CCTK\_INT, CCTK\_REAL, CCTK\_COMPLEX --- rather than explicitly setting the size, as this gives maximum +{\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 -code with different precisions to test for round-off effects, or to run more +code with different precisions to test for roundoff effects, or to run more quickly with a lower accuracy. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Group Types} -Groups can be either {\tt scalars}, {\tt grid functions (GFs)}, or {\tt grid arrays}. Different attributes are relevant for the different group types. +Groups can be either \textit{scalars}, \textit{grid functions} (GFs), or +\textit{grid arrays}. Different attributes are relevant for the different group +types. + \begin{Lentry} -\item[SCALAR] +\item[{\tt SCALAR}] This is just a single number, e.g.\ the total energy of some field. These variables aren't communicated between processors --- what would be the result of such communication? -\item[GF] +\item[{\tt GF}] This is the most common group type. A GF is an array with a -specific size, set at run-time in the parameter file, which is distributed +specific size, set at run time in the parameter file, which is distributed across processors. All GFs have the same size, and the same number of ghostzones. Groups of GFs can also specify a dimension, number of timelevels, and stagger type. -\item[ARRAY] +\item[{\tt ARRAY}] This is a more general form of the GF. Each group of arrays can have a distinct size and number of ghostzones, in addition to dimension, number of timelevels and stagger type. @@ -891,10 +899,10 @@ loop: Timelevel rotation means that, for example, {\tt phi\_p} now holds the values of the former {\tt phi}, and {\tt phi\_p\_p} the values of the former {\tt phi\_p}, etc. -Note that after rotation {\tt phi} is undefined, and it's values should +Note that after rotation {\tt phi} is undefined, and its values should not be used until they have been updated. -All timelevels, except the current level, should be considered {\bf read-only} during evolution, that is their values should not be changed by thorns. +All timelevels, except the current level, should be considered \emph{read-only} during evolution, that is their values should not be changed by thorns. The exception to this rule is for function initialisation, when the values at the previous timelevels do need to be explicitly filled out. @@ -906,7 +914,7 @@ A Cactus grid function or array has a size set at runtime by parameters. This size can either be the global size of the array across all processors ({\tt DISTRIB=DEFAULT}), or, if {\tt DISTRIB=CONSTANT} the specified -size on {\bf each} processor. +size on \emph{each} processor. If the size is split across processors, the driver thorn is responsible for assigning the size on each processor. @@ -914,7 +922,7 @@ responsible for assigning the size on each processor. \section{Ghost Size} -Cactus is based upon a {\tt distributed computing} paradigm. That is, +Cactus is based upon a \textit{distributed computing} paradigm. That is, the problem domain is split into blocks, each of which is assigned to a processor. For hyperbolic and parabolic problems the blocks only need to communicate at the edges. @@ -927,7 +935,7 @@ $x$), ($t-\Delta t$, $x$), ($t$, $x+\Delta x$) and ($t$, $x-\Delta x$) only. Ignoring the points at $x$, which are obviously always available on a given processor, you can see that the algorithm requires a point on either side of the point $x$, i.e.\ this algorithm -has {\tt stencil size} 1. Similarly algorithms requiring two points +has \textit{stencil size} 1. Similarly algorithms requiring two points on either side have stencil size 2, etc. Now, if you evolve the above scheme, it becomes apparent that at each @@ -946,17 +954,17 @@ At the outer boundary of the physical domain the data for the boundary point can be generated by the boundary conditions, however at internal boundaries the data has to be copied from the adjacent processor. It would be inefficient to copy each point individually, so instead, a -number of {\bf ghostzones} are created at the internal boundaries. A +number of \textit{ghostzones} are created at the internal boundaries. A ghostzone consists of a copy of the whole plane (in 3d, line in 2d, point in 1d) of the data from the adjacent processor. That is, the array on each processor is augmented with copies of points from the adjacent -processors, thus allowing the algorithm to proceed {\bf on the points +processors, thus allowing the algorithm to proceed \textit{on the points owned by this processor} without having to worry about copying data. Once the data has been evolved one step, the data in the ghostzones -can be exchanged (or {\bf synchronised}) between processors in one +can be exchanged (or \textit{synchronised}) between processors in one fell swoop before the next evolution step. (See figure \ref{fig:withghost}.) Note that you should have at least as many -ghostzones as your stencil-size requires. +ghostzones as your stencil size requires. \begin{figure}[ht] \begin{center} @@ -970,7 +978,7 @@ ghostzones as your stencil-size requires. \section{Staggering} -The staggering of a gridfunction or array describes the {\em physical} +The staggering of a gridfunction or array describes the \emph{physical} placement of that gridfunction relative to the supporting grid structure. For example, a gridfunction does not have to be placed at the intersection @@ -978,9 +986,9 @@ of the ``grid lines''. It can be moved by half a grid spacing in any or all dimensions. In the latter case, it will be placed in the center of a cell. -The staggering of a grid function is a pure {\em physical} property: +The staggering of a grid function is a pure \emph{physical} property: the values will be calculated at a different position in physical -space. Still the indexing (or bookeeping) is kept the same for all +space. Still the indexing (or bookkeeping) is kept the same for all types of staggerings: the indexing of the default unstaggered grids is used. @@ -999,17 +1007,16 @@ stagger attribute: relative to the default gridpoint. \item[{\tt C}] centre staggering. The physical location is offset by half of the grid spacing in the positive direction (or to the right). -\item[{\tt P}] full staggered. P refers to plus. The physical location -is offset by a full gridspacing in the positive direction (or the -right). +\item[{\tt P}] full staggered. {\tt P} refers to plus. The physical location +is offset by a full gridspacing in the positive direction (or the right). \end{Lentry} For multi dimensional gridfunctions you concatenate the code -characters in xyz order. In Figure \ref{fig:stagger1} we show four different +characters in $xyz$ order. In Figure \ref{fig:stagger1} we show four different staggerings of a two dimensional grid function. The solid black grid circles show the default location of the grid function at the intersections of the grid lines. In (A) we show an additional grid -function of type {\tt stagger=MC}: no staggering in x direction, -center staggered in y direction. In (B) we have {\tt stagger=CM} and +function of type {\tt stagger=MC}: no staggering in $x$ direction, +center staggered in $y$ direction. In (B) we have {\tt stagger=CM} and staggering each direction ({\tt stagger=CC}) is shown in (C). The full staggering in (D) ({\tt stagger=PP}) obeys the same rules, but is rather unusual; it is included here for completeness. @@ -1034,7 +1041,7 @@ 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 routins, 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: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}). \begin{itemize} @@ -1047,12 +1054,11 @@ Fundamental information about grid functions (e.g.\ local grid size and location \item {\tt CCTK\_Groupbbox[GN|GI|VN|VI]} An array of integers which indicate whether the boundaries are internal boundaries (e.g.\ between processors), or physical boundaries. - A value of 1 indicates + A value of {\tt 1} indicates a physical (outer) boundary at the edge of the computational grid, - and 0 indicates an internal boundary. + and {\tt 0} indicates an internal boundary. -\item {\tt CCTK\_Groupnghostzones[GN|GI|VN|VI]} -An array of integers with +\item {\tt CCTK\_Groupnghostzones[GN|GI|VN|VI]} An array of integers with the number of ghostzones used in each direction. \item {\tt CCTK\_Grouplbnd[GN|GI|VN|VI]} An array of integers @@ -1075,15 +1081,15 @@ An array of integers with \chapter{Cactus Parameters} \label{chap:capa} -Parameters are the means by which the user specifies the run-time behaviour of +Parameters are the means by which the user specifies the runtime behaviour of the code. The user specifies values for parameters in the parameter file, and -then the flesh validates these values against the ranges the thorn writers have +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 steerable, see below). For a detailed discussion of the {\tt param.ccl} syntax see Appendix \ref{sec:pa}. -The full specification for a parameter decalaration is +The full specification for a parameter declaration is \begin{verbatim} [EXTENDS|USES] <parameter_type>[[<size>]] <parameter name> "<parameter description>" { @@ -1101,7 +1107,8 @@ Parameters can be of several types: \item[Integer] Can take any integral value \item[Real] Can take any floating point value \item[Keyword] Can have a value consisting of one of a choice of strings -\item[Boolean] Can be true or false (1, `t', `true', or 0, `f', `false'). +\item[Boolean] Can be true or false ({\t 1}, {\t t}, {\t true}, or +{\t 0}, {\t f}, {\t false}). \item[String] Can have any string value \end{Lentry} @@ -1119,15 +1126,15 @@ lower:upper:stride \end{verbatim} -where {\em lower} and {\em upper} specify the lower and upper allowed -range, and {\em stride} allows numbers to be be missed out. e.g.\ +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.\ \begin{verbatim} 1:21:2 \end{verbatim} means the value must be an odd number between one and twenty-one (inclusive). -A missing end of range (or a `*') implies negative or positive +A missing end of range (or a `{\t *}') indicates negative or positive infinity, and the default stride is one. \subsection{Real} @@ -1136,15 +1143,15 @@ The range specification is of the form \begin{verbatim} lower:upper \end{verbatim} -where {\em lower} and {\em upper} specify the lower and upper allowed -range. A missing end of range (or a `*') implies negative or positive -infinity. The above is inclusive of the end-points. A '(' (or ')') -before (or after) the lower (or upper) range specifies an open -end-point. +where \textit{lower} and \textit{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 +endpoint. -The numbers written in a param.ccl file are interpreted as C code. +The numbers written in a {\tt param.ccl} file are interpreted as C code. To express a number in `scientific notation', use -e.g.\ ``1e-10'', which is a double precision constant in C. (If the +e.g.\ `{\tt 1e-10}', which is a double precision constant in C. (If the floating precision of the variable to which it is assigned is not double, then C will typecast appropriately. If you \emph{really} want to specify a single precision floating constant, or a long double @@ -1153,7 +1160,7 @@ constant, append the number with {\t f} or {\t l} respectively.) \subsection{Keyword} The range specification consists of a string, which will be matched in -a case-insensitive manner. +a case insensitive manner. \subsection{Boolean} @@ -1169,9 +1176,9 @@ to be portable. \section{Scope} -Parameters can be {\em GLOBAL}, {\em RESTRICTED}, or {\em PRIVATE}. +Parameters can be {\tt GLOBAL}, {\tt RESTRICTED}, or {\tt PRIVATE}. Global parameters are visible to all thorns. Restricted parameters -are visible to any thorn which chooses to {\em USE} or {\em EXTEND} +are visible to any thorn which chooses to {\tt USE} or {\tt EXTEND} it. A private parameter is only visible to the thorn which declares it. @@ -1211,11 +1218,11 @@ The full specification for a schedule declaration is \end{verbatim} This full schedule specification consists of a mandatory part, a set -of options, and the main body limited by braces, referred to as the {\tt schedule -block}. +of options, and the main body limited by braces, referred to as the +\textit{schedule block}. -Each schedule item is scheduled either {\em AT} a particular {\em -scheduling bin}, or {\em IN} a schedule {\em group}. +Each schedule item is scheduled either {\tt AT} a particular +\textit{scheduling bin}, or {\tt IN} a schedule \textit{group}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1225,14 +1232,14 @@ scheduling bin}, or {\em IN} a schedule {\em group}. These are the main times at which scheduled functions are run, from fixed points in the Flesh and Driver thorn (schedule bins can easily be traversed from any thorn, although this is not usual). When a -schedule bin is {\it traversed}, all the functions scheduled in that +schedule bin is \textit{traversed}, all the functions scheduled in that particular are called, in the manner described in \ref{scheduling:calling_scheduled_functions} and respecting the requested ordering of functions~\ref{scheduling:schedule_options}. In the absence of any ordering, functions in a particular schedule bin will be called in an undetermined order. The schedule bins are described in \ref{subsec:schedule_ccl}. Note that -the preceeding {\tt CCTK\_} is optional for the use of the bin names +the preceding {\tt CCTK\_} is optional for the use of the bin names in the {\tt schedule.ccl} file. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1243,14 +1250,14 @@ in the {\tt schedule.ccl} file. If the optional {\tt GROUP} specifier is used, the item is a schedule group rather than a normal function. Schedule groups are effectively new, user-defined, schedule bins. Functions or groups may be -scheduled {\em IN} these in the same way as they are scheduled {\em +scheduled {\tt IN} these in the same way as they are scheduled {\tt AT} the main schedule bins. (That is, groups may be nested.) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Schedule Options} \label{scheduling:schedule_options} -The options define various charactertics of the schedule item. +The options define various characteristics of the schedule item. \begin{Lentry} \item[{\tt BEFORE or AFTER}] @@ -1258,14 +1265,14 @@ These specify a function or group before or after which this item will be scheduled. \item[{\tt WHILE}] This specifies a {\tt CCTK\_INT} grid scalar which is used to control -the execution of this item. If the grid scalar has a non-zero value +the execution of this item. If the grid scalar has a nonzero value the schedule item will be executed, otherwise the item will be ignored. This allows some dynamic behaviour with scheduling. \item[{\tt AS}] This assigns a new name to a function for scheduling purposes. This is used, for instance, to allow a thorn to schedule something before or after a routine from another implementation; two thorns providing this -implementation can schedule a routine {\em AS} the same thing, thus +implementation can schedule a routine {\tt AS} the same thing, thus allowing other thorns to operate independently of which one is active. \end{Lentry} @@ -1287,7 +1294,7 @@ which memory should be allocated for the duration of the routine or schedule group. The storage status reverts to its previous status after completion of the routine or schedule group. \item[\texttt{TRIGGER}] -This is only used for items scheduled at {\em CCTK\_ANALYSIS}. The +This is only used for items scheduled at timebin {\tt CCTK\_ANALYSIS}. The item will only be executed if output is due for at least one variable in one of the listed groups. \item[\texttt{SYNC}] @@ -1295,7 +1302,7 @@ On exit from this item the ghost zones of the listed groups will be exchanged. \item[\texttt{OPTIONS}] This is for miscellaneous options. The only currently supported -option is {\em GLOBAL} which tells the driver that this routine does +option is {\tt GLOBAL} which tells the driver that this routine does not use a local grid, but instead uses global operations to process data; such a routine should only be called once however many sub-grids the driver may have broken the problem into. @@ -1306,11 +1313,11 @@ sub-grids the driver may have broken the problem into. \section{How Cactus Calls Scheduled Functions} \label{scheduling:calling_scheduled_functions} -For each scheduled function called, the flesh performs a variety of jobs +For each scheduled function called, the Flesh performs a variety of jobs at entry and exit. On entry to a scheduled routine, if the routine is being called at the -ANALYSIS timebin first a check is made to see if the routine should +{\tt CCTK\_ANALYSIS} timebin first a check is made to see if the routine should actually be called on this timestep. For this, all grid variables in the trigger groups for the routine are checked with all registered output methods to determine if it is time to output any triggers. The routine @@ -1319,9 +1326,9 @@ a grid variable has been analyzed it gets marked as such and will not be analyzed again during this iteration. Thus if more than one analysis routine should be triggered on the same trigger variable(s) they must be scheduled in a single group.\\ -Routines from all timebins other than ANALYSIS are always called. +Routines from all timebins other than {\tt ANALYSIS} are always called. -Next storage is assigned for any required variables, remembering the +Next, storage is assigned for any required variables, remembering the original state of storage. The routine is then called, and on exit, any required grid variables are @@ -1340,22 +1347,22 @@ returned to the original state. When you start writing a new thorn, the first decision to make is which programming language to use? The source code in Cactus thorns -can be written in any mixture of {\tt FORTRAN77}, {\tt FORTRAN90}, -{\tt C} or {\tt C++}. The following points should be considered when +can be written in any mixture of Fortran 77, Fortran 90, +C or C++. The following points should be considered when choosing a language to work in \begin{itemize} \item All functions designed for application thorn writers are available in all languages, however some interfaces for infrastructure - thorn writing are only available from {\tt C} or {\tt C++}. + thorn writing are only available from C or C++. % This is no longer relevant? -%\item If you are writing in {\tt FORTRAN}, use {\tt F77} if you want +%\item If you are writing in Fortran, use {\tt F77} if you want % to distribute your code to people who may not be able to afford -% to buy proprietory {\tt F90} compilers. +% to buy proprietary Fortran 90 compilers. -\item Stick to {\tt C} rather than {\tt C++}, unless you really need - features from {\tt C++}, this will help you with portability. +\item Stick to C rather than C++, unless you really need + features from C++, this will help you with portability. \end{itemize} @@ -1367,14 +1374,14 @@ use machine dependent extensions. \section{What the Flesh provides} -The flesh provides for thorns: +The Flesh provides for thorns: \begin{Lentry} \item [{\tt Variables}] \item [{\tt Parameters}] \item [{\tt Cactus Functions}] \begin{itemize} - \item{} driver (parallelisation) utilities + \item{} Driver (parallelisation) utilities \item{} IO utilities \item{} Coordinates utilities \item{} Reduction utilities @@ -1391,8 +1398,8 @@ the header file {\tt cctk.h} using the line \begin{verbatim} #include "cctk.h" \end{verbatim} -(Fortran programmers should not be put of by this being a C style -header file, most Cactus files are run through a C preprocessor +(Fortran programmers should not be put off by this being a C style +header file --- most Cactus files are run through a C preprocessor before compilation). \subsubsection{Variables} @@ -1429,11 +1436,12 @@ no grid hierarchy exists. \subsubsection{Parameters} All parameters defined in a thorn's {\tt param.ccl} and all {\tt global} -parameters appear as local variables of the corresponding CCTK datatype -in Fortran source code, ie. Booleans and Integers appear as CCTK\_INT types -(with non-zero/zero values for boolean {\t yes/no}), -Reals as CCTK\_REAL, and Keywords and String parameters as CCTK\_POINTER (see -also note below). These variables are {\tt read only} and {\em changes should +parameters appear as local variables of the corresponding {\tt CCTK} datatype +in Fortran source code, i.e.. Booleans and Integers appear as {\tt CCTK\_INT} +types (with nonzero/zero values for boolean {\t yes/no}), +Reals as {\tt CCTK\_REAL}, and Keywords and String parameters as +{\tt CCTK\_POINTER} (see +also note below). These variables are \emph{read only} and \emph{changes should not be made to them}. The effect of changing a parameter is undefined (at best). Any routine using Cactus parameters should include at @@ -1547,7 +1555,7 @@ $(SYS_OBJD)/MyRoutine.F.o: $(SYS_OBJD)/MyModule.F.o The intrinsic function {\tt MOD} in Fortran takes two integer arguments, which should both be of the same type. This means -that it may be necessary to cast the arguements to {\it e.g} +that it may be necessary to cast the arguments to \textit{e.g.} {\tt INT} for some architectures. This can occur in particular when a {\tt CCTK\_INT} parameter and the Cactus variable {\tt cctk\_iteration} (which is declared to be {\tt INTEGER}) are used, @@ -1577,7 +1585,7 @@ should include at the top of the file the header A Cactus macro {\tt CCTK\_ARGUMENTS} is defined for each thorn to contain \begin{itemize} -\item General information about the grid hierachy, for example the +\item General information about the grid hierarchy, for example the number of grid points on the processor. See Section \ref{sec:cava2} for a complete list. \item All the grid variables defined in the thorn's {\tt interface.ccl} @@ -1600,11 +1608,11 @@ no grid hierarchy exists. \subsubsection{Parameters} All parameters defined in a thorn's {\tt param.ccl} and all {\tt global} -parameters appear as local variables of the corresponding CCTK datatype -in C source code, ie. Integers and Booleans appear as CCTK\_INT types (with -non-zero/zero values for boolean {\t yes/no)}, Reals as -CCTK\_REAL, and Keywords and String parameters as CCTK\_STRING. -These variables are {\tt read only} and {\em changes should not be made to +parameters appear as local variables of the corresponding {\tt CCTK} datatype +in C source code, i.e. Integers and Booleans appear as {\tt CCTK\_INT} types +(with nonzero/zero values for boolean {\t yes/no}), Reals as +{\tt CCTK\_REAL}, and Keywords and String parameters as {\tt CCTK\_STRING}. +These variables are \emph{read only} and \emph{changes should not be made to them}. The effect of changing a parameter is undefined (at best). Any routine using Cactus parameters should include at @@ -1618,7 +1626,7 @@ of the routine using them with the macro {\tt DECLARE\_CCTK\_PARAMETERS}. \subsubsection{Example} -The C routine ``MyCRoutine'' is scheduled in the {\tt schedule.ccl} file, +The C routine {\tt MyCRoutine} is scheduled in the {\tt schedule.ccl} file, and uses Cactus parameters. The source file should look like \begin{verbatim} #include "cctk.h" @@ -1648,15 +1656,15 @@ functionality available in Fortran. These functions are {\tt CCTK\_Cmplx}, \subsubsection{Specifically for C Programmers} -Grid functions are held in memory as 1D C arrays. These are laid +Grid functions are held in memory as 1-dimensional C arrays. These are laid out in memory as in Fortran. This means that the first index should be incremented through most rapidly. This is illustrated in the example below. Cactus provides -macros to find the 1D index which is needed from the multidimensional +macros to find the 1-dimensional index which is needed from the multidimensional indices which are usually used. There is a macro for each dimension of -grid function. Below is an articifial example to demonstrate this +grid function. Below is an artificial example to demonstrate this using the 3D macro {\tt CCTK\_GFINDEX3D}: \begin{verbatim} for (k=0; k<cctk_lsh[2]; k++) @@ -1682,13 +1690,13 @@ Here, {\tt CCTK\_GFINDEX3D(cctkGH,i,j,k)]} expands to The Cactus variables which are passed through the macro {\tt CCTK\_ARGUMENTS} are \begin{Lentry} -\item [{\tt cctkGH}] A C pointer identifying the grid hierachy. +\item [{\tt cctkGH}] A C pointer identifying the grid hierarchy. \item [{\tt cctk\_dim}] An integer with the number of dimensions used for this grid hierarchy. \item [{\tt cctk\_lsh}] An array of {\tt cctk\_dim} integers with the local grid size on this processor. \item [{\tt cctk\_gsh}] An array of {\tt cctk\_dim} integers - with the {\it global} grid size. + with the \textit{global} grid size. \item [\texttt{cctk\_iteration}] The current iteration number. \item [{\tt cctk\_delta\_time}] A {\tt CCTK\_REAL} with the timestep. \item [{\tt cctk\_time}] A {\tt CCTK\_REAL} with the current time. @@ -1728,8 +1736,8 @@ the global grid. Fortran thorns. \item {\tt cctk\_bbox} An array of 2$*${\tt cctk\_dim} integers (in the order - $[{\mbox{dim}}_0^{\mbox{min}}, \mbox{dim}_0^{\mbox{max}}, - {\mbox dim}_1^{\mbox{min}}, {\mbox dim}_1^{\mbox{max}}, \ldots]$), + $[\mbox{dim}_0^{\mbox{min}}, \mbox{dim}_0^{\mbox{max}}, + \mbox{dim}_1^{\mbox{min}}, \mbox{dim}_1^{\mbox{max}}, \ldots]$), which indicate whether the boundaries are internal boundaries (e.g.\ between processors), or physical boundaries. A value of 1 indicates @@ -1753,15 +1761,17 @@ The following variable is needed for grid refinement methods base grid. \end{itemize} -The following variable is used for identifing convergence levels. {\tt NOTE:} Convergence is not currently implemented by Cactus, so that {\tt cctk\_convlevel} is currently always 0. +The following variable is used for identifying convergence levels. \emph{NOTE:} +Convergence is not currently implemented by Cactus, so that +{\tt cctk\_convlevel} is currently always 0. \begin{itemize} -\item {\tt cctk\_convlevel} The convergence level of this grid hierachy. +\item {\tt cctk\_convlevel} The convergence level of this grid hierarchy. The base level is 0, and every level above that is currently coarsened by a factor of 2. \end{itemize} The variables {\tt cctk\_delta\_space}, {\tt cctk\_delta\_time}, and {\tt cctk\_origin\_space} denote the grid spacings, time step size, -and spatial origin on the {\em base} grid. If you are using a grid +and spatial origin on the \textit{base} grid. If you are using a grid refinement method, you need to calculate these quantities on the grid you are on. There are Cactus macros provided for this, with the syntax {\tt CCTK\_DELTA\_SPACE(dir)}, {\tt CCTK\_ORIGIN\_SPACE(dir)}, @@ -1827,9 +1837,9 @@ location (it's only addressed by indices) why add staggering if the indexing is the same? Indeed, you could roll your own, but there compelling reasons: -Readabilty and the fact that you are able to query the staggertype of a +Readability and the fact that you are able to query the staggertype of a gridfunction. More important: in the way the grid is laid out, there is one grid -point {\em less} for {\tt M} and {\tt P} staggered grid functions. This is +point \emph{less} for {\tt M} and {\tt P} staggered grid functions. This is illustrated in picture \ref{fig:stagger2}, which shows 15 gridpoints distributed across 3 processors. The solid black circles show the default location of the gridfunctions, the grey circles depict the ghostzones. @@ -1839,13 +1849,13 @@ the last one. (The same is true for full staggered gridpoints). \subsubsection{Staggertypes} The string specifying the staggering is encoded in a number called -the {\em staggerindex}. With the 3 supported staggerings, the string -is converted into a base-3 number. Several routines exist, to extract the -staggering in a specific direction, called {\em directional -staggerindex}. E.g.\ {\tt stagger = MCM}: {\em staggerindex} = 3, in the -x-direction: {\em directional staggerindex} = CCTK\_STAGGER\_M (value 0), +the \textit{staggerindex}. With the 3 supported staggerings, the string +is converted into a base 3 number. Several routines exist to extract the +staggering in a specific direction, called \textit{directional +staggerindex}. E.g.\ {\tt stagger = MCM}: \textit{staggerindex} = 3, in the +$x$-direction: \textit{directional staggerindex} = {\tt CCTK\_STAGGER\_M} (value 0), in the -y-direction: {\em directional staggerindex} = CCTK\_STAGGER\_C (value 1). +$y$-direction: \textit{directional staggerindex} = {\tt CCTK\_STAGGER\_C} (value 1). \begin{Lentry} \item[{\tt CCTK\_STAGGER\_M}] value used for M-type staggering @@ -1886,7 +1896,7 @@ of processor local gridpoints, including ghostzones. \begin{itemize} \item{macro has to be in capital letters} \item{This macro is C/Fortran indexing aware: -can specify the dimension in C ranging from $0 \ldots$ and in Fortan +can specify the dimension in C ranging from $0 \ldots$ and in Fortran ranging from $1 \ldots$.} \end{itemize} \end{Lentry} @@ -1897,60 +1907,59 @@ 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 -%{\em staggerindex} for a given group index. +%\textit{staggerindex} for a given group index. \item[{\tt call CCTK\_GroupStaggerIndexGI(int staggerindex, int -group\_index)}] returns the {\em staggerindex} for a given group index. +group\_index)}] returns the \textit{staggerindex} for a given group index. \end{Lentry} \vskip .45cm \begin{Lentry} \item[{\tt int CCTK\_GroupStaggerIndexGN(char *group\_name)}] %returns the -%{\em staggerindex} for a given group name. +%\textit{staggerindex} for a given group name. \item[{\tt call CCTK\_GroupStaggerIndexGN(int staggerindex, char *group\_name)}] returns the -{\em staggerindex} for a given group name. \vskip .25cm +\textit{staggerindex} for a given group name. \vskip .25cm \end{Lentry} \vskip .45cm \begin{Lentry} \item[{\tt int CCTK\_GroupStaggerIndexVI(int variable\_index)}] %returns the -%{\em staggerindex} for a given variable index. +%\textit{staggerindex} for a given variable index. \item[{\tt call CCTK\_GroupStaggerIndexVI(int staggerindex, int variable\_index)}] returns the -{\em staggerindex} for a given variable index. +\textit{staggerindex} for a given variable index. \end{Lentry} \vskip .45cm \begin{Lentry} \item[{\tt int CCTK\_GroupStaggerIndexVN(char *variable\_name)}] %returns the -%{\em staggerindex} for a given variable name. +%\textit{staggerindex} for a given variable name. \item[{\tt call CCTK\_GroupStaggerIndexVN(int staggerindex, char *variable\_name)}] returns the -{\em staggerindex} for a given variable name. +\textit{staggerindex} for a given variable name. \end{Lentry} \vskip .45cm \begin{Lentry} -\item[{\tt int CCTK\_StaggerIndex(char *stagger\_string)}] %return the {\em +\item[{\tt int CCTK\_StaggerIndex(char *stagger\_string)}] %return the \textit{ %staggerindex} for a given stagger string. -\item[{\tt call CCTK\_StaggerIndex(int staggerindex, char *stagger\_string)}] return the {\em -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. \end{Lentry} \vskip .45cm \begin{Lentry} \item[{\tt int CCTK\_DirStaggerIndex(int direction, char *stagger\_string)}] -%returns the {\em directional staggerindex} for a given direction and +%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 {\em directional staggerindex} for a given direction and +returns the \textit{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)}] -%returns the {\em directional staggerindex} for a given direction and +%returns the \textit{directional staggerindex} for a given direction and %staggerindex. \item[{\tt call CCTK\_DirStaggerIndexI(int dir\_direction, char *stagger\_type)}] -returns the {\em directional staggerindex} for a given direction and +returns the \textit{directional staggerindex} for a given direction and staggerindex. \end{Lentry} @@ -1960,14 +1969,14 @@ staggerindex. \section{Parallelisation} \label{seap} -The flesh itself does not actually set up grid variables. This -is done by a {\it driver} thorn. To allow the distribution of +The Flesh itself does not actually set up grid variables. This +is done by a \textit{driver} thorn. To allow the distribution of a grid over a number of processors, the driver thorn must also provide the grid decomposition, and routines to enable parallelisation. The method used to provide this parallelisation (e.g.\ MPI, PVM) is not usually important for the thorn writer since the driver thorn provides routines which are called by standard interfaces -from the flesh. Here we describe briefly the most important of these routines +from the Flesh. Here we describe briefly the most important of these routines for the application thorn writer. A more detailed description of these interfaces with their arguments, is given in the Reference Manual. A complete description of the @@ -1997,20 +2006,20 @@ is a parallel unigrid driver. \section{Coordinates} \label{sec:co} -The flesh provides utility routines for registering and querying -coordinate information. The flesh does not provide any coordinates +The Flesh provides utility routines for registering and querying +coordinate information. The Flesh does not provide any coordinates itself, these must be supplied by a thorn. Thorns are not required to -register coordinates to the flesh, but registering coordinates +register coordinates to the Flesh, but registering coordinates provides a means for infrastructure thorns to make use of coordinate information. -Coordinate support is still being developed in the Cactus flesh. At +Coordinate support is still being developed in the Cactus Flesh. At the moment, it is assumed that coordinates will usually be grid functions. -Coordinates are grouped into {\it coordinate systems}, which have a +Coordinates are grouped into \textit{coordinate systems}, which have a specified dimension. Any number of coordinate systems can be -registered with the flesh, and a coordinate system must be registered +registered with the Flesh, and a coordinate system must be registered before any coordinates can be registered, since they must be associated with their corresponding system. Coordinates can be registered, with any chosen name, with an existing coordinate system, @@ -2023,7 +2032,7 @@ 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 refered to by both its name and +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. @@ -2050,7 +2059,7 @@ ierr = CCTK\_CoordRegisterSystem(dim,"cart3d"); Defines a coordinate in a given coordinate system, with a given direction and name, and optionally associates it to a grid variable. The directions of the coordinates range from 1 to the dimension of the -coordinate system. For example, to register the grid variable {\it grid::y3d} +coordinate system. For example, to register the grid variable {\tt grid::y3d} to have the coordinate name {\tt y} in the {\tt cart3d} system {\tt @@ -2062,7 +2071,7 @@ ierr = CCTK\_CoordRegisterData(dir,"grid::y3d","y","cart3d"); \item[{\tt CCTK\_CoordRegisterRange}] Assigns the global computational maximum and minimum for a coordinate -on a grid hierachy, that is in a {\tt cctkGH}. At this time the +on a grid hierarchy, that is in a {\tt cctkGH}. At this time the maximum and minimum values have to be of type {\tt CCTK\_REAL}. For example, if the {\tt y} coordinate for the {\tt cart3d} system ranges between zero and one @@ -2087,9 +2096,9 @@ ierr = CCTK\_CoordRegisterRange(cctkGH, lower, upper, 2, NULL, "cart3d"); \item[{\tt CCTK\_CoordRegisterPhysIndex}] Implementing such things as symmetry properties for a grid leads to -the need to know the details of the {\it physical} section of a grid. +the need to know the details of the \emph{physical} section of a grid. Such information is typically needed by IO thorns. The following call -illustrates how To register the +illustrates how to register the indices 3 and 25 as supplying the physical range of the {\tt y} coordinate in the {\tt cart3d} system @@ -2163,7 +2172,7 @@ const char *name = CCTK\_CoordSystemName(handle); \item[{\tt CCTK\_CoordIndex}] -Provides the grid variable index for a given coordinate. Notethat it is +Provides the grid variable index for a given coordinate. Note that it is not necessary for a registered coordinate to have an associated grid variable, and if no such grid variable is found a negative integer will be returned. For example, to find the grid variable index associated with the {\tt y} @@ -2193,11 +2202,11 @@ could not be found. \item[{\tt CCTK\_CoordRange}] -Provides the global range (that is, the minumum and maximum values across -the complete grid) of a coordinate on a given grid hierachy. Currently -the minumum and maximum values must be of type {\tt CCTK\_REAL}. The +Provides the global range (that is, the minimum and maximum values across +the complete grid) of a coordinate on a given grid hierarchy. Currently +the minimum and maximum values must be of type {\tt CCTK\_REAL}. The coordinate can be specified either by name or by its direction. Note that -this call returns the {\tt addresses} or the minumum and maximum values. +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 @@ -2218,7 +2227,7 @@ ierr = CCTK\_CoordRange(cctkGH, \&lower, \&upper, 2, NULL, "cart3d"); \item[{\tt CCTK\_CoordLocalRange}] Provides the local range of a coordinate on a processor for a given -grid hierachy. WARNING: This utility only currently works for regular +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 @@ -2236,7 +2245,7 @@ ierr = CCTK\_CoordLocalRange(cctkGH, \&lower, \&upper, 2, NULL, "cart3d"); \item[{\tt CCTK\_CoordRangePhysIndex}] -For a given coordinate, provides the indices describing the {\it physical} +For a given coordinate, provides the indices describing the \emph{physical} range of the coordinate. A negative return value signifies that no such range was registered for the coordinate. @@ -2269,7 +2278,7 @@ should usually be the case. \section{IO} \label{sec:io} -To allow flexible IO, the flesh itself does not provide any output +To allow flexible IO, the Flesh itself does not provide any output routines, however it provides a mechanism for thorns to register different routines as IO methods (see chapter \ref{chap:io_methods}). Application thorns can interact with the different IO methods through @@ -2327,13 +2336,13 @@ name of the variable for the purpose of constructing a filename. \section{Interpolation Operators} \label{sec:inop} -The flesh does not provide interpolation routines by itself. Instead +The Flesh does not provide interpolation routines by itself. Instead it offers a general function API to thorns for the registration and invocation of interpolation operators. -There are several different flesh APIs for interpolation, depending -on whether the data arrays are Cactus grid arrays or processor-local -``ordinary programming-language'' arrays, and on what assumptions +There are several different Flesh APIs for interpolation, depending +on whether the data arrays are Cactus grid arrays or processor-local, +programming language built-in arrays, and on what assumptions are made about the topology and spacing of the grid (these descriptions are for 3-D, but the generalizations to other numbers of dimensions should be obvious): @@ -2354,10 +2363,10 @@ should be obvious): \item[{\tt CCTK\_InterpLocal()}] Interpolate processor-local arrays (old API, will be phased out soon) \item[{\tt CCTK\_InterpLocalUniform()}] - Interpolates processor-local arrays with {\em uniformly\/} + Interpolates processor-local arrays with \emph{uniformly} spaced data points, \ie{} where the coordinates~$xyz$ are related to the integer array subscripts~\verb|ijk| by - {\em linear\/} functions + \emph{linear} functions \begin{flushleft} $x = \verb|origin|_x + \verb|delta|_x \verb|i|$ \\ $y = \verb|origin|_y + \verb|delta|_y \verb|j|$ \\ @@ -2366,10 +2375,10 @@ should be obvious): where the caller specifies the \verb|origin| and \verb|delta| values. %notyet \item[{\tt CCTK\_InterpLocalNonUniform()}] -%notyet Interpolates processor-local arrays with {\em nonuniformly\/} +%notyet Interpolates processor-local arrays with \emph{non-uniformly} %notyet spaced data points, \ie{} where the coordinates~$xyz$ %notyet are related to the integer array subscripts~\verb|ijk| by -%notyet {\em nonlinear\/} (but still single-variable) functions +%notyet \emph{nonlinear} (but still single-variable) functions %notyet \begin{flushleft} %notyet $x = x(\verb|i|)$ \\ %notyet $y = y(\verb|j|)$ \\ @@ -2378,10 +2387,10 @@ should be obvious): %notyet where the caller specifies the functions $x$, $y$, and $z$ %notyet by providing 1-D arrays giving their values at the grid points. %notyet \item[{\tt CCTK\_InterpLocalWarped()}] -%notyet Interpolates processor-local arrays with {\em curvilinearly -%notyet warped\/} data points, \ie{} where the coordinates~$xyz$ +%notyet Interpolates processor-local arrays with \emph{curvilinearly +%notyet warped} data points, \ie{} where the coordinates~$xyz$ %notyet are related to the integer array subscripts~\verb|ijk| by -%notyet generic {\em nonlinear\/} functions +%notyet generic \emph{nonlinear} functions %notyet \begin{flushleft} %notyet $x = x(\verb|i|, \verb|j|, \verb|k|)$ \\ %notyet $y = y(\verb|i|, \verb|j|, \verb|k|)$ \\ @@ -2391,7 +2400,7 @@ should be obvious): %notyet by providing 3-D arrays giving their values at the grid points. \end{Lentry} -There are separate flesh routines to register interpolation operators for +There are separate Flesh routines to register interpolation operators for the APIs (note the calling sequences differ slightly from one registration routine to another!): \begin{Lentry} @@ -2410,12 +2419,12 @@ routine to another!): \end{Lentry} These are described in detail in the Reference Manual. -Each operator is registered under a character-string name; at +Each operator is registered under a character string name; at registration the name is mapped to a unique integer handle which may be used to refer to the operator. \verb|CCTK_InterpHandle()| -is used to get the handle corresponding to a given character-string +is used to get the handle corresponding to a given character string name. In general each name/handle is actually associated with a -{\em set\/} of interpolation operators, one for each of the +\emph{set} of interpolation operators, one for each of the interpolation APIs.%%% \footnote{%%% If (as is often the case) an operator @@ -2450,16 +2459,16 @@ truncation error. The exchange of information across processors needs the functionality of a communication layer e.g.\ {\tt CactusPUGH/PUGH}. For this reason, the -reduction operation itself is not part of the flesh, instead Cactus (again) +reduction operation itself is not part of the Flesh, instead Cactus (again) provides a registration mechanism for thorns to register routines they provide as reduction operators. The different operators are -identified by their name and/or a unique number, called a {\em handle}. +identified by their name and/or a unique number, called a \textit{handle}. The registration mechanism gives the advantage of a common interface while hiding the individual communication calls in the layer. In Cactus, reduction operators can in principle be applied to -grid functions, arrays, and scalars, as well as to local (non CCTK-) arrays. Note that +grid functions, arrays, and scalars, as well as to local (non-CCTK) arrays. Note that different implementations of reduction operators may be limited in the types of objects to which they can be applied. There is a fundamental difference between a reduction operation on @@ -2476,7 +2485,7 @@ Reference Manual. {\bf Obtaining the reduction handle} Before calling the routine which performs the reduction operation, -the handle, which indentifies the operation, must be derived from its +the handle, which identifies the operation, must be derived from its registered name. To obtain a handle for the reduction of a CCTK variable, use % \begin{verbatim} @@ -2487,7 +2496,7 @@ integer reduction_handle character*(*) reduction_name \end{verbatim} % -(for C or Fortran respectively), while for a local, non-CCTK-array, use +(for C or Fortran respectively), while for a local, non-CCTK array, use % \begin{verbatim} int CCTK_ReductionArrayHandle(const char *reduction_name); @@ -2513,7 +2522,7 @@ Computational Toolkit release which provides reduction operators is (Note that although it would appear to be far more convenient to pass the name of the reduction operator directly to the following function call to {\t CCTK\_Reduce} this causes problems with the -translation of strings from {\t FORTRAN} to {\t C} with variable +translation of strings from Fortran to C with variable argument lists). @@ -2577,9 +2586,9 @@ call CCTK_ReduceArray( integer returnvalue, \begin{Lentry} \item[{\tt returnvalue}] the return value of the operation. A negative value indicates a failure to perform the reduction. A zero -indicates successfull operation. +indicates successful operation. -\item[{\tt GH} or {\tt cctkGH}] the pointer to the grid hierachy +\item[{\tt GH} or {\tt cctkGH}] the pointer to the grid hierarchy structure. \item[{\tt processor}] the processor which collects the @@ -2598,7 +2607,7 @@ number, this would be one. \item[{\tt type\_out\_arrays}, {\tt type\_in\_arrays}] specifies the type of the data you are communicating. Use the values as specified in -\ref{sec:datyansi}. Note: Do not {\em mix} datatypes. For example, in +\ref{sec:datyansi}. Note: Do not \emph{mix} datatypes. For example, in Fortran do not declare a variable as {\tt integer} and then specify the type {\tt CCTK\_VARIABLE\_INT} in the reduction command. These types may not be the same on some architectures and will conflict. @@ -2606,19 +2615,19 @@ types may not be the same on some architectures and will conflict. \item[{\tt out\_vals}] a pointer to the buffer which will hold the output values. Note that the input and output buffer must be distinct. -\item[{\tt num\_dims}] (CCTK\_ReduceArray only) the number of dimensions of the input and output arrays. +\item[{\tt num\_dims}] ({\tt CCTK\_ReduceArray} only) the number of dimensions of the input and output arrays. -\item[{\tt num\_in\_fields}] (CCTK\_Reduce only) specifies the number of input CCTK +\item[{\tt num\_in\_fields}] ({\tt CCTK\_Reduce} only) specifies the number of input CCTK variables which will be specified in the variable argument list $<$...$>$. -\item[{\tt num\_in\_arrays}] (CCTK\_ReduceArray only) specifies the -number of imput \emph{arrays} (not the number of input \emph{fields}, +\item[{\tt num\_in\_arrays}] ({\tt CCTK\_ReduceArray} only) specifies the +number of input \textit{arrays} (not the number of input \textit{fields}, which would be $\mathrm{num\_in\_arrays}*(\mathrm{num\_dims}+1)$, see below) which will be specified in the variable argument list $<$...$>$. -\item[{\tt ...}] indicates a varible argument list:\\ +\item[{\tt ...}] indicates a variable argument list:\\ % -\textbf{for CCTK\_Reduce:} Specify a list of CCTK variable indicies, +\textbf{for CCTK\_Reduce:} Specify a list of CCTK variable indices, one for each variable that is to be reduced. The number of specified variables must be the same as the value of the {\tt num\_in\_fields} variable.\\ @@ -2666,8 +2675,8 @@ call CCTK_ReduceLocScalar(integer returnvalue, \begin{Lentry} \item[{\tt returnvalue}] the return value of the operation. A negative value indicates a failure to perform the reduction. A zero -indicates successfull operation. -\item[{\tt GH} or {\tt cctkGH}] the pointer to the grid hierachy +indicates successful operation. +\item[{\tt GH} or {\tt cctkGH}] the pointer to the grid hierarchy structure. \item[{\tt processor}] the processor which collects the information; a negative value will distribute the data to all @@ -2716,8 +2725,8 @@ call CCTK_ReduceLocArrayToArray1D( integer returnvalue \begin{Lentry} \item[{\tt returnvalue}] the return value of the operation. A negative value indicates a failure to perform the reduction. A zero -indicates successfull operation. -\item[{\tt GH} or {\tt cctkGH}] the pointer to the grid hierachy +indicates successful operation. +\item[{\tt GH} or {\tt cctkGH}] the pointer to the grid hierarchy structure. \item[{\tt processor}] the processor which collects the information; a negative value will distribute the data to all @@ -2766,8 +2775,8 @@ call CCTK_ReduceLocArrayToArray2D( integer returnvalue \begin{Lentry} \item[{\tt returnvalue}] the return value of the operation. A negative value indicates a failure to perform the reduction. A zero -indicates successfull operation. -\item[{\tt GH} or {\tt cctkGH}] the pointer to the grid hierachy +indicates successful operation. +\item[{\tt GH} or {\tt cctkGH}] the pointer to the grid hierarchy structure. \item[{\tt processor}] the processor which collects the information; a negative value will distribute the data to all @@ -2780,8 +2789,8 @@ processors. processors, element by element. \item[{\tt out\_array2d}] two dimensional array to hold the reduction result. out\_array2d[i,j]= Reduction(in\_array2d[i,j]). -\item[{\tt xsize}] the size of the two dimensional array in x direction. -\item[{\tt ysize}] the size of the two dimensional array in y +\item[{\tt xsize}] the size of the two dimensional array in $x$ direction. +\item[{\tt ysize}] the size of the two dimensional array in $y$ direction. Note that the input and output array must be distinct. \item[{\tt data\_type}] specifies the type of the gridfunction you are @@ -2819,8 +2828,8 @@ call CCTK_ReduceLocArrayToArray3D(integer returnvalue \begin{Lentry} \item[{\tt returnvalue}] the return value of the operation. A negative value indicates a failure to perform the reduction. A zero -indicates successfull operation. -\item[{\tt GH} or {\tt cctkGH}] the pointer to the grid hierachy +indicates successful operation. +\item[{\tt GH} or {\tt cctkGH}] the pointer to the grid hierarchy structure. \item[{\tt processor}] the processor which collects the information; a negative value will distribute the data to all @@ -2833,9 +2842,9 @@ processors. processors, element by element. \item[{\tt out\_array3d}] three dimensional array holding the reduction result. out\_array3d[i,j,k]= Reduction(in\_array3d[i,j,k]). -\item[{\tt xsize}] the size of the three dimensional array in x direction. -\item[{\tt ysize}] the size of the three dimensional array in y direction. -\item[{\tt ysize}] the size of the three dimensional array in z +\item[{\tt xsize}] the size of the three dimensional array in $x$ direction. +\item[{\tt ysize}] the size of the three dimensional array in $y$ direction. +\item[{\tt zsize}] the size of the three dimensional array in $z$ direction. Note that the input and output array must be distinct. \item[{\tt data\_type}] specifies the type of the gridfunction you are @@ -2845,7 +2854,7 @@ communicating. Use the values as specified in \ref{sec:datyansi}. \vskip .24cm {\bf Some brief examples:} -{\bf Reduction of a scalar:} A local error is reduced across all +\textit{Reduction of a scalar:} A local error is reduced across all processors with the maximum operation. The variable {\tt tmp} will hold the maximum of the error and is the same on all processors. This quantity can then be reassigned to {\tt normerr}. @@ -2869,9 +2878,9 @@ processors. This quantity can then be reassigned to {\tt normerr}. \end{verbatim} -{\bf Reduction of a 2d array:} A two dimensional $(2x3)$ array is +\textit{Reduction of a 2d array:} A two dimensional $(2\times3)$ array is reduced; the reduction result (array of same size: {\tt bla\_tmp}) is seen -on all processors ($-1$ entry as the thid argument). This example also demonstrates +on all processors ($-1$ entry as the third argument). This example also demonstrates some simple error checking with the {\tt CCTKi\_EXPECTOK} macro. \begin{verbatim} CCTK_REAL bla(2,3),bla_tmp(2,3); @@ -2903,7 +2912,8 @@ the reduction call is made. Note that since most source files (see Section~\ref{nacofosofi} for exceptions) pass through a C preprocessor, C style comments can be -used in Fortran code. (Note that C++ comments (that is //), +used in Fortran code. (Note that C++ comments (that is ones starting +with ``{\tt //}''), should only be used in C++ source code). The Flesh and the Cactus thorns use the {\tt grdoc} Code Documenting @@ -2915,7 +2925,7 @@ source code. \section{Providing Runtime Information} \label{sec:prrutiin} -To write from thorns to standard output ({\it i.e.} the screen) +To write from thorns to standard output (\textit{i.e.} the screen) at runtime, use the macro {\tt CCTK\_INFO} or the function {\tt CCTK\_VInfo()}. For example, from the Fortran thorn {\tt MyThorn}, @@ -3011,10 +3021,10 @@ and from C Note that {\tt CCTK\_WARN} is just a macro which expands to a call to the internal function {\tt CCTK\_Warn()}. The macro automatically includes the name of the thorn, the source file name and line number of the warning in the -funtion call. (For this reason it is important for Fortran code that capital +function call. (For this reason it is important for Fortran code that capital letters are always used in order to expand the macro). -If the flesh parameter {\tt cctk\_full\_warnings} is set to true, then the +If the Flesh parameter {\tt cctk\_full\_warnings} is set to true, then the source file name and line number will be printed to standard error along with the originating processor number, the thorn name and the warning message. The default is to omit the source file name and line number. @@ -3054,7 +3064,7 @@ In Fortran 90, you can also do: call CCTK_WARN (1, trim(message)) \end{verbatim} -The flesh will be implementing standard error return codes +The Flesh will be implementing standard error return codes which can be used by the thorns, although this is not yet ready. In general, thorns should attempt to handle errors without terminating, and warning messages should be liberally @@ -3065,7 +3075,7 @@ used. \section{Adding documentation} \label{sec:addo} -Documentation is a vital part of your thorn, helping to ensure it's +Documentation is a vital part of your thorn, helping to ensure its ease of use and longevity, not only for others but also for the thorn authors. Although any kind of independent documentation can be added to a thorn (ideally in the {\tt doc} directory), there are two @@ -3078,14 +3088,14 @@ The {\tt README}, in the top level of a thorn, should contain brief and essential details about the thorn, such as the authors, any copyright details, and a synopsis of what the thorn does. -\subsection{Contribution to ThornGuide} +\subsection{Contribution to Thorn Guide} -The latex file {\tt doc/documentation.tex} is included in Thorn Guides +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 -(and {\it up-to-date}) details about the thorn, exactly what is -relevent is for the authors to decide, but remember that the Cactus -make system automically parses the thorn {\tt CCL} files to include +(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 information about all parameters, variables and scheduling. Suggested sections include: @@ -3103,7 +3113,7 @@ sections include: \item{\bf history} Here is where you should describe why the thorn was written, any previous software or experience which was made use of, - the authors of the thorn sourcecode and documentation, how to get + the authors of the thorn source code and documentation, how to get hold of the thorn etc. \item{\bf references} A bibliography can be included, referencing papers @@ -3112,17 +3122,16 @@ sections include: \end{itemize} -A latex template for the Thorn Guide documentation can be found in the +A LaTeX template for the Thorn Guide documentation can be found in the Flesh distribution at {\tt doc/ThornGuide/template.tex}, -this file is -automatically copied to the correct location in a new thorn which is -created with {\tt gmake newthorn}. +this file is automatically copied to the correct location in a new thorn +which is created with {\tt gmake newthorn}. Since Cactus scripts need to parse this documentation, and since the -latex document should be consistent across all thorns included in a +LaTeX document should be consistent across all thorns included in a Thorn Guide, please follow the guidelines below when filling in the documentation: @@ -3152,12 +3161,12 @@ and \item The command {\tt $\backslash$def} can be used to define macros, but all such definitions must lie between the {\tt START} and {\tt END} - line. Do not redefine any standard latex command + line. Do not redefine any standard LaTeX command \item Do not use the {\t $\backslash$appendix} command, instead include any appendices you have as standard sections. - \item Currently we only support postscript ({\tt .eps or .ps}) figures. + \item Currently we only support PostScript ({\tt .eps or .ps}) figures. Graphics figures should be included using the {\tt includegraphics} command (not {\tt epsffig}), with no file extension specified. For example, @@ -3180,7 +3189,7 @@ and blackhole.eps, you should rename your image to be {\tt CactusWave\_WaveToyC\_blackhole.eps} - \item References should be formatted with the standard latex {\bf + \item References should be formatted with the standard LaTeX {\bf bibitem} command, for example, a bibliography section should look like: @@ -3188,7 +3197,7 @@ and \begin{verbatim} \begin{thebibliography}{9} \bibitem{MyArrangement_MyThorn_Author99} - {J. Author, {\em The Title of the Book, Journal, or periodical}, 1 (1999), + {J. Author, \textit{The Title of the Book, Journal, or periodical}, 1 (1999), 1--16. \url{http://www.nowhere.com/}} \end{thebibliography} \end{verbatim} @@ -3203,7 +3212,7 @@ and To add a test suite to your thorn, devise a series of parameter files which use as many aspects of your thorn as possible. -Make sure that the parameter files produce ascii output to files, +Make sure that the parameter files produce ASCII output to files, and that these files are in the directory {\tt ./<parameter file base name>}. @@ -3244,10 +3253,10 @@ You can add any number of timers to your thorn source code, providing each with a chosen name, for example {\tt TimeMyRoutine}, {\tt TimeNextCalculation}, and then use Cactus functions to switch on the timers, stop or reset them, and recover timing information. -Note that we use the word {\it Clock} to describe the timing instrument +Note that we use the word \textit{clock} to describe the timing instrument itself, for example the hardware counters on a machine, and the word -{\it Timer} to describe the calls in your code which collect results -from the different {\it Clocks}. +\textit{timer} to describe the calls in your code which collect results +from the different clocks. \subsection{Timing calls} @@ -3283,7 +3292,7 @@ Access the actual timing results, which are passed back as a structure, {\t cTimerData} described below, in {\t CCTK\_Timer}. Since the timing data is dynamic, before it can be assessed, the structure must be allocated with a call to {\t CCTK\_TimerCreateData}. A similar function -is provided to destroy the stucture +is provided to destroy the structure \item[{\t CCTK\_NumTimers}] @@ -3418,7 +3427,7 @@ ierr = CCTK_TimerDestroyData(info); Cactus provides a mechanism for thorns to add code to include files which can be used by any other thorn. Such include files can contain executable source code, or header/declaration -information. A difference is made between these two cases, since included +information. A distinction is made between these two cases, since included executable code is protected from being run if a thorn is compiled but not active by being wrapped by a call to {\tt CCTK\_IsThornActive}. @@ -3502,13 +3511,13 @@ available in C only. \label{sec:acmetr} Memory tracing has to be activated at configure time. The standard -malloc statements are overriden with macros ({\tt CCTK\_MALLOC}). To +{\tt malloc} statements are overridden with macros ({\tt CCTK\_MALLOC}). To activate memory tracing use either \begin{Lentry} \item[{\tt DEBUG=all}] Enables all debug options (compiler debug -flags, redefines malloc) -\item[{\tt DEBUG=memory}] Redefine malloc only. +flags, redefines {\tt malloc}) +\item[{\tt DEBUG=memory}] Redefine {\tt malloc} only. \end{Lentry} The {\tt CCTK\_MALLOC} statements can also be used directly in the C @@ -3536,7 +3545,7 @@ allocation some time later. Request a ticket: save the current total memory to a database. Return an integer (ticket). Use the ticket to calculate the difference in memory allocation between the two instances in - CCTK\_MemTicketCash. + {\tt CCTK\_MemTicketCash}. \item[{\tt long int CCTK\_MemTicketCash(int your\_ticket)}] Cash in your ticket: return the memory difference between now and the @@ -3548,7 +3557,7 @@ allocation some time later. allocated either if you compile undebugged. \item[{\tt int CCTK\_MemTicketDelete(int your\_ticket)}] - Delete the memory ticket. The ticket-id will not be reused, since + Delete the memory ticket. The ticket ID will not be reused, since it's incremented with every ticket request, but the memory of the memory datastructure is deallocated. @@ -3561,8 +3570,8 @@ allocation some time later. successive calls to this routine, as well as the difference. \end{Lentry} -Sample C Code demonstrating the ticket handling. Two tickets are -requested during malloc operations. The {\tt CCTK\_MALLOC} statement is +Sample C code demonstrating the ticket handling. Two tickets are +requested during {\tt malloc} operations. The {\tt CCTK\_MALLOC} statement is used directly. They are cashed in and the memory difference is printed. Ticket 1 is cashed twice. The tickets are deleted at the end. @@ -3601,7 +3610,7 @@ CCTK_MemTicketDelete(t2); \section[Calls to different language]{Calls between different programming languages} %\pagestyle{empty} -\subsection{Calling C routines from FORTRAN} +\subsection{Calling C routines from Fortran} \label{sec:cacrofr} To make the following C routine, @@ -3622,7 +3631,7 @@ void CCTK\_FCALL CCTK\_FNAME(<routine name>)(int *ierr, <argument list>)\\ } The convention used in Cactus is that {\tt <routine name>} be the same as any -C-callable routine name, and that this is mixed-case. The macros change +C routine name, and that this is mixed-case. The macros change the case and number of underscores of the routine name to match that expected by Fortran. @@ -3658,7 +3667,7 @@ translation to C strings. The macros are defined in {\tt cctk\_FortranString.h} which should be included in your C file. -String arguments {\em must always come last} in the argument list for +String arguments \emph{must always come last} in the argument list for these macros to be effective (some Fortran compilers automatically migrate the strings to the end so there is no portable workaround). @@ -3689,7 +3698,7 @@ In more detail: \item[{\tt <ONE|TWO|THREE>\_FORTSTRING\_PTR}] These macros, used in the declaration section of the C routine - {\em after} the {\tt CREATE} macro, + \emph{after} the {\tt CREATE} macro, should be used if you need to modify one of the passed-in strings. They declare and define pointers to the passed-in strings. @@ -3736,7 +3745,7 @@ from Fortran, they should be treated as read-only. To change the data in a string passed from Fortran, you need to use the {\tt FORTSTRING\_PTR} macros, which declare and set up pointers to the strings passed from C. Note that this macro must be used -{\em after} the {\tt FORTSTRING\_CREATE} macro. For example, the +\emph{after} the {\tt FORTSTRING\_CREATE} macro. For example, the following routine copies the contents of the second string to the first string. @@ -3770,13 +3779,13 @@ int CCTK_FCALL CCTK_FNAME(CopyStrings)(TWO_FORTSTRING_ARG) \end{verbatim} Note that in the example above two new variables, pointers to the -Fortran strings, were created. These are just pointers and {\em -should not be freed}. The example also illustrates the +Fortran strings, were created. These are just pointers and +\emph{should not be freed}. The example also illustrates the automatically-created variables (e.g.\ {\tt cctk\_strlen1} which hold the sizes of original Fortran strings. When writing to a string its length should never be exceeded. -\subsection{Calling FORTRAN routines from C} +\subsection{Calling Fortran routines from C} \label{sec:caforofr} To call a utility Fortran routine from C use @@ -3798,7 +3807,7 @@ strings from C. As well as calling functions in a different language, Cactus offers a mechanism for calling a function in a different thorn where you need not know which thorn is actually providing the function, nor what -language the function is provided in. The idea of {\it function +language the function is provided in. The idea of \textit{function aliasing} is similar to that of thorns; the routine that calls a function should not need to know anything about it except that the function exists. @@ -3949,10 +3958,12 @@ function reference section. \item{} Thorn names must not start with the word ``Cactus'' (in any case). -\item{} Arrangements will be ignored if their names start with \# or . - or end in \~{} .bak or .BAK. -\item{} Thorns will be ignored if they are called doc or start with - \# or . or end in \~{} .bak or .BAK. +\item{} Arrangements will be ignored if their names start with a + hash mark `{\tt \#}' or dot `{\tt .}' + or end in a tilde `{\tt \~{}}', {\tt .bak} or {\tt .BAK}. +\item{} Thorns will be ignored if they are called doc or start with a + hash mark `{\tt \#}' or dot `{\tt .}' + or end in a tilde `{\tt \~{}}', {\tt .bak} or {\tt .BAK}. \item{} Routine names have to be unique among all thorns. \end{itemize} @@ -3961,7 +3972,7 @@ function reference section. \section{General Naming Conventions} -The following naming conventions are followed by the flesh and the +The following naming conventions are followed by the Flesh and the supported Cactus arrangements. They are not compulsory, but if followed allow for a homogeneous code. @@ -4082,7 +4093,7 @@ For example, the variable {\tt cctkGH} is of this type. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\chapter{Telling the makesystem what to do} +\chapter{Telling the make system what to do} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% diff --git a/doc/UsersGuide/UtilityRoutines.tex b/doc/UsersGuide/UtilityRoutines.tex index b10d1405..660ebecb 100644 --- a/doc/UsersGuide/UtilityRoutines.tex +++ b/doc/UsersGuide/UtilityRoutines.tex @@ -31,17 +31,17 @@ general overview of programming with these utility routines. \section{Motivation} -Various Cactus functions need to pass information through a generic -interface. In the past we have used various ad-hoc means to do this, +Cactus functions may need to pass information through a generic +interface. In the past we have used various ad hoc means to do this, and we often had trouble passing "extra" information that wasn't anticipated in the original design. For example, for interpolation \verb|CCTK_InterpLocal()| and \verb|CCTK_InterpGV()| require that any parameters (such as the order of the interpolant) be encoded into the interpolator's character string name. Similarly, elliptic -solvers often need to pass various parameters, but we don't have a +solvers often need to pass various parameters, but we haven't had a good way to do this. -Key/value tables (``tables'' for short) provide a clean solution +Key/value tables (\textit{tables} for short) provide a clean solution to these problems. They're implemented by the \verb|Util_Table|* functions (described in detail in the Reference Manual). @@ -49,23 +49,23 @@ functions (described in detail in the Reference Manual). \section{The Basic Idea} -Basically, a table is an object which maps strings to almost-arbitrary +Basically, a table is an object which maps strings to almost arbitrary user-defined data. (If you know Perl, a table is very much like a Perl hash table.)%%% \footnote{%%% However, the present Cactus tables implementation is optimized for a relatively small number of distinct keys in any one table. It will still - work ok for huge numbers of keys, but it will be + work OK for huge numbers of keys, but it will be slow. }%%% -More formally, a table is an object which stores a set of ``keys'' -and a corresponding set of ``values''. We refer to a (key,value) -pair as a table ``entry''. +More formally, a table is an object which stores a set of \textit{keys} +and a corresponding set of \textit{values}. We refer to a (key,value) +pair as a table \textit{entry}. Keys are C-style null-terminated character strings, with the slash -character \verb|'/'| reserved for future expansion.%%% +character `{\tt /}' reserved for future expansion.%%% \footnote{%%% Think of hierarchical tables for storing tree-like data structures.%%% @@ -89,17 +89,17 @@ and/or \verb|Util_TableGetString()| functions. Finally, when you're through with a table you destroy it with \verb|Util_TableDestroy()|. There are also convenience functions \verb|Util_TableSetFromString()| -to set entries in a table based on a parameter-file--style string, +to set entries in a table based on a parameter-file-style string, and \verb|Util_TableCreateFromString()| to create a table and then -set entries in it based on a parameter-file--style string. +set entries in it based on a parameter-file-style string. As well, there are ``table iterator'' functions \verb|Util_TableIt*()| to allow manipulation of a table even if you don't know its keys. A table has an integer ``flags word'' which may be used to specify -various options, via bit flags defined in \verb|"util_Table.h"|. +various options, via bit flags defined in \verb|util_Table.h|. For example, the flags word can be used to control whether keys -should be compared as case-sensitive or case-insensitive strings. +should be compared as case sensitive or case insensitive strings. See the detailed function description of \verb|Util_TableCreate()| in the Reference Manual for a list of the possible bit flags and their semantics. @@ -135,18 +135,18 @@ Util_TableGetInt(handle, &two_value, "two"); /* sets two_value = 2 */ Util_TableGetReal(handle, &pi_value, "pi"); /* sets pi_value = 3.14 */ \end{verbatim} -Actually, you shouldn't write code like this -- in the real world +Actually, you shouldn't write code like this --- in the real world errors sometimes happen, and it's much better to catch them close to -their point of occurence rather than silently produce garbage results -or crash your program. So, the {\em right\/} thing to do is to always +their point of occurrence rather than silently produce garbage results +or crash your program. So, the \emph{right} thing to do is to always check for errors. To allow this, all the table routines return a status, which is zero or positive for a successful return, but negative if -and only if some sort of error has occured.%%% +and only if some sort of error has occurred.%%% \footnote{%%% Often (as in the examples here) you don't care - about the details of which error occured. But if + about the details of which error occurred. But if you do, there are various error codes defined in - {\t "util\_Table.h"} and {\t "util\_ErrorCodes.h"}; + {\t util\_Table.h} and {\t util\_ErrorCodes.h}; the detailed function descriptions in the Reference Manual say which error codes each function can return. @@ -187,7 +187,7 @@ if (Util_TableGetReal(handle, &pi_value, "pi") < 0) As well as a single numbers (or characters or pointers), tables can also store 1-dimensional arrays of numbers (or characters or pointers).%%% \footnote{%%% - The table makes (stores) a {\em copy\/} of the array + The table makes (stores) a \emph{copy} of the array you pass in, so you probably shouldn't use tables to store really big arrays like grid functions. But it's fine to store things like parameters and coefficients. @@ -213,15 +213,15 @@ if (count < 0) As you can see, a table entry remembers the length of any array value that has been stored in it.%%% \footnote{%%% - In fact, actually {\em all\/} table values are - arrays -- setting or getting a single value is + In fact, actually \emph{all} table values are + arrays --- setting or getting a single value is just the special case where the array length is 1. }%%% {} If you only want the first few values of a larger array, just pass in the appropriate length of your array, -that's ok: +that's OK: \begin{verbatim} CCTK_INT blah2[2]; int count = Util_TableGetIntArray(handle, 2, blah2, "my array"); @@ -244,8 +244,8 @@ if (count < 0) One very common thing you might want to store in a table is a character string. While you could do this by explicitly storing -an array of \verb|CCTK_CHAR|, there are also more-convenient routines -specially for setting and getting strings: +an array of \verb|CCTK_CHAR|, there are also routines +specially for conveniently setting and getting strings: \begin{verbatim} if (Util_TableSetString(handle, "black holes are fun", "bh") < 0) CCTK_WARN(-1, "couldn't set string value in table!"); @@ -259,7 +259,7 @@ if (Util_TableGetString(handle, 50, buffer, "bh") < 0) \end{verbatim} \verb|Util_TableGetString()| guarantees that the string is -terminated by a null character (\verb|'\0'|), and also returns an +terminated by a null character (`\verb|\0|'), and also returns an error if the string is too long for the buffer. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -287,11 +287,11 @@ if (Util_TableSetFromString(handle, "two=2 pi=3.14") != 2) There is also an even higher-level convenience function \verb|Util_TableCreateFromString()|: this creates a table with the -case-insensitive flag set (to match Cactus parameter-file semantics), -then (assuming no errors occured) calls \verb|Util_TableSetFromString()| +case insensitive flag set (to match Cactus parameter file semantics), +then (assuming no errors occurred) calls \verb|Util_TableSetFromString()| to set values in the table. -For example the following code sets up a table (with the case-insensitive flag +For example the following code sets up a table (with the case insensitive flag set) with four entries: an integer number ({\tt two}), a real number ({\tt pi}), a string ({\tt buffer}), and an integer array with three elements ({\tt array}): @@ -310,7 +310,7 @@ if (handle < 0) Note that this code passes a single string to \verb|Util_TableCreateFromString()|%%% \footnote{C automatically concatenates -adjacent character string constants separated only by whitespaces.} +adjacent character string constants separated only by whitespace.} {} which then gets parsed into key/value pairs, with the key separated from its corresponding value by an equals sign. @@ -373,7 +373,7 @@ using an iterator to print out all the entries in a table. \section{Multithreading and Multiprocessor Issues} -{\bf At the moment, the table functions are {\em not\/} thread-safe +{\bf At the moment, the table functions are \emph{not} thread-safe in a multithreaded environment!} However, this should change in the not-too-distant future: then all the table functions will default to being thread-safe. That is, user code will be able call these @@ -402,7 +402,7 @@ In a multiprocessor environment, tables are always processor-local. \section{Metadata about All Tables} -We have decided that tables do not {\em themselves\/} have names or other +We have decided that tables do not \emph{themselves} have names or other attributes. However, at some time in the future we may add some special ``system tables'' to be used by Cactus itself to store this sort of information for those cases where it's needed. @@ -410,11 +410,11 @@ information for those cases where it's needed. For example, at some time in the future we may add support for a ``checkpoint me'' bit in a table's flags word, so that if you want a table to be checkpointed, you just need to set this bit. -In this case the table will probably get a system-generated name in +In this case the table will probably get a system generated name in the checkpoint dump file. But if you want the table to have some other name in the dump file, then you need to tell the checkpointing code that by setting an appropriate entry in a checkpoint table. -(You would find the checkpoing table by looking in a special +(You would find the checkpoint table by looking in a special ``master system table'' that records handles of other interesting tables.) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |