diff options
| author | jthorn <jthorn@17b73243-c579-4c4c-a9d2-2d5706c11dac> | 2004-12-10 15:18:32 +0000 |
|---|---|---|
| committer | jthorn <jthorn@17b73243-c579-4c4c-a9d2-2d5706c11dac> | 2004-12-10 15:18:32 +0000 |
| commit | fc8ba03cd9a83acab096575552ea19b2c57d86a4 (patch) | |
| tree | 64d3c463526a6ee62a794d5826ac318391bf5c7d /doc/UsersGuide/ThornWriters.tex | |
| parent | cc3aef29e93e18456accae9f6a0e6bc069745cd2 (diff) | |
document new CCTK_WARN_* severity-level macros
git-svn-id: http://svn.cactuscode.org/flesh/trunk@3924 17b73243-c579-4c4c-a9d2-2d5706c11dac
Diffstat (limited to 'doc/UsersGuide/ThornWriters.tex')
| -rw-r--r-- | doc/UsersGuide/ThornWriters.tex | 1184 |
1 files changed, 611 insertions, 573 deletions
diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex index 2629694e..bd5f5ea0 100644 --- a/doc/UsersGuide/ThornWriters.tex +++ b/doc/UsersGuide/ThornWriters.tex @@ -72,7 +72,7 @@ and all your evolution thorns in another arrangement, or you may want to have separate arrangements for your developments, private and shared thorns. -The arrangements live in the {\tt arrangements} directory off the main +The arrangements live in the \texttt{arrangements} directory off the main Cactus directory. Arrangement names must be (case independently) unique, must start with a letter, and can only contain @@ -97,11 +97,11 @@ without affecting any other thorn. 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 {\tt driver}. This +\texttt{CactusPUGH/PUGH} provides the implementation \texttt{driver}. This implementation is responsible for providing memory for grid variables and -for communication. Another thorn can also implement {\tt driver}, +for communication. Another thorn can also implement \texttt{driver}, 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. +At runtime, the user can decide which thorn providing \texttt{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 @@ -125,26 +125,26 @@ 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[\texttt{interface.ccl}] the Cactus interface, which defines the grid functions, variables, etc. See \ref{sec:Appendix.interface}. -\item[{\tt param.ccl}] the parameters introduced by this thorn, and the +\item[\texttt{param.ccl}] the parameters introduced by this thorn, and the parameters needed from other thorns. See \ref{sec:Appendix.param}. -\item[{\tt schedule.ccl}] scheduling information for routines called by +\item[\texttt{schedule.ccl}] scheduling information for routines called by the Flesh. See \ref{sec:Appendix.schedule}. -\item[{\tt configuration.ccl}] configuration options for the thorn. See +\item[\texttt{configuration.ccl}] configuration options for the thorn. See \ref{sec:Appendix.configuration.ccl}. \end{Lentry} Thorns can also contain \begin{itemize} -\item a subdirectory called {\tt src}, which should hold source files +\item a subdirectory called \texttt{src}, which should hold source files and compilation instructions for the thorn -\item a subdirectory {\tt src/include} for include files -\item a {\tt README} containing a brief description of the thorn -\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 +\item a subdirectory \texttt{src/include} for include files +\item a \texttt{README} containing a brief description of the thorn +\item a \texttt{doc} directory for documentation +\item a \texttt{par} directory for example parameter files +\item a \texttt{test} subdirectory may also be added, to hold the thorn's test suite. See \ref{sec:adding_test_suite} for details. \end{itemize} @@ -153,7 +153,7 @@ Thorns can also contain \section{Creating a thorn} -To simplify the creation of a thorn, a {\tt make} target {\tt +To simplify the creation of a thorn, a \texttt{make} target {\tt gmake newthorn} has been provided. When this is run: \begin{enumerate} @@ -174,20 +174,20 @@ These are: \begin{Lentry} -\item [{\tt interface.ccl}] +\item [\texttt{interface.ccl}] This defines the \textit{implementation} (Section~\ref{sec:implementations}) the thorn provides, and the variables the thorn needs, along with their visibility to other implementations. -\item [{\tt param.ccl}] +\item [\texttt{param.ccl}] This defines the parameters that are used to control the thorn, along with their visibility to other implementations. -\item [{\tt schedule.ccl}] +\item [\texttt{schedule.ccl}] 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}] +\item [\texttt{configuration.ccl}] This file is optional for a thorn. If it exists it contains extra configuration options of this thorn. @@ -197,16 +197,16 @@ configuration options of this thorn. \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 hash `{\tt \#}' +case independent, and may contain comments introduced by the hash `\texttt{\#}' 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 +`\texttt{$\backslash$}', the following line is treated as a continuation of the current line. -\subsection{The {\tt interface.ccl} file} +\subsection{The \texttt{interface.ccl} file} \label{subsec:interface_ccl} -The {\tt interface.ccl} file is used to declare +The \texttt{interface.ccl} file is used to declare \begin{itemize} \item the implementation provided by the thorn, @@ -220,18 +220,18 @@ The implementation is declared by a single line at the top of the file \begin{alltt} implements: <\var{name}> \end{alltt} -Where {\tt <\var{name}>} can be any combination of alphanumeric +Where \texttt{<\var{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} -\item[{\tt Public}] +\item[\texttt{Public}] Can be `inherited' by other implementations (see below). -\item[{\tt Protected}] +\item[\texttt{Protected}] Can be shared with other implementations which declare themselves to be friends of this one (see below). -\item[{\tt Private}] +\item[\texttt{Private}] Can only be seen by this thorn. \end{Lentry} @@ -239,27 +239,27 @@ Corresponding to the first two access levels there are two relationship statements that can be used to get variables from other thorns. \begin{Lentry} -\item [{\tt Inherits: <\var{name}>}] -This gets all {\tt Public} variables from implementation {\tt <\var{name}>}, and all -variables that {\tt <\var{name}>} has in turn inherited. +\item [\texttt{Inherits: <\var{name}>}] +This gets all \texttt{Public} variables from implementation \texttt{<\var{name}>}, and all +variables that \texttt{<\var{name}>} has in turn inherited. An implementation may inherit from any number of other implementations. -\item [{\tt Friend: <\var{name}>}] -This gets all {\tt Protected} variables from implementation {\tt <\var{name}>}, but, -unlike {\tt inherits}, it is symmetric and also defines a transitive relation by -pushing its own implementation's {\tt Protected} variables onto implementation +\item [\texttt{Friend: <\var{name}>}] +This gets all \texttt{Protected} variables from implementation \texttt{<\var{name}>}, but, +unlike \texttt{inherits}, it is symmetric and also defines a transitive relation by +pushing its own implementation's \texttt{Protected} variables onto implementation \var{name}. This keyword is used to define a group of implementations which -all end up with the same {\tt Protected} variables. +all end up with the same \texttt{Protected} variables. \end{Lentry} -So, for example, an {\tt interface.ccl} starting +So, for example, an \texttt{interface.ccl} starting \begin{alltt} implements: wavetoy inherits: grid friend: wave_extract \end{alltt} -declares that the thorn provides an implementation called {\tt wavetoy}, gets -all the {\tt public} variables declared by an implementation called {\tt grid}, -and shares all {\tt protected} variables with {\tt wave\_extract} and its +declares that the thorn provides an implementation called \texttt{wavetoy}, gets +all the \texttt{public} variables declared by an implementation called \texttt{grid}, +and shares all \texttt{protected} variables with \texttt{wave\_extract} and its friends. Cactus variables, described in Chapter~\ref{chap:cactus_variables}, are placed @@ -268,16 +268,16 @@ the attributes describe properties such as the data type, group type, dimension, ghostsize, number of timelevels, type of staggering and distribution. -For example, a group, called {\tt realfields} of 5 real grid -functions ({\tt phi}, {\tt a}, -{\tt b}, {\tt c}, {\tt d}), on a 3D grid, would be defined by +For example, a group, called \texttt{realfields} of 5 real grid +functions (\texttt{phi}, \texttt{a}, +\texttt{b}, \texttt{c}, \texttt{d}), on a 3D grid, would be defined by \begin{verbatim} CCTK_REAL realfields type=GF TimeLevels=3 Dim=3 { phi a,b,c,d } "Example grid functions"\end{verbatim} -or, for a group called {\tt intfields} consisting of just one +or, for a group called \texttt{intfields} consisting of just one distributed 2D array of integers, \begin{verbatim} CCTK_INT intfields type=ARRAY size=xsize,ysize ghostsize=gxsize,gysize dim=2 @@ -285,22 +285,22 @@ CCTK_INT intfields type=ARRAY size=xsize,ysize ghostsize=gxsize,gysize dim=2 anarray } "My 2D arrays" \end{verbatim} -where {\tt xsize}, {\tt ysize}, {\tt gxsize}, {\tt gysize} are all -parameters defined in the thorn's {\tt param.ccl}. +where \texttt{xsize}, \texttt{ysize}, \texttt{gxsize}, \texttt{gysize} are all +parameters defined in the thorn's \texttt{param.ccl}. -By default all groups are {\tt private}, to change this an access -specification of the form {\tt public:} or {\tt protected:} (or -{\tt private:} to change it back) may be placed on a line by itself. This +By default all groups are \texttt{private}, to change this an access +specification of the form \texttt{public:} or \texttt{protected:} (or +\texttt{private:} to change it back) may be placed on a line by itself. This changes the access level for any group defined in the file from that point on. All variables seen by any one thorn must have distinct names. -\subsection{The {\tt param.ccl} file} +\subsection{The \texttt{param.ccl} file} \label{subsec:param_ccl} Users control the operation of thorns via parameters given in a file -at runtime. The {\tt param.ccl} file +at runtime. The \texttt{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 @@ -310,11 +310,11 @@ file, it is given its default value. There are three access levels available for parameters: \begin{Lentry} -\item [{\tt Global}] +\item [\texttt{Global}] These parameters are seen by all thorns. -\item [{\tt Restricted}] +\item [\texttt{Restricted}] These parameters may be used by other implementations if they so desire. -\item [{\tt Private}] +\item [\texttt{Private}] These are only seen by this thorn. \end {Lentry} @@ -323,13 +323,13 @@ A parameter specification consists of: \item the parameter type (each may have an optional {\t CCTK\_} in front) \begin{Lentry} -\item [{\tt REAL}] -\item [{\tt INT}] -\item [{\tt KEYWORD}] +\item [\texttt{REAL}] +\item [\texttt{INT}] +\item [\texttt{KEYWORD}] A distinct string with only a few known allowed values. -\item [{\tt STRING}] +\item [\texttt{STRING}] An arbitrary string, which must conform to a given regular expression. -\item [{\tt BOOLEAN}] +\item [\texttt{BOOLEAN}] 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} @@ -358,7 +358,7 @@ This must be one of the allowed values. \end{itemize} -For the numeric types {\tt INT} and {\tt REAL}, a range consists +For the numeric types \texttt{INT} and \texttt{REAL}, a range consists of a string of the form lower-bound:upper-bound:step, where a missing number or an asterisk `{\t *}' denotes anything (i.e.\ infinite bounds or an infinitesimal step). @@ -390,30 +390,30 @@ REAL Length[2] "Length in each direction" } 1.0 \end{verbatim} -defines a {\tt REAL} parameter, a {\tt BOOLEAN} parameter, a {\tt KEYWORD} -and an array of {\tt REAL} parameters. +defines a \texttt{REAL} parameter, a \texttt{BOOLEAN} parameter, a \texttt{KEYWORD} +and an array of \texttt{REAL} parameters. -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 +By default all parameters are \texttt{private}; to change this, an access +specification of the form \texttt{global:} or \texttt{restricted:} (or +\texttt{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. -To access {\tt restricted} parameters from another implementation, a line -containing {\tt shares: <\var{name}>} declares that all parameters mentioned in +To access \texttt{restricted} parameters from another implementation, a line +containing \texttt{shares: <\var{name}>} declares that all parameters mentioned in the file from now until the next access specification originate in -implementation {\tt <\var{name}>}. (Note that only one implementation can be -specified on each {\tt shares:} line.) Each of these parameters must be qualified by the initial token {\tt USES} or {\tt EXTENDS}, where +implementation \texttt{<\var{name}>}. (Note that only one implementation can be +specified on each \texttt{shares:} line.) Each of these parameters must be qualified by the initial token \texttt{USES} or \texttt{EXTENDS}, where \begin{Lentry} -\item[{\tt USES}] indicates that the parameters range remains unchanged. -\item[{\tt EXTENDS}] indicates that the parameters range is going to be extended. +\item[\texttt{USES}] indicates that the parameters range remains unchanged. +\item[\texttt{EXTENDS}] indicates that the parameters range is going to be extended. \end{Lentry} In contrast to parameter declarations in other access blocks, the default 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 {\tt REAL} parameter {\tt speed}. +\texttt{initial\_data} originally defined in the implementation \texttt{einstein}, +and uses the \texttt{REAL} parameter \texttt{speed}. \begin{verbatim} shares:einstein @@ -429,15 +429,15 @@ USES CCTK_REAL speed \end{verbatim} -Note that you must compile at least one thorn which implements {\tt einstein}. +Note that you must compile at least one thorn which implements \texttt{einstein}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{The {\tt schedule.ccl} file} +\subsection{The \texttt{schedule.ccl} file} \label{subsec:schedule_ccl} -By default no routine of a thorn will be run. The {\tt schedule.ccl} +By default no routine of a thorn will be run. The \texttt{schedule.ccl} file defines those that should be run and when and under which conditions they should be run. @@ -453,108 +453,108 @@ schedule <\var{name}> at <\var{time bin}> [\var{other options}] SYNC: [\var{group list}] \} "\var{A description}" \end{alltt} -where {\tt <\var{name}>} is the name of the routine, and -{\tt <\var{time bin}>} is the name of a schedule bins (the {\tt CCTK\_} +where \texttt{<\var{name}>} is the name of the routine, and +\texttt{<\var{time bin}>} is the name of a schedule bins (the \texttt{CCTK\_} prefix is optional). A list of the most useful schedule bins for application thorns is given here, a complete and more descriptive list is provided in Appendix~\ref{sec:Appendix.schedule_bins}: \begin{Lentry} -\item [{\tt CCTK\_STARTUP}] +\item [\texttt{CCTK\_STARTUP}] For routines run before the grid hierarchy is set up, for example function registration. -\item [{\tt CCTK\_PARAMCHECK}] +\item [\texttt{CCTK\_PARAMCHECK}] For routines which check parameter combinations, routines registered here only have access to the grid size and the parameters. -\item [{\tt CCTK\_BASEGRID}] +\item [\texttt{CCTK\_BASEGRID}] Responsible for setting up coordinates etc. -\item [{\tt CCTK\_INITIAL}] +\item [\texttt{CCTK\_INITIAL}] For generating initial data. -\item [{\tt CCTK\_POSTINITIAL}] +\item [\texttt{CCTK\_POSTINITIAL}] Tasks which must be applied after initial data is created. -\item [{\tt CCTK\_PRESTEP}] +\item [\texttt{CCTK\_PRESTEP}] Stuff done before the evolution step. -\item [{\tt CCTK\_EVOL}] +\item [\texttt{CCTK\_EVOL}] The evolution step. -\item [{\tt CCTK\_POSTSTEP}] +\item [\texttt{CCTK\_POSTSTEP}] Stuff done after the evolution step. -\item [{\tt CCTK\_ANALYSIS}] +\item [\texttt{CCTK\_ANALYSIS}] For analysing data. \end{Lentry} The \var{other options} allow finer grained control of the scheduling. It is -possible to state that the routine must run {\tt BEFORE} or {\tt AFTER} +possible to state that the routine must run \texttt{BEFORE} or \texttt{AFTER} another routine. It is also possible to schedule the routine under an -alias name by using {\tt AS <\var{alias\_name}>}. +alias name by using \texttt{AS <\var{alias\_name}>}. \begin{Lentry} -\item[{\tt LANG}] -The {\tt LANG} keyword specifies the linkage of the scheduled routine +\item[\texttt{LANG}] +The \texttt{LANG} keyword specifies the linkage of the scheduled routine which determines how to call it from the scheduler. C and Fortran linkage are possible here. C++ routines should be defined as -{\tt extern "C"} and registered as {\tt LANG: C}. +\texttt{extern "C"} and registered as \texttt{LANG: C}. -\item[{\tt STORAGE}] The {\tt STORAGE} keyword specifies any groups for +\item[\texttt{STORAGE}] The \texttt{STORAGE} keyword specifies any groups for which memory should be allocated for the duration of the routine. The storage status reverts to its previous status after the routine -returns. The format of the {\tt STORAGE} statement includes specifying +returns. The format of the \texttt{STORAGE} statement includes specifying the number of timelevels of each group for which storage should be activated. -{\tt STORAGE: <\var{group1}>[\var{timelevels1}], +\texttt{STORAGE: <\var{group1}>[\var{timelevels1}], <\var{group2}>[\var{timelevels2}]} - This number can range from one to the maximum number of timelevels for the group as specified in the group definition in its {\tt interface.ccl} file. If this maximum number is one, the timelevel specification can be omitted from the -{\tt STORAGE} statement. + This number can range from one to the maximum number of timelevels for the group as specified in the group definition in its \texttt{interface.ccl} file. If this maximum number is one, the timelevel specification can be omitted from the +\texttt{STORAGE} statement. -\item[{\tt TRIGGERS}] {\tt TRIGGERS} is used when the routine is -registered at {\tt ANALYSIS}. This is a special time bin; a routine +\item[\texttt{TRIGGERS}] \texttt{TRIGGERS} is used when the routine is +registered at \texttt{ANALYSIS}. This is a special time bin; a routine registered here will only be called if one of the variables from a -group in {\tt TRIGGERS} is due for output. (A routine without {\tt +group in \texttt{TRIGGERS} is due for output. (A routine without {\tt TRIGGERS} declaration will always be called.) -\item[{\tt SYNC}] -The keyword {\tt SYNC} specifies groups of variables which should be +\item[\texttt{SYNC}] +The keyword \texttt{SYNC} specifies groups of variables which should be synchronised (that is, their ghostzones should be exchanged between 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()} (see the Reference Manual) from inside a -routine. Using the {\tt SYNC} -keyword in the {\tt schedule.ccl} is the preferred method, since it +grid variables in \texttt{schedule.ccl} is an alternative to calling the +function \texttt{CCTK\_SyncGroup()} (see the Reference Manual) from inside a +routine. Using the \texttt{SYNC} +keyword in the \texttt{schedule.ccl} is the preferred method, since it provides the Flesh with more information about the behaviour of your code, and in particular is a requirement for using a driver with adaptive mesh refinement. \end{Lentry} -Besides schedule blocks it's possible to embed C style {\tt if/else} -statements in the {\tt schedule.ccl} file. These can be used to +Besides schedule blocks it's possible to embed C style \texttt{if/else} +statements in the \texttt{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 \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 +If the parameter \texttt{evolve\_hydro} is positively set, the Fortran +routine \texttt{hydro\_predictor} is scheduled to run in the \textit{evolution} +loop, after the routine \texttt{metric\_predictor} and before +\texttt{metric\_corrector}. The routine names \texttt{metric\_predictor} and +\texttt{metric\_corrector} may either be real routine names from the same +or a different thorn, or they may be \texttt{aliased} routine names (see the next example). -Before entry to {\tt hydro\_predictor} +Before entry to \texttt{hydro\_predictor} storage will be allocated for one timelevel for the group of grid -variables {\tt hydro\_variables}, on exit from the routine this storage +variables \texttt{hydro\_variables}, on exit from the routine this storage will be deallocated and the contents of the variables will be lost. \begin{verbatim} if(CCTK_Equals(evolve_hydro,"yes")) @@ -567,21 +567,21 @@ if(CCTK_Equals(evolve_hydro,"yes")) } \end{verbatim} -If the parameter {\tt evolve\_hydro} is set negatively, the {\tt +If the parameter \texttt{evolve\_hydro} is set negatively, the {\tt hydro\_predictor} routine will not be called by the scheduler. Note -that if the {\tt evolve\_hydro} parameter is {\tt STEERABLE} it can be +that if the \texttt{evolve\_hydro} parameter is \texttt{STEERABLE} it can be dynamically scheduled and de-scheduled during a run if a steering interface is available. \vskip .5cm {\bf Example II:} -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 +The thorns \texttt{WaveToy77} and \texttt{WaveToyC} each provide a +routine to evolve the 3D wave equation: \texttt{WaveToyF77\_Evolution} and +\texttt{WaveToyC\_Evolution}. The routine names have to be different, so 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}. +time in the parameter file via \texttt{ActiveThorns}. Since each evolution routine provides the same functionality, it makes sense to schedule them under the common alias {\tt @@ -589,7 +589,7 @@ WaveToy\_Evolution} to allow relative scheduling ({\tt BEFORE/AFTER}) independent of the actual routine name (which may change depending on the activation in the parameter file). -In both cases the group of variables {\tt scalarfield} are synchronised +In both cases the group of variables \texttt{scalarfield} are synchronised across processes when the routine is exited. \begin{verbatim} schedule WaveToyF77_Evolution AS WaveToy_Evolution AT evol @@ -606,8 +606,8 @@ schedule WaveToyC_Evolution AS WaveToy_Evolution AT evol SYNC: scalarfield } "Evolution of 3D wave equation" \end{verbatim} -The thorn {\tt IDScalarWave} schedules the routine {\tt WaveBinary} -after the alias {\tt WaveToy\_Evolution}. It is scheduled independently of +The thorn \texttt{IDScalarWave} schedules the routine \texttt{WaveBinary} +after the alias \texttt{WaveToy\_Evolution}. It is scheduled independently of the C or Fortran routine name. \begin{verbatim} schedule WaveBinary AT evol AFTER WaveToy_Evolution @@ -618,26 +618,26 @@ schedule WaveBinary AT evol AFTER WaveToy_Evolution \end{verbatim} \subsubsection{Storage Outside of Schedule Blocks} -The keyword {\tt STORAGE} can also be used outside of the schedule +The keyword \texttt{STORAGE} can also be used outside of the schedule blocks to indicate that storage for these groups should be switched on at the start of the run. Note that the storage is only allocated in this way at the start, a thorn could explicitly switch the storage off -(although this is not recommended practise). As for the {\tt STORAGE} +(although this is not recommended practise). As for the \texttt{STORAGE} statement in schedule blocks, each group must also specify how many timelevels to activate storage for. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{The {\tt configuration.ccl}} +\subsection{The \texttt{configuration.ccl}} \label{subsec:configuration_ccl} -[{\bf NOTE:} the {\tt configuration.ccl} is a new feature, and not all the +[{\bf NOTE:} the \texttt{configuration.ccl} is a new feature, and not all the features described in this section have been fully implemented yet. PROVIDES and REQUIRES should work, but script support and OPTIONAL are still being developed.] -The {\tt configuration.ccl} file is optional. It can be used for two +The \texttt{configuration.ccl} file is optional. It can be used for two purposes: to detect certain features of the host system, such as the presence or absence of libraries, variable types, etc, or the location of libraries; or to provide access to certain functions too @@ -750,8 +750,8 @@ The following restrictions apply to file names: \begin{itemize} \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 allright, but {\tt MyFile.c} and {\tt MYFILE.c} could cause problems). + system being case sensitive (e.g.\ having \texttt{MyFile.c} and + \texttt{MYFILE.f77} is allright, but \texttt{MyFile.c} and \texttt{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. @@ -761,20 +761,20 @@ to relax this in future. Different thorns can have files with the same names. \section{Adding source files} -By default the CCTK looks in the {\tt src} directory of the thorn for source +By default the CCTK looks in the \texttt{src} directory of the thorn for source files. There are two ways in which to specify the sources. The easiest is to use the -{\tt make.code.defn} based method in which the CCTK does all the work, but you -may instead put a {\tt Makefile} in the {\tt src} directory and do everything +\texttt{make.code.defn} based method in which the CCTK does all the work, but you +may instead put a \texttt{Makefile} in the \texttt{src} directory and do everything yourself. -\subsection{{\tt make.code.defn} based thorn building} +\subsection{\texttt{make.code.defn} based thorn building} \label{sec:mabathbu} This is the standard way to compile your thorn's source files. -The Cactus make system looks for a file called {\tt make.code.defn} in that -directory (if there is no file called {\tt Makefile} in the {\tt src} directory). At its simplest, this file contains two lines +The Cactus make system looks for a file called \texttt{make.code.defn} in that +directory (if there is no file called \texttt{Makefile} in the \texttt{src} directory). At its simplest, this file contains two lines \begin{itemize} \item {\t SRCS = <list of all source files in this directory>} @@ -783,55 +783,55 @@ directory (if there is no file called {\tt Makefile} in the {\tt src} directory) \end{itemize} -Each subdirectory listed should then have a {\tt make.code.defn} file -containing just a {\tt SRCS = } line, a {\tt SUBDIRS = } line will +Each subdirectory listed should then have a \texttt{make.code.defn} file +containing just a \texttt{SRCS = } line, a \texttt{SUBDIRS = } line will be ignored. -In addition, each directory can have a {\tt make.code.deps} file, which, +In addition, each directory can have a \texttt{make.code.deps} file, which, for files in that directory, can contain additional make rules and dependencies for files in that directory. See the GNU Make documentation for complete details of the syntax. -\subsection{{\tt Makefile} based thorn building} +\subsection{\texttt{Makefile} based thorn building} This method gives you the ultimate responsibility. The only requirement is that -a library called {\tt \$NAME} be created by the {\tt Makefile}. +a library called \texttt{\$NAME} be created by the \texttt{Makefile}. The makefile is passed the following variables \begin{Lentry} -\item [{\tt \$(CCTK\_HOME)}] the main Cactus directory +\item [\texttt{\$(CCTK\_HOME)}] the main Cactus directory -\item [{\tt \$(TOP)}] the configuration directory +\item [\texttt{\$(TOP)}] the configuration directory -\item [{\tt \$(SRCDIR)}] the directory in which the source files can be found +\item [\texttt{\$(SRCDIR)}] the directory in which the source files can be found -\item [{\tt \$(CONFIG)}] the directory containing the configuration files +\item [\texttt{\$(CONFIG)}] the directory containing the configuration files -\item [{\tt \$(THORN)}] the thorn name +\item [\texttt{\$(THORN)}] the thorn name -\item [{\tt \$(SCRATCH\_BUILD)}] the scratch directory where Fortran 90 module +\item [\texttt{\$(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 +\item [\texttt{\$(NAME)}] the name of the library to be built \end{Lentry} -and has a working directory of {\tt <config>/build/<thorn\_name>} . +and has a working directory of \texttt{<config>/build/<thorn\_name>} . \subsection{Other makefile variables} \begin{itemize} -\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} +\item \texttt{CC} +\item \texttt{CXX} +\item \texttt{F90} +\item \texttt{F77} +\item \texttt{CFLAGS} +\item \texttt{CXXFLAGS} +\item \texttt{F90FLAGS} +\item \texttt{F77FLAGS} +\item \texttt{LD} \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -894,19 +894,19 @@ bytes occupied by the a variable of the type). \begin{Lentry} \item[INTEGER] -{\tt CCTK\_INT}, {\tt CCTK\_INT1}, {\tt CCTK\_INT2}, {\tt CCTK\_INT4}, {\tt CCTK\_INT8}. -({\tt CCTK\_INT} defaults to being {\tt CCTK\_INT4}). +\texttt{CCTK\_INT}, \texttt{CCTK\_INT1}, \texttt{CCTK\_INT2}, \texttt{CCTK\_INT4}, \texttt{CCTK\_INT8}. +(\texttt{CCTK\_INT} defaults to being \texttt{CCTK\_INT4}). \item[REAL] -{\tt CCTK\_REAL}, {\tt CCTK\_REAL4}, {\tt CCTK\_REAL8}, {\tt CCTK\_REAL16}. ({\tt CCTK\_REAL} defaults to being {\tt CCTK\_REAL8}). +\texttt{CCTK\_REAL}, \texttt{CCTK\_REAL4}, \texttt{CCTK\_REAL8}, \texttt{CCTK\_REAL16}. (\texttt{CCTK\_REAL} defaults to being \texttt{CCTK\_REAL8}). \item[COMPLEX] -{\tt CCTK\_COMPLEX}, {\tt CCTK\_COMPLEX8}, {\tt CCTK\_COMPLEX16}, {\tt CCTK\_COMPLEX32}. -({\tt CCTK\_COMPLEX} defaults to being {\tt CCTK\_COMPLEX16}). +\texttt{CCTK\_COMPLEX}, \texttt{CCTK\_COMPLEX8}, \texttt{CCTK\_COMPLEX16}, \texttt{CCTK\_COMPLEX32}. +(\texttt{CCTK\_COMPLEX} defaults to being \texttt{CCTK\_COMPLEX16}). \item[BYTE] This is a 1 byte data type. \end{Lentry} Normally a thorn should use the default types --- -{\tt CCTK\_INT}, {\tt CCTK\_REAL}, {\tt CCTK\_COMPLEX} --- rather than explicitly setting the size, as this gives maximum +\texttt{CCTK\_INT}, \texttt{CCTK\_REAL}, \texttt{CCTK\_COMPLEX} --- rather than explicitly setting the size, as this gives maximum portability. Also, the defaults can be changed at configuration time (see \ref{subsec:Compilation-Available_Options}), and this allows people to compile the code with different precisions to test for roundoff effects, or to run more @@ -923,17 +923,17 @@ types. \begin{Lentry} -\item[{\tt SCALAR}] +\item[\texttt{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[{\tt GF}] +\item[\texttt{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 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[{\tt ARRAY}] +\item[\texttt{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. @@ -968,9 +968,9 @@ to the $t$ variable. To remove this extraneous copy, Cactus allows you to specify the number of timelevels used by your numerical scheme. It then generates variables -with the base name (e.g.\ {\tt phi}) suffixed by a qualifier for +with the base name (e.g.\ \texttt{phi}) suffixed by a qualifier for which timelevel is being referred to --- no suffix for the -next timelevel, and {\tt \_p} for each previous timelevel. +next timelevel, and \texttt{\_p} for each previous timelevel. The timelevels are rotated (by the driver thorn) at the start of each evolution step, that is: @@ -990,9 +990,9 @@ loop: \end{verbatim} 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 its values should +\texttt{phi\_p} now holds the values of the former \texttt{phi}, +and \texttt{phi\_p\_p} the values of the former \texttt{phi\_p}, etc. +Note that after rotation \texttt{phi} is undefined, and its values should not be used until they have been updated. All timelevels, except the current level, should be considered \emph{read-only} during evolution, that is their values should not be changed by thorns. @@ -1005,8 +1005,8 @@ values at the previous timelevels do need to be explicitly filled out. 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 +(\texttt{DISTRIB=DEFAULT}), +or, if \texttt{DISTRIB=CONSTANT} the specified size on \emph{each} processor. If the size is split across processors, the driver thorn is responsible for assigning the size on each processor. @@ -1092,17 +1092,17 @@ used. {\bf Specifying the staggertype} The type of staggering applied to a grid function can be specified in -the {\tt interface.ccl} file by the attribute {\tt stagger} (see +the \texttt{interface.ccl} file by the attribute \texttt{stagger} (see \ref{sec:Appendix.interface}). Cactus supports three kinds of staggering per dimension. The physical location of a grid function is shifted relative to the default position by adding the following values to the stagger attribute: \begin{Lentry} -\item[{\tt M}] no staggering, default. Refers to the ``minus'' face +\item[\texttt{M}] no staggering, default. Refers to the ``minus'' face relative to the default gridpoint. -\item[{\tt C}] centre staggering. The physical location is offset by +\item[\texttt{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. {\tt P} refers to plus. The physical location +\item[\texttt{P}] full staggered. \texttt{P} refers to plus. The physical location is offset by a full grid spacing in the positive direction (or the right). \end{Lentry} For multi dimensional grid functions you concatenate the code @@ -1110,10 +1110,10 @@ 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 -staggering each direction ({\tt stagger=CC}) is shown in (C). The full -staggering in (D) ({\tt stagger=PP}) obeys the same rules, but is +function of type \texttt{stagger=MC}: no staggering in $x$ direction, +center staggered in $y$ direction. In (B) we have \texttt{stagger=CM} and +staggering each direction (\texttt{stagger=CC}) is shown in (C). The full +staggering in (D) (\texttt{stagger=PP}) obeys the same rules, but is rather unusual; it is included here for completeness. \begin{figure}[ht] @@ -1122,7 +1122,7 @@ rather unusual; it is included here for completeness. \includegraphics[angle=0,width=8cm]{staggering1} \end{center} \caption[]{\small {\bf Staggered gridpoints in 2D} for several -staggerings. (a) : {\tt MC}, (b): {\tt CM}, (c): {\tt CC}, (d): {\tt +staggerings. (a) : \texttt{MC}, (b): \texttt{CM}, (c): \texttt{CC}, (d): {\tt PP}. Note that the staggering of grid functions does not change its index. The staggered gridpoints and the corresponding unstaggered points (arrows) are accessed by the same indices.} @@ -1141,34 +1141,34 @@ location, number of ghostzones) is passed through the argument list of scheduled routines (see~\ref{sec:cactus_variables_c}). To obtain similar information from non-scheduled routines, or for general grid variables, a set of functions are provided, the last two letters of which specify whether -the information is requested using a group name ({\tt GN}) or index -({\tt GI}), or a variable name ({\tt VN}) or index ({\tt VI}). +the information is requested using a group name (\texttt{GN}) or index +(\texttt{GI}), or a variable name (\texttt{VN}) or index (\texttt{VI}). \begin{itemize} -\item {\tt CCTK\_Grouplsh[GN|GI|VN|VI]} An array of integers +\item \texttt{CCTK\_Grouplsh[GN|GI|VN|VI]} An array of integers with the local grid size on this processor. -\item {\tt CCTK\_Groupgsh[GN|GI|VN|VI]} An array of integers +\item \texttt{CCTK\_Groupgsh[GN|GI|VN|VI]} An array of integers with the global grid size. -\item {\tt CCTK\_Groupbbox[GN|GI|VN|VI]} An array of integers +\item \texttt{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 {\tt 1} indicates + A value of \texttt{1} indicates a physical (outer) boundary at the edge of the computational grid, - and {\tt 0} indicates an internal boundary. + and \texttt{0} indicates an internal boundary. -\item {\tt CCTK\_Groupnghostzones[GN|GI|VN|VI]} An array of integers with +\item \texttt{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 +\item \texttt{CCTK\_Grouplbnd[GN|GI|VN|VI]} An array of integers containing the lowest index (in each direction) of the local grid, as seen on the global grid. Note that these indices start from zero, so you need to add one when using them in Fortran thorns. -\item {\tt CCTK\_Groupubnd[GN|GI|VN|VI]} An array of integers +\item \texttt{CCTK\_Groupubnd[GN|GI|VN|VI]} An array of integers containing the largest index (in each direction) of the local grid, as seen on the global grid. Note that these indices start from zero, so you need to add one when using them in @@ -1185,7 +1185,7 @@ the information is requested using a group name ({\tt GN}) or index Parameters are the means by which the user specifies the runtime behaviour of the code. Each parameter has a data type and a name, as well as a range of allowed values and a default value. These are declared in the thorn's -{\tt param.ccl} file. +\texttt{param.ccl} file. The thorn determines which parameters can be used in other thorns by specifying a \textit{scope} for the thorn, as explained in @@ -1198,7 +1198,7 @@ Otherwise, the initial value of the parameter is taken to be its default. Once validated, parameter values are fixed, and cannot be changed, unless the parameter is specified to be \textit{steerable} (see \ref{sec:Cactus_parameters.steerable}). -For a detailed discussion of the {\tt param.ccl} syntax see +For a detailed discussion of the \texttt{param.ccl} syntax see Appendix~\ref{sec:Appendix.param}. The full specification for a parameter declaration is @@ -1210,7 +1210,7 @@ The full specification for a parameter declaration is \end{alltt} You can obtain lists of the parameters associated with -each thorn using the Cactus command line options {\tt -o} and {\tt -O} +each thorn using the Cactus command line options \texttt{-o} and \texttt{-O} (Section~\ref{sec:command_line_options}). @@ -1262,13 +1262,13 @@ The range specification is of the form \end{alltt} where \var{lower} and \var{upper} specify the lower and upper allowed range. A missing end of range (or a `{\t *}') implies negative or positive -infinity. The above is inclusive of the endpoints. A `{\tt (}' -(or `{\tt )}') before (or after) the lower (or upper) range specifies an open +infinity. The above is inclusive of the endpoints. A `\texttt{(}' +(or `\texttt{)}') before (or after) the lower (or upper) range specifies an open endpoint. -The numbers written in a {\tt param.ccl} file are interpreted as C code. +The numbers written in a \texttt{param.ccl} file are interpreted as C code. To express a number in `scientific notation', use -e.g.\ `{\tt 1e-10}', which is a double precision constant in C. (If the +e.g.\ `\texttt{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 @@ -1294,9 +1294,9 @@ to be portable. \section{Scope} \label{sec:Cactus_parameters.scope} -Parameters can be {\tt GLOBAL}, {\tt RESTRICTED}, or {\tt PRIVATE}. +Parameters can be \texttt{GLOBAL}, \texttt{RESTRICTED}, or \texttt{PRIVATE}. Global parameters are visible to all thorns. Restricted parameters -are visible to any thorn which chooses to {\tt USE} or {\tt EXTEND} +are visible to any thorn which chooses to \texttt{USE} or \texttt{EXTEND} it. A private parameter is only visible to the thorn which declares it. @@ -1306,7 +1306,7 @@ A parameter can be changed dynamically if it is specified to be \textit{steerable} (see Section~\ref{subsec:Appendix.param.specification_items}). It can then be changed by a call to the Flesh function -{\tt CCTK\_ParameterSet} (see the Reference Guide for a description +\texttt{CCTK\_ParameterSet} (see the Reference Guide for a description of this function). %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1347,8 +1347,8 @@ This full schedule specification consists of a mandatory part, a set of options, and the main body limited by braces, referred to as the \texttt{schedule block}. -Each schedule item is scheduled either {\tt AT} a particular -\var{scheduling bin}, or {\tt IN} a schedule \var{group}. +Each schedule item is scheduled either \texttt{AT} a particular +\var{scheduling bin}, or \texttt{IN} a schedule \var{group}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1365,18 +1365,18 @@ requested ordering of functions~\ref{scheduling:schedule_options}. In the absenc an undetermined order. The schedule bins are described in \ref{subsec:schedule_ccl}. Note that -the preceding {\tt CCTK\_} is optional for the use of the bin names -in the {\tt schedule.ccl} file. +the preceding \texttt{CCTK\_} is optional for the use of the bin names +in the \texttt{schedule.ccl} file. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Groups} \label{scheduling:groups} -If the optional {\tt GROUP} specifier is used, the item is a schedule +If the optional \texttt{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 {\tt IN} these in the same way as they are scheduled {\tt +scheduled \texttt{IN} these in the same way as they are scheduled {\tt AT} the main schedule bins. (That is, groups may be nested.) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1386,19 +1386,19 @@ AT} the main schedule bins. (That is, groups may be nested.) The options define various characteristics of the schedule item. \begin{Lentry} -\item[{\tt BEFORE or AFTER}] +\item[\texttt{BEFORE or AFTER}] 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 +\item[\texttt{WHILE}] +This specifies a \texttt{CCTK\_INT} grid scalar which is used to control 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}] +\item[\texttt{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 {\tt AS} the same thing, thus +implementation can schedule a routine \texttt{AS} the same thing, thus allowing other thorns to operate independently of which one is active. \end{Lentry} @@ -1413,14 +1413,14 @@ or group. \begin{Lentry} \item[\texttt{LANG}] This specifies the language of the routine. Currently this is either -C or Fortran. C++ routines should be defined as {\tt extern "C"} -and registered as {\tt LANG: C}. -\item[\texttt{STORAGE}] The {\tt STORAGE} keyword specifies groups for +C or Fortran. C++ routines should be defined as \texttt{extern "C"} +and registered as \texttt{LANG: C}. +\item[\texttt{STORAGE}] The \texttt{STORAGE} keyword specifies groups for 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 timebin {\tt CCTK\_ANALYSIS}. +This is only used for items scheduled at timebin \texttt{CCTK\_ANALYSIS}. The item will only be executed if output is due for at least one variable in one of the listed groups. (The item will also be called if there is no group listed.) @@ -1441,7 +1441,7 @@ 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 -{\tt CCTK\_ANALYSIS} timebin first a check is made to see if the routine should +\texttt{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 @@ -1452,7 +1452,7 @@ 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 {\tt ANALYSIS} are always called. +Routines from all timebins other than \texttt{ANALYSIS} are always called. Next, storage is assigned for any required variables, remembering the original state of storage. @@ -1483,7 +1483,7 @@ choosing a language to work in thorn writing are only available from C or C++. % This is no longer relevant? -%\item If you are writing in Fortran, use {\tt F77} if you want +%\item If you are writing in Fortran, use \texttt{F77} if you want % to distribute your code to people who may not be able to afford % to buy proprietary Fortran 90 compilers. @@ -1502,9 +1502,9 @@ use machine dependent extensions. The Flesh provides for thorns: \begin{Lentry} -\item [{\tt Variables}] -\item [{\tt Parameters}] -\item [{\tt Cactus Functions}] +\item [\texttt{Variables}] +\item [\texttt{Parameters}] +\item [\texttt{Cactus Functions}] \begin{itemize} \item{} Driver (parallelisation) utilities @@ -1520,7 +1520,7 @@ The Flesh provides for thorns: \subsection{Fortran Routines} Any source file using Cactus infrastructure should include -the header file {\tt cctk.h} using the line +the header file \texttt{cctk.h} using the line \begin{verbatim} #include "cctk.h" \end{verbatim} @@ -1537,22 +1537,22 @@ should include at the top of the file the header #include "cctk_Arguments.h" \end{verbatim} -A Cactus macro {\tt CCTK\_ARGUMENTS} is defined for each thorn +A Cactus macro \texttt{CCTK\_ARGUMENTS} is defined for each thorn to contain: \begin{itemize} \item General information about the grid hierarchy, for example the number of grid points used. See Section \ref{sec:cactus_variables_c} for a complete list. -\item All the grid variables defined in the thorn's {\tt interface.ccl} +\item All the grid variables defined in the thorn's \texttt{interface.ccl} \item All the grid variables required from other thorns as requested by - the {\tt inherits} and {\tt friend} lines in the {\tt interface.ccl} + the \texttt{inherits} and \texttt{friend} lines in the \texttt{interface.ccl} \end{itemize} These variables must be declared at the start of the routine using -the macro {\tt DECLARE\_CCTK\_ARGUMENTS}. +the macro \texttt{DECLARE\_CCTK\_ARGUMENTS}. To pass the arguments to another routine in the same thorn use the macro -{\tt CCTK\_PASS\_FTOF} in the calling routine, and again the macro -{\tt CCTK\_ARGUMENTS} in the receiving routine. +\texttt{CCTK\_PASS\_FTOF} in the calling routine, and again the macro +\texttt{CCTK\_ARGUMENTS} in the receiving routine. Note that you cannot use Cactus argument lists in routines scheduled at the {\t CCTK\_STARTUP} and {\t CCTK\_SHUTDOWN} time bins because at this time @@ -1561,12 +1561,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 {\tt CCTK} data type -in Fortran source code, i.e.. Booleans and Integers appear as {\tt CCTK\_INT} +All parameters defined in a thorn's \texttt{param.ccl} and all \texttt{global} +parameters appear as local variables of the corresponding \texttt{CCTK} data type +in Fortran source code, i.e.. Booleans and Integers appear as \texttt{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 +Reals as \texttt{CCTK\_REAL}, and Keywords and String parameters as +\texttt{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). @@ -1577,19 +1577,19 @@ the top of the file the header \end{verbatim} The parameters should be declared at the start of the routine -using them with the macro {\tt DECLARE\_CCTK\_PARAMETERS}. +using them with the macro \texttt{DECLARE\_CCTK\_PARAMETERS}. In Fortran, special care should be taken with string valued parameters. These parameters are passed as C pointers, and can not be treated as normal Fortran strings. To compare a string valued parameter and Fortran -string use the macro {\tt CCTK\_EQUALS()} or the function {\tt CCTK\_Equals()} -(see the reference manual for a description of the {\tt CCTK\_} functions). +string use the macro \texttt{CCTK\_EQUALS()} or the function \texttt{CCTK\_Equals()} +(see the reference manual for a description of the \texttt{CCTK\_} functions). To print the value of a string valued parameter to screen, use the subroutine -{\tt CCTK\_PrintString()}. A further function {\tt CCTK\_FortranString} +\texttt{CCTK\_PrintString()}. A further function \texttt{CCTK\_FortranString} provides a mechanism for converting a string parameter to a Fortran string. -For example, if {\tt operator} is a Cactus string parameter holding the name of a reduction operator whose handle you need to find, you cannot pass it -directly into the subroutine {\tt CCTK\_LocalArrayReductionHandle} which is expecting +For example, if \texttt{operator} is a Cactus string parameter holding the name of a reduction operator whose handle you need to find, you cannot pass it +directly into the subroutine \texttt{CCTK\_LocalArrayReductionHandle} which is expecting a Fortran string. Instead, the following is needed: % \begin{verbatim} @@ -1648,7 +1648,7 @@ c Main code goes here \subsubsection{Cactus Fortran Functions} -Cactus Fortran functions, for example {\tt CCTK\_MyProc} and {\tt +Cactus Fortran functions, for example \texttt{CCTK\_MyProc} and {\tt CCTK\_Equals}, can all be declared by adding the statement % \begin{verbatim} @@ -1673,24 +1673,24 @@ module \texttt{metric} should thus be placed e.g.\ into a file to automatically deduce the compile time dependencies. If you do not follow this convention, then you have to include the -modules into the thorn's {\tt make.code.deps} file +modules into the thorn's \texttt{make.code.deps} file (\ref{sec:mabathbu}) to ensure they are compiled before the routines which use them. This is especially important for parallel building. -For example, if a routine in {\tt MyRoutine.F90} uses a module in {\tt +For example, if a routine in \texttt{MyRoutine.F90} uses a module in {\tt MyModule.F90}, then add the line: % \begin{verbatim} $(SYS_OBJD)/MyRoutine.F90.o: $(SYS_OBJD)/MyModule.F90.o \end{verbatim} -\subsubsection{The {\tt MOD} function} +\subsubsection{The \texttt{MOD} function} -The intrinsic function {\tt MOD} in Fortran takes two integer +The intrinsic function \texttt{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 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, +\texttt{INT} for some architectures. This can occur in particular +when a \texttt{CCTK\_INT} parameter and the Cactus variable \texttt{cctk\_iteration} +(which is declared to be \texttt{INTEGER}) are used, in which case the correct code is \begin{verbatim} MOD(cctk_iteration,INT(MyParameter)) @@ -1700,7 +1700,7 @@ MOD(cctk_iteration,INT(MyParameter)) \subsection{C Routines} Any source file using Cactus infrastructure should include -the header file {\tt cctk.h} using the line +the header file \texttt{cctk.h} using the line \begin{verbatim} #include "cctk.h" \end{verbatim} @@ -1714,23 +1714,23 @@ should include at the top of the file the header #include "cctk_Arguments.h" \end{verbatim} -A Cactus macro {\tt CCTK\_ARGUMENTS} is defined for each thorn +A Cactus macro \texttt{CCTK\_ARGUMENTS} is defined for each thorn to contain \begin{itemize} \item General information about the grid hierarchy, for example the number of grid points on the processor. See Section \ref{sec:cactus_variables_c} for a complete list. -\item All the grid variables defined in the thorn's {\tt interface.ccl} +\item All the grid variables defined in the thorn's \texttt{interface.ccl} \item All the grid variables required from other thorns as requested by - the {\tt inherits} and {\tt friend} lines in the {\tt interface.ccl} + the \texttt{inherits} and \texttt{friend} lines in the \texttt{interface.ccl} \end{itemize} These variables must be declared at the start of the routine using -the macro {\tt DECLARE\_CCTK\_ARGUMENTS}. This macro should always be the +the macro \texttt{DECLARE\_CCTK\_ARGUMENTS}. This macro should always be the first line of the routine. To pass the arguments to another routine in the same thorn use the macro -{\tt CCTK\_PASS\_CTOC} in the calling routine, and again the macro -{\tt CCTK\_ARGUMENTS} in the receiving routine. +\texttt{CCTK\_PASS\_CTOC} in the calling routine, and again the macro +\texttt{CCTK\_ARGUMENTS} in the receiving routine. Note that you cannot use Cactus argument lists in routines scheduled at the {\t CCTK\_STARTUP} and {\t CCTK\_SHUTDOWN} time bins because at this time @@ -1739,11 +1739,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 {\tt CCTK} data type -in C source code, i.e. Integers and Booleans appear as {\tt CCTK\_INT} types +All parameters defined in a thorn's \texttt{param.ccl} and all \texttt{global} +parameters appear as local variables of the corresponding \texttt{CCTK} data type +in C source code, i.e. Integers and Booleans appear as \texttt{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}. +\texttt{CCTK\_REAL}, and Keywords and String parameters as \texttt{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). @@ -1754,11 +1754,11 @@ the top of the file the header \end{verbatim} The parameters should be declared as the last statement in the declaration part -of the routine using them with the macro {\tt DECLARE\_CCTK\_PARAMETERS}. +of the routine using them with the macro \texttt{DECLARE\_CCTK\_PARAMETERS}. \subsubsection{Example} -The C routine \verb|MyCRoutine| is scheduled in the {\tt schedule.ccl} file, +The C routine \verb|MyCRoutine| is scheduled in the \texttt{schedule.ccl} file, and uses Cactus parameters. The source file should look like \begin{verbatim} #include "cctk.h" @@ -1779,11 +1779,11 @@ void MyCRoutine(CCTK_ARGUMENTS) Cactus supports complex grid variables, and since there is no complex data type in C, Cactus provides a number of functions for manipulating complex numbers to mirror the -functionality available in Fortran. These functions are {\tt CCTK\_Cmplx}, -{\tt CCTK\_CmplxReal}, {\tt CCTK\_CmplxImag}, {\tt CCTK\_CmplxConjg}, -{\tt CCTK\_CmplxAdd}, {\tt CCTK\_CmplxSub}, {\tt CCTK\_CmplxMul}, -{\tt CCTK\_CmplxDiv}, {\tt CCTK\_CmplxExp}, {\tt CCTK\_CmplSin}, -{\tt CCTK\_CmplxAbs}, {\tt CCTK\_CmplxLog}, and {\tt CCTK\_CmplSqrt}. +functionality available in Fortran. These functions are \texttt{CCTK\_Cmplx}, +\texttt{CCTK\_CmplxReal}, \texttt{CCTK\_CmplxImag}, \texttt{CCTK\_CmplxConjg}, +\texttt{CCTK\_CmplxAdd}, \texttt{CCTK\_CmplxSub}, \texttt{CCTK\_CmplxMul}, +\texttt{CCTK\_CmplxDiv}, \texttt{CCTK\_CmplxExp}, \texttt{CCTK\_CmplSin}, +\texttt{CCTK\_CmplxAbs}, \texttt{CCTK\_CmplxLog}, and \texttt{CCTK\_CmplSqrt}. See the Reference Manual for more details. @@ -1798,7 +1798,7 @@ Cactus provides 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 artificial example to demonstrate this -using the 3D macro {\tt CCTK\_GFINDEX3D}: +using the 3D macro \texttt{CCTK\_GFINDEX3D}: \begin{verbatim} for (k=0; k<cctk_lsh[2]; k++) { @@ -1821,31 +1821,31 @@ Here, \verb|CCTK_GFINDEX3D(cctkGH,i,j,k)| expands to \label{sec:cactus_variables_c} The Cactus variables which are passed through the macro -{\tt CCTK\_ARGUMENTS} are +\texttt{CCTK\_ARGUMENTS} are \begin{Lentry} -\item [{\tt cctkGH}] A C pointer identifying the grid hierarchy. -\item [{\tt cctk\_dim}] An integer with the number of dimensions +\item [\texttt{cctkGH}] A C pointer identifying the grid hierarchy. +\item [\texttt{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 +\item [\texttt{cctk\_lsh}] An array of \texttt{cctk\_dim} integers with the local grid size on this processor. -\item [{\tt cctk\_gsh}] An array of {\tt cctk\_dim} integers +\item [\texttt{cctk\_gsh}] An array of \texttt{cctk\_dim} integers 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. -\item [{\tt cctk\_delta\_space}] An array of {\tt cctk\_dim} {\tt +\item [\texttt{cctk\_delta\_time}] A \texttt{CCTK\_REAL} with the timestep. +\item [\texttt{cctk\_time}] A \texttt{CCTK\_REAL} with the current time. +\item [\texttt{cctk\_delta\_space}] An array of \texttt{cctk\_dim} {\tt CCTK\_REAL}s with the grid spacing in each direction. -\item [{\tt cctk\_nghostzones}] An array of {\tt cctk\_dim} integers with +\item [\texttt{cctk\_nghostzones}] An array of \texttt{cctk\_dim} integers with the number of ghostzones used in each direction. -%\item [{\tt cctk\_from}] The index value from which the user should start loops. -%\item [{\tt cctk\_to}] ... end loops. -\item [{\tt cctk\_origin\_space}] An array of {\tt cctk\_dim} {\tt +%\item [\texttt{cctk\_from}] The index value from which the user should start loops. +%\item [\texttt{cctk\_to}] ... end loops. +\item [\texttt{cctk\_origin\_space}] An array of \texttt{cctk\_dim} {\tt CCTK\_REAL}s with the spatial coordinates of the global origin of the grid. The coordinates of the $i$th local grid point in - the $x$ direction can e.g.\ in C be calculated by {\tt x = + the $x$ direction can e.g.\ in C be calculated by \texttt{x = CCTK\_ORIGIN\_SPACE(0) + (cctk\_lsh[0] + i) * CCTK\_DELTA\_SPACE(0)}. -\item [{\tt cctk\_lssh}] This is an internal array used to hold +\item [\texttt{cctk\_lssh}] This is an internal array used to hold array extents for staggering. One should use the macro CCTK\_LSSH(,) to access its elements. @@ -1855,20 +1855,20 @@ The following variables describe the location of the local grid (e.g.\ the grid treated on a given processor) within the global grid. \begin{itemize} -\item {\tt cctk\_lbnd} - An array of {\tt cctk\_dim} integers +\item \texttt{cctk\_lbnd} + An array of \texttt{cctk\_dim} integers containing the lowest index (in each direction) of the local grid, as seen on the global grid. Note that these indices start from zero, so you need to add one when using them in Fortran thorns. -\item {\tt cctk\_ubnd} - An array of {\tt cctk\_dim} integers +\item \texttt{cctk\_ubnd} + An array of \texttt{cctk\_dim} integers containing the largest index (in each direction) of the local grid, as seen on the global grid. Note that these indices start from zero, so you need to add one when using them in Fortran thorns. -\item {\tt cctk\_bbox} - An array of 2$*${\tt cctk\_dim} integers (in the order +\item \texttt{cctk\_bbox} + An array of 2$*$\texttt{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]$), which indicate whether the boundaries are internal boundaries @@ -1880,16 +1880,16 @@ the global grid. The following variable is needed for grid refinement methods \begin{itemize} -\item {\tt cctk\_levfac} An array of {\tt cctk\_dim} integer factors +\item \texttt{cctk\_levfac} An array of \texttt{cctk\_dim} integer factors by which the local grid is refined in the corresponding direction with respect to the base grid. -\item {\tt cctk\_levoff} and {\tt cctk\_levoffdenom} Two arrays of - {\tt cctk\_dim} integers describing the distance by which the +\item \texttt{cctk\_levoff} and \texttt{cctk\_levoffdenom} Two arrays of + \texttt{cctk\_dim} integers describing the distance by which the local grid is offset with respect to the base grid, measured - in local grid spacings. The distance in direction {\tt dir} - is given by {\tt 1.0 * cctk\_levoff[dir] / + in local grid spacings. The distance in direction \texttt{dir} + is given by \texttt{1.0 * cctk\_levoff[dir] / cctk\_levoffdenom[dir]}. -\item {\tt cctk\_timefac} The integer factor +\item \texttt{cctk\_timefac} The integer factor by which the time step size is reduced with respect to the base grid. \end{itemize} @@ -1897,29 +1897,29 @@ The following variable is needed for grid refinement methods The following variables are used for identifying convergence levels. \emph{NOTE:} Convergence is not currently implemented by Cactus, so that -{\tt cctk\_convlevel} is currently always $0$. +\texttt{cctk\_convlevel} is currently always $0$. \begin{itemize} -\item {\tt cctk\_convlevel} The convergence level of this grid hierarchy. +\item \texttt{cctk\_convlevel} The convergence level of this grid hierarchy. The base level is $0$, and every level above that is - coarsened by a factor of {\tt cctk\_convfac}. -\item {\tt cctk\_convfac} The factor between convergence levels. + coarsened by a factor of \texttt{cctk\_convfac}. +\item \texttt{cctk\_convfac} The factor between convergence levels. The relation between the resolutions of different convergence levels is $\Delta x_L = \Delta x_0 \cdot F^L$, where $L$ is the convergence level and $F$ is the convergence factor. The convergence factor defaults to $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, +The variables \texttt{cctk\_delta\_space}, \texttt{cctk\_delta\_time}, and +\texttt{cctk\_origin\_space} denote the grid spacings, time step size, 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)}, -and {\tt CCTK\_DELTA\_TIME} for both C and Fortran. It is recommended +syntax \texttt{CCTK\_DELTA\_SPACE(dir)}, \texttt{CCTK\_ORIGIN\_SPACE(dir)}, +and \texttt{CCTK\_DELTA\_TIME} for both C and Fortran. It is recommended that these macros are always used to provide the grid spacings, time step sizes, and spatial origins in your thorns. In doing so, you -incorporate the effects of {\tt cctk\_levfac}, {\tt cctk\_levoff}, -{\tt cctk\_levoffdenom}, and {\tt cctk\_timefac}, so that you do not +incorporate the effects of \texttt{cctk\_levfac}, \texttt{cctk\_levoff}, +\texttt{cctk\_levoffdenom}, and \texttt{cctk\_timefac}, so that you do not explicitly have to take them into account. \subsection{Cactus Data Types} @@ -1935,15 +1935,15 @@ declarations. \begin{Lentry} -\item[{\tt CCTK\_INT}] default size 4 bytes -\item[{\tt CCTK\_REAL}] default size 8 bytes +\item[\texttt{CCTK\_INT}] default size 4 bytes +\item[\texttt{CCTK\_REAL}] default size 8 bytes \end{Lentry} \subsubsection{Example} In the following example \verb|MyScalar| is a grid scalar which -is declared in the {\tt interface.ccl} as {\tt CCTK\_REAL}. +is declared in the \texttt{interface.ccl} as \texttt{CCTK\_REAL}. % \begin{verbatim} subroutine InitialData(CCTK_ARGUMENTS) @@ -1959,8 +1959,8 @@ is declared in the {\tt interface.ccl} as {\tt CCTK\_REAL}. end \end{verbatim} % -Declaring {\tt local\_var} to have a non-Cactus data type, e.g.\ -{\tt REAL*4}, or using one of the other Cactus real data types +Declaring \texttt{local\_var} to have a non-Cactus data type, e.g.\ +\texttt{REAL*4}, or using one of the other Cactus real data types described in Section~\ref{sec:datyansi} could give problems for different architectures or configurations. @@ -1979,7 +1979,7 @@ indexing is the same? Indeed, you could roll your own, but there compelling reasons: Readability and the fact that you are able to query the staggertype of a grid function. More important: in the way the grid is laid out, there is one grid -point \emph{less} for {\tt M} and {\tt P} staggered grid functions. This is +point \emph{less} for \texttt{M} and \texttt{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 grid functions, the grey circles depict the ghostzones. @@ -1992,19 +1992,19 @@ The string specifying the staggering is encoded in a number called 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), +staggerindex}. E.g.\ \texttt{stagger = MCM}: \textit{staggerindex} = 3, in the +$x$-direction: \textit{directional staggerindex} = \texttt{CCTK\_STAGGER\_M} (value 0), in the -$y$-direction: \textit{directional staggerindex} = {\tt CCTK\_STAGGER\_C} (value 1). +$y$-direction: \textit{directional staggerindex} = \texttt{CCTK\_STAGGER\_C} (value 1). \begin{Lentry} -\item[{\tt CCTK\_STAGGER\_M}] value used for M-type staggering -\item[{\tt CCTK\_STAGGER\_C}] value used for C-type staggering -\item[{\tt CCTK\_STAGGER\_P}] value used for P-type staggering -\item[{\tt CCTK\_NO\_STAGGER}] value to indicate no staggering -\item[{\tt CCTK\_STAGGER}] value to indicate staggering -\item[{\tt CCTK\_NSTAGGER}] number of coded staggerings (3) -%\item[{\tt CCTK\_STAGGER\_ERROR}] failed stagger operation, negative +\item[\texttt{CCTK\_STAGGER\_M}] value used for M-type staggering +\item[\texttt{CCTK\_STAGGER\_C}] value used for C-type staggering +\item[\texttt{CCTK\_STAGGER\_P}] value used for P-type staggering +\item[\texttt{CCTK\_NO\_STAGGER}] value to indicate no staggering +\item[\texttt{CCTK\_STAGGER}] value to indicate staggering +\item[\texttt{CCTK\_NSTAGGER}] number of coded staggerings (3) +%\item[\texttt{CCTK\_STAGGER\_ERROR}] failed stagger operation, negative \end{Lentry} @@ -2023,13 +2023,13 @@ treat this case in a easy way is explained below. } When a thorn programmer uses staggered gridpoints, he has to be aware of this gridpoint anomaly. This can be done most easily by using the -{\tt CCTK\_LSSH(<\var{dir\_staggertype}>,<\var{direction}>)} macro. +\texttt{CCTK\_LSSH(<\var{dir\_staggertype}>,<\var{direction}>)} macro. For a given staggertype and direction, this 2d array returns the local number of gridpoints, including ghostzones and the necessary change for the staggering on the outermost processor. \begin{Lentry} -\item[{\tt CCTL\_LSSH(<\var{dir\_staggertype}>,<\var{direction}>)}] +\item[\texttt{CCTL\_LSSH(<\var{dir\_staggertype}>,<\var{direction}>)}] for a given staggertype and a direction this macro returns the number of processor local gridpoints, including ghostzones. @@ -2045,25 +2045,25 @@ ranging from $1 \ldots$.} Several functions exist to derive the staggertype for a given group and for a certain direction. \begin{Lentry} -\item[{\tt int CCTK\_GroupStaggerIndexGI(int \var{group\_index})}] %returns the +\item[\texttt{int CCTK\_GroupStaggerIndexGI(int \var{group\_index})}] %returns the %\textit{staggerindex} for a given group index. -\item[{\tt call CCTK\_GroupStaggerIndexGI(int \var{staggerindex}, int +\item[\texttt{call CCTK\_GroupStaggerIndexGI(int \var{staggerindex}, int \var{group\_index})}] returns the \var{staggerindex} for a given group index. \end{Lentry} \vskip .45cm \begin{Lentry} -\item[{\tt int CCTK\_GroupStaggerIndexGN(char *\var{group\_name})}] %returns the +\item[\texttt{int CCTK\_GroupStaggerIndexGN(char *\var{group\_name})}] %returns the %\textit{staggerindex} for a given group name. -\item[{\tt call CCTK\_GroupStaggerIndexGN(int \var{staggerindex}, char *\var{group\_name})}] returns the +\item[\texttt{call CCTK\_GroupStaggerIndexGN(int \var{staggerindex}, char *\var{group\_name})}] returns the \var{staggerindex} for a given group name. \vskip .25cm \end{Lentry} \vskip .45cm %\begin{Lentry} -%\item[{\tt int CCTK\_GroupStaggerIndexVI(int variable\_index)}] %returns the +%\item[\texttt{int CCTK\_GroupStaggerIndexVI(int variable\_index)}] %returns the %%\textit{staggerindex} for a given variable index. -%\item[{\tt call CCTK\_GroupStaggerIndexVI(int staggerindex, int variable\_index)}] returns the +%\item[\texttt{call CCTK\_GroupStaggerIndexVI(int staggerindex, int variable\_index)}] returns the %\textit{staggerindex} for a given variable index. @@ -2071,36 +2071,36 @@ and for a certain direction. %\vskip .45cm % %\begin{Lentry} -%\item[{\tt int CCTK\_GroupStaggerIndexVN(char *variable\_name)}] %returns the +%\item[\texttt{int CCTK\_GroupStaggerIndexVN(char *variable\_name)}] %returns the %%\textit{staggerindex} for a given variable name. -%\item[{\tt call CCTK\_GroupStaggerIndexVN(int staggerindex, char *variable\_name)}] returns the +%\item[\texttt{call CCTK\_GroupStaggerIndexVN(int staggerindex, char *variable\_name)}] returns the %\textit{staggerindex} for a given variable name. %\end{Lentry} %\vskip .45cm \begin{Lentry} -\item[{\tt int CCTK\_StaggerIndex(char *\var{stagger\_string})}] %return the \textit{ +\item[\texttt{int CCTK\_StaggerIndex(char *\var{stagger\_string})}] %return the \textit{ %staggerindex} for a given stagger string. -\item[{\tt call CCTK\_StaggerIndex(int \var{staggerindex}, char *\var{stagger\_string})}] return the \var{staggerindex} for a given stagger string. +\item[\texttt{call CCTK\_StaggerIndex(int \var{staggerindex}, char *\var{stagger\_string})}] return the \var{staggerindex} for a given stagger string. \end{Lentry} \vskip .45cm \begin{Lentry} -\item[{\tt int CCTK\_DirStaggerIndex(int \var{direction}, char *\var{stagger\_string})}] +\item[\texttt{int CCTK\_DirStaggerIndex(int \var{direction}, char *\var{stagger\_string})}] %returns the \textit{directional staggerindex} for a given direction and %stagger string. -\item[{\tt call CCTK\_DirStaggerIndex(int \var{dir\_staggerindex}, int \var{direction}, char *\var{stagger\_string})}] +\item[\texttt{call CCTK\_DirStaggerIndex(int \var{dir\_staggerindex}, int \var{direction}, char *\var{stagger\_string})}] returns the \var{directional staggerindex} for a given direction and stagger string. \end{Lentry} \vskip .45cm \begin{Lentry} -\item[{\tt int CCTK\_DirStaggerIndexI(int \var{direction}, char *\var{stagger\_type})}] +\item[\texttt{int CCTK\_DirStaggerIndexI(int \var{direction}, char *\var{stagger\_type})}] %returns the \textit{directional staggerindex} for a given direction and %staggerindex. -\item[{\tt call CCTK\_DirStaggerIndexI(int \var{dir\_direction}, char *\var{stagger\_type})}] +\item[\texttt{call CCTK\_DirStaggerIndexI(int \var{dir\_direction}, char *\var{stagger\_type})}] returns the \var{directional staggerindex} for a given direction and staggerindex. @@ -2124,17 +2124,17 @@ of these interfaces with their arguments, is given in the Reference Manual. A complete description of the routines a driver thorn must provide will be provided in the Infrastructure Thorn Writers guide (Part \ref{part:Infrastructure}). The standard driver thorn is -currently {\tt PUGH} in the {\tt CactusPUGH} package, which +currently \texttt{PUGH} in the \texttt{CactusPUGH} package, which is a parallel unigrid driver. \begin{Lentry} -\item[{\tt CCTK\_nProcs}] Returns the number of processors being used -\item[{\tt CCTK\_MyProc}] Returns the processor number (this starts at +\item[\texttt{CCTK\_nProcs}] Returns the number of processors being used +\item[\texttt{CCTK\_MyProc}] Returns the processor number (this starts at processor number zero) -\item[{\tt CCTK\_SyncGroup}] Synchronises a group of variables by +\item[\texttt{CCTK\_SyncGroup}] Synchronises a group of variables by exchanging the values held in each processor ghostzones with the physical values of their neighbours (see the Reference Manual) -\item[{\tt CCTK\_Barrier}] Waits for all processors to reach this point +\item[\texttt{CCTK\_Barrier}] Waits for all processors to reach this point before proceeding \end{Lentry} @@ -2190,11 +2190,11 @@ Coordinate systems and their properties can be registered at any time with the F The registration utilities for thorns providing coordinates are: \begin{Lentry} -\item[{\tt CCTK\_CoordRegisterSystem}] +\item[\texttt{CCTK\_CoordRegisterSystem}] Assigns a coordinate system with a chosen name and dimension. For example, a 3-dimensional Cartesian coordinate system could be registered with the -name {\tt cart3d} using the call from C +name \texttt{cart3d} using the call from C % \begin{verbatim} int ierr; @@ -2202,13 +2202,13 @@ int dim=3; ierr = CCTK_CoordRegisterSystem(dim,"cart3d"); \end{verbatim} -\item[{\tt CCTK\_CoordRegisterData}] +\item[\texttt{CCTK\_CoordRegisterData}] 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 {\tt grid::y3d} -to have the coordinate name {\tt y} in the {\tt cart3d} system +coordinate system. For example, to register the grid variable \texttt{grid::y3d} +to have the coordinate name \texttt{y} in the \texttt{cart3d} system % \begin{verbatim} int ierr; @@ -2216,12 +2216,12 @@ int dir=2; ierr = CCTK_CoordRegisterData(dir,"grid::y3d","y","cart3d"); \end{verbatim} -\item[{\tt CCTK\_CoordRegisterRange}] +\item[\texttt{CCTK\_CoordRegisterRange}] Assigns the global computational maximum and minimum for a coordinate -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 +on a grid hierarchy, that is in a \texttt{cctkGH}. At this time the +maximum and minimum values have to be of type \texttt{CCTK\_REAL}. For +example, if the \texttt{y} coordinate for the \texttt{cart3d} system ranges between zero and one % \begin{verbatim} @@ -2241,14 +2241,14 @@ int ierr; ierr = CCTK_CoordRegisterRange(cctkGH, lower, upper, 2, NULL, "cart3d"); \end{verbatim} -\item[{\tt CCTK\_CoordRegisterPhysIndex}] +\item[\texttt{CCTK\_CoordRegisterPhysIndex}] Implementing such things as symmetry properties for a grid leads to 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 -indices 3 and 25 as supplying the physical range of the {\tt y} -coordinate in the {\tt cart3d} system +indices 3 and 25 as supplying the physical range of the \texttt{y} +coordinate in the \texttt{cart3d} system % \begin{verbatim} int loweri=3; @@ -2272,7 +2272,7 @@ The utilities for thorns using coordinates are: \begin{Lentry} -\item[{\tt CCTK\_NumCoordSystems}] +\item[\texttt{CCTK\_NumCoordSystems}] Returns the number of coordinate systems registered with the Flesh. For example, % @@ -2281,11 +2281,11 @@ int num; num = CCTK_NumCoordSystems(); \end{verbatim} -\item[{\tt CCTK\_CoordSystemName}] +\item[\texttt{CCTK\_CoordSystemName}] Provides the name of a registered coordinate system, given the integer handle (or index) for the system in the Flesh's coordinate data base. -Note that the handle ranges between zero and the number of coordinate systems minus one: $0 \le \mbox{handle} \le \mbox{\tt CCTK\_NumCoordSystems()}-1$. +Note that the handle ranges between zero and the number of coordinate systems minus one: $0 \le \mbox{handle} \le \mbox\texttt{CCTK\_NumCoordSystems()}-1$. It is important to remember that the handle given to a coordinate system depends on the order in which systems are registered, and can be different from one simulation to the next. @@ -2297,30 +2297,30 @@ for (i=0; i<CCTK_NumCoordSystems(); i++) printf("%s ",CCTK_CoordSystemNName(i)); \end{verbatim} -\item[{\tt CCTK\_CoordSystemDim}] +\item[\texttt{CCTK\_CoordSystemDim}] Provides the dimension of a coordinate system. For example, if -the {\tt cart3d} system was registered as having 3 dimensions, the -variable {\tt dim} below will now be set to 3, +the \texttt{cart3d} system was registered as having 3 dimensions, the +variable \texttt{dim} below will now be set to 3, % \begin{verbatim} int dim; dim = CCTK_CoordSystemDim("cart3d"); \end{verbatim} -\item[{\tt CCTK\_CoordSystemHandle}] +\item[\texttt{CCTK\_CoordSystemHandle}] Provides the integer handle for a given coordinate system name. The handle describes the index for the coordinate system in the Flesh coordinate database, and its value will range between zero and the number of registered systems minus one. For example, -the handle for the {\tt cart3d} coordinate system can be found using +the handle for the \texttt{cart3d} coordinate system can be found using % \begin{verbatim} int handle; handle = CCTK_CoordSystemHandle("cart3d"); \end{verbatim} -\item[{\tt CCTK\_CoordSystemName}] +\item[\texttt{CCTK\_CoordSystemName}] The inverse to the previous function call, this provides the name for a given coordinate system handle. For example to find the first coordinate system in the Flesh database @@ -2330,13 +2330,13 @@ int handle = 0; const char *name = CCTK_CoordSystemName(handle); \end{verbatim} -\item[{\tt CCTK\_CoordIndex}] +\item[\texttt{CCTK\_CoordIndex}] 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} -coordinate of the {\tt cart3d} system, either of the two following +For example, to find the grid variable index associated with the \texttt{y} +coordinate of the \texttt{cart3d} system, either of the two following calls could be made % \begin{verbatim} @@ -2350,12 +2350,12 @@ index = CCTK_CoordIndex(-1,"y","cart3d"); \end{verbatim} -\item[{\tt CCTK\_CoordDir}] +\item[\texttt{CCTK\_CoordDir}] Provides the direction for a given coordinate. Directions are integers ranging from one to the number of dimensions for the coordinate system. -For example, to return the direction of the {\tt y} coordinate in -the {\tt cart3d} system +For example, to return the direction of the \texttt{y} coordinate in +the \texttt{cart3d} system % \begin{verbatim} int dir; @@ -2365,14 +2365,14 @@ dir = CCTK_CoordDir("y","cart3d"); The return of a negative integer indicates that the coordinate direction could not be found. -\item[{\tt CCTK\_CoordRange}] +\item[\texttt{CCTK\_CoordRange}] 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 +the minimum and maximum values must be of type \texttt{CCTK\_REAL}. The coordinate can be specified either by name or by its direction. Note that this call takes the \emph{addresses} of the minimum and maximum values. -For example, the range of the {\tt y} coordinate of the {\tt cart3d} +For example, the range of the \texttt{y} coordinate of the \texttt{cart3d} coordinate system can be found using % \begin{verbatim} @@ -2389,12 +2389,12 @@ ierr = CCTK_CoordRange(cctkGH, &lower, &upper, 2, NULL, "cart3d"); \end{verbatim} -\item[{\tt CCTK\_CoordLocalRange}] +\item[\texttt{CCTK\_CoordLocalRange}] Provides the local range of a coordinate on a processor for a given 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 +\texttt{y} coordinate of the \texttt{cart3d} coordinate system can be found using % \begin{verbatim} CCTK_REAL lower, upper; @@ -2409,7 +2409,7 @@ int ierr; ierr = CCTK_CoordLocalRange(cctkGH, &lower, &upper, 2, NULL, "cart3d"); \end{verbatim} -\item[{\tt CCTK\_CoordRangePhysIndex}] +\item[\texttt{CCTK\_CoordRangePhysIndex}] For a given coordinate, provides the indices describing the \emph{physical} range of the coordinate. A negative return value signifies that no such range @@ -2418,7 +2418,7 @@ was registered for the coordinate. This index range provides a mechanism for describing grid points which should not be considered part of the simulation results (for example, grid points used for different boundary conditions). The physical range of the -{\tt y} coordinate of the {\tt cart3d} system can be found using +\texttt{y} coordinate of the \texttt{cart3d} system can be found using \begin{verbatim} int ilower, iupper; @@ -2432,7 +2432,7 @@ int ierr; ierr = CCTK_CoordRangePhysIndex(cctkGH,&ilower,&iupper, 2, NULL, "cart3d"); \end{verbatim} -\item[{\tt CCTK\_CoordSystemImplementation}] +\item[\texttt{CCTK\_CoordSystemImplementation}] This call returns the name of the implementation which registered a coordinate system. Note that there is no guarantee that a thorn which registered a coordinate system is @@ -2454,7 +2454,7 @@ the following function calls: \begin{description} -\item {\tt CCTK\_OutputGH (const cGH *\var{GH})} +\item \texttt{CCTK\_OutputGH (const cGH *\var{GH})} This call loops over all registered IO methods, calling the routine that each method has registered for {\t OutputGH}. The expected @@ -2464,7 +2464,7 @@ routines (that is, not all methods will supply routines to output all different types of variables) and if the method decides it is an appropriate time to output. -\item {\tt CCTK\_OutputVar (const cGH *\var{GH}, const char *\var{varname})} +\item \texttt{CCTK\_OutputVar (const cGH *\var{GH}, const char *\var{varname})} Output a variable \var{varname} looping over all registered IO methods. \var{varname} may have an optional I/O options string appended. @@ -2472,7 +2472,7 @@ The output should take place if at all possible. If output goes into a file and the appropriate file exists the data is appended, otherwise a new file is created. -\item {\tt CCTK\_OutputVarAs (const cGH *\var{GH}, const char *\var{varname}, const char *\var{alias})} +\item \texttt{CCTK\_OutputVarAs (const cGH *\var{GH}, const char *\var{varname}, const char *\var{alias})} Output a variable \var{varname} looping over all registered IO methods. \var{varname} may have an optional I/O options string appended. @@ -2481,7 +2481,7 @@ a file and the appropriate file exists the data is appended, otherwise a new file is created. Uses \var{alias} as the name of the variable for the purpose of constructing a filename. -\item {\tt CCTK\_OutputVarByMethod (const cGH *\var{GH}, const char *\var{varname}, const char *\var{methodname})} +\item \texttt{CCTK\_OutputVarByMethod (const cGH *\var{GH}, const char *\var{varname}, const char *\var{methodname})} Output a variable \var{varname} using the IO method \var{methodname} if it is registered. \var{varname} may have an optional I/O options string appended. @@ -2489,7 +2489,7 @@ The output should take place if at all possible. If output goes into a file and the appropriate file exists the data is appended, otherwise a new file is created. -\item {\tt CCTK\_OutputVarAsByMethod (const cGH *\var{GH}, +\item \texttt{CCTK\_OutputVarAsByMethod (const cGH *\var{GH}, const char *\var{varname}, const char *\var{methodname},\\ const char *\var{alias})} @@ -2519,16 +2519,16 @@ 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): \begin{Lentry} -\item[{\tt CCTK\_InterpGridArrays()}] +\item[\texttt{CCTK\_InterpGridArrays()}] Interpolates Cactus grid arrays, with the topology of the grid implicitly specified by a Cactus coordinate system. This API doesn't provide an interpolation functionality itself, it only takes care of the interprocessor communication necessary when interpolating distributed grid arrays, and invokes - the {\tt CCTK\_InterpLocalUniform()} API on the each processor's + the \texttt{CCTK\_InterpLocalUniform()} API on the each processor's local patch of the data. -\item[{\tt CCTK\_InterpLocalUniform()}] +\item[\texttt{CCTK\_InterpLocalUniform()}] 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 @@ -2540,7 +2540,7 @@ should be obvious): \end{flushleft} where the caller specifies the \verb|origin| and \verb|delta| values. -%notyet \item[{\tt CCTK\_InterpLocalNonUniform()}] +%notyet \item[\texttt{CCTK\_InterpLocalNonUniform()}] %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 @@ -2552,7 +2552,7 @@ should be obvious): %notyet \end{flushleft} %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 \item[\texttt{CCTK\_InterpLocalWarped()}] %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 @@ -2570,11 +2570,11 @@ should be obvious): %notyet the APIs: The Flesh provides an API to register local interpolation operators: \begin{Lentry} -\item[{\tt CCTK\_InterpRegisterOpLocalUniform()}] +\item[\texttt{CCTK\_InterpRegisterOpLocalUniform()}] Register a \verb|CCTK_InterpLocalUniform()| interpolation operator -%notyet \item[{\tt CCTK\_InterpRegisterOpLocalNonUniform()}] +%notyet \item[\texttt{CCTK\_InterpRegisterOpLocalNonUniform()}] %notyet Register a \verb|CCTK_InterpLocalNonUniform()| interpolation operator -%notyet \item[{\tt CCTK\_InterpRegisterOpLocalWarped()}] +%notyet \item[\texttt{CCTK\_InterpRegisterOpLocalWarped()}] %notyet Register a \verb|CCTK_InterpLocalWarped()| interpolation operator \end{Lentry} %notyet These are described in detail in the Reference Manual. @@ -2611,7 +2611,7 @@ therefor making the previous processor local error known to all processors. The exchange of information across processors needs the functionality of a -communication layer e.g. {\tt CactusPUGH/PUGH}. For this reason, the +communication layer e.g. \texttt{CactusPUGH/PUGH}. For this reason, the 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 @@ -2641,23 +2641,23 @@ are made about the topology and spacing of the grid (these descriptions are for 3-D, but the generalisations to other numbers of dimensions should be obvious): \begin{Lentry} -\item[{\tt CCTK\_ReduceGridArrays()}] +\item[\texttt{CCTK\_ReduceGridArrays()}] Reduces Cactus grid arrays, with the topology of the grid implicitly specified by a Cactus coordinate system. This API doesn't provide a reduction functionality itself, it only takes care of the interprocessor communication necessary when reducing distributed grid arrays, and invokes - the {\tt CCTK\_ReduceLocalArrays()} API on the each processor's + the \texttt{CCTK\_ReduceLocalArrays()} API on the each processor's local patch of the data. -\item[{\tt CCTK\_ReduceLocalArrays()}] +\item[\texttt{CCTK\_ReduceLocalArrays()}] Reduces processor-local arrays with various options including \emph{offsets}, \emph{strides} and \emph{masks}. \end{Lentry} The Flesh provides an API to register local reduction operators: \begin{Lentry} -\item[{\tt CCTK\_RegisterLocalArrayReductionOperator()}] +\item[\texttt{CCTK\_RegisterLocalArrayReductionOperator()}] Register a \verb|CCTK_ReduceLocalArrays()| interpolation operator \end{Lentry} This is described in detail in the Reference Manual. @@ -2698,15 +2698,15 @@ call CCTK_ReductionArrayHandle(reduction_handle, reduction_name) \vskip .25cm \begin{Lentry} -\item[{\tt reduction\_handle}] +\item[\texttt{reduction\_handle}] In Fortran the name of the variable will contain the handle value after the call. In C this value is the function value. -\item[{\tt reduction\_name}] +\item[\texttt{reduction\_name}] is the name under which the operator has been registered by the providing thorn. The only thorn in the standard Computational Toolkit release which provides reduction operators is -{\tt CactusPUGH/PUGHReduce}. +\texttt{CactusPUGH/PUGHReduce}. \item[{\bf error checking}] negative handle value indicates failure to identify the correct operator. @@ -2778,36 +2778,36 @@ call CCTK_ReduceArray(int returnvalue, } \begin{Lentry} -\item[{\tt int returnvalue}] +\item[\texttt{int returnvalue}] the return value of the operation. negative value indicates failure to perform reduction. Zero indicates successful operation. -\item[{\tt cctkGH}] +\item[\texttt{cctkGH}] in Fortran the pointer to the grid hierarchy structure. Cannot be used within Fortran but can be used from within C. Since this name is fixed write it out shown above. -\item[{\tt cGH *GH}] +\item[\texttt{cGH *GH}] in the C the pointer to the grid hierarchy. -\item[{\tt int processor}] +\item[\texttt{int processor}] the processor which collects the information, negative value ($-1$) will distribute the data to all processors. -\item[{\tt int operation\_handle}] the number of the reduction operation - handle, needs to be found by calling {\tt CCTK\_ReductionHandle} or - {\tt CCTK\_ReductionArrayHandle}. -\item[{\tt int num\_out\_vals}] integer defining the number of ?? -\item[{\tt int type\_out\_arrays}, {\tt type\_in\_arrays}] +\item[\texttt{int operation\_handle}] the number of the reduction operation + handle, needs to be found by calling \texttt{CCTK\_ReductionHandle} or + \texttt{CCTK\_ReductionArrayHandle}. +\item[\texttt{int num\_out\_vals}] integer defining the number of ?? +\item[\texttt{int type\_out\_arrays}, \texttt{type\_in\_arrays}] specifies the type of the gridfunction you are communicating. Use the values as specified in \ref{sec:datyansi}. Note: do not {\em mix} datatypes: e.g. in -Fortran do not declare a variable as {\tt integer} and then specify -the type {\tt CCTK\_VARIABLE\_INT} in the reduction command. These +Fortran do not declare a variable as \texttt{integer} and then specify +the type \texttt{CCTK\_VARIABLE\_INT} in the reduction command. These types need not be the same on some architectures and will conflict. -\item[{\tt out\_vals}] -\item[{\tt int num\_in\_fields}] specifies the number of to follow -\item[{\tt ...}] indicates a variable argument list: specify the size +\item[\texttt{out\_vals}] +\item[\texttt{int num\_in\_fields}] specifies the number of to follow +\item[\texttt{...}] indicates a variable argument list: specify the size of the array in each dimension, comma separated numbers or integer variables. Specify the arrays which will be reduced, the number of specified arrays must be the same as the value of the {\tt @@ -2847,11 +2847,11 @@ call CCTK_ReduceLocScalar(int returnvalue, \end{verbatim} } \begin{Lentry} -\item[{\tt in\_scalar}] the processor local variable with local value to be reduced -\item[{\tt out\_scalar}] the reduction result: a processor local variable -with the global value (same on all procs) if {\tt processor} has been -set to $-1$. Otherwise {\tt processor} will hold the reduction result. -\item[{\tt data\_type}] +\item[\texttt{in\_scalar}] the processor local variable with local value to be reduced +\item[\texttt{out\_scalar}] the reduction result: a processor local variable +with the global value (same on all procs) if \texttt{processor} has been +set to $-1$. Otherwise \texttt{processor} will hold the reduction result. +\item[\texttt{data\_type}] specifies the type of the gridfunction you are communicating. Use the values as specified in \ref{sec:datyansi}. @@ -2884,11 +2884,11 @@ call CCTK_ReduceLocArrayToArray1D( int returnvalue } \begin{Lentry} -\item[{\tt in\_array1d}] one dimensional local arrays, to be reduced across a +\item[\texttt{in\_array1d}] one dimensional local arrays, to be reduced across a processors, element by element. -\item[{\tt out\_array1d}] array holding the reduction result. out\_array1d[1] +\item[\texttt{out\_array1d}] array holding the reduction result. out\_array1d[1] = Reduction(in\_array[1]). -\item[{\tt xsize}] the size of the one dimensional array. +\item[\texttt{xsize}] the size of the one dimensional array. \end{Lentry} \vskip 0.25cm @@ -2922,12 +2922,12 @@ call CCTK_ReduceLocArrayToArray2D( int returnvalue } \begin{Lentry} -\item[{\tt in\_array1d}] two dimensional local arrays, to be reduced across a +\item[\texttt{in\_array1d}] two dimensional local arrays, to be reduced across a processors, element by element. -\item[{\tt out\_array1d}] two dimensional array holding the reduction +\item[\texttt{out\_array1d}] two dimensional array holding the reduction result. out\_array2d[i,j]= Reduction(in\_array2d[i,j]). -\item[{\tt xsize}] the size of the one dimensional array in x direction. -\item[{\tt ysize}] the size of the one dimensional array in y direction. +\item[\texttt{xsize}] the size of the one dimensional array in x direction. +\item[\texttt{ysize}] the size of the one dimensional array in y direction. \end{Lentry} \vskip 0.25cm @@ -2961,13 +2961,13 @@ call CCTK_ReduceLocArrayToArray3D(int returnvalue } \begin{Lentry} -\item[{\tt in\_array3d}] two dimensional local arrays, to be reduced across a +\item[\texttt{in\_array3d}] two dimensional local arrays, to be reduced across a processors, element by element. -\item[{\tt out\_array3d}] two dimensional array holding the reduction +\item[\texttt{out\_array3d}] two dimensional array holding the reduction result. out\_array3d[i,j,k]= Reduction(in\_array3d[i,j,k]). -\item[{\tt xsize}] the size of the one dimensional array in x direction. -\item[{\tt ysize}] the size of the one dimensional array in y direction. -\item[{\tt ysize}] the size of the one dimensional array in z direction. +\item[\texttt{xsize}] the size of the one dimensional array in x direction. +\item[\texttt{ysize}] the size of the one dimensional array in y direction. +\item[\texttt{ysize}] the size of the one dimensional array in z direction. \end{Lentry} \vskip .25cm @@ -2975,9 +2975,9 @@ result. out\_array3d[i,j,k]= Reduction(in\_array3d[i,j,k]). {\bf Some brief examples:} {\bf Reduction of a local scalars:} a local error is reduced across all -processors with the maximum operation. The variable {\tt tmp} will +processors with the maximum operation. The variable \texttt{tmp} will hold the maximum of the error and is the same on all -processors. This quantity can then be reassigned to {\tt normerr}. +processors. This quantity can then be reassigned to \texttt{normerr}. \begin{verbatim} CCTK_REAL normerr, tmp integer ierr, reduction_handle @@ -2985,23 +2985,23 @@ processors. This quantity can then be reassigned to {\tt normerr}. call CCTK_ReductionArrayHandle(reduction_handle,"maximum") if (reduction_handle.lt.0) then - call CCTK_WARN(1,"Cannot get reduction handle for maximum operation.") + call CCTK_WARN(CCTK_WARN_ALERT, "Cannot get reduction handle for maximum operation.") endif call CCTK_ReduceLocScalar(ierr, cctkGH, -1, . reduction_handle, . normerr, tmp, CCTK_VARIABLE_REAL) if (ierr.ne.0) then - call CCTK_WARN(1,"Reduction of norm failed!"); + call CCTK_WARN(CCTK_WARN_ALERT, "Reduction of norm failed!"); endif normerr = tmp \end{verbatim} {\bf Reduction of a local 2d array:} a two dimensional array $(2x3)$ is -reduced, reduction results (array of same size: {\tt bla\_tmp}) is seen +reduced, reduction results (array of same size: \texttt{bla\_tmp}) is seen on all processors ($-1$ entry as the third argument); also demonstrates -some simple error checking with the {\tt CCTKi\_EXPECTOK} macro. +some simple error checking with the \texttt{CCTKi\_EXPECTOK} macro. \begin{verbatim} CCTK_REAL bla(2,3),bla_tmp(2,3); integer ierr, sum_handle @@ -3034,10 +3034,10 @@ 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 ones starting -with ``{\tt //}''), +with ``\texttt{//}''), should only be used in C++ source code). -The Flesh and the Cactus thorns use the {\tt grdoc} Code Documenting +The Flesh and the Cactus thorns use the \texttt{grdoc} Code Documenting System\\(\url{http://jean-luc.aei.mpg.de/Codes/grdoc/}) to document source code. @@ -3047,9 +3047,9 @@ source code. \label{sec:prrutiin} 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()}. +at runtime, use the macro \texttt{CCTK\_INFO} or the function \texttt{CCTK\_VInfo()}. -For example, from the Fortran thorn {\tt MyThorn}, +For example, from the Fortran thorn \texttt{MyThorn}, \begin{verbatim} call CCTK_INFO("Starting Tricky Calculation") \end{verbatim} @@ -3061,12 +3061,12 @@ will write the line: For a multiprocessor run, only runtime information from processor zero will be printed to screen by default. The standard output of other processors -will usually be discarded unless the ``{\tt -r}'' command line option is used +will usually be discarded unless the ``\texttt{-r}'' command line option is used (Section~\ref{sec:command_line_options}). -Note that the routine {\tt CCTK\_VInfo()} can only be called from C because +Note that the routine \texttt{CCTK\_VInfo()} can only be called from C because Fortran doesn't know about variable argument lists. So including variables in -the info message using {\tt CCTK\_INFO} is currently more tricky, since you +the info message using \texttt{CCTK\_INFO} is currently more tricky, since you need to build the string to be output. For example, in C you would just write @@ -3096,11 +3096,11 @@ In Fortran 90, you can also do: Note that: \begin{itemize} -\item{} {\tt CCTK\_INFO} is just a macro which expands to a call to - the internal function {\tt CCTK\_Info()} and automatically includes +\item{} \texttt{CCTK\_INFO} is just a macro which expands to a call to + the internal function \texttt{CCTK\_Info()} and automatically includes the thorn name in function call. -\item{} {\tt CCTK\_INFO} should be used rather than print statements, +\item{} \texttt{CCTK\_INFO} should be used rather than print statements, since it will give consistent behaviour on multiprocessors, and also provides a mechanism for switching the output to screen on and off, even on a thorn-by-thorn basis. (Although this is @@ -3112,55 +3112,93 @@ Note that: \section{Error handling, warnings and code termination} \sectionmark{Error handling, ...} \label{sec:erhawancote} -The Cactus function {\tt CCTK\_VWarn()} and its accompanying {\tt CCTK\_WARN} -macro should be used to issue warning messages during code execution. -Along with the warning message, an integer is given to indicate the severity of -the warning. The warning severity indicates whether the message is actually -printed to standard error and whether the code should be stopped. A level 0 -warning indicates the highest severity, with higher numbers indicating lower -severity. - -By default, a Cactus run will abort on a level 0 warning -and will report level 1 and severer warnings to screen. -This behaviour can be amended using command line arguments, -as described in Section~\ref{sec:command_line_options}. - -For example, to provide a warning which will be printed to standard -error but which will not terminate the code for a run with default -options, a level 1 warning should be used. +The Cactus function \texttt{CCTK\_VWarn()} and its accompanying +\texttt{CCTK\_WARN} macro should be used to issue warning messages +during code execution. + +Along with the warning message, an integer is given to indicate the +severity of the warning. Only warnings with severity levels less +than or equal to the global Cactus warning level threshold%%% +\footnote{%%% + As discussed in section~\ref{sec:command_line_options} + of this manual, the Cactus warning level threshold is + set with the \texttt{-W} or \texttt{-warning-level} + command-line option when running Cactus; see + section~\ref{sec:command_line_options}. + }%%% +{} will be printed. A level~0 warning indicates the highest severity +(and is guaranteed to abort the Cactus run), while larger numbers +indicate less severe warnings. The global Cactus warning level threshold +defaults to~1, \ie{} level~1 warnings are printed, but level~2 and higher +are not printed. + +The severity level may actually be any integer, and a lot of existing +code uses bare ``magic number'' integers for warning levels, but to +help standardize warning levels across thorns, new code should probably +use one of the following macros, defined in \verb|"cctk_WarnLevel.h"| +(which is \verb|#include|d by \verb|"cctk.h"|): +\begin{verbatim} +#define CCTK_WARN_ABORT 0 /* abort the Cactus run */ +#define CCTK_WARN_ALERT 1 /* the results of this run will probably */ + /* be wrong, but this isn't quite certain, */ + /* so we're not going to abort the run */ +#define CCTK_WARN_COMPLAIN 2 /* the user should know about this, but */ + /* the results of this run are probably ok */ +#define CCTK_WARN_PICKY 3 /* this is for small problems that can */ + /* probably be ignored, but that careful */ + /* people may want to know about */ +#define CCTK_WARN_DEBUG 4 /* these messages are probably useful */ + /* only for debugging purposes */ +\end{verbatim} + +For example, to provide a warning for a serious problem, which +indicates that the results of the run are quite likely wrong, +and which will be printed to the screen by default, +a level~\verb|CCTK_WARN_ALERT| warning should be used. The syntax from Fortran is \begin{verbatim} - call CCTK_WARN(1, "Your warning message") + call CCTK_WARN(CCTK_WARN_ALERT, "Your warning message") \end{verbatim} and from C \begin{verbatim} - CCTK_WARN(1, "Your warning message"); + CCTK_WARN(CCTK_WARN_ALERT, "Your warning message"); \end{verbatim} -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 -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 +Note that \texttt{CCTK\_WARN} is just a macro which expands to a call +to an internal function. The macro automatically includes the thorn name +and the source code file name and line number in the message.%%% +\footnote{%%% + In calling \texttt{CCTK\_VWarn()} you need to + provide this information yourself. Cactus + provides the macro \texttt{CCTK\_THORNSTRING} + which is the character-string name of the + current thorn. In C, you can get the source + file name and line number from the predefined + preprocessor macros \texttt{\_\_FILE\_\_} and + \texttt{\_\_LINE\_\_} respectively. In Fortran + you're out of luck. :( + }%%% +{} (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 \texttt{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. -Note that the routine {\tt CCTK\_VWarn()} can only be called from C because +Note that the routine \texttt{CCTK\_VWarn()} can only be called from C because Fortran doesn't know about variable argument lists. So including variables in -the warning message using {\tt CCTK\_WARN} is currently more tricky, since you -need to build the string to be output. +the warning message using \texttt{CCTK\_WARN} is currently more tricky, since +you need to build the string to be output. For example, in C you would just write \begin{verbatim} int myint; double myreal; - CCTK_VWarn(1, __LINE__, __FILE__, CCTK_THORNSTRING, + CCTK_VWarn(CCTK_WARN_ALERT, __LINE__, __FILE__, CCTK_THORNSTRING, "Your warning message, including %f and %d", myreal, myint); \end{verbatim} @@ -3172,7 +3210,7 @@ But in Fortran you have to do the following: character*200 message write (message, '("Your warning message, including ",g12.7," and ",i8)') myreal, myint - call CCTK_WARN (1, message) + call CCTK_WARN (CCTK_WARN_ALERT, message) \end{verbatim} In Fortran 90, you can also do: @@ -3182,7 +3220,7 @@ In Fortran 90, you can also do: character(200) message write (message, '("Your warning message, including ",g12.7," and ",i8)') myreal, myint - call CCTK_WARN (1, message) + call CCTK_WARN (CCTK_WARN_ALERT, message) \end{verbatim} The Flesh will be implementing standard error return codes @@ -3199,20 +3237,20 @@ used. 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 -standard places for adding thorn documentation, a {\tt README} and a -file {\tt doc/documentation.tex} for including in Thorn Guides. +to a thorn (ideally in the \texttt{doc} directory), there are two +standard places for adding thorn documentation, a \texttt{README} and a +file \texttt{doc/documentation.tex} for including in Thorn Guides. -\subsection{{\tt README}} +\subsection{\texttt{README}} -The {\tt README}, in the top level of a thorn, should contain brief +The \texttt{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 Thorn Guide} -The LaTeX file {\tt doc/documentation.tex} is included in Thorn Guides -built by the Cactus make system. (e.g.\ by {\tt gmake +The LaTeX file \texttt{doc/documentation.tex} is included in Thorn Guides +built by the Cactus make system. (e.g.\ by \texttt{gmake $<$\var{config}$>$-ThornGuide}). Ideally this file should contain complete (and \textit{up-to-date}) details about the thorn, exactly what is relevant is for the authors to decide, but remember that the Cactus @@ -3246,10 +3284,10 @@ sections include: A LaTeX template for the Thorn Guide documentation can be found in the Flesh distribution at -{\tt doc/ThornGuide/template.tex}, +\texttt{doc/ThornGuide/template.tex}, this file is automatically copied to the correct location in a new thorn -which is created with {\tt gmake newthorn}. +which is created with \texttt{gmake newthorn}. Since Cactus scripts need to parse this documentation, and since the LaTeX document should be consistent across all thorns included in a @@ -3259,7 +3297,7 @@ documentation: \begin{itemize} \item Use the Cactus Thorn Guide style file, located in the Flesh - distribution at {\tt doc/latex/cactus.sty}. This should be + distribution at \texttt{doc/latex/cactus.sty}. This should be included using a relative link, so that updates to the style file are applied to all thorns. % @@ -3267,27 +3305,27 @@ documentation: \usepackage{../../../../doc/latex/cactus} \end{verbatim} - \item Aside from the {\tt date}, {\tt author}, and {\tt title} fields, + \item Aside from the \texttt{date}, \texttt{author}, and \texttt{title} fields, all of the documentation to be included in a Thorn Guide should be placed between the lines - {\tt \% START CACTUS THORNGUIDE} + \texttt{\% START CACTUS THORNGUIDE} and - {\tt \% END CACTUS THORNGUIDE} + \texttt{\% END CACTUS THORNGUIDE} - \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} + \item The command \texttt{$\backslash$def} can be used to define macros, but all + such definitions must lie between the \texttt{START} and \texttt{END} 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. - Graphics figures should be included using the {\tt includegraphics} - command (not {\tt epsffig}), with no file extension specified. For example, + \item Currently we only support PostScript (\texttt{.eps or .ps}) figures. + Graphics figures should be included using the \texttt{includegraphics} + command (not \texttt{epsffig}), with no file extension specified. For example, % \begin{verbatim} \begin{figure}[ht] @@ -3301,7 +3339,7 @@ and \item All {\bf labels}, {\bf citations}, {\bf references}, and {\bf graphic images} names should conform to the following guidelines: - {\tt ARRANGEMENT\_THORN\_LABEL}. For instance, if you arrangement is + \texttt{ARRANGEMENT\_THORN\_LABEL}. For instance, if you arrangement is called CactusWave, your thorn WaveToyC, and your original image blackhole.eps, you should rename your image to be {\tt CactusWave\_WaveToyC\_blackhole.eps} @@ -3329,21 +3367,21 @@ 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, and that these files are in the directory -{\tt ./<parameter file base name>}. +\texttt{./<parameter file base name>}. Run Cactus on each of the parameter files, and move the parameter files, -and the output directories they produced, to the {\tt test} directory +and the output directories they produced, to the \texttt{test} directory in your thorn. Document carefully any situations or architectures in which your test suite does not give the correct answers. You can also specify options for running your testsuite by adding an -optional configuration file called {\tt test.ccl} in the {\tt test} +optional configuration file called \texttt{test.ccl} in the \texttt{test} directory. These are simple text files and may contain comments -introduced by the hash `{\tt \#}' character, which indicates that the +introduced by the hash `\texttt{\#}' character, which indicates that the rest of the line is a comment. If the last non-blank character of a -line in a config file is a backslash `{\tt $\backslash$}', the +line in a config file is a backslash `\texttt{$\backslash$}', the following line is treated as a continuation of the current line. Options include test specific absolute and relative tolerances, thorn specific absolute and relative tolerances and file extensions. The @@ -3366,7 +3404,7 @@ which states that when comparing files of test \verb|test_example|, the absolute and relative tolerances. For all other tests in the thorn, the default value of absolute and relative tolerances are set to \verb|thorn_absolute_tolerance| and -\verb|thorn_relative_tolerance|. The {\tt EXTENSIONS} option adds +\verb|thorn_relative_tolerance|. The \texttt{EXTENSIONS} option adds \verb|extension_1|, \verb|extension_2| and \verb|extension_3| to the list of file extensions that are compared. This list is global over all tests in a configuration. @@ -3415,9 +3453,9 @@ ways (provided the underlying functionality is available on your system): \begin{Lentry} -\item[{\tt GetTimeOfDay}] +\item[\texttt{GetTimeOfDay}] Provides ``wall clock time'' via the unix \texttt{gettimeofday} function. -\item[{\tt GetrUsage}] +\item[\texttt{GetrUsage}] Provides CPU usage time via the unix \texttt{getrusage} function. \end{Lentry} @@ -3523,14 +3561,14 @@ from the {\t cTimerVal} pointer argument. \subsection{How to insert timers in your code} The function prototypes and structure definitions are contained in the -include file {\tt cctk\_Timers.h}, which is included in the standard -thorn header file {\tt cctk.h}. At the moment the timer calls are only +include file \texttt{cctk\_Timers.h}, which is included in the standard +thorn header file \texttt{cctk.h}. At the moment the timer calls are only available from C. The following example, which uses a timer to instrument a section of code, illustrates how timers are used by application thorns. A working example is available in the thorn -{\tt CactusTest/TestTimers}. +\texttt{CactusTest/TestTimers}. {\bf Creating a timer} @@ -3595,11 +3633,11 @@ include files which can be used by any other thorn. Such include files can contain executable source code, or header/declaration 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}. +not active by being wrapped by a call to \texttt{CCTK\_IsThornActive}. Any thorn which uses the include file must declare this in its -{\tt interface.ccl} with the line +\texttt{interface.ccl} with the line \begin{alltt} USES INCLUDE [SOURCE|HEADER]: <\var{file_name}> @@ -3611,7 +3649,7 @@ code which is incorrectly assumed to be \emph{header} code will be executed in another thorn \emph{even if the providing thorn is inactive}. Thus it is recommended to always include the optional \verb![SOURCE|HEADER]! specification.) Any thorn which wishes to add -to this include file, declares in its own {\tt interface.ccl} +to this include file, declares in its own \texttt{interface.ccl} \begin{alltt} INCLUDE [SOURCE|HEADER]: <\var{file_to_include}> in <\var{file_name}> @@ -3630,18 +3668,18 @@ c Get source code from other thorns allterms = 0d0 #include "AllSources.inc" \end{verbatim} -and would then add to {\tt interface.ccl} the line +and would then add to \texttt{interface.ccl} the line \begin{verbatim} USES INCLUDE SOURCE: AllSources.inc \end{verbatim} If thorn B wants to add terms for the calculation, it would -create a file, say {\tt Bterms.inc} with the lines +create a file, say \texttt{Bterms.inc} with the lines \begin{verbatim} c Add this to AllSources.inc allterms = allterms + 1d0 \end{verbatim} -and would add to its own {\tt interface.ccl} +and would add to its own \texttt{interface.ccl} \begin{verbatim} INCLUDE SOURCE: Bterms.inc in AllSources.inc @@ -3658,7 +3696,7 @@ c Add this to AllSources.inc \end{verbatim} Any Fortran thorn routines which include source code must include -the declaration {\tt DECLARE\_CCTK\_FUNCTIONS}. +the declaration \texttt{DECLARE\_CCTK\_FUNCTIONS}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -3666,7 +3704,7 @@ the declaration {\tt DECLARE\_CCTK\_FUNCTIONS}. \label{sec:metr} Cactus provides a mechanism for overriding the standard C memory -allocation routines ({\tt malloc, free,} \ldots) with Cactus specific +allocation routines (\texttt{malloc, free,} \ldots) with Cactus specific routines, that track the amount of memory allocated and from where the allocation call was made. This information can be accessed by the user to provide an understanding of the memory consumption between two @@ -3677,16 +3715,16 @@ available in C only. \label{sec:acmetr} Memory tracing has to be activated at configure time. The standard -{\tt malloc} statements are overridden with macros ({\tt CCTK\_MALLOC}). To +\texttt{malloc} statements are overridden with macros (\texttt{CCTK\_MALLOC}). To activate memory tracing use either \begin{Lentry} -\item[{\tt DEBUG=all}] Enables all debug options (compiler debug -flags, redefines {\tt malloc}) -\item[{\tt DEBUG=memory}] Redefine {\tt malloc} only. +\item[\texttt{DEBUG=all}] Enables all debug options (compiler debug +flags, redefines \texttt{malloc}) +\item[\texttt{DEBUG=memory}] Redefine \texttt{malloc} only. \end{Lentry} -The {\tt CCTK\_MALLOC} statements can also be used directly in the C +The \texttt{CCTK\_MALLOC} statements can also be used directly in the C code. But by employing them this way, only a fraction of the total memory consumption is traced. Also, they cannot be turned off at configure time. (this behavior might change). For example: @@ -3695,8 +3733,8 @@ machine> gmake bigbuild DEBUG=yes machine> gmake bigbuild-config DEBUG=memory \end{verbatim} -The new configuration {\tt bigbuild} is configured with all debugging -features turned on. The already existing configuration {\tt bigbuild} +The new configuration \texttt{bigbuild} is configured with all debugging +features turned on. The already existing configuration \texttt{bigbuild} is reconfigured with memory tracing only. \subsection{Using Memory Tracing} @@ -3707,13 +3745,13 @@ instance in the program flow and return the difference in memory allocation some time later. \begin{Lentry} -\item[{\tt int CCTK\_MemTicketRequest(void)}] +\item[\texttt{int CCTK\_MemTicketRequest(void)}] 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 - {\tt CCTK\_MemTicketCash}. + \texttt{CCTK\_MemTicketCash}. -\item[{\tt long int CCTK\_MemTicketCash(int your\_ticket)}] +\item[\texttt{long int CCTK\_MemTicketCash(int your\_ticket)}] Cash in your ticket: return the memory difference between now and the time the ticket was requested. Tickets can be cashed in several times. See Example below. @@ -3722,22 +3760,22 @@ allocation some time later. done to provide the database, motivation is that this is not allocated either if you compile undebugged. -\item[{\tt int CCTK\_MemTicketDelete(int your\_ticket)}] +\item[\texttt{int CCTK\_MemTicketDelete(int your\_ticket)}] 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. -\item[{\tt unsigned long int CCTK\_TotalMemory(void)}] +\item[\texttt{unsigned long int CCTK\_TotalMemory(void)}] Returns the total allocated memory (not including the tracing data structures). -\item[{\tt void CCTK\_MemStat}] Prints an info string, stating the current, +\item[\texttt{void CCTK\_MemStat}] Prints an info string, stating the current, past and total memory (in bytes) allocation between two successive calls to this routine, as well as the difference. \end{Lentry} Sample C code demonstrating the ticket handling. Two tickets are -requested during {\tt malloc} operations. The {\tt CCTK\_MALLOC} statement is +requested during \texttt{malloc} operations. The \texttt{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. @@ -3789,14 +3827,14 @@ int <routine name>(<argument list>)\\ } also callable from Fortran, a new routine must added, which is -declared using the {\tt CCTK\_FCALL} and {\tt CCTK\_FNAME} macros: +declared using the \texttt{CCTK\_FCALL} and \texttt{CCTK\_FNAME} macros: {\tt void CCTK\_FCALL CCTK\_FNAME(<routine name>)(int *ierr, <argument list>)\\ <rewrite routine code, or call C routine itself> } -The convention used in Cactus is that {\tt <routine name>} be the same as any +The convention used in Cactus is that \texttt{<routine name>} be the same as any 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. @@ -3830,7 +3868,7 @@ void CCTK_FCALL CCTK_FNAME(MyCRoutine)(CCTK_INT *arg1, Fortran passes string arguments in a special, compiler-dependent, way. To facilitate this, the CCTK provides a set of macros to enable the translation to C strings. -The macros are defined in {\tt cctk\_FortranString.h} which +The macros are defined in \texttt{cctk\_FortranString.h} which should be included in your C file. String arguments \emph{must always come last} in the argument list for @@ -3839,38 +3877,38 @@ migrate the strings to the end so there is no portable workaround). The macros to use depends upon the number of string arguments -- we currently support up to three. The macros are -{\tt <ONE|TWO|THREE>\_FORTSTRING\_ARG}. +\texttt{<ONE|TWO|THREE>\_FORTSTRING\_ARG}. Corresponding to each of these are two macros -{\tt <ONE|TWO|THREE>\_FORTSTRING\_CREATE} and -{\tt <ONE|TWO|THREE>\_FORTSTRING\_PTR} +\texttt{<ONE|TWO|THREE>\_FORTSTRING\_CREATE} and +\texttt{<ONE|TWO|THREE>\_FORTSTRING\_PTR} which take one,two,or three arguments depending on the number of strings. The latter set is only necessary if a string is to be modified. In more detail: \begin{Lentry} -\item[{\tt <ONE|TWO|THREE>\_FORTSTRING\_ARG}] +\item[\texttt{<ONE|TWO|THREE>\_FORTSTRING\_ARG}] Used in the argument list of the C routine to which the Fortran strings are passed. -\item[{\tt <ONE|TWO|THREE>\_FORTSTRING\_CREATE}] +\item[\texttt{<ONE|TWO|THREE>\_FORTSTRING\_CREATE}] Used in the declaration section of the C routine to which the Fortran strings are passed. These macros have one, two or three arguments which are the variable names you choose to use for the strings in the C routine, created - by null-terminating the passed-in Fortran strings. The {\tt CREATE} + by null-terminating the passed-in Fortran strings. The \texttt{CREATE} macros create new strings with the names you provide, and thus should be treated as read-only and freed after use. -\item[{\tt <ONE|TWO|THREE>\_FORTSTRING\_PTR}] +\item[\texttt{<ONE|TWO|THREE>\_FORTSTRING\_PTR}] These macros, used in the declaration section of the C routine - \emph{after} the {\tt CREATE} macro, + \emph{after} the \texttt{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. -\item[{\tt cctk\_strlen<1|2|3>}] these integer variables, +\item[\texttt{cctk\_strlen<1|2|3>}] these integer variables, automatically defined by - the {\tt CREATE} macro, hold the lengths of the passed in + the \texttt{CREATE} macro, hold the lengths of the passed in Fortran strings. \end{Lentry} @@ -3909,9 +3947,9 @@ Since the null terminated strings may be copies of the strings passed 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 +the \texttt{FORTSTRING\_PTR} macros, which declare and set up pointers to the strings passed from C. Note that this macro must be used -\emph{after} the {\tt FORTSTRING\_CREATE} macro. For example, the +\emph{after} the \texttt{FORTSTRING\_CREATE} macro. For example, the following routine copies the contents of the second string to the first string. @@ -3947,7 +3985,7 @@ int CCTK_FCALL CCTK_FNAME(CopyStrings)(TWO_FORTSTRING_ARG) Note that in the example above two new variables, pointers to 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} +automatically-created variables (e.g.\ \texttt{cctk\_strlen1} which hold the sizes of original Fortran strings. When writing to a string its length should never be exceeded. @@ -4007,15 +4045,15 @@ REQUIRES FUNCTION SumStuff USES FUNCTION SumStuff \end{verbatim} A prototype of this function will be available to any C routine that -includes the {\tt cctk.h} header file. +includes the \texttt{cctk.h} header file. In a Fortran file, the declaration of the function will be included -in the {\tt DECLARE\_CCTK\_FUNCTIONS} macro, which is available after +in the \texttt{DECLARE\_CCTK\_FUNCTIONS} macro, which is available after the statement \texttt{\#include "cctk\_Functions.h"}. -The keywords {\tt IN} and {\tt OUT} -work in the same fashion as {\tt INTENT} statements in Fortran 90. -That is, the C prototype will expect an argument with intent {\tt IN} -to be a value and one with intent {\tt OUT} to be a pointer. There -also exists the {\tt ARRAY} keyword for passing arrays of any +The keywords \texttt{IN} and \texttt{OUT} +work in the same fashion as \texttt{INTENT} statements in Fortran 90. +That is, the C prototype will expect an argument with intent \texttt{IN} +to be a value and one with intent \texttt{OUT} to be a pointer. There +also exists the \texttt{ARRAY} keyword for passing arrays of any dimension. Functions which are required by some thorn (which doesn't provide it itself) are checked at startup to be provided by some other thorn. @@ -4024,7 +4062,7 @@ are checked at startup to be provided by some other thorn. \subsection{Providing a function} To provide an aliased function you must again add the prototype to -your {\tt interface.ccl} file. A statement containing the name of the +your \texttt{interface.ccl} file. A statement containing the name of the providing function and the language it is provided in must also be given. For example, \begin{verbatim} @@ -4043,18 +4081,18 @@ default will be assumed. Various restrictions are necessary to make function aliasing work. These are \begin{itemize} -\item The return type of any function must be either {\tt void} or one - of the Cactus data types {\tt CCTK\_INT} or {\tt - CCTK\_REAL}. Standard types such as {\tt int} are not allowed. +\item The return type of any function must be either \texttt{void} or one + of the Cactus data types \texttt{CCTK\_INT} or {\tt + CCTK\_REAL}. Standard types such as \texttt{int} are not allowed. \item The type of an argument must be one of scalar types {\tt CCTK\_INT, CCTK\_REAL, CCTK\_STRING, CCTK\_POINTER, - CCTK\_FPOINTER}, or an array or pointer type {\tt CCTK\_INT ARRAY, + CCTK\_FPOINTER}, or an array or pointer type \texttt{CCTK\_INT ARRAY, CCTK\_REAL ARRAY}. The scalar types are assumed to be not modifiable. Any changes made to a scalar argument by a providing function may be silently lost, or may not; it is dependent on the language of the providing and calling function. If you wish to - modify an argument then it must have intent {\tt OUT} (and hence - must be either a {\tt CCTK\_INT} or {\tt CCTK\_REAL}). + modify an argument then it must have intent \texttt{OUT} (and hence + must be either a \texttt{CCTK\_INT} or \texttt{CCTK\_REAL}). \item The name of both the aliased and providing function are restricted. They must follow the standard C semantics (start with a letter, contain only letters, numbers or underscores). Additionally, @@ -4069,10 +4107,10 @@ CCTK_REAL Integrate(CCTK_REAL CCTK_FPOINTER func(CCTK_REAL IN x), \ It is assumed that the function pointer argument has the same language as the calling function. Function pointer arguments may not be nested. -\item {\tt CCTK\_STRING} arguments follow the same conventions as in +\item \texttt{CCTK\_STRING} arguments follow the same conventions as in the previous section. That is, they must appear at the end of the argument list, there must be at most three, and a function with a - {\tt CCTK\_STRING} argument can only be provided in C, not Fortran, + \texttt{CCTK\_STRING} argument can only be provided in C, not Fortran, although they may be called from either. \end{itemize} @@ -4095,11 +4133,11 @@ CCTK_REAL Integrate(CCTK_REAL CCTK_FPOINTER func(CCTK_REAL IN x), \ PROVIDES FUNCTION Invert WITH FindInverse LANGUAGE Fortran USES FUNCTION Invert \end{verbatim} -\noindent Note that {\tt SUBROUTINE} has the same meaning as {\tt void +\noindent Note that \texttt{SUBROUTINE} has the same meaning as \texttt{void FUNCTION}. \item A Fortran function is provided that integrates any function over - an interval. The {\tt interface.ccl} should read + an interval. The \texttt{interface.ccl} should read \begin{verbatim} CCTK_REAL Integrate(CCTK_REAL CCTK_FPOINTER func(CCTK_REAL IN x), \ CCTK_REAL IN xmin, CCTK_REAL IN xmax) @@ -4115,7 +4153,7 @@ The calling thorn does not know if an aliased function is even provided by another thorn. Calling an aliased function that has not been provided will lead to a level 0 warning message, stopping the code. In order to check if a function has been provided by some thorn, -use the {\tt CCTK\_IsFunctionAliased} function described in the +use the \texttt{CCTK\_IsFunctionAliased} function described in the function reference section. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -4127,11 +4165,11 @@ 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 a - hash mark `{\tt \#}' or dot `{\tt .}' - or end in a tilde `{\tt \~{}}', {\tt .bak} or {\tt .BAK}. + hash mark `\texttt{\#}' or dot `\texttt{.}' + or end in a tilde `\texttt{\~{}}', \texttt{.bak} or \texttt{.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}. + hash mark `\texttt{\#}' or dot `\texttt{.}' + or end in a tilde `\texttt{\~{}}', \texttt{.bak} or \texttt{.BAK}. \item{} Routine names have to be unique among all thorns. \end{itemize} @@ -4147,11 +4185,11 @@ allow for a homogeneous code. \begin{itemize} \item Parameters: lower case (except for acronyms) with words separated - by an underscore. Examples: {\tt my\_first\_parameter}, - {\tt solve\_PDE\_equation}. + by an underscore. Examples: \texttt{my\_first\_parameter}, + \texttt{solve\_PDE\_equation}. \item Filenames and routine names: Prefixed by thorn name with an underscore, then capitalised words, with no spaces. - Examples: {\tt MyThorn\_StartUpRoutine}, {\tt BestSolver\_InitialDataForPDE}. + Examples: \texttt{MyThorn\_StartUpRoutine}, \texttt{BestSolver\_InitialDataForPDE}. \end{itemize} @@ -4269,9 +4307,9 @@ Data Type & Variable Type & C equivalent \\ \subsection{Fortran Thorn Writers} -Cactus provides a further data type {\tt CCTK\_POINTER} +Cactus provides a further data type \texttt{CCTK\_POINTER} for use in Fortran code to declare a pointer passed from C. -For example, the variable {\tt cctkGH} is of this type. +for example, the variable \texttt{cctkGH} is of this type. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |