% /*@@
%   @file      CCTKReference.tex
%   @date      27 Jan 1999
%   @author    Tom Goodale, Gabrielle Allen, Gerd Lanferman
%   @desc
%   Function Reference for the Cactus User's Guide
%   @enddesc
%   @version $Header$
%   @history
%   @date       Sat Nov  3 18:47:53 MET 2001
%   @author     Jonathan Thornburg <jthorn@aei.mpg.de>
%   @desc       Add new section for Utility functions,
%               add key/value table functions in that section
%   @endhistory
%   @history
%   @date       Sun Jul 20 13:28:43 CEST 2003
%   @author     Jonathan Thornburg <jthorn@aei.mpg.de>
%   @desc       rename this to CCTKReference.tex,
%               split Util_*() functions off into a separate file
%               UtilReference.tex
%   @endhistory
% @@*/

\begin{cactuspart}{\code{CCTK\_*} Functions Reference}{}{$Revision$}
\label{part:CCTKReference}
\renewcommand{\thepage}{\Alph{part}\arabic{page}}

In this chapter all \code{CCTK\_*} Cactus functions are described.
These functions are callable from Fortran or C thorns.  Note that whereas
all functions are available from C, not all are currently available
from Fortran.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Functions Alphabetically}


\begin{Lentry}

\item[\code{CCTK\_Abort}] [\pageref{CCTK-Abort}]
  Causes abnormal Cactus termination

\item[\code{CCTK\_ActivatingThorn}] [\pageref{CCTK-ActivatingThorn}]
  Finds the thorn which activated a particular implementation

\item[\code{CCTK\_ActiveTimeLevels}] [\pageref{CCTK-ActiveTimeLevels}]
  Returns the number of active timelevels from a group name

\item[\code{CCTK\_ActiveTimeLevelsGI}] [\pageref{CCTK-ActiveTimeLevels}]
  Returns the number of active timelevels from a group index

\item[\code{CCTK\_ActiveTimeLevelsGN}] [\pageref{CCTK-ActiveTimeLevels}]
  Returns the number of active timelevels from a group name

\item[\code{CCTK\_ActiveTimeLevelsVI}] [\pageref{CCTK-ActiveTimeLevels}]
  Returns the number of active timelevels from a variable index

\item[\code{CCTK\_ActiveTimeLevelsVN}] [\pageref{CCTK-ActiveTimeLevels}]
  Returns the number of active timelevels from a variable name

\item[\code{CCTK\_ArrayGroupSize}] [\pageref{CCTK-ArrayGroupSize}]
  Returns a pointer to the local size for a group, given by its group name

\item[\code{CCTK\_ArrayGroupSizeI}] [\pageref{CCTK-ArrayGroupSizeI}]
  Returns a pointer to the local size for a group, given by its group index

\item[\code{CCTK\_Barrier}] [\pageref{CCTK-Barrier}]
  Synchronizes all processors

\item[\code{CCTK\_ClockRegister}] [\pageref{CCTK-ClockRegister}]
  Registers a new named clock with the Flesh.

\item[\code{CCTK\_Cmplx}] [\pageref{CCTK-Cmplx}]
  Turns two real numbers into a complex number (only C)

\item[\code{CCTK\_CmplxAbs}] [\pageref{CCTK-CmplxAbs}]
  Returns the absolute value of a complex number (only C)

\item[\code{CCTK\_CmplxAdd}] [\pageref{CCTK-CmplxAdd}]
  Returns the sum of two complex numbers (only C)

\item[\code{CCTK\_CmplxConjg}] [\pageref{CCTK-CmplxConjg}]
  Returns the complex conjugate of a complex number (only C)

\item[\code{CCTK\_CmplxCos}] [\pageref{CCTK-CmplxCos}]
  Returns the Cosine of a complex number (only C) [not yet available]

\item[\code{CCTK\_CmplxDiv}] [\pageref{CCTK-CmplxDiv}]
  Returns the division of two complex numbers (only C)

\item[\code{CCTK\_CmplxExp}] [\pageref{CCTK-CmplxExp}]
  Returns the Exponentiation of a complex number (only C) [not yet available]

\item[\code{CCTK\_CmplxImag}] [\pageref{CCTK-CmplxImag}]
  Returns the imaginary part of a complex number (only C)

\item[\code{CCTK\_CmplxLog}] [\pageref{CCTK-CmplxLog}]
  Returns the Logarithm of a complex number (only C) [not yet available]

\item[\code{CCTK\_CmplxMul}] [\pageref{CCTK-CmplxMul}]
  Returns the multiplication of two complex numbers (only C)

\item[\code{CCTK\_CmplxReal}] [\pageref{CCTK-CmplxReal}]
  Returns the real part of a complex number (only C)

\item[\code{CCTK\_CmplxSin}] [\pageref{CCTK-CmplxSin}]
  Returns the Sine of a complex number (only C) [not yet available]

\item[\code{CCTK\_CmplxSqrt}] [\pageref{CCTK-CmplxSqrt}]
  Returns the square root of a complex number (only C) [not yet available]

\item[\code{CCTK\_CmplxSub}] [\pageref{CCTK-CmplxSub}]
  Returns the subtraction of two complex numbers (only C)

\item[\code{CCTK\_CompileDate}] [\pageref{CCTK-CompileDate}]
  Returns a formatted string containing the date stamp when Cactus was compiled

\item[\code{CCTK\_CompileDateTime}] [\pageref{CCTK-CompileDateTime}]
  Returns a formatted string containing the datetime stamp when Cactus was compiled

\item[\code{CCTK\_CompileTime}] [\pageref{CCTK-CompileTime}]
  Returns a formatted string containing the time stamp when Cactus was compiled

\item[\code{CCTK\_CompiledImplementation}]
  [\pageref{CCTK-CompiledImplementation}]
  Return the name of the compiled implementation with given index

\item[\code{CCTK\_CompiledThorn}] [\pageref{CCTK-CompiledThorn}]
  Return the name of the compiled thorn with given index

\item[\code{CCTK\_CoordDir}] [\pageref{CCTK-CoordDir}]
  Give the direction for a given coordinate name \textbf{(deprecated)}

\item[\code{CCTK\_CoordIndex}] [\pageref{CCTK-CoordIndex}]
  Give the grid variable index for a given coordinate \textbf{(deprecated)}

\item[\code{CCTK\_CoordRange}] [\pageref{CCTK-CoordRange}]
  Return the global upper and lower bounds for a given coordinate name
  on a cctkGH \textbf{(deprecated)}

\item[\code{CCTK\_CoordRegisterData}] [\pageref{CCTK-CoordRegisterData}]
  Register a coordinate as belonging to a coordinate system,
  with a given name and direction, and optionally with a grid variable
  \textbf{(deprecated)}

\item[\code{CCTK\_CoordRegisterRange}] [\pageref{CCTK-CoordRegisterRange}]
  Saves the global upper and lower bounds for a given coordinate name
  on a cctkGH \textbf{(deprecated)}

\item[\code{CCTK\_CoordRegisterSystem}] [\pageref{CCTK-CoordRegisterSystem}]
  Registers a coordinate system with a given dimension \textbf{(deprecated)}

\item[\code{CCTK\_CoordSystemDim}] [\pageref{CCTK-CoordDim}]
  Provides the dimension of a given coordinate system \textbf{(deprecated)}

\item[\code{CCTK\_CoordSystemHandle}] [\pageref{CCTK-CoordSystemHandle}]
  Get the handle associated with a registered coordinate system
  \textbf{(deprecated)}

\item[\code{CCTK\_CoordSystemName}] [\pageref{CCTK-CoordSystemName}]
  Provides the name of the coordinate system identified by its handle
  \textbf{(deprecated)}

\item[\code{CCTK\_CreateDirectory}] [\pageref{CCTK-CreateDirectory}]
  Creates a directory

\item[\code{CCTK\_DecomposeName}] [\pageref{CCTK-DecomposeName}]
  Given the full name of a variable/group, separates the name
  returning both the implementation and the variable/group

\item[\code{CCTK\_DisableGroupComm}] [\pageref{CCTK-DisableGroupComm}]
  Disable the communication for a group

\item[\code{CCTK\_DisableGroupCommI}] [\pageref{CCTK-DisableGroupCommI}]
  Disable the communication for a group

\item[\code{CCTK\_DisableGroupStorage}] [\pageref{CCTK-DisableGroupStorage}]
  Disable the storage for a group

\item[\code{CCTK\_DisableGroupStorageI}] [\pageref{CCTK-DisableGroupStorageI}]
  Disable the storage for a group

\item[\code{CCTK\_EnableGroupComm}] [\pageref{CCTK-EnableGroupComm}]
  Enable the communication for a group

\item[\code{CCTK\_EnableGroupCommI}] [\pageref{CCTK-EnableGroupCommI}]
  Enable the communication for a group

\item[\code{CCTK\_EnableGroupStorage}] [\pageref{CCTK-EnableGroupStorage}]
  Enable the storage for a group

\item[\code{CCTK\_EnableGroupStorageI}] [\pageref{CCTK-EnableGroupStorageI}]
  Enable the storage for a group

\item[\code{CCTK\_Equals}] [\pageref{CCTK-Equals}]
  Check a STRING or KEYWORD parameter for equality equality
  with a given string

\item[\code{CCTK\_ERROR}] [\pageref{CCTK-ERROR}]
  Macro to print a single string as error message to standard error
  and stop the code

\item[\code{CCTK\_Error}] [\pageref{CCTK-Error}]
  Function to print a single string as error message to standard error
  and stop the code

\item[\code{CCTK\_Exit}] [\pageref{CCTK-Exit}]
  Causes normal Cactus termination

\item[\code{CCTK\_FirstVarIndex}] [\pageref{CCTK-FirstVarIndex}]
  Given a group name returns the first variable index in the group

\item[\code{CCTK\_FirstVarIndexI}] [\pageref{CCTK-FirstVarIndexI}]
  Given a group index returns the first variable index in the group

\item[\code{CCTK\_FortranString}] [\pageref{CCTK-FortranString}]
  Copy the contents of a C string into a Fortran string variable

\item[\code{CCTK\_FullName}] [\pageref{CCTK-FullName}]
  Given a variable index, returns the full name of the variable

\item[\code{CCTK\_GetClockName}] [\pageref{CCTK-GetClockName}]
  Given a pointer to a clock {\t cTimerVal} structure, returns the name
  of the clock.

\item[\code{CCTK\_GetClockResolution}] [\pageref{CCTK-GetClockResolution}]
  Given a pointer to a clock {\t cTimerVal} structure, returns the resolution
  of the clock.

\item[\code{CCTK\_GetClockSeconds}] [\pageref{CCTK-GetClockSeconds}]
  Given a pointer to a clock {\t cTimerVal} structure, returns the elapsed time.

\item[\code{CCTK\_GetClockValue}] [\pageref{CCTK-GetClockValue}]
  Given the name of a clock, returns a pointer to the corresponding
  {\t cTimerVal} structure within the {\t cTimerData} structure.

\item[\code{CCTK\_GetClockValueI}] [\pageref{CCTK-GetClockValueI}]
  Given the index of a clock, returns a pointer to the corresponding
  {\t cTimerVal} structure within the {\t cTimerData} structure.

\item[\code{CCTK\_GHExtension}] [\pageref{CCTK-GHExtension}]
  Get the pointer to a registered extension to the Cactus GH structure

\item[\code{CCTK\_GHExtensionHandle}] [\pageref{CCTK-GHExtensionHandle}]
  Get the handle associated with a extension to the Cactus GH structure

\item[\code{CCTK\_GridArrayReductionOperator}] [\pageref{CCTK-GridArrayReductionOperator}]
     The name of the implementation of a grid array reduction operator, or NULL if the handle is invalid

\item[\code{CCTK\_GroupbboxGI}] [\pageref{CCTK-GroupbboxGI}]
  Given a group index, return an array of the bounding box
  of the group for each face

\item[\code{CCTK\_GroupbboxGN}] [\pageref{CCTK-GroupbboxGN}]
  Given a group name, return an array of the bounding box
  of the group for each face

\item[\code{CCTK\_GroupbboxVI}] [\pageref{CCTK-GroupbboxVI}]
  Given a variable index, return an array of the bounding box
  of the variable for each face

\item[\code{CCTK\_GroupbboxVN}] [\pageref{CCTK-GroupbboxVN}]
  Given a variable name, return an array of the bounding box
  of the variable for each face

\item[\code{CCTK\_GroupData}] [\pageref{CCTK-GroupData}]
  Given a group index, returns information about the variables
  held in the group

\item[\code{CCTK\_GroupDimFromVarI}] [\pageref{CCTK-GroupDimFromVarI}]
  Given a variable index, returns the dimension of all variables in the group
  associated with this variable

\item[\code{CCTK\_GroupDimI}] [\pageref{CCTK-GroupDimI}]
  Given a group index, returns the dimension of variables in that group

\item[\code{CCTK\_GroupDynamicData}] [\pageref{CCTK-GroupDynamicData}]
  Given a group index, returns information about the variables
  held in the group

\item[\code{CCTK\_GroupGhostsizesI}] [\pageref{CCTK-GroupGhostsizesI}]
  Given a group index, returns the ghost size array of that group

\item[\code{CCTK\_GroupgshGI}] [\pageref{CCTK-GroupgshGI}]
  Given a group index, return an array of the global size
  of the group in each dimension

\item[\code{CCTK\_GroupgshGN}] [\pageref{CCTK-GroupgshGN}]
  Given a group name, return an array of the global size
  of the group in each dimension

\item[\code{CCTK\_GroupgshVI}] [\pageref{CCTK-GroupgshVI}]
  Given a variable index, return an array of the global size
  of the variable in each dimension

\item[\code{CCTK\_GroupgshVN}] [\pageref{CCTK-GroupgshVN}]
  Given a variable name, return an array of the global size
  of the variable in each dimension

\item[\code{CCTK\_GroupIndex}] [\pageref{CCTK-GroupIndex}]
  Get the index number for a group name

\item[\code{CCTK\_GroupIndexFromVar}] [\pageref{CCTK-GroupIndexFromVar}]
  Given a variable name, returns the index of the associated group

\item[\code{CCTK\_GroupIndexFromVarI}] [\pageref{CCTK-GroupIndexFromVarI}]
  Given a variable index, returns the index of the associated group

\item[\code{CCTK\_GrouplbndGI}] [\pageref{CCTK-GrouplbndGI}]
  Given a group index, return an array of the lower bounds
  of the group in each dimension

\item[\code{CCTK\_GrouplbndGN}] [\pageref{CCTK-GrouplbndGN}]
  Given a group name, return an array of the lower bounds
  of the group in each dimension

\item[\code{CCTK\_GrouplbndVI}] [\pageref{CCTK-GrouplbndVI}]
  Given a variable index, return an array of the lower bounds
  of the variable in each dimension

\item[\code{CCTK\_GrouplbndVN}] [\pageref{CCTK-GrouplbndVN}]
  Given a variable name, return an array of the lower bounds
  of the variable in each dimension

\item[\code{CCTK\_GrouplshGI}] [\pageref{CCTK-GrouplshGI}]
  Given a group index, return an array of the local size
  of the group in each dimension

\item[\code{CCTK\_GrouplshGN}] [\pageref{CCTK-GrouplshGN}]
  Given a group name, return an array of the local size
  of the group in each dimension

\item[\code{CCTK\_GrouplshVI}] [\pageref{CCTK-GrouplshVI}]
  Given a variable index, return an array of the local size
  of the variable in each dimension

\item[\code{CCTK\_GrouplshVN}] [\pageref{CCTK-GrouplshVN}]
  Given a variable name, return an array of the local size
  of the variable in each dimension

\item[\code{CCTK\_GroupashGI}] [\pageref{CCTK-GroupashGI}]
  Given a group index, return an array of the local allocated size
  of the group in each dimension

\item[\code{CCTK\_GroupashGN}] [\pageref{CCTK-GroupashGN}]
  Given a group name, return an array of the local allocated size
  of the group in each dimension

\item[\code{CCTK\_GroupashVI}] [\pageref{CCTK-GroupashVI}]
  Given a variable index, return an array of the local allocated size
  of the variable in each dimension

\item[\code{CCTK\_GroupashVN}] [\pageref{CCTK-GroupashVN}]
  Given a variable name, return an array of the local allocated size
  of the variable in each dimension

\item[\code{CCTK\_GroupName}] [\pageref{CCTK-GroupName}]
  Given a group index, returns the group name

\item[\code{CCTK\_GroupNameFromVarI}] [\pageref{CCTK-GroupNameFromVarI}]
  Given a variable index, return the name of the associated group

\item[\code{CCTK\_GroupnghostzonesGI}] [\pageref{CCTK-GroupnghostzonesGI}]
  Given a group index, return an array with the number of ghostzones
  in each dimension of the group

\item[\code{CCTK\_GroupnghostzonesGN}] [\pageref{CCTK-GroupnghostzonesGN}]
  Given a group name, return an array with the number of ghostzones
  in each dimension of the group

\item[\code{CCTK\_GroupnghostzonesVI}] [\pageref{CCTK-GroupnghostzonesVI}]
  Given a variable index, return an array with the number of ghostzones
  in each dimension of the variable's group

\item[\code{CCTK\_GroupnghostzonesVN}] [\pageref{CCTK-GroupnghostzonesVN}]
  Given a group variable, return an array with the number of ghostzones
  in each dimension of the variable's group

\item[\code{CCTK\_GroupSizesI}] [\pageref{CCTK-GroupSizesI}]
  Given a group index, returns the size array of that group

\item[\code{CCTK\_GroupStorageDecrease}] [\pageref{CCTK-GroupStorageDecrease}]
  Decrease the active number of timelevels for a list of groups

\item[\code{CCTK\_GroupStorageIncrease}] [\pageref{CCTK-GroupStorageIncrease}]
  Increase the active number of timelevels for a list of groups

\item[\code{CCTK\_GroupTagsTable}] [\pageref{CCTK-GroupTagsTable}]
  Given a group name, return the table handle of the group's tags table.

\item[\code{CCTK\_GroupTagsTableI}] [\pageref{CCTK-GroupTagsTableI}]
  Given a group index, return the table handle of the group's tags table.

\item[\code{CCTK\_GroupTypeFromVarI}] [\pageref{CCTK-GroupTypeFromVarI}]
  Provides a group's group type index given a variable index

\item[\code{CCTK\_GroupTypeI}] [\pageref{CCTK-GroupTypeI}]
  Provides a group's group type index given a group index

\item[\code{CCTK\_GroupubndGI}] [\pageref{CCTK-GroupubndGI}]
  Given a group index, return an array of the upper bounds
  of the group in each dimension

\item[\code{CCTK\_GroupubndGN}] [\pageref{CCTK-GroupubndGN}]
  Given a group name, return an array of the upper bounds
  of the group in each dimension

\item[\code{CCTK\_GroupubndVI}] [\pageref{CCTK-GroupubndVI}]
  Given a variable index, return an array of the upper bounds
  of the variable in each dimension

\item[\code{CCTK\_GroupubndVN}] [\pageref{CCTK-GroupubndVN}]
  Given a variable name, return an array of the upper bounds
  of the variable in each dimension

\item[\code{CCTK\_ImpFromVarI}] [\pageref{CCTK-ImpFromVarI}]
  Given a variable index, returns the implementation name

\item[\code{CCTK\_ImplementationRequires}]
  [\pageref{CCTK-ImplementationRequires}]
  Return the ancestors for an implementation

\item[\code{CCTK\_ImplementationThorn}]
  [\pageref{CCTK-ImplementationThorn}]
  Returns the name of one thorn providing an implementation

\item[\code{CCTK\_ImpThornList}] [\pageref{CCTK-ImpThornList}]
  Return the thorns for an implementation

\item[\code{CCTK\_INFO}] [\pageref{CCTK-INFO}]
  Macro to print a single string as an information message to screen

\item[\code{CCTK\_Info}] [\pageref{CCTK-Info}]
  Function to print a single string as an information message to screen

\item[\code{CCTK\_InfoCallbackRegister}] [\pageref{CCTK-INFOCallbackRegister}]
  Register one or more routines for dealing with information messages
  in addition to printing them to screen

\item[\code{CCTK\_InterpGridArrays}] [\pageref{CCTK-InterpGridArrays}]
  Performs an interpolation on a list of CCTK grid variables,
  using a chosen external local interpolation operator

\item[\code{CCTK\_InterpHandle}] [\pageref{CCTK-InterpHandle}]
  Returns the handle for a given interpolation operator

%notyet \item[\code{CCTK\_InterpLocalNonUniform}]
%notyet   [\pageref{CCTK-InterpLocalNonUniform}]
%notyet   Interpolate a list of processor-local arrays
%notyet   which define a nonuniformly spaced data grid (not implemented yet)

\item[\code{CCTK\_InterpLocalUniform}] [\pageref{CCTK-InterpLocalUniform}]
  Interpolate a list of processor-local arrays
  which define a uniformly-spaced data grid

%notyet \item[\code{CCTK\_InterpLocalWarped}]
%notyet   [\pageref{CCTK-InterpLocalWarped}]
%notyet   Interpolate a list of processor-local arrays
%notyet   which define a curvilinearly-warped data grid (not implemented yet)

%notyet \item[\code{CCTK\_InterpRegisterOpLocalNonUniform}]
%notyet   [\pageref{CCTK-InterpRegisterOpLocalNonUniform}]
%notyet   Registers a routine as a \code{CCTK\_InterpLocalNonUniform}
%notyet   interpolation operator

\item[\code{CCTK\_InterpRegisterOpLocalUniform}]
  [\pageref{CCTK-InterpRegisterOpLocalUniform}]
  Registers a routine as a \code{CCTK\_InterpLocalUniform}
  interpolation operator

%notyet \item[\code{CCTK\_InterpRegisterOpLocalWarped}]
%notyet   [\pageref{CCTK-InterpRegisterOpLocalWarped}]
%notyet   Registers a routine as a \code{CCTK\_InterpLocalWarped}
%notyet   interpolation operator

\item[\code{CCTK\_IsFunctionAliased}]
  [\pageref{CCTK-IsFunctionAliased}]
  Reports whether an aliased function has been provided

\item[\code{CCTK\_IsImplementationActive}]
  [\pageref{CCTK-IsImplementationActive}]
  Reports whether an implementation was activated in a parameter file

\item[\code{CCTK\_IsImplementationCompiled}]
  [\pageref{CCTK-IsImplementationCompiled}]
  Reports whether an implementation was compiled into a configuration

\item[\code{CCTK\_IsThornActive}] [\pageref{CCTK-IsThornActive}]
  Reports whether a thorn was activated in a parameter file

\item[\code{CCTK\_IsThornCompiled}] [\pageref{CCTK-IsThornCompiled}]
  Reports whether a thorn was compiled into a configuration

\item[\code{CCTK\_LocalArrayReduceOperator}] [\pageref{CCTK-LocalArrayReduceOperator}]
  Returns the name of a registered reduction operator

\item[\code{CCTK\_LocalArrayReduceOperatorImplementation}] [\pageref{CCTK-LocalArrayReduceOperatorImplementation}]
  Provide the implementation which provides an local array reduction operator

\item[\code{CCTK\_LocalArrayReductionHandle}] [\pageref{CCTK-LocalArrayReductionHandle}]
  Returns the handle of a given local array reduction operator

\item[\code{CCTK\_MaxDim}] [\pageref{CCTK-MaxDim}]
  Get the maximum dimension of any grid variable

\item[\code{CCTK\_MaxGFDim}] [\pageref{CCTK-MaxGFDim}]
  Get the maximum dimension of all grid functions

\item[\code{CCTK\_MaxTimeLevels}] [\pageref{CCTK-MaxTimeLevels}]
  Gives the maximum number of timelevels for a group

\item[\code{CCTK\_MaxTimeLevelsGI}] [\pageref{CCTK-MaxTimeLevelsGI}]
  Gives the maximum number of timelevels for a group

\item[\code{CCTK\_MaxTimeLevelsGN}] [\pageref{CCTK-MaxTimeLevelsGN}]
  Gives the maximum number of timelevels for a group

\item[\code{CCTK\_MaxTimeLevelsVI}] [\pageref{CCTK-MaxTimeLevelsVI}]
  Gives the maximum number of timelevels for a variable

\item[\code{CCTK\_MaxTimeLevelsVN}] [\pageref{CCTK-MaxTimeLevelsVN}]
  Gives the maximum number of timelevels for a variable

\item[\code{CCTK\_MyProc}] [\pageref{CCTK-MyProc}]
  Get the local processor number

\item[\code{CCTK\_nProcs}] [\pageref{CCTK-nProcs}]
  Get the total number of processors used

\item[\code{CCTK\_NullPointer}] [\pageref{CCTK-NullPointer}]
  Returns a C-style NULL pointer value

\item[\code{CCTK\_NumCompiledImplementations}]
  [\pageref{CCTK-NumCompiledImplementations}]
  Return the number of implementations compiled in

\item[\code{CCTK\_NumCompiledThorns}] [\pageref{CCTK-NumCompiledThorns}]
  Return the number of thorns compiled in

\item[\code{CCTK\_NumGridArrayReductionOperators}] [\pageref{CCTK-NumGridArrayReductionOperators}]
  The number of grid array reduction operators registered

\item[\code{CCTK\_NumGroups}] [\pageref{CCTK-NumGroups}]
  Get the number of groups of variables compiled in the code

\item[\code{CCTK\_NumIOMethods}] [\pageref{CCTK-NumIOMethods}]
  Returns the total number of I/O methods registered with the flesh

\item[\code{CCTK\_NumLocalArrayReduceOperators}] [\pageref{CCTK-NumLocalArrayReduceOperators}]
  The number of local reduction operators registered

\item[\code{CCTK\_NumReductionArraysGloballyOperators}] [\pageref{CCTK-NumReductionArraysGloballyOperators}]
  The number of global array reduction operators registered

\item[\code{CCTK\_NumTimeLevels}] [\pageref{CCTK-NumTimeLevels}]
  Returns the number of active timelevels from a group name
  \textbf{(deprecated)}

\item[\code{CCTK\_NumTimeLevelsGI}] [\pageref{CCTK-NumTimeLevels}]
  Returns the number of active timelevels from a group index
  \textbf{(deprecated)}

\item[\code{CCTK\_NumTimeLevelsGN}] [\pageref{CCTK-NumTimeLevels}]
  Returns the number of active timelevels from a group name
  \textbf{(deprecated)}

\item[\code{CCTK\_NumTimeLevelsVI}] [\pageref{CCTK-NumTimeLevels}]
  Returns the number of active timelevels from a variable index
  \textbf{(deprecated)}

\item[\code{CCTK\_NumTimeLevelsVN}] [\pageref{CCTK-NumTimeLevels}]
  Returns the number of active timelevels from a variable name
  \textbf{(deprecated)}

\item[\code{CCTK\_NumTimerClocks}] [\pageref{CCTK-NumTimerClocks}]
  Returns the number of clocks in a {\t cTimerData} structure.

\item[\code{CCTK\_NumVars}] [\pageref{CCTK-NumVars}]
  Get the number of grid variables compiled in the code

\item[\code{CCTK\_NumVarsInGroup}] [\pageref{CCTK-NumVarsInGroup}]
  Provides the number of variables in a group from the group name

\item[\code{CCTK\_NumVarsInGroupI}] [\pageref{CCTK-NumVarsInGroupI}]
  Provides the number of variables in a group from the group index

\item[\code{CCTK\_OutputGH}] [\pageref{CCTK-OutputGH}]
  Conditional output of all variables on a GH by all I/O methods

\item[\code{CCTK\_OutputVar}] [\pageref{CCTK-OutputVar}]
  Output of a single variable by all I/O methods

\item[\code{CCTK\_OutputVarAs}] [\pageref{CCTK-OutputVarAs}]
  Output of a single variable as an alias by all I/O methods

\item[\code{CCTK\_OutputVarAsByMethod}] [\pageref{CCTK-OutputVarAsByMethod}]
  Output of a single variable as an alias by a single I/O method

\item[\code{CCTK\_OutputVarByMethod}] [\pageref{CCTK-OutputVarByMethod}]
  Output of a single variable by a single I/O method

\item[\code{CCTK\_ParallelInit}] [\pageref{CCTK-ParallelInit}]
  Initializes the parallel subsystem

\item[\code{CCTK\_ParameterData}]
  [\pageref{CCTK-ParameterData}]
  Get parameter properties for given parameter/thorn pair

\item[\code{CCTK\_ParameterGet}]
  [\pageref{CCTK-ParameterGet}]
  Get the data pointer to and type of a parameter's value

\item[\code{CCTK\_ParameterLevel}]
  [\pageref{CCTK-ParameterLevel}]
  Return the parameter checking level

\item[\code{CCTK\_ParameterQueryTimesSet}]
  [\pageref{CCTK-ParameterQueryTimesSet}]
  Return number of times a parameter has been set

\item[\code{CCTK\_ParameterSet}]
  [\pageref{CCTK-ParameterSet}]
  Sets the value of a parameter

\item[\code{CCTK\_ParameterSetNotifyRegister}]
  [\pageref{CCTK-ParameterSetNotifyRegister}]
  Registers a parameter set operation notify callback

\item[\code{CCTK\_ParameterSetNotifyUnregister}]
  [\pageref{CCTK-ParameterSetNotifyUnregister}]
  Unregisters a parameter set operation notify callback

\item[\code{CCTK\_ParameterValString}]
  [\pageref{CCTK-ParameterValString}]
  Get the string representation of a parameter's value

\item[\code{CCTK\_ParameterWalk}]
  [\pageref{CCTK-ParameterWalk}]
  Walk through the list of parameters

\item[\code{CCTK\_PARAMWARN}] [\pageref{CCTK-PARAMWARN}]
  Prints a warning from parameter checking, and possibly stops the code

\item[\code{CCTK\_PointerTo}] [\pageref{CCTK-PointerTo}]
  Returns a pointer to a Fortran variable.

\item[\code{CCTK\_PrintGroup}] [\pageref{CCTK-PrintGroup}]
  Prints a group name from its index

\item[\code{CCTK\_PrintString}] [\pageref{CCTK-PrintString}]
  Prints a Cactus string to screen (from Fortran)

\item[\code{CCTK\_PrintVar}] [\pageref{CCTK-PrintVar}]
  Prints a variable name from its index

\item[\code{CCTK\_QueryGroupStorage}] [\pageref{CCTK-QueryGroupStorage}]
  Queries storage for a group given by its group name

\item[\code{CCTK\_QueryGroupStorageB}] [\pageref{CCTK-QueryGroupStorageB}]
  Queries storage for a group given by its group name or index

\item[\code{CCTK\_QueryGroupStorageI}] [\pageref{CCTK-QueryGroupStorageI}]
  Queries storage for a group given by its group index

\item[\code{CCTK\_ReduceArraysGlobally}] [\pageref{CCTK-ReduceArraysGlobally}]
  Reduces a list of local arrays globally

\item[\code{CCTK\_ReduceGridArrays}] [\pageref{CCTK-ReduceGridArrays}]
  Reduces a list of local arrays (new grid array reduction API)

\item[\code{CCTK\_ReduceLocalArrays}] [\pageref{CCTK-ReduceLocalArrays}]
  Reduces a list of local arrays (new local array reduction API)
  Returns the address of a variable passed in by reference
  from a Fortran routine

%\item[\code{CCTK\_Reduce}]
%  [\pageref{CCTK-Reduce}]
%  Perform a reduction operation using a registered operator

%\item[\code{CCTK\_Reduce1}]
%  [\pageref{CCTK-Reduce1}]
%  Perform a reduction operation using a registered operator

\item[\code{CCTK\_ReductionHandle}] [\pageref{CCTK-ReductionHandle}]
  Get the handle for a registered reduction operator

\item[\code{CCTK\_RegexMatch}] [\pageref{CCTK-RegexMatch}]
  Perform a regular expression match of string against pattern

\item[\code{CCTK\_RegisterBanner}] [\pageref{CCTK-RegisterBanner}]
  Register a banner for a thorn

\item[\code{CCTK\_RegisterGHExtension}]
  [\pageref{CCTK-RegisterGHExtension}]
  Register the name of an extension to the Cactus GH

\item[\code{CCTK\_RegisterGHExtensionInitGH}]
  [\pageref{CCTK-RegisterGHExtensionInitGH}]
  Register a routine for providing initialisation for an extension to
  the Cactus GH

\item[\code{CCTK\_RegisterGHExtensionScheduleTraverseGH}]
  [\pageref{CCTK-RegisterGHExtensionScheduleTraverseGH}]
  Register a GH extension schedule traversal routine

\item[\code{CCTK\_RegisterGridArrayReductionOperator}] [\pageref{CCTK-RegisterGridArrayReductionOperator}]
  Registers a function as a grid array reduction operator of a certain name

\item[\code{CCTK\_RegisterGHExtensionSetupGH}]
  [\pageref{CCTK-RegisterGHExtensionSetupGH}]
  Register a routine for setting up an extension to the Cactus GH

\item[\code{CCTK\_RegisterIOMethod}]
  [\pageref{CCTK-RegisterIOMethod}]
  Registers a new I/O method

\item[\code{CCTK\_RegisterIOMethodOutputGH}]
  [\pageref{CCTK-RegisterIOMethodOutputGH}]
  Registers an I/O method's routine for conditional output

\item[\code{CCTK\_RegisterIOMethodOutputVarAs}]
  [\pageref{CCTK-RegisterIOMethodOutputVarAs}]
  Registers an I/O method's routine for unconditional output

\item[\code{CCTK\_RegisterIOMethodTimeToOutput}]
  [\pageref{CCTK-RegisterIOMethodTimeToOutput}]
  Register a routine for deciding if it is time to output for an IO method

\item[\code{CCTK\_RegisterIOMethodTriggerOutput}]
  [\pageref{CCTK-RegisterIOMethodTriggerOutput}]
  Register a routine for dealing with trigger output for an IO method

\item[\code{CCTK\_RegisterLocalArrayReductionOperator}] [\pageref{CCTK-RegisterLocalArrayReductionOperator}]
  Registers a function as a reduction operator of a certain name

\item[\code{CCTK\_RegisterReduceArraysGloballyOperator}]
  [\pageref{CCTK-RegisterReduceArraysGloballyOperator}]
  Register a function as providing a global array reduction operation

\item[\code{CCTK\_RegisterReductionOperator}]
  [\pageref{CCTK-RegisterReductionOperator}]
  Register a function as providing a reduction operation

\item[\code{CCTK\_SchedulePrintTimes}] [\pageref{CCTK-SchedulePrintTimes}]
  Output the timing results for a certain schedule item to stdout

\item[\code{CCTK\_SchedulePrintTimesToFile}] [\pageref{CCTK-SchedulePrintTimesToFile}]
  Output the timing results for a certain schedule item to a file

\item[\code{CCTK\_SetupGH}] [\pageref{CCTK-SetupGH}]
  Sets up a CCTK grid hierarchy

\item[\code{CCTK\_SyncGroup}] [\pageref{CCTK-SyncGroup}]
  Synchronize the ghost zones for a group of variables (identified by the group name)

\item[\code{CCTK\_SyncGroupI}] [\pageref{CCTK-SyncGroupI}]
  Synchronize the ghost zones for a group of variables (identified by the group index)

\item[\code{CCTK\_SyncGroupsI}] [\pageref{CCTK-SyncGroupsI}]
  Synchronize the ghost zones for a list of groups of variables (identified by their group indices)

\item[\code{CCTK\_TerminateNext}] [\pageref{CCTK-TerminateNext}]
  Causes a Cactus simulation to terminate after the next iteration

\item[\code{CCTK\_TerminationReached}] [\pageref{CCTK-TerminationReached}]
  Returns true if {\tt CCTK\_TerminateNext} has been called.

\item[\code{CCTK\_ThornImplementation}]
  [\pageref{CCTK-ThornImplementation}]
  Returns the implementation provided by the thorn

\item[\code{CCTK\_Timer}] [\pageref{CCTK-Timer}]
  Fills a timer {\t cTimerData} structure with current values of all clocks
  of a timer with a given name.

\item[\code{CCTK\_TimerCreate}] [\pageref{CCTK-TimerCreate}]
  Create a timer with a given name, returns a timer index.

\item[\code{CCTK\_TimerCreateData}] [\pageref{CCTK-TimerCreateData}]
  Allocates a timer {\t cTimerData} structure.

\item[\code{CCTK\_TimerCreateI}] [\pageref{CCTK-TimerCreateI}]
  Create an unnamed timer, returns a timer index.

\item[\code{CCTK\_TimerDestroy}] [\pageref{CCTK-TimerDestroy}]
  Reclaims resources for a timer with a given name.

\item[\code{CCTK\_TimerDestroyData}] [\pageref{CCTK-TimerDestroyData}]
  Reclaims resources of a timer {\t cTimerData} structure.

\item[\code{CCTK\_TimerDestroyI}] [\pageref{CCTK-TimerDestroyI}]
  Reclaims resources for a timer with a given index.

\item[\code{CCTK\_TimerI}] [\pageref{CCTK-TimerI}]
  Fills a timer {\t cTimerData} structure with current values of all clocks
  of a timer with a given index.

\item[\code{CCTK\_TimerReset}] [\pageref{CCTK-TimerReset}]
  Initialises the timer with a given name.

\item[\code{CCTK\_TimerResetI}] [\pageref{CCTK-TimerResetI}]
  Initialises the timer with a given index.

\item[\code{CCTK\_TimerStart}] [\pageref{CCTK-TimerStart}]
  Initialises the timer with a given name.

\item[\code{CCTK\_TimerStartI}] [\pageref{CCTK-TimerStartI}]
  Initialises the timer with a given index.

\item[\code{CCTK\_TimerStop}] [\pageref{CCTK-TimerStop}]
  Gets current values for all clocks of the timer with a given name.

\item[\code{CCTK\_TimerStopI}] [\pageref{CCTK-TimerStopI}]
  Gets current values for all clocks of the timer with a given index.

\item[\code{CCTK\_TraverseString}] [\pageref{CCTK-TraverseString}]
  Traverse through all variables and/or groups whose names appear in the given string.

\item[\code{CCTK\_VarDataPtr}] [\pageref{CCTK-VarDataPtr}]
  Returns the data pointer for a grid variable

\item[\code{CCTK\_VarDataPtrB}] [\pageref{CCTK-VarDataPtrB}]
  Returns the data pointer for a grid variable from the variable index or name

\item[\code{CCTK\_VarDataPtrI}] [\pageref{CCTK-VarDataPtrI}]
  Returns the data pointer for a grid variable from the variable index

\item[\code{CCTK\_VarIndex}]
   [\pageref{CCTK-VarIndex}]
  Get the index for a variable

\item[\code{CCTK\_VarName}] [\pageref{CCTK-VarName}]
  Given a variable index, returns the variable name

\item[\code{CCTK\_VarTypeI}] [\pageref{CCTK-VarTypeI}]
  Provides variable type index from the variable index

\item[\code{CCTK\_VarTypeSize}] [\pageref{CCTK-VarTypeSize}]
  Provides variable type size in bytes from the variable type index

\item[\code{CCTK\_VError}] [\pageref{CCTK-VError}]
  Prints a formatted string with a variable argument list as error
  message to standard error and stops the code

\item[\code{CCTK\_VInfo}] [\pageref{CCTK-VInfo}]
  Prints a formatted string with a variable argument list as an information
  message to screen

\item[\code{CCTK\_VWarn}] [\pageref{CCTK-VWarn}]
  Prints a formatted string with a variable argument list as a warning message
  to standard error and possibly stops the code

\item[\code{CCTK\_WARN}] [\pageref{CCTK-WARN}]
  Macro to print a single string as a warning message to standard error and
  possibly stop the code

\item[\code{CCTK\_Warn}] [\pageref{CCTK-Warn}]
  Function to print a single string as a warning message to standard error and
  possibly stop the code

\item[\code{CCTK\_WarnCallbackRegister}] [\pageref{CCTK-WARNCallbackRegister}]
  Register one or more routines for dealing with warning messages in addition
  to printing them to standard error

\end{Lentry}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Full Description of Functions}

%%%%%
% AAA
%%%%%

% CommOverloadables.c
%Entering a function description for CCTK\_Abort
\begin{FunctionDescription}{CCTK\_Abort}
\label{CCTK-Abort}
Abnormal Cactus termination.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int dummy = CCTK_Abort(const cGH *cctkGH, int exitcode);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"

subroutine CCTK_Abort (dummy, cctkGH, exitcode)
   integer      dummy
   CCTK_POINTER cctkGH
   integer      exitcode
end subroutine CCTK_Abort
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{}
The function never returns, and hence never produces a result.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{GH ($\ne$ NULL)}
Pointer to a valid Cactus grid hierarchy.
\end{Parameter}
\begin{Parameter}{exitcode}
Exit code that is passed to the operating system
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This routine causes an immediate, abnormal Cactus termination.
It never returns to the caller.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_Exit}{CCTK-Exit}
Exit the code cleanly
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ERROR}{CCTK-ERROR}
Macro to print a single string as error message and stop the code
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_VError}{CCTK-VError}
Prints a formatted string with a variable argument list as error
message to standard error and stops the code
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_VWarn}{CCTK-VWarn}
Prints a formatted string with a variable argument list as a warning
message to standard error and possibly stops the code
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_WARN}{CCTK-WARN}
Macro to print a single string as a warning message and possibly stop the code
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{}
The function never returns, and hence never reports an error.
\end{Error}
\end{ErrorSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
#include "cctk.h"
CCTK_Abort (cctkGH);
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
#include "cctk.h"
integer dummy
call CCTK_Abort (dummy, cctkGH)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}



% ActiveThorns.c
%Entering a function description for CCTK\_ActivatingThorn
\begin{FunctionDescription}{CCTK\_ActivatingThorn}
\label{CCTK-ActivatingThorn}
Finds the thorn which activated a particular implementation.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

const char *thorn = CCTK_ActivatingThorn(const char *name);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{thorn}
Name of activating thorn, or \code{NULL} if inactive
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{name}
Implementation name
\end{Parameter}
\end{ParameterSection}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_CompiledImplementation}{CCTK-CompiledImplementation}
  Return the name of the compiled implementation with given index
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompiledThorn}{CCTK-CompiledThorn}
  Return the name of the compiled thorn with given index
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImplementationRequires}{CCTK-ImplementationRequires}
  Return the ancestors for an implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImplementationThorn}{CCTK-ImplementationThorn}
  Returns the name of one thorn providing an implementation.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImpThornList}{CCTK-ImpThornList}
  Return the thorns for an implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive}
  Reports whether an implementation was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled}
  Reports whether an implementation was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive}
  Reports whether a thorn was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled}
  Reports whether a thorn was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_NumCompiledImplementations}{CCTK-NumCompiledImplementations}
  Return the number of implementations compiled in
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_NumCompiledThorns}{CCTK-NumCompiledThorns}
  Return the number of thorns compiled in
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ThornImplementation}{CCTK-ThornImplementation}
  Returns the implementation provided by the thorn
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{NULL}
The implementation is inactive, or an error occurred.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}



% cctk_GroupsOnGH.h
%Entering a function description for CCTK\_ActiveTimeLevels
\begin{FunctionDescription}{CCTK\_ActiveTimeLevels}
\label{CCTK-ActiveTimeLevels}
Returns the number of active time levels for a group.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int timelevels = CCTK_ActiveTimeLevels(const cGH *cctkGH,
                                       const char *groupname);

int timelevels = CCTK_ActiveTimeLevelsGI(const cGH *cctkGH,
                                         int groupindex);

int timelevels = CCTK_ActiveTimeLevelsGN(const cGH *cctkGH,
                                         const char *groupname);

int timelevels = CCTK_ActiveTimeLevelsVI(const cGH *cctkGH,
                                         int varindex);

int timelevels = CCTK_ActiveTimeLevelsVN(const cGH *cctkGH,
                                         const char *varname);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"

subroutine CCTK_ActiveTimeLevels(timelevels, cctkGH, groupname)
   integer       timelevels
   CCTK_POINTER  cctkGH
   character*(*) groupname
end subroutine CCTK_ActiveTimeLevels

subroutine CCTK_ActiveTimeLevelsGI(timelevels, cctkGH, groupindex)
   integer       timelevels
   CCTK_POINTER  cctkGH
   integer       groupindex
end subroutine CCTK_ActiveTimeLevelsGI

subroutine CCTK_ActiveTimeLevelsGN(timelevels, cctkGH, groupname)
   integer       timelevels
   CCTK_POINTER  cctkGH
   character*(*) groupname
end subroutine CCTK_ActiveTimeLevelsGN

subroutine CCTK_ActiveTimeLevelsVI(timelevels, cctkGH, varindex)
   integer       timelevels
   CCTK_POINTER  cctkGH
   integer       varindex
end subroutine CCTK_ActiveTimeLevelsVI

subroutine CCTK_ActiveTimeLevelsVN(timelevels, cctkGH, varname)
   integer       timelevels
   CCTK_POINTER  cctkGH
   character*(*) varname
end subroutine CCTK_ActiveTimeLevelsVN
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{timelevels}
The currently active number of timelevels for the group.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{GH ($\ne$ NULL)}
Pointer to a valid Cactus grid hierarchy.
\end{Parameter}
\begin{Parameter}{groupname}
Name of the group.
\end{Parameter}
\begin{Parameter}{groupindex}
Index of the group.
\end{Parameter}
\begin{Parameter}{varname}
Name of a variable in the group.
\end{Parameter}
\begin{Parameter}{varindex}
Index of a variable in the group.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This function returns the number of timelevels for which storage has
been activated, which is always equal to or less than the maximum
number of timelevels which may have storage provided by
\code{CCTK\_MaxTimeLevels}.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_MaxTimeLevels}{CCTK-MaxTimeLevels}
Return the maximum number of active timelevels.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_NumTimeLevels}{CCTK-NumTimeLevels}
Deprecated; same as \code{CCTK\_ActiveTimeLevels}.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_GroupStorageDecrease}{CCTK-GroupStorageDecrease}
Base function, overloaded by the driver, which decreases the number of
active timelevels, and also returns the number of active timelevels.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_GroupStorageIncrease}{CCTK-GroupStorageIncrease}
Base function, overloaded by the driver, which increases the number of
active timelevels, and also returns the number of active timelevels.
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{timelevels $<$ 0}
Illegal arguments given.
\end{Error}
\end{ErrorSection}

%\begin{ExampleSection}
%\end{ExampleSection}
\end{FunctionDescription}



% cctk_Comm.h
%Entering a function description for CCTK\_ArrayGroupSize}{
\begin{FunctionDescription}{CCTK\_ArrayGroupSize}{}
\label{CCTK-ArrayGroupSize}
Returns a pointer to the processor-local size for variables in a
group, specified by its name, in a given dimension.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int *size = CCTK_ArrayGroupSize(const cGH *cctkGH,
                                int dir,
                                const char *groupname);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{NULL}
A \code{NULL} pointer is returned if the group index or the dimension given are invalid.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{GH ($\ne$ NULL)}
Pointer to a valid Cactus grid hierarchy.
\end{Parameter}
\begin{Parameter}{dir ($\ge$ 0)}
Which dimension of array to query.
\end{Parameter}
\begin{Parameter}{groupname}
Name of the group.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
For a CCTK\_ARRAY or CCTK\_GF group, this routine returns a pointer to
the processor-local size for variables in that group in a given
direction. The direction is counted in C order (zero being the lowest
dimension).

This function returns a pointer to the result for technical reasons;
so that it will efficiently interface with Fortran.  This may change
in the future.  Consider using \code{CCTK\_GroupgshGN} instead.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2} {CCTK\_GroupgshGN} {CCTK-GroupgshGN}
Returns an array with the array size in all dimensions.
\end{SeeAlso2}
\begin{SeeAlso}{...}
There are many related functions which grab information from the GH,
but many are not yet documented.
\end{SeeAlso}
\end{SeeAlsoSection}
%\begin{ErrorSection}
%\end{ErrorSection}
%\begin{ExampleSection}
%\end{ExampleSection}
\end{FunctionDescription}


% cctk_Comm.h
%Entering a function description for CCTK\_ArrayGroupSizeI}{
\begin{FunctionDescription}{CCTK\_ArrayGroupSizeI}{}
\label{CCTK-ArrayGroupSizeI}
Returns a pointer to the processor-local size for variables in a
group, specified by its index, in a given dimension.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int *size = CCTK_ArrayGroupSizeI(const cGH *cctkGH,
                                 int dir,
                                 int groupi);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{NULL}
A \code{NULL} pointer is returned if the group index or the dimension
given are invalid.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{GH ($\ne$ NULL)}
Pointer to a valid Cactus grid hierarchy.
\end{Parameter}
\begin{Parameter}{dir ($\ge$ 0)}
Which dimension of array to query.
\end{Parameter}
\begin{Parameter}{groupi}
The group index.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
For a CCTK\_ARRAY or CCTK\_GF group, this routine returns a pointer to
the processor-local size for variables in that group in a given
direction. The direction is counted in C order (zero being the lowest
dimension).

This function returns a pointer to the result for technical reasons;
so that it will efficiently interface with Fortran.  This may change
in the future.  Consider using \code{CCTK\_GroupgshGI} instead.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2} {CCTK\_GroupgshGI} {CCTK-GroupgshGI}
Returns an array with the array size in all dimensions.
\end{SeeAlso2}
\begin{SeeAlso}{...}
There are many related functions which grab information from the GH,
but many are not yet documented.
\end{SeeAlso}
\end{SeeAlsoSection}
%\begin{ErrorSection}
%\end{ErrorSection}
%\begin{ExampleSection}
%\end{ExampleSection}
\end{FunctionDescription}


%%%%%
% BBB
%%%%%

% CommOverloadables.c
\begin{FunctionDescription}{CCTK\_Barrier}{Synchronizes all processors at a given execution point}
\label{CCTK-Barrier}
This routine synchronizes all processors in a parallel job at a given point of
execution. No processor will continue execution until all other processors
have called \code{CCTK\_Barrier}. Note that this is a collective operation --
it must be called by all processors otherwise the code will hang.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int istat = CCTK_Barrier(const cGH *cctkGH)
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
subroutine CCTK_Barrier (istat, cctkGH)
  integer               itat
  CCTK_POINTER_TO_CONST cctkGH
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\end{FunctionDescription}


%%%%%
% CCC
%%%%%

%Entering a function description for CCTK\_ClockRegister
\begin{FunctionDescription}{CCTK\_ClockRegister}
\label{CCTK-ClockRegister}
Registers a named timer clock with the Flesh.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int err = CCTK_ClockRegister(name, functions)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{const char * name}
The name the clock will be given
\end{Parameter}

\begin{Parameter}{const cClockFuncs * functions}
The structure holding the function pointers that define the clock
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The {\t cClockFuncs} structure contains function pointers defined by
the clock module to be registered.
\end{Discussion}

\begin{ErrorSection}
\begin{Error}{}
A negative return value indicates an error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_Cmplx}{Turns two real numbers into a complex number}
\label{CCTK-Cmplx}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}CCTK_COMPLEX cmpno = CCTK_Cmplx( CCTK_REAL realpart, CCTK_REAL imagpart)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{cmpno}
The complex number
\end{Parameter}
\begin{Parameter}{realpart}
The real part of the complex number
\end{Parameter}
\begin{Parameter}{imagpart}
The imaginary part of the complex number
\end{Parameter}
\end{ParameterSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
cmpno = CCTK_Cmplx(re,im);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_CmplxAbs}{Absolute value of a complex number}
\label{CCTK-CmplxAbs}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}CCTK_COMPLEX absval = CCTK_CmplxAbs( CCTK_COMPLEX inval)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{absval}
The computed absolute value
\end{Parameter}
\begin{Parameter}{realpart}
The complex number who absolute value is to be returned
\end{Parameter}
\end{ParameterSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
absval = CCTK_CmplxAbs(inval);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_CmplxAdd}{Sum of two complex numbers}
\label{CCTK-CmplxAdd}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}CCTK_COMPLEX addval = CCTK_CmplxAdd( CCTK_COMPLEX inval1, CCTK_COMPLEX inval2)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{addval}
The computed added value
\end{Parameter}
\begin{Parameter}{inval1}
The first complex number to be summed
\end{Parameter}
\begin{Parameter}{inval2}
The second complex number to be summed
\end{Parameter}
\end{ParameterSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
addval = CCTK_CmplxAdd(inval1,inval2);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_CmplxConjg}{Complex conjugate of a complex number}
\label{CCTK-CmplxConjg}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}CCTK_COMPLEX conjgval = CCTK_CmplxConjg( CCTK_COMPLEX inval)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{conjval}
The computed conjugate
\end{Parameter}
\begin{Parameter}{inval}
The complex number to be conjugated
\end{Parameter}
\end{ParameterSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
conjgval = CCTK_CmplxConjg(inval);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_CmplxCos}{Cosine of a complex number}
\label{CCTK-CmplxCos}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}CCTK_COMPLEX cosval = CCTK_CmplxCos( CCTK_COMPLEX inval)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{cosval}
The computed cosine
\end{Parameter}
\begin{Parameter}{inval}
The complex number to be cosined
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
{\bf NOT YET AVAILABLE}
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
cosval = CCTK_CmplxCos(inval);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_CmplxDiv}{Division of two complex numbers}
\label{CCTK-CmplxDiv}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}CCTK_COMPLEX divval = CCTK_CmplxDiv( CCTK_COMPLEX inval1, CCTK_COMPLEX inval2)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{divval}
The divided value
\end{Parameter}
\begin{Parameter}{inval1}
The enumerator
\end{Parameter}
\begin{Parameter}{inval1}
The denominator
\end{Parameter}
\end{ParameterSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
divval = CCTK_CmplxDiv(inval1,inval2);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_CmplxExp}{Exponent of a complex number}
\label{CCTK-CmplxExp}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}CCTK_COMPLEX expval = CCTK_CmplxExp( CCTK_COMPLEX inval)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{expval}
The computed exponent
\end{Parameter}
\begin{Parameter}{inval}
The complex number to be exponented
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
{\bf NOT YET AVAILABLE}
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
expval = CCTK_CmplxExp(inval);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_CmplxImag}{Imaginary part of a complex number}
\label{CCTK-CmplxImag}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}CCTK_REAL imval = CCTK_CmplxImag( CCTK_COMPLEX inval)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{imval}
The imaginary part
\end{Parameter}
\begin{Parameter}{inval}
The complex number
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The imaginary part of a complex number $z=a+bi$ is $b$.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
imval = CCTK_CmplxImag(inval);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_CmplxLog}{Logarithm of a complex number}
\label{CCTK-CmplxLog}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}CCTK_COMPLEX logval = CCTK_CmplxLog( CCTK_COMPLEX inval)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{logval}
The computed logarithm
\end{Parameter}
\begin{Parameter}{inval}
The complex number
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
{\bf NOT YET AVAILABLE}
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
logval = CCTK_CmplxLog(inval);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_CmplxMul}{Multiplication of two complex numbers}
\label{CCTK-CmplxMul}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}CCTK_COMPLEX mulval = CCTK_CmplxMul( CCTK_COMPLEX inval1, CCTK_COMPLEX inval2)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{mulval}
The product
\end{Parameter}
\begin{Parameter}{inval1}
First complex number to be multiplied
\end{Parameter}
\begin{Parameter}{inval2}
Second complex number to be multiplied
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The product of two complex numbers $z_1=a_1+b_1 i$ and $z_2=a_2+b_2 i$ is
$z=(a_1 a_2 - b_1 b_2) + (a_1 b_2 + a_2 b_1)i$.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
mulval = CCTK_CmplxMul(inval1,inval2);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}



\begin{FunctionDescription}{CCTK\_CmplxReal}{Real part of a complex number}
\label{CCTK-CmplxReal}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}CCTK_REAL reval = CCTK_CmplxReal( CCTK_COMPLEX inval)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{reval}
The real part
\end{Parameter}
\begin{Parameter}{inval}
The complex number
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The real part of a complex number $z=a+bi$ is $a$.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
reval = CCTK_CmplxReal(inval);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_CmplxSin}{Sine of a complex number}
\label{CCTK-CmplxSin}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}CCTK_COMPLEX sinval = CCTK_CmplxSin( CCTK_COMPLEX inval)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{sinval}
The computed sine
\end{Parameter}
\begin{Parameter}{inval}
The complex number to be Sined
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
{\bf NOT YET AVAILABLE}
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
sinval = CCTK_CmplxSin(inval);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_CmplxSqrt}{Square root of a complex number}
\label{CCTK-CmplxSqrt}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}CCTK_COMPLEX sqrtval = CCTK_CmplxSqrt( CCTK_COMPLEX inval)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{expval}
The computed square root
\end{Parameter}
\begin{Parameter}{inval}
The complex number to be square rooted
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
{\bf NOT YET AVAILABLE}
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
sqrtval = CCTK_CmplxSqrt(inval);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_CmplxSub}{Subtraction of two complex numbers}
\label{CCTK-CmplxSub}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}CCTK_COMPLEX subval = CCTK_CmplxSub( CCTK_COMPLEX inval1, CCTK_COMPLEX inval2)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{addval}
The computed subtracted value
\end{Parameter}
\begin{Parameter}{inval1}
The complex number to be subtracted from
\end{Parameter}
\begin{Parameter}{inval2}
The complex number to subtract
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
If $z_1=a_1 + b_1 i$ and $z_2 = a_2+ b_2 i$ then
$$
z_1-z_2 = (a_1-a_2)+ (b_1 - b_2)i
$$
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
subval = CCTK_CmplxSub(inval1,inval2);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


% datestamp.c
\begin{FunctionDescription}{CCTK\_CompileDate}
\label{CCTK-CompileDate}
Returns a formatted string containing the date stamp when Cactus was compiled

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

const char *compile_date = CCTK_CompileDate ();
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{compile\_date}
formatted string containing the date stamp
\end{Result}
\end{ResultSection}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_CompileTime}{CCTK-CompileTime}
  Returns a formatted string containing the time stamp when Cactus was compiled
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompileDateTime}{CCTK-CompileDateTime}
  Returns a formatted string containing the datetime stamp when Cactus was compiled
\end{SeeAlso2}
\end{SeeAlsoSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_CompileDateTime}
\label{CCTK-CompileDateTime}
Returns a formatted string containing the datetime stamp when Cactus was compiled

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

const char *compile_datetime = CCTK_CompileDateTime ();
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{compile\_datetime}
formatted string containing the datetime stamp
\end{Result}
\end{ResultSection}

\begin{Discussion}
If possible, the formatted string returned contains the datetime in a
machine-processable format as defined in ISO 8601 chapter 5.4.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_CompileDate}{CCTK-CompileDate}
  Returns a formatted string containing the date stamp when Cactus was compiled
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompileTime}{CCTK-CompileTime}
  Returns a formatted string containing the time stamp when Cactus was compiled
\end{SeeAlso2}
\end{SeeAlsoSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_CompileTime}
\label{CCTK-CompileTime}
Returns a formatted string containing the time stamp when Cactus was compiled

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

const char *compile_time = CCTK_CompileTime ();
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{compile\_time}
formatted string containing the time stamp
\end{Result}
\end{ResultSection}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_CompileDate}{CCTK-CompileDate}
  Returns a formatted string containing the date stamp when Cactus was compiled
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompileDateTime}{CCTK-CompileDateTime}
  Returns a formatted string containing the datetime stamp when Cactus was compiled
\end{SeeAlso2}
\end{SeeAlsoSection}
\end{FunctionDescription}


% cctk_ActiveThorns.c
\begin{FunctionDescription}{CCTK\_CompiledImplementation}
\label{CCTK-CompiledImplementation}
Return the name of the compiled implementation with given index.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

const char *imp = CCTK_CompiledImplementation(int index);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{imp}
Name of the implementation
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{index}
Implementation index, with $0 \le \code{index} < \code{numimpls}$,
where \code{numimpls} is returned by
\code{CCTK\_NumCompiledImplementations}.
\end{Parameter}
\end{ParameterSection}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ActivatingThorn}{CCTK-ActivatingThorn}
  Finds the thorn which activated a particular implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompiledThorn}{CCTK-CompiledThorn}
  Return the name of the compiled thorn with given index
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImplementationRequires}{CCTK-ImplementationRequires}
  Return the ancestors for an implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImplementationThorn}{CCTK-ImplementationThorn}
  Returns the name of one thorn providing an implementation.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImpThornList}{CCTK-ImpThornList}
  Return the thorns for an implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive}
  Reports whether an implementation was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled}
  Reports whether an implementation was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive}
  Reports whether a thorn was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled}
  Reports whether a thorn was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_NumCompiledImplementations}{CCTK-NumCompiledImplementations}
  Return the number of implementations compiled in
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_NumCompiledThorns}{CCTK-NumCompiledThorns}
  Return the number of thorns compiled in
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ThornImplementation}{CCTK-ThornImplementation}
  Returns the implementation provided by the thorn
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{NULL}
Error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}



% cctk_ActiveThorns.c
%Entering a function description for CCTK_CompiledThorn
\begin{FunctionDescription}{CCTK\_CompiledThorn}
\label{CCTK-CompiledThorn}
Return the name of the compiled thorn with given index.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

const char *thorn = CCTK_CompiledThorn(int index);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{thorn}
Name of the thorn
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{index}
Thorn index, with $0 \le \code{index} < \code{numthorns}$, where
\code{numthorns} is returned by \code{CCTK\_NumCompiledThorns}.
\end{Parameter}
\end{ParameterSection}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ActivatingThorn}{CCTK-ActivatingThorn}
  Finds the thorn which activated a particular implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompiledImplementation}{CCTK-CompiledImplementation}
  Return the name of the compiled implementation with given index
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImplementationRequires}{CCTK-ImplementationRequires}
  Return the ancestors for an implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImplementationThorn}{CCTK-ImplementationThorn}
  Returns the name of one thorn providing an implementation.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImpThornList}{CCTK-ImpThornList}
  Return the thorns for an implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive}
  Reports whether an implementation was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled}
  Reports whether an implementation was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive}
  Reports whether a thorn was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled}
  Reports whether a thorn was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_NumCompiledImplementations}{CCTK-NumCompiledImplementations}
  Return the number of implementations compiled in
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_NumCompiledThorns}{CCTK-NumCompiledThorns}
  Return the number of thorns compiled in
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ThornImplementation}{CCTK-ThornImplementation}
  Returns the implementation provided by the thorn
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{NULL}
Error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{FunctionDescription}{CCTK\_CoordDir}%%%
{Give the direction for a given coordinate.

\textbf{All the \texttt{CCTK\_Coord*} APIs are deprecated,
and will probably be phased out fairly soon.
New code should use the APIs provided by the \texttt{CoordBase} thorn
instead (this lives in the \texttt{CactusBase} arrangement).}
}
\label{CCTK-CoordDir}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int dir = CCTK_CoordDir( const char * coordname, const char * systemname)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_CoordDir(dir , coordname, systemname )

integer dir
character*(*) coordname
character*(*) systemname \end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{dir}
The direction of the coordinate
\end{Parameter}
\begin{Parameter}{coordname}
The name assigned to this coordinate
\end{Parameter}
\begin{Parameter}{systemname}
The name of the coordinate system
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The coordinate name is independent of the grid function name.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
direction = CCTK_CoordDir("xdir","cart3d");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call  CCTK_COORDDIR(direction,"radius","spher3d")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{FunctionDescription}{CCTK\_CoordIndex}%%%
{Give the grid variable index for a given coordinate.

\textbf{All the \texttt{CCTK\_Coord*} APIs are deprecated,
and will probably be phased out fairly soon.
New code should use the APIs provided by the \texttt{CoordBase} thorn
instead (this lives in the \texttt{CactusBase} arrangement).}
}
\label{CCTK-CoordIndex}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int index = CCTK_CoordIndex( int direction, const char * coordname, const char * systemname)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_CoordIndex(index , direction, coordname, systemname )

integer index
integer direction
character*(*) coordname
character*(*) systemname\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{index}
The coordinates associated grid variable index
\end{Parameter}
\begin{Parameter}{direction}
The direction of the coordinate in this coordinate system
\end{Parameter}
\begin{Parameter}{coordname}
The name assigned to this coordinate
\end{Parameter}
\begin{Parameter}{systemname}
The coordinate system for this coordinate
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The coordinate name is independent of the grid variable name.
To find the index, the coordinate system name must be given, and either
the coordinate direction or the coordinate name. The coordinate name
will be used if the coordinate direction is given as less than or equal to zero, otherwise the coordinate name will be used.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
index = CCTK_CoordIndex(-1,"xdir","cart3d");
\end{verbatim}
\end{Example}
\begin{Example}{C}
\begin{verbatim}call  CCTK_COORDINDEX(index,one,"radius","spher2d")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Coord.c
\begin{FunctionDescription}{CCTK\_CoordRange}%%%
{Return the global upper and lower bounds for a given coordinate.

\textbf{All the \texttt{CCTK\_Coord*} APIs are deprecated,
and will probably be phased out fairly soon.
New code should use the APIs provided by the \texttt{CoordBase} thorn
instead (this lives in the \texttt{CactusBase} arrangement).}
}
\label{CCTK-CoordRange}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int ierr = CCTK_CoordRange( const cGH * cctkGH, CCTK_REAL * lower, CCTK_REAL * upper, int direction, const char * coordname, const char * systemname)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_CoordRange(ierr , cctkGH, lower, upper, direction, coordname, systemname )

integer ierr
CCTK_POINTER cctkGH
CCTK_REAL lower
CCTK_REAL upper
integer direction
character*(*) coordname
character*(*) systemname \end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{ierr}
Error code
\end{Parameter}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\begin{Parameter}{lower}
Global lower bound of the coordinate (POINTER in C)
\end{Parameter}
\begin{Parameter}{upper}
Global upper bound of the coordinate (POINTER in C)
\end{Parameter}
\begin{Parameter}{direction}
Direction of coordinate in coordinate system
\end{Parameter}
\begin{Parameter}{coordname}
Coordinate name
\end{Parameter}
\begin{Parameter}{systemname}
Coordinate system name
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The coordinate name is independent of the grid function name.
The coordinate range is registered by \code{CCTK\_CoordRegisterRange}.
To find the range, the coordinate system name must be given, and either
the coordinate direction or the coordinate name. The coordinate direction
will be used if is given as a positive value, otherwise the coordinate
name will be used.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
ierr = CCTK_CoordRange(cctkGH, &xmin, &xmax, -1, "xdir", "mysystem");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_COORDRANGE(ierr, cctkGH, Rmin, Rmax, -1, "radius", "sphersystem")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Coord.c
\begin{FunctionDescription}{CCTK\_CoordRegisterData}%%%
{Define a coordinate in a given coordinate system.

\textbf{All the \texttt{CCTK\_Coord*} APIs are deprecated,
and will probably be phased out fairly soon.
New code should use the APIs provided by the \texttt{CoordBase} thorn
instead (this lives in the \texttt{CactusBase} arrangement).}
}
\label{CCTK-CoordRegisterData}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int ierr = CCTK_CoordRegisterData( int direction, const char * gvname, const char * coordname, const char * systemname)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_CoordRegisterData(ierr , direction, gvname, coordname, systemname )

integer ierr
integer direction
character*(*) gvname
character*(*) coordname
character*(*) systemname \end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{ierr}
Error code
\end{Parameter}
\begin{Parameter}{direction}
Direction of coordinate in coordinate system
\end{Parameter}
\begin{Parameter}{gvname}
Name of grid variable associated with coordinate
\end{Parameter}
\begin{Parameter}{coordname}
Name of this coordinate
\end{Parameter}
\begin{Parameter}{systemname}
Name of this coordinate system
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
There must already be a coordinate system registered,
using \code{CCTK\_CoordRegisterSystem}.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
ierr = CCTK_CoordRegisterData(1,"coordthorn::myx","x2d","cart2d");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
two = 2
call CCTK_COORDREGISTERDATA(ierr,two,"coordthorn::mytheta","spher3d")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Coord.c
\begin{FunctionDescription}{CCTK\_CoordRegisterRange}%%%
{Assign the global maximum and minimum
values of a coordinate on a given grid hierachy.

\textbf{All the \texttt{CCTK\_Coord*} APIs are deprecated,
and will probably be phased out fairly soon.
New code should use the APIs provided by the \texttt{CoordBase} thorn
instead (this lives in the \texttt{CactusBase} arrangement).}
}
\label{CCTK-CoordRegisterRange}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int ierr = CCTK_CoordRegisterRange( const cGH * cctkGH, CCTK_REAL min, CCTK_REAL max, int direction, const char * coordname, const char * systemname)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_CoordRegisterRange(ierr , cctkGH, min, max, direction, coordname, systemname )

integer ierr
CCTK_POINTER cctkGH
CCTK_REAL min
CCTK_REAL max
integer direction
character*(*) coordname
character*(*) systemname \end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{ierr}
Error code
\end{Parameter}
\begin{Parameter}{dimension}
Pointer to CCTK grid hierachy
\end{Parameter}
\begin{Parameter}{min}
Global minimum of coordinate
\end{Parameter}
\begin{Parameter}{max}
Global maximum of coordinate
\end{Parameter}
\begin{Parameter}{direction}
Direction of coordinate in coordinate system
\end{Parameter}
\begin{Parameter}{coordname}
Name of coordinate in coordinate system
\end{Parameter}
\begin{Parameter}{systemname}
Name of this coordinate system
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
There must already
be a coordinate registered with the given name, with
\code{CCTK\_CoordRegisterData}.
The coordinate range
can be accessed by \code{CCTK\_CoordRange}.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
ierr = CCTK_CoordRegisterRange(cctkGH,-1.0,1.0,1,"x2d","cart2d");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
min = 0
max = 3.1415d0/2.0d0
two = 2
call CCTK_COORDREGISTERRANGE(ierr,min,max,two,"coordthorn::mytheta","spher3d")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Coord.c
\begin{FunctionDescription}{CCTK\_CoordRegisterSystem}%%%
{Assigns a coordinate system with a chosen name and dimension.

\textbf{All the \texttt{CCTK\_Coord*} APIs are deprecated,
and will probably be phased out fairly soon.
New code should use the APIs provided by the \texttt{CoordBase} thorn
instead (this lives in the \texttt{CactusBase} arrangement).}
}
\label{CCTK-CoordRegisterSystem}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int ierr = CCTK_CoordRegisterSystem( int dimension, const char * systemname)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_CoordRegisterSystem(ierr , dimension, systemname )

integer ierr
integer dimension
character*(*) systemname \end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{ierr}
Error code
\end{Parameter}
\begin{Parameter}{dimension}
Dimension of coordinate system
\end{Parameter}
\begin{Parameter}{systemname}
Unique name assigned to coordinate system
\end{Parameter}
\end{ParameterSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
ierr = CCTK_CoordRegisterSystem(3,"cart3d");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
three = 3
call CCTK_COORDREGISTERSYSTEM(ierr,three,"sphersystem")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{FunctionDescription}{CCTK\_CoordSystemDim}%%%
{Give the dimension for a given coordinate system.

\textbf{All the \texttt{CCTK\_Coord*} APIs are deprecated,
and will probably be phased out fairly soon.
New code should use the APIs provided by the \texttt{CoordBase} thorn
instead (this lives in the \texttt{CactusBase} arrangement).}
}
\label{CCTK-CoordDim}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int dim = CCTK_CoordSystemDim( const char * systemname)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_CoordSystemDim(dim , systemname )

integer dim
character*(*) systemname \end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{dim}
The dimension of the coordinate system
\end{Parameter}
\begin{Parameter}{systemname}
The name of the coordinate system
\end{Parameter}
\end{ParameterSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
dim = CCTK_CoordSystemDim("cart3d");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call  CCTK_COORDSYSTEMDIM(dim,"spher3d")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Coord.c
\begin{FunctionDescription}{CCTK\_CoordSystemHandle}%%%
{Returns the handle associated with a registered coordinate system.

\textbf{All the \texttt{CCTK\_Coord*} APIs are deprecated,
and will probably be phased out fairly soon.
New code should use the APIs provided by the \texttt{CoordBase} thorn
instead (this lives in the \texttt{CactusBase} arrangement).}
}
\label{CCTK-CoordSystemHandle}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int handle = CCTK_CoordSystemHandle( const char * systemname)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_CoordSystemHandle(handle , systemname )

integer handle
character*(*) systemname \end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{handle}
The coordinate system handle
\end{Parameter}
\begin{Parameter}{systemname}
Name of the coordinate system
\end{Parameter}
\end{ParameterSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
handle =  CCTK_CoordSystemHandle("my coordinate system");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_CoordSystemHandle(handle,"my coordinate system")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\begin{ErrorSection}
\begin{Error}{negative}
A negative return code indicates an invalid coordinate system name.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Coord.c
\begin{FunctionDescription}{CCTK\_CoordSystemName}%%%
{Returns the name of a registered coordinate system.

\textbf{All the \texttt{CCTK\_Coord*} APIs are deprecated,
and will probably be phased out fairly soon.
New code should use the APIs provided by the \texttt{CoordBase} thorn
instead (this lives in the \texttt{CactusBase} arrangement).}
}
\label{CCTK-CoordSystemName}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}const char * systemname = CCTK_CoordSystemName(  int handle)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{handle}
The coordinate system handle
\end{Parameter}
\begin{Parameter}{systemname}
The coordinate system name
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
No Fortran routine exists at the moment.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
systemname = CCTK_CoordSystemName(handle);
handle =  CCTK_CoordSystemHandle(systemname);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\begin{ErrorSection}
\begin{Error}{NULL}A NULL pointer is returned if an invalid handle was given.\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Coord.c
\begin{FunctionDescription}{CCTK\_CreateDirectory}{Create a directory with required permissions}
\label{CCTK-CreateDirectory}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int ierr = CCTK_CreateDirectory( int mode, const char * pathname)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_CreateDirectory(ierr , mode, pathname )

integer ierr
integer mode
character*(*) pathname \end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{ierr}
Error code
\end{Parameter}
\begin{Parameter}{mode}
Permission mode for new directory as an octal number
\end{Parameter}
\begin{Parameter}{pathname}
Directory to create
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
To create a directory readable by everyone, but writeable only by the
user running the code, the permission mode would be 0755.
Alternatively, a permission mode of 0777 gives everyone unlimited
access; the user's \code{umask} setting should cut this down to
whatever the user's normal default permissions are anyway.

Note that
(partly for historical reasons and partly for Fortran~77 compatability)
the order of the arguments is the opposite of that of the usual Unix
\code{mkdir(2)} system call.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
ierr = CCTK_CreateDirectory(0755, "Results/New");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_CREATEDIRECTORY(ierr,0755, "Results/New")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\begin{ErrorSection}
\begin{Error}{1}Directory already exists\end{Error}
\begin{Error}{0}Directory successfully created\end{Error}
\begin{Error}{-1}Memory allocation failed\end{Error}
\begin{Error}{-2}Failed to create directory\end{Error}
\begin{Error}{-3}Some component of \code{pathname} already exists but is not a directory\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


%%%%%
% DDD
%%%%%


% Groups.c
\begin{FunctionDescription}{CCTK\_DecomposeName}{Given the full name of a variable/group, separates the name returning both the implementation and the variable/group}
\label{CCTK-DecomposeName}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_DecomposeName( const char * fullname, char ** imp, char ** name)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{istat}
Status flag returned by routine
\end{Parameter}
\begin{Parameter}{fullname}
The full name of the group/variable
\end{Parameter}
\begin{Parameter}{imp}
The implementation name
\end{Parameter}
\begin{Parameter}{name}
The group/variable name
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The implementation name and the group/variable name must be
explicitly freed after they have been used.

No Fortran routine exists at the moment.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
istat = CCTK_DecomposeName("evolve::scalars",imp,name)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


% CommOverloadables.c
\begin{FunctionDescription}{CCTK\_DisableGroupComm}{Turn communications off for a group of grid variables}
\label{CCTK-DisableGroupComm}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_DisableGroupComm( cGH * cctkGH, const char * group)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
Turning off communications means that ghost zones will not be
communicated during a call to \code{CCTK\_SyncGroup}. By default
communications are all off.
\end{Discussion}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_DisableGroupCommI}
\label{CCTK-DisableGroupCommI}
Turn communications off for a group of grid variables.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int istat = CCTK_DisableGroupCommI(cGH * cctkGH, int group);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0}
The Group has been disabled.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\begin{Parameter}{group}
number of group of grid variables to turn off
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Turning off communications means that ghost zones will not be
communicated during a call to \code{CCTK\_SyncGroup}. By default
communications are all off.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2} {CCTK\_DisableGroupComm} {CCTK-DisableGroupComm}
Turn communications off for a group of grid variables.
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_EnableGroupCommI} {CCTK-EnableGroupCommI}
Turn communications on for a group of grid variables.
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_EnableGroupComm} {CCTK-EnableGroupComm}
Turn communications on for a group of grid variables.
\end{SeeAlso2}
\end{SeeAlsoSection}

%\begin{ErrorSection}
%\end{ErrorSection}
\end{FunctionDescription}

% CommOverloadables.c
\begin{FunctionDescription}{CCTK\_DisableGroupStorage}{Free the storage associated with a group of grid variables}
\label{CCTK-DisableGroupStorage}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_DisableGroupStorage( cGH * cctkGH, const char * group)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\end{ParameterSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_DisableGroupStorageI}
\label{CCTK-DisableGroupStorageI}
Deallocates memory for a group based upon its index
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int  CCTK_DisableGroupStorageI(const cGH *GH, int group);\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0}
The group previously had storage
\end{Result}
\begin{Result}{1}
The group did not have storage to disable storage
\end{Result}
\begin{Result}{-1}
The decrease storage routine was not overloaded
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{GH}
pointer to grid hierarchy
\end{Parameter}
\begin{Parameter}{group}
index of the group to deallocate storage for
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The disable group storage routine should deallocate memory for a group and return the previous status of that memory.
This default function checks for the presence of the newer GroupStorageDecrease function, and if that is not available it flags an error. If it is available it makes a call to it, passing -1 as the timelevel argument, which is supposed to mean disable all timelevels, i.e. preserving this obsolete behaviour.
\end{Discussion}
\end{FunctionDescription}

%%%%%
% EEE
%%%%%

% CommOverloadables.c
\begin{FunctionDescription}{CCTK\_EnableGroupComm}{Turn communications on for a group of grid variables}
\label{CCTK-EnableGroupComm}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_EnableGroupComm( cGH * cctkGH, const char * group)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
Grid variables with communication enabled will have their ghost zones communicated during a call
to \code{CCTK\_SyncGroup}. In general, this function does not need to be used, since communication
is automatically enabled for grid variables who have assigned storage via the \code{schedule.ccl}
file.
\end{Discussion}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_EnableGroupCommI}
\label{CCTK-EnableGroupCommI}
Turn communications on for a group of grid variables.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int istat = CCTK_EnableGroupCommI(cGH * cctkGH, int group);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0}
The Group has been enabled.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\begin{Parameter}{group}
number of the group of grid variables to turn on
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Grid variables with communication enabled will have their ghost zones communicated during a call
to \code{CCTK\_SyncGroup}. In general, this function does not need to be used, since communication
is automatically enabled for grid variables who have assigned storage via the \code{schedule.ccl}
file.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2} {CCTK\_DisableGroupComm} {CCTK-DisableGroupComm}
Turn communications off for a group of grid variables.
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_DisableGroupCommI} {CCTK-DisableGroupCommI}
Turn communications off for a group of grid variables.
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_EnableGroupComm} {CCTK-EnableGroupCommI}
Turn communications on for a group of grid variables.
\end{SeeAlso2}
\end{SeeAlsoSection}
%\begin{ErrorSection}
%\end{ErrorSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_EnableGroupStorage}
\label{CCTK-EnableGroupStorage}
Assign the storage for a group of grid variables
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int istat = CCTK_EnableGroupStorage(cGH * cctkGH, const char * group);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0}
The Storage has been enabled.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\begin{Parameter}{group}
name of the group to allocate storage for
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
In general this function does not need to be used, since storage assignment is best handled by
the Cactus scheduler via a thorn's \code{schedule.ccl} file.
\end{Discussion}

%\begin{SeeAlsoSection}
%\end{SeeAlsoSection}
%\begin{ErrorSection}
%\end{ErrorSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_EnableGroupStorageI}
\label{CCTK-EnableGroupStorageI}
Assign the storage for a group of grid variables
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int istat = CCTK_EnableGroupStorageI(cGH * cctkGH, int group);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0}
The Storage has been enabled.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\begin{Parameter}{group}
Index of the group to allocate storage for
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
In general this function does not need to be used, since storage assignment is best handled by
the Cactus scheduler via a thorn's \code{schedule.ccl} file.
\end{Discussion}

%\begin{SeeAlsoSection}
%\end{SeeAlsoSection}
%\begin{ErrorSection}
%\end{ErrorSection}
\end{FunctionDescription}

%Entering a function description for CCTK_Equals
\begin{FunctionDescription}{CCTK\_Equals}
\label{CCTK-Equals}
Checks a STRING or KEYWORD parameter for equality with a given string

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int status = CCTK_Equals(const char* parameter, const char* value)
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
integer status
CCTK_POINTER  parameter
character*(*) value
status = CCTK_Equals(parameter, value)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{1}
if the parameter is (case-independently) equal to the specified value
\end{Result}
\begin{Result}{0}
if the parameter is (case-independently) not equal to the specified value
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{parameter}
The string or keyword parameter to compare; Cactus represents this
as a \verb|CCTK_POINTER| pointing to the string value.
\end{Parameter}
\begin{Parameter}{value}
The value against which to compare the string or keyword parameter.
This is typically a string literal (see the examples below).
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This function compares a Cactus parameter of type STRING or KEYWORD against a
given string value. The comparison is performed case-independently,
returning a 1 if the strings are equal, and zero if they differ.

Note that in Fortran code, STRING or KEYWORD parameters are passed as C
pointers, and can not be treated as normal Fortran strings. Thus
\verb|CCTK_Equals| should be used to check the value of such a parameter.
See the examples below for typical usage.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2} {Util\_StrCmpi} {Util-StrCmpi}
compare two C-style strings case-independently
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{null pointer}
If either argument is passed as a null pointer, \verb|CCTK_Equals()|
aborts the Cactus run with an error message.  Otherwise, there are no
error returns from this function.
\end{Error}
\end{ErrorSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
#include "cctk.h"
#include "cctk_Arguments.h"
#include "cctk_Parameters.h"

/*
 * assume this thorn has a string or keyword parameter  my_parameter
 */
void MyThorn_some_function(CCTK_ARGUMENTS)
{
  DECLARE_CCTK_ARGUMENTS;
  DECLARE_CCTK_PARAMETERS;
  
  if (CCTK_Equals(my_parameter, "option A")) {
    CCTK_VInfo(CCTK_THORNSTRING, "using option A");
  }
}
\end{verbatim}
\end{Example}

\begin{Example}{Fortran}
\begin{verbatim}
#include "cctk.h"
#include "cctk_Arguments.h"
#include "cctk_Functions.h"
#include "cctk_Parameters.h"

!
! assume this thorn has a string or keyword parameter  my_parameter
!
subroutine MyThorn_some_routine(CCTK_ARGUMENTS)
   implicit none
   DECLARE_CCTK_ARGUMENTS
   DECLARE_CCTK_FUNCTIONS
   DECLARE_CCTK_PARAMETERS
   
   if (CCTK_Equals(my_parameter, "option A") /= 0) then
      call CCTK_INFO("using option A")
   end if
end subroutine MyThorn_some_routine
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

% WarnLevel.c
%Entering a function description for CCTK_ERROR
\begin{FunctionDescription}{CCTK\_ERROR}
\label{CCTK-ERROR}
Macro to print a single string as error message and stop the code

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include <cctk.h>

CCTK_ERROR(const char *message);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"

call CCTK_ERROR(message)
character*(*) message
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{message}
The error message to print
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This macro can be used by thorns to print a single string as error
message to \code{stderr}.

\code{CCTK\_ERROR(message)} expands to a call to a \verb|CCTK_Error()|
which is equivalent to \verb|CCTK_VError()|, but without the
variable-number-of-arguments feature (so it can be used from
Fortran).%%%
\footnote{%%%
         Some code calls this function directly.
         For reference, the function is:\\
         \texttt{\hbox{}void CCTK\_Error(int line\_number, const char* file\_name, const char* thorn\_name,}\\
         \texttt{\hbox{}~~~~~~~~~~~~~~const char* message)}
         }%%%
{}  The macro automatically includes details about the origin of the warning
(the thorn name, the source code file name and the line number where the macro
occurs).

To include variables in the error message from C, you can use the routine
\code{CCTK\_VError} which accepts a variable argument list.
To include variables from Fortran, a string must be constructed and passed
in a \code{CCTK\_ERROR} macro.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_Abort}{CCTK-Abort}
Abort the code
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_Exit}{CCTK-Exit}
Exit the code cleanly
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_VError}{CCTK-VError}
prints an error message with a variable argument list
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_VWarn}{CCTK-VWarn}
Prints a formatted string with a variable argument list as a warning
message to standard error and possibly stops the code
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_WARN}{CCTK-WARN}
Macro to print a single string as a warning message and possibly stop the code
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
#include <cctk.h>

CCTK_ERROR("Divide by 0");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
#include "cctk.h"

integer       myint
CCTK_REAL     myreal
character*200 message

write(message, '(A32, G12.7, A5, I8)')
&     'Your error message, including ', myreal, ' and ', myint
call CCTK_ERROR(message)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%Entering a function description for CCTK_Error
\begin{FunctionDescription}{CCTK\_Error}
\label{CCTK-Error}
Function to print a single string as error message and stop the code

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include <cctk.h>

void CCTK_Error(int line_number, const char* file_name, 
                const char* thorn_name,const char* message)
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"

call CCTK_Error(line_number, file_name, thorn_name, message)
integer line_number
character*(*) file_name, thorn_name, message
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{line\_number}
The line number in the originating source file where the \code{CCTK\_VError} call
occured. You can use the standardized \code{\_\_LINE\_\_} preprocessor macro here.
\end{Parameter}
\begin{Parameter}{file\_name}
The file name of the originating source file where the \code{CCTK\_VError} call
occured. You can use the standardized \code{\_\_FILE\_\_} preprocessor macro here.
\end{Parameter}
\begin{Parameter}{thorn\_name}
The thorn name of the originating source file where the \code{CCTK\_VError} call occured. You can use the \code{CCTK\_THORNSTRING} macro here (defined in \code{cctk.h}).
\end{Parameter}
\begin{Parameter}{message}
The error message to print
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The macro \verb|CCTK_ERROR| automatically includes the line number, file name
and the name of the originating thorn in the
info message. It is recommended that the macro \code{CCTK\_ERROR} is used
to print a message rather than calling \code{CCTK\_Error} directly.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_Abort}{CCTK-Abort}
Abort the code
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_Exit}{CCTK-Exit}
Exit the code cleanly
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_VError}{CCTK-VError}
prints an error message with a variable argument list
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_VWarn}{CCTK-VWarn}
Prints a formatted string with a variable argument list as a warning
message to standard error and possibly stops the code
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_WARN}{CCTK-WARN}
Macro to print a single string as a warning message and possibly stop the code
\end{SeeAlso2}
\end{SeeAlsoSection}
\end{FunctionDescription}

% CommOverloadables.c
\begin{FunctionDescription}{CCTK\_Exit}{Exit the code cleanly}
\label{CCTK-Exit}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_Exit( cGH * cctkGH, int value)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_Exit(istat , cctkGH, value )

integer istat
CCTK_POINTER cctkGH
integer value \end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\begin{Parameter}{value}
the return code to exit with
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
This routine causes an immediate, regular termination of Cactus.
It never returns to the caller.
\end{Discussion}
\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_Abort}{CCTK-Abort}
Abort the code
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ERROR}{CCTK-ERROR}
Macro to print a single string as error message and stop the code
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_VError}{CCTK-VError}
Prints a formatted string with a variable argument list as error
message to standard error and stops the code
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_VWarn}{CCTK-VWarn}
Prints a formatted string with a variable argument list as a warning
message to standard error and possibly stops the code
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_WARN}{CCTK-WARN}
Macro to print a single string as a warning message and possibly stop the code
\end{SeeAlso2}
\end{SeeAlsoSection}
\end{FunctionDescription}




%%%%%
% FFF
%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Groups.c
%Entering a function description for CCTK_FirstVarIndex
\begin{FunctionDescription}{CCTK\_FirstVarIndex}
\label{CCTK-FirstVarIndex}
Given a group name, returns the first variable index in the group.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int first_varindex = CCTK_FirstVarIndex(const char* group_name);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"
        integer first_varindex
        character*(*) group_name
        call CCTK_FirstVarIndex(first_varindex, group_name)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{first\_varindex ($\ge$ 0)}
The first variable index in the group.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{group\_name ($\ne$ {\t NULL} in C)}
For C, this is a non-{\t NULL} pointer to the character-string name
of the group.  For Fortran, this is the character-string name of the
group.  In both cases this should be of the form
{\t "implementation::group"}.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
If the group contains $N > 0$ variables, and $V$ is the value of
{\t first\_varindex} returned by this function, then the group's
variables have variable indices $V$, $V+1$, $V+2$, \dots, $V+N-1$.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_FirstVarIndexI()}
Given a group index, returns the first variable index in the group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupData()}
Get ``static'' information about a group
(including the number of variables in the group).
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupDynamicData()}
Get ``dynamic'' information about a group.
\end{SeeAlso}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{-1}
Group name is invalid.
\end{Error}
\begin{Error}{-2}
Group has no members.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Groups.c
%Entering a function description for CCTK_FirstVarIndexI
\begin{FunctionDescription}{CCTK\_FirstVarIndexI}
\label{CCTK-FirstVarIndexI}
Given a group index, returns the first variable index in the group.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int first_varindex = CCTK_FirstVarIndexI(int group_index)
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"
        integer first_varindex, group_index
        call CCTK_FirstVarIndexI(first_varindex, group_index)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{first\_varindex ($\ge$ 0)}
The first variable index in the group.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{group\_index ($\ge$ 0)}
The group index, e.g. as returned by {\t CCTK\_GroupIndex()}.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
If the group contains $N > 0$ variables, and $V$ is the value of
{\t first\_varindex} returned by this function, then the group's
variables have variable indices $V$, $V+1$, $V+2$, \dots, $V+N-1$.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_FirstVarIndex()}
Given a group name, returns the first variable index in the group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupData()}
Get ``static'' information about a group
(including the number of variables in the group).
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupDynamicData()}
Get ``dynamic'' information about a group.
\end{SeeAlso}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{-1}
Group index is invalid.
\end{Error}
\begin{Error}{-2}
Group has no members.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%Entering a function description for CCTK_FortranString
\begin{FunctionDescription}{CCTK\_FortranString}
\label{CCTK-FortranString}
Copy the contents of a C string into a Fortran string variable

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int CCTK_FortranString (char const * c_string,
                        char       * fortran_string,
                        int          fortran_length);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"
subroutine CCTK_FortranString (string_length, c_string, fortran_string)
   CCTK_INT              string_length
   CCTK_POINTER_TO_CONST c_string
   character*(*)         fortran_string
end subroutine
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{c\_string}
This is (a pointer to) a standard C-style (NUL-terminated) string.
Typically this argument is the name of a Cactus keyword or string
paramameter.
\end{Parameter}
\begin{Parameter}{fortran\_string}
[This is an output argument]
A Fortran character variable into which this function copies
the C string (or as much of it as will fit).
\end{Parameter}
\begin{Parameter}{fortran\_length}
The length of the Fortran character variable.
\end{Parameter}
\end{ParameterSection}

\begin{ResultSection}
\begin{Result}{string\_length}
This function sets this variable to the number of characters in the
C string (not counting the terminating NUL character).  If this is
larger than the declared length of \code{fortran\_string} then the
string was truncated.  If this is negative, then an error occurred.
\end{Result}
\end{ResultSection}

\begin{Discussion}
String or keyword parameters in Cactus are passed into Fortran routines
as pointers to C strings, which can't be directly used by Fortran code.
This subroutine copies such a C string into a Fortran character*N string
variable, from where it can be used by Fortran code.
\end{Discussion}

\begin{ExampleSection}
\begin{Example}{Fortran}
\begin{verbatim}
# *** this is param.ccl for some thorn ***

# This example shows how we can use a Cactus string parameter to
# specify the contents of a Cactus key/value table, or the name of
# a Fortran output file

string our_parameters "parameter string"
{
".*" :: "any string acceptable to Util_TableCreateFromString()"
} "order=3"

string output_file_name "name of our output file"
{
".*" :: "any valid file name"
} "foo.dat"


c *** this is sample Fortran code in this same thorn ***
#include "util_Table.h"
#include "cctk.h"
#include "cctk_Arguments.h"
#include "cctk_Parameters.h"

        subroutine my_Fortran_subroutine(CCTK_ARGUMENTS)
        DECLARE_CCTK_ARGUMENTS
        DECLARE_CCTK_PARAMETERS

        CCTK_INT :: string_length
        integer  :: status
        integer  :: table_handle

        integer, parameter:: max_string_length = 500
        character*max_string_length :: our_parameters_fstring
        character*max_string_length :: output_file_name_fstring

c
c create Cactus key/value table from  our_parameters  parameter
c
        call CCTK_FortranString(string_length,
     $                          our_parameters,
     $                          our_parameters_fstring)
        if (string_length .gt. max_string_length) then
           call CCTK_WARN(CCTK_WARN_ALERT, "'our_parameters' string too long!")
        end if
        call Util_TableCreateFromString(table_handle, our_parameters_fstring)

c
c open a Fortran output file named via  output_file_name  parameter
c
        call CCTK_FortranString(string_length,
     $                          output_file_name,
     $                          output_file_name_fstring)
        if (string_length .gt. max_string_length) then
           call CCTK_WARN(CCTK_WARN_ALERT, "'output_file_name' string too long!")
        end if
        open (unit=9, iostat=status, status='replace',
     $        file=output_file_name_fstring)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}



\begin{FunctionDescription}{CCTK\_FullName}{Given a variable index, returns the full name of the variable}
\label{CCTK-FullName}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}char * fullname = CCTK_FullName( int index)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{implementation}
The full variable name
\end{Parameter}
\begin{Parameter}{index}
The variable index
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The full variable name must be explicitly freed after it has been used.

No Fortran routine exists at the moment. The full variable name is in
the form \code{<implementation>::<variable>}
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
index = CCTK_VarIndex("evolve::phi");
name = CCTK_FullName(index);
printf ("Variable name: %s", name);
free (name);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}




%%%%%
% GGG
%%%%%


\begin{FunctionDescription}{CCTK\_GetClockName}
\label{CCTK-GetClockName}
Given a pointer to the {\tt cTimerVal}
corresponding to a timer clock returns a pointer to a string that is
the name of the clock
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
const char * CCTK_GetClockName(val)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{const cTimerVal * val}
timer clock value pointer
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Do not attempt to free the returned pointer directly.  You must use the
string before calling {\tt CCTK\_TimerDestroyData} on the containing
timer info.
\end{Discussion}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_GetClockResolution}
\label{CCTK-GetClockResolution}
Given a pointer to the
{\tt cTimerVal} corresponding to a timer clock returns the resolution of
the clock in seconds.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
double CCTK_GetClockResolution(val)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{const cTimerVal * val}
timer clock value pointer
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Ideally, the resolution should represent a good lower bound on the smallest
non-zero difference between two consecutive calls of {\t CCTK\_GetClockSeconds}.
In practice, it is sometimes far smaller than it should be.  Often it just
represents the smallest value representable due to how the information is
stored internally.
\end{Discussion}
\end{FunctionDescription}



\begin{FunctionDescription}{CCTK\_GetClockSeconds}
\label{CCTK-GetClockSeconds}
Given a pointer to the {\tt cTimerVal}
corresponding to a timer clock returns a the elapsed time in seconds between
the preceding {\tt CCTK\_TimerStart} and {\tt CCTK\_TimerStop} as recorded
by the requested clock.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
double CCTK_GetClockSeconds(val)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{const cTimerVal * val}
timer clock value pointer
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Be aware, different clocks measure different things (proper time,
CPU time spent on this process, etc.), and have varying resolution
and accuracy.
\end{Discussion}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_GetClockValue}
\label{CCTK-GetClockValue}
Given a name of a clock that is
in the given {\tt cTimerData} structure,
returns a pointer to the {\tt cTimerVal} structure holding the clock's value.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
const cTimerVal * CCTK_GetClockValue(name, info)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter} {const char * name}
Name of clock
\end{Parameter}

\begin{Parameter} {const cTimerData * info}
Timer information structure containing clock.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Do not attempt to free the returned pointer directly.
\end{Discussion}
\begin{ErrorSection}
\begin{Error}
A null return value indicates an error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}



\begin{FunctionDescription}{CCTK\_GetClockValueI}
\label{CCTK-GetClockValueI}
Given a index of a clock that is
in the given {\tt cTimerData} structure,
returns a pointer to the {\tt cTimerVal} structure holding the clock's value.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
const cTimerVal * CCTK_GetClockValue(index, info)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter} {int index}
Index of clock
\end{Parameter}

\begin{Parameter} {const cTimerData * info}
Timer information structure containing clock.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Do not attempt to free the returned pointer directly.
\end{Discussion}
\begin{ErrorSection}
\begin{Error}
A null return value indicates an error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


% cctk_GHExtensions.h
\begin{FunctionDescription}{CCTK\_GHExtension}{Get the pointer to a registered extension to the Cactus GH structure}
\label{CCTK-GHExtension}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}void * extension = CCTK_GHExtension( const GH * cctkGH, const char * name)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{extension}
The pointer to the GH extension
\end{Parameter}
\begin{Parameter}{cctkGH}
The pointer to the CCTK grid hierarchy
\end{Parameter}
\begin{Parameter}{name}
The name of the GH extension
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
No Fortran routine exists at the moment.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
void *extension = CCTK_GHExtension(GH, "myExtension");
\end{verbatim}
\end{Example}
\end{ExampleSection}
\begin{ErrorSection}
\begin{Error}{NULL}A NULL pointer is returned if an invalid extension name was given.\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

% cctk_GHExtensions.h
\begin{FunctionDescription}{CCTK\_GHExtensionHandle}{Get the handle associated with a extension to the Cactus GH structure}
\label{CCTK-GHExtensionHandle}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int handle = CCTK_GHExtensionHandle( const char * name)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_GHExtensionHandle(handle , name )

integer handle
character*(*) name\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{handle}
The GH extension handle
\end{Parameter}
\begin{Parameter}{group}
The name of the GH extension
\end{Parameter}
\end{ParameterSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
handle =  CCTK_GHExtension("myExtension") ;
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_GHExtension(handle,"myExtension")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}



% Groups.c
%Reduction.c
\begin{FunctionDescription}{CCTK\_GridArrayReductionOperator}
\label{CCTK-GridArrayReductionOperator}
The name of the implementation of the registered grid array reduction operator, NULL if none is registered

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

const char *ga_reduc_imp = CCTK_GridArrayReductionOperator();
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{ga\_reduc\_imp}
Returns the name of the implementation of the registered grid array reduction operator
or NULL if none is registered
\end{Result}
\end{ResultSection}


%\begin{ParameterSection}
%\end{ParameterSection}

\begin{Discussion}
We only allow one grid array reduction operator currently. This function can be used to check if any grid array reduction operator has been registered.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_ReduceGridArrays()}
Performs reduction on a list of distributed grid arrays
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_RegisterGridArrayReductionOperator()}
Registers a function as a grid array reduction operator of a certain name
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_NumGridArrayReductionOperators()}
The number of grid array reduction operators registered
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}


% GroupsOnGH.h
%Entering a function description for CCTK_GroupbboxGI, CCTK_GroupbboxGN
\begin{FunctionDescription}{CCTK\_GroupbboxGI, CCTK\_GroupbboxGN}
\label{CCTK-GroupbboxGI}
\label{CCTK-GroupbboxGN}
Given a group index or name, return an array of the bounding box of the group for each face

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_GroupbboxGI(const cGH *cctkGH,
                              int dim,
                              int *bbox,
                              int groupindex);

int status = CCTK_GroupbboxGN(const cGH *cctkGH,
                              int dim,
                              int *bbox,
                              const char *groupname);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_GroupbboxGI(status, cctkGH, dim, bbox, groupindex)

call CCTK_GroupbboxGN(status, cctkGH, dim, bbox, groupname)

integer       status
CCTK_POINTER  cctkGH
integer       dim
integer       bbox(dim)
integer       groupindex
character*(*) groupname
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{-1} incorrect dimension supplied \end{Result}
\begin{Result}{-2} data not available from driver \end{Result}
\begin{Result}{-3} called on a scalar group \end{Result}
\begin{Result}{-4} invalid group index \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{status} Return value. \end{Parameter}
\begin{Parameter}{cctkGH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter}
\begin{Parameter}{dim ($\ge 1$)} Number of dimensions of group. \end{Parameter}
\begin{Parameter}{bbox ($\ne$ NULL)} Pointer to array which will hold the return values. \end{Parameter}
\begin{Parameter}{groupindex} Group index. \end{Parameter}
\begin{Parameter}{groupname} Group's full name. \end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The bounding box for a given group is returned in a user-supplied array buffer.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GroupbboxVI, CCTK\_GroupbboxVN}
Returns the lower bounds for a given variable.
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}


%Entering a function description for CCTK_GroupbboxVI, CCTK_GroupbboxVN
\begin{FunctionDescription}{CCTK\_GroupbboxVI, CCTK\_GroupbboxVN}
\label{CCTK-GroupbboxVI}
\label{CCTK-GroupbboxVN}
Given a variable index or name, return an array of the bounding box of the variable for each face

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_GroupbboxVI(const cGH *cctkGH,
                              int dim,
                              int *bbox,
                              int varindex);

int status = CCTK_GroupbboxVN(const cGH *cctkGH,
                              int dim,
                              int *bbox,
                              const char *varname);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_GroupbboxVI(status, cctkGH, dim, bbox, varindex)

call CCTK_GroupbboxVN(status, cctkGH, dim, bbox, varname)

integer       status
CCTK_POINTER  cctkGH
integer       dim
integer       bbox(dim)
integer       varindex
character*(*) varname
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{-1} incorrect dimension supplied \end{Result}
\begin{Result}{-2} data not available from driver \end{Result}
\begin{Result}{-3} called on a scalar group \end{Result}
\begin{Result}{-4} invalid variable index \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{status} Return value. \end{Parameter}
\begin{Parameter}{cctkGH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter}
\begin{Parameter}{dim ($\ge 1$)} Number of dimensions of variable. \end{Parameter}
\begin{Parameter}{bbox ($\ne$ NULL)} Pointer to array which will hold the return values. \end{Parameter}
\begin{Parameter}{varindex} Group index. \end{Parameter}
\begin{Parameter}{varname} Group's full name. \end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The bounding box for a given variable is returned in a user-supplied array buffer.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GroupbboxGI, CCTK\_GroupbboxGN}
Returns the upper bounds for a given group.
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Groups.c
%Entering a function description for CCTK\_GroupData
\begin{FunctionDescription}{CCTK\_GroupData}
\label{CCTK-GroupData}
Given a group index, returns information about the group and its variables.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int status = CCTK_GroupData(int group_index, cGroup* group_data_buffer);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0}
success
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{group\_index}
The group index for which the information is desired.
\end{Parameter}
\begin{Parameter}{group\_data\_buffer ($\ne$ NULL)}
Pointer to a {\t cGroup} structure in which the information should be
stored.  See the "Discussion" section below for more information about
this structure.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The {\t cGroup} structure%%%
\footnote{%%%
         {\t cGroup} is is a {\t typedef} for a structure.
         It's defined in {\t "cctk\_Group.h"}, which is
         {\t \#include}d by {\t "cctk.h"}.
         }%%%
{} contains (at least) the following members:%%%
\footnote{%%%
         Note that the members are {\bf not\/}
         guaranteed to be declared in the order
         listed here.
         }%%%
\begin{verbatim}
  int grouptype;      /* group type, as returned by CCTK_GroupTypeNumber() */
  int vartype;        /* variable type, as returned by CCTK_VarTypeNumber() */
  int disttype;       /* distribution type, */
                      /* as returned by CCTK_GroupDistribNumber() */
  int dim;            /* dimension (rank) of the group */
                      /* e.g. 3 for a group of 3-D variables */
  int numvars;        /* number of variables in the group */
  int numtimelevels;  /* maximum number of time levels for this group's variables */
  int vectorgroup;    /* 1 if this is a vector group, 0 if it's not */
  int vectorlength;   /* vector length of group */
                      /* (i.e. number of vector elements) */
                      /* (it is numvars = vectorlength * num_basevars, */
                      /*  where num_basevars is the number of */
                      /*  variables that have been given names in the */
                      /*  interface.ccl) */
                      /* 1 if this isn't a vector group */
  int tagstable;      /* handle to the group's tags table; */
                      /* this is a Cactus key-value table used to store */
                      /* metadata about the group and its variables, */
                      /* such as the variables' tensor types */
\end{verbatim}
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{"interface.ccl"}
Defines variables, groups, tags tables, and lots of other things.
\end{SeeAlso}
\begin{SeeAlso2} {CCTK\_GroupDynamicData} {CCTK-GroupDynamicData}
Gets grid-size information for a group's variables.
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_GroupIndex} {CCTK-GroupIndex}
Gets the group index for a given group name.
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_GroupIndexFromVar} {CCTK-GroupIndexFromVar}
Gets the group index for a given variable name.
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_GroupName} {CCTK-GroupName}
Gets the group name for a given group index.
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_GroupNameFromVarI} {CCTK-GroupNameFromVarI}
Gets the group name for a given variable name.
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_GroupTypeI} {CCTK-GroupTypeI}
Gets a group type index for a given group index.
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_GroupTypeFromVarI} {CCTK-GroupTypeFromVarI}
Gets a group type index for a given variable index.
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{-1}
{\t group\_index} is invalid.
\end{Error}
\begin{Error}{-2}
{\t group\_data\_buffer} is {\t NULL}.
\end{Error}
\end{ErrorSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
#include <stdio.h>
#include "cctk.h"

cGroup group_info;
int group_index, status;

group_index = CCTK_GroupIndex("BSSN_MoL::ADM_BSSN_metric");
if (group_index < 0)
        CCTK_VWarn(CCTK_WARN_ABORT,
"error return %d trying to get BSSN metric's group index!",
                   group_index);                                /*NOTREACHED*/

status = CCTK_GroupData(group_index, &group_info);
if (status < 0)
        CCTK_VWarn(CCTK_WARN_ABORT,
"error return %d trying to get BSSN metric's group information!",
                   status);                                     /*NOTREACHED*/

printf("this group's arrays are %-dimensional and have %d time levels\n",
       group_info.dim, group_info.numtimelevels);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%Entering a function description for CCTK\_GroupDimFromVarI
\begin{FunctionDescription}{CCTK\_GroupDimFromVarI}
\label{CCTK-GroupDimFromVarI}
Given a variable index, returns the dimension of all variables in the corresponding group.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int dim = CCTK_GroupDimFromVarI(int varindex);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_GroupDimFromVarI(dim, varindex)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{positive} the dimension of the group\end{Result}
\begin{Result}{-1} invalid variable index \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{varindex}Variable index\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The dimension of all variables in a group associcated with the given variable is returned.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GroupDimI}
Returns the dimension for a given group
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}

%Entering a function description for CCTK\_GroupDimI
\begin{FunctionDescription}{CCTK\_GroupDimI}
\label{CCTK-GroupDimI}
Given a group index, returns the dimension of that group.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int dim = CCTK_GroupDimI(int groupindex);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_GroupDimI(dim, groupindex)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{positive} the dimension of the group\end{Result}
\begin{Result}{-1} invalid group index \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{groupindex}Group index\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The dimension of variables in the given group is returned.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GroupDimFromVarI}
Returns the dimension for a group given by a member variable index
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}


%Entering a function description for CCTK\_GroupDynamicData}{
\begin{FunctionDescription}{CCTK\_GroupDynamicData}{}
\label{CCTK-GroupDynamicData}
Returns the driver's internal data for a given group
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int retval = CCTK_GroupDynamicData (const cGH *GH, int group, cGroupDynamicData *data);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin {Result}{0}
Sucess
\end{Result}
\begin{Result}{-1}
the given pointer to the data structure data is null
\end{Result}
\begin{Result}{-3}
the givenGH pointer is invalid
\end{Result}
\begin{Result}{-77}
the requested group has zero variables
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{GH}
a valid initialized GH structure for your driver
\end{Parameter}
\begin{Parameter}{group}
the index of the group you're interested in
\end{Parameter}
\begin{Parameter}{data}
a pointer to a caller-supplied data structure to store the group data
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This function returns information about the given grid hierarchy.
The data structure used to store the information in is of type cGroupDynamicData.
The members of this structure that are set are:
\begin{itemize}
\item{dim:} The number of dimensions in this group.
\item{lsh:} The (process-)local size.
\item{ash:} The (process-)local allocated size.
\item{gsh:} The global grid size.
\item{lbnd:} The lowest index of the local grid as seen on the global
  grid. (These use zero based indexing.)
\item{ubnd:} The largest index of the local grid as seen on the global
  grid. (These use zero based indexing.)
\item{nghostzones:} The number of ghostzones for each dimension.
\item{bbox:} Values indicating whether these are inter-process
  boundaries (0) or physical boundaries (1).
\item{activetimelevels:} The number of active time levels.
\end{itemize}-
\end{Discussion}

%\begin{SeeAlsoSection}
%\end{SeeAlsoSection}
%\begin{ErrorSection}
%\end{ErrorSection}
%\begin{ExampleSection}
%\end{ExampleSection}
\end{FunctionDescription}

%Entering a function description for CCTK\_GroupGhostsizesI
\begin{FunctionDescription}{CCTK\_GroupGhostsizesI}
\label{CCTK-GroupGhostsizesI}
Given a group index, return a pointer to an array containing the ghost sizes of the group in each dimension.
 
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

CCTK_INT **ghostsizes = CCTK_GroupGhostsizesI(int groupindex);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{non-NULL} a pointer to the ghost size array\end{Result}
\begin{Result}{NULL} invalid group index \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{groupindex}Group index\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The ghost sizes in each dimension for a given group are returned as a pointer reference.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GroupDimI}
Returns the dimension for a group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupSizesI}
Returns the size arrays for a group.
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}

%Entering a function description for CCTK\_GroupgshGI, CCTK\_GroupgshGN
\begin{FunctionDescription}{CCTK\_GroupgshGI, CCTK\_GroupgshGN}
\label{CCTK-GroupgshGI}
\label{CCTK-GroupgshGN}
Given a group index or name, return an array of the global size of the group in each dimension

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_GroupgshGI(const cGH *cctkGH,
                             int dim,
                             int *gsh,
                             int groupindex);

int status = CCTK_GroupgshGN(const cGH *cctkGH,
                             int dim,
                             int *gsh,
                             const char *groupname);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_GroupgshGI(status, cctkGH, dim, gsh, groupindex)

call CCTK_GroupgshGN(status, cctkGH, dim, gsh, groupname)

integer       status
CCTK_POINTER  cctkGH
integer       dim
integer       gsh(dim)
integer       groupindex
character*(*) groupname
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{-1} incorrect dimension supplied \end{Result}
\begin{Result}{-2} data not available from driver \end{Result}
\begin{Result}{-3} called on a scalar group \end{Result}
\begin{Result}{-4} invalid group name \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{cctkGH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter}
\begin{Parameter}{dim ($\ge 1$)} Number of dimensions of group. \end{Parameter}
\begin{Parameter}{gsh ($\ne$ NULL)} Pointer to array which will hold the return values. \end{Parameter}
\begin{Parameter}{groupindex} Index of the group. \end{Parameter}
\begin{Parameter}{groupname} Name of the group. \end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The global size in each dimension for a given group is returned in a user-supplied array buffer.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GroupgshVI, CCTK\_GroupgshVN}
Returns the global size for a given variable.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GrouplshGI, CCTK\_GrouplshGN}
Returns the local size for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GrouplshVI, CCTK\_GrouplshVN}
Returns the local size for a given variable.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupashGI, CCTK\_GroupashGN}
Returns the local allocated size for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupashVI, CCTK\_GroupashVN}
Returns the local allocated size for a given variable.
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}


%Entering a function description for CCTK\_GroupgshVI, CCTK\_GroupgshVN
\begin{FunctionDescription}{CCTK\_GroupgshVI, CCTK\_GroupgshVN}
\label{CCTK-GroupgshVI}
\label{CCTK-GroupgshVN}
Given a variable index or its full name, return an array of the global size of the variable in each dimension

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_GroupgshVI(const cGH *cctkGH,
                             int dim,
                             int *gsh,
                             int varindex);

int status = CCTK_GroupgshVN(const cGH *cctkGH,
                             int dim,
                             int *gsh,
                             const char *varname);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_GroupgshVI(status, cctkGH, dim, gsh, varindex)

call CCTK_GroupgshVN(status, cctkGH, dim, gsh, varname)

integer         status
CCTK_POINTER    cctkGH
integer         dim
integer         gsh(dim)
integer         varindex
chararacter*(*) varname
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{-1} incorrect dimension supplied \end{Result}
\begin{Result}{-2} data not available from driver \end{Result}
\begin{Result}{-3} called on a scalar group \end{Result}
\begin{Result}{-4} invalid variable index \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{status} Return value. \end{Parameter}
\begin{Parameter}{cctkGH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter}
\begin{Parameter}{dim ($\ge 1$)} Number of dimensions of variable. \end{Parameter}
\begin{Parameter}{gsh ($\ne$ NULL)} Pointer to array which will hold the return values. \end{Parameter}
\begin{Parameter}{varindex} Variable index. \end{Parameter}
\begin{Parameter}{varname} Variable's full name. \end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The global size in each dimension for a given variable is returned in a user-supplied array buffer.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GroupgshGI, CCTK\_GroupgshGN}
Returns the global size for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GrouplshGI, CCTK\_GrouplshGN}
Returns the local size for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GrouplshVI, CCTK\_GrouplshVN}
Returns the local size for a given variable.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupashGI, CCTK\_GroupashGN}
Returns the local size for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupashVI, CCTK\_GroupashVN}
Returns the local size for a given variable.
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}


% Groups.c
\begin{FunctionDescription}{CCTK\_GroupIndex}{Get the index number for a group name}
\label{CCTK-GroupIndex}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int index = CCTK_GroupIndex( const char * groupname)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_GroupIndex(index , groupname )

integer index
character*(*) groupname\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{groupname}
The name of the group
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The group name should be the given in its fully qualified form, that is \code{<implementation>::<group>} for a public or protected group, and \code{<thornname>::<group>} for a private group.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
index = CCTK_GroupIndex("evolve::scalars");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_GroupIndex(index,"evolve::scalars")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}



% Groups.c
\begin{FunctionDescription}{CCTK\_GroupIndexFromVar}{Given a variable name, returns the index of the associated group}
\label{CCTK-GroupIndexFromVar}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int groupindex = CCTK_GroupIndexFromVar( const char * name)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_GroupIndexFromVar(groupindex , name )

integer groupindex
character*(*) name \end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{groupindex}
The index of the group
\end{Parameter}
\begin{Parameter}{name}
The full name of the variable
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The variable name should be in the form \code{<implementation>::<variable>}
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
groupindex = CCTK_GroupIndexFromVar("evolve::phi") ;
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_GROUPINDEXFROMVAR(groupindex,"evolve::phi")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


% Groups.c
\begin{FunctionDescription}{CCTK\_GroupIndexFromVarI}{Given a variable index, returns the index of the associated group}
\label{CCTK-GroupIndexFromVarI}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int groupindex = CCTK_GroupIndexFromVarI( int varindex)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_GroupIndexFromVarI(groupindex , varindex )

integer groupindex
integer varindex \end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{groupindex}
The index of the group
\end{Parameter}
\begin{Parameter}{varindex}
The index of the variable
\end{Parameter}
\end{ParameterSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
index = CCTK_VarIndex("evolve::phi");
groupindex = CCTK_GroupIndexFromVarI(index);
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_VARINDEX("evolve::phi")
CCTK_GROUPINDEXFROMVARI(groupindex,index)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


%Entering a function description for CCTK_GrouplbndGI, CCTK_GrouplbndGN
\begin{FunctionDescription}{CCTK\_GrouplbndGI, CCTK\_GrouplbndGN}
\label{CCTK-GrouplbndGI}
\label{CCTK-GrouplbndGN}
Given a group index or name, return an array of the lower bounds of the group in each dimension

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_GrouplbndGI(const cGH *cctkGH,
                              int dim,
                              int *lbnd,
                              int groupindex);

int status = CCTK_GrouplbndGN(const cGH *cctkGH,
                              int dim,
                              int *lbnd,
                              const char *groupname);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_GrouplbndGI(status, cctkGH, dim, lbnd, groupindex)

call CCTK_GrouplbndGN(status, cctkGH, dim, lbnd, groupname)

integer       status
CCTK_POINTER  cctkGH
integer       dim
integer       lbnd(dim)
integer       groupindex
character*(*) groupname
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{-1} incorrect dimension supplied \end{Result}
\begin{Result}{-2} data not available from driver \end{Result}
\begin{Result}{-3} called on a scalar group \end{Result}
\begin{Result}{-4} invalid group index \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{status} Return value. \end{Parameter}
\begin{Parameter}{cctkGH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter}
\begin{Parameter}{dim ($\ge 1$)} Number of dimensions of group. \end{Parameter}
\begin{Parameter}{lbnd ($\ne$ NULL)} Pointer to array which will hold the return values. \end{Parameter}
\begin{Parameter}{groupindex} Group index. \end{Parameter}
\begin{Parameter}{groupname} Group's full name. \end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The lower bounds in each dimension for a given group is returned in a user-supplied array buffer.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GrouplbndVI, CCTK\_GrouplbndVN}
Returns the lower bounds for a given variable.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupubndGI, CCTK\_GroupubndGN}
Returns the upper bounds for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupubndVI, CCTK\_GroupubndVN}
Returns the upper bounds for a given variable.
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}


%Entering a function description for CCTK\_GrouplbndVI, CCTK\_GrouplbndVN
\begin{FunctionDescription}{CCTK\_GrouplbndVI, CCTK\_GrouplbndVN}
\label{CCTK-GrouplbndVI}
\label{CCTK-GrouplbndVN}
Given a variable index or name, return an array of the lower bounds of the variable in each dimension

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_GrouplbndVI(const cGH *cctkGH,
                              int dim,
                              int *lbnd,
                              int varindex);

int status = CCTK_GrouplbndVN(const cGH *cctkGH,
                              int dim,
                              int *lbnd,
                              const char *varname);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_GrouplbndVI(status, cctkGH, dim, lbnd, varindex)

call CCTK_GrouplbndVN(status, cctkGH, dim, lbnd, varname)

integer       status
CCTK_POINTER  cctkGH
integer       dim
integer       lbnd(dim)
integer       varindex
character*(*) varname
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{-1} incorrect dimension supplied \end{Result}
\begin{Result}{-2} data not available from driver \end{Result}
\begin{Result}{-3} called on a scalar group \end{Result}
\begin{Result}{-4} invalid variable index \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{status} Return value. \end{Parameter}
\begin{Parameter}{cctkGH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter}
\begin{Parameter}{dim ($\ge 1$)} Number of dimensions of variable. \end{Parameter}
\begin{Parameter}{lbnd ($\ne$ NULL)} Pointer to array which will hold the return values. \end{Parameter}
\begin{Parameter}{varindex} Group index. \end{Parameter}
\begin{Parameter}{varname} Group's full name. \end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The lower bounds in each dimension for a given variable is returned in a user-supplied array buffer.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GrouplbndGI, CCTK\_GrouplbndGN}
Returns the lower bounds for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupubndGI, CCTK\_GroupubndGN}
Returns the upper bounds for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupubndVI, CCTK\_GroupubndVN}
Returns the upper bounds for a given variable.
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}


%Entering a function description for CCTK\_GrouplshGI, CCTK\_GrouplshGN
\begin{FunctionDescription}{CCTK\_GrouplshGI, CCTK\_GrouplshGN}
\label{CCTK-GrouplshGI}
\label{CCTK-GrouplshGN}
Given a group index or name, return an array of the local size of the group in each dimension

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_GrouplshGI(const cGH *cctkGH,
                             int dim,
                             int *lsh,
                             int groupindex);

int status = CCTK_GrouplshGN(const cGH *cctkGH,
                             int dim,
                             int *lsh,
                             const char *groupname);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_GrouplshGI(status, cctkGH, dim, lsh, groupindex)

call CCTK_GrouplshGN(status, cctkGH, dim, lsh, groupname)

integer       status
CCTK_POINTER  cctkGH
integer       dim
integer       lsh(dim)
integer       groupindex
character*(*) groupname
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{-1} incorrect dimension supplied \end{Result}
\begin{Result}{-2} data not available from driver \end{Result}
\begin{Result}{-3} called on a scalar group \end{Result}
\begin{Result}{-4} invalid group name \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{cctkGH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter}
\begin{Parameter}{dim ($\ge 1$)} Number of dimensions of group. \end{Parameter}
\begin{Parameter}{lsh ($\ne$ NULL)} Pointer to array which will hold the return values. \end{Parameter}
\begin{Parameter}{groupindex} Index of the group. \end{Parameter}
\begin{Parameter}{groupname} Name of the group. \end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The local size in each dimension for a given group is returned in a user-supplied array buffer.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GroupgshGI, CCTK\_GroupgshGN}
Returns the global size for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupgshVI, CCTK\_GroupgshVN}
Returns the global size for a given variable.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GrouplshVI, CCTK\_GrouplshVN}
Returns the local size for a given variable.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupashGI, CCTK\_GroupashGN}
Returns the local allocated size for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupashVI, CCTK\_GroupashVN}
Returns the local allocated size for a given variable.
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}


%Entering a function description for CCTK\_GrouplshVI, CCTK\_GrouplshVN
\begin{FunctionDescription}{CCTK\_GrouplshVI, CCTK\_GrouplshVN}
\label{CCTK-GrouplshVI}
\label{CCTK-GrouplshVN}
Given a variable index or its full name, return an array of the local size of the variable in each dimension

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_GrouplshVI(const cGH *cctkGH,
                             int dim,
                             int *lsh,
                             int varindex);

int status = CCTK_GrouplshVN(const cGH *cctkGH,
                             int dim,
                             int *lsh,
                             const char *varname);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_GrouplshVI(status, cctkGH, dim, lsh, varindex)

call CCTK_GrouplshVN(status, cctkGH, dim, lsh, varname)

integer       status
CCTK_POINTER  cctkGH
integer       dim
integer       lsh(dim)
integer       varindex
character*(*) varname
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{-1} incorrect dimension supplied \end{Result}
\begin{Result}{-2} data not available from driver \end{Result}
\begin{Result}{-3} called on a scalar group \end{Result}
\begin{Result}{-4} invalid variable index \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{status} Return value. \end{Parameter}
\begin{Parameter}{cctkGH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter}
\begin{Parameter}{dim ($\ge 1$)} Number of dimensions of variable. \end{Parameter}
\begin{Parameter}{lsh ($\ne$ NULL)} Pointer to array which will hold the return values. \end{Parameter}
\begin{Parameter}{varindex} Variable index. \end{Parameter}
\begin{Parameter}{varname} Variable's full name. \end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The local size in each dimension for a given variable is returned in a user-supplied array buffer.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GroupgshGI, CCTK\_GroupgshGN}
Returns the global size for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupgshVI, CCTK\_GroupgshVN}
Returns the global size for a given variable.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GrouplshGI, CCTK\_GrouplshGN}
Returns the local size for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupashGI, CCTK\_GroupashGN}
Returns the local allocated size for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupashVI, CCTK\_GroupashVN}
Returns the local allocated size for a given variable.
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}


%Entering a function description for CCTK\_GroupashGI, CCTK\_GroupashGN
\begin{FunctionDescription}{CCTK\_GroupashGI, CCTK\_GroupashGN}
\label{CCTK-GroupashGI}
\label{CCTK-GroupashGN}
Given a group index or name, return an array of the local allocated size
of the group in each dimension

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_GroupashGI(const cGH *cctkGH,
                              int size,
                              int *ash,
                              int groupindex);

int status = CCTK_GroupashGN(const cGH *cctkGH,
                              int size,
                              int *ash,
                              const char *groupname);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_GroupashGI(status, cctkGH, size, ash, groupindex)

call CCTK_GroupashGN(status, cctkGH, size, ash, groupname)

integer       status
CCTK_POINTER  cctkGH
integer       size
integer       ash(size)
integer       groupindex
character*(*) groupname
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{-1} incorrect dimension supplied \end{Result}
\begin{Result}{-2} data not available from driver \end{Result}
\begin{Result}{-3} called on a scalar group \end{Result}
\begin{Result}{-4} invalid group name \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{cctkGH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter}
\begin{Parameter}{size ($\ge 1$)} Size of output array, should be at
least dimension of group. \end{Parameter}
\begin{Parameter}{ash ($\ne$ NULL)} Pointer to array which will hold the return values. \end{Parameter}
\begin{Parameter}{groupindex} Index of the group. \end{Parameter}
\begin{Parameter}{groupname} Name of the group. \end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The local allocated size in each dimension for a given group is returned in a user-supplied array buffer.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GroupgshGI, CCTK\_GroupgshGN}
Returns the global size for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupgshVI, CCTK\_GroupgshVN}
Returns the global size for a given variable.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GrouplshGI, CCTK\_GrouplshGN}
Returns the local size for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GrouplshVI, CCTK\_GrouplshVN}
Returns the local size for a given variable.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupashVI, CCTK\_GroupashVN}
Returns the local allocated size for a given variable.
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}


%Entering a function description for CCTK\_GroupashVI, CCTK\_GroupashVN
\begin{FunctionDescription}{CCTK\_GroupashVI, CCTK\_GroupashVN}
\label{CCTK-GroupashVI}
\label{CCTK-GroupashVN}
Given a variable index or its full name, return an array of the local
allocated size of the variable in each dimension

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_GroupashVI(const cGH *cctkGH,
                              int size,
                              int *ash,
                              int varindex);

int status = CCTK_GroupashVN(const cGH *cctkGH,
                              int size,
                              int *ash,
                              const char *varname);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_GroupashVI(status, cctkGH, size, ash, varindex)

call CCTK_GroupashVN(status, cctkGH, size, ash, varname)

integer       status
CCTK_POINTER  cctkGH
integer       size
integer       ash(size)
integer       varindex
character*(*) varname
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{-1} incorrect dimension supplied \end{Result}
\begin{Result}{-2} data not available from driver \end{Result}
\begin{Result}{-3} called on a scalar group \end{Result}
\begin{Result}{-4} invalid variable index \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{status} Return value. \end{Parameter}
\begin{Parameter}{cctkGH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter}
\begin{Parameter}{size ($\ge 1$)} Size of output array, should be at
least dimension of group. \end{Parameter}
\begin{Parameter}{ash ($\ne$ NULL)} Pointer to array which will hold the return values. \end{Parameter}
\begin{Parameter}{varindex} Variable index. \end{Parameter}
\begin{Parameter}{varname} Variable's full name. \end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The local allocated size in each dimension for a given variable is returned in a user-supplied array buffer.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GroupgshGI, CCTK\_GroupgshGN}
Returns the global size for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupgshVI, CCTK\_GroupgshVN}
Returns the global size for a given variable.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GrouplshGI, CCTK\_GrouplshGN}
Returns the local size for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GrouplshVI, CCTK\_GrouplshVN}
Returns the local size for a given variable.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupashGI, CCTK\_GroupashGN}
Returns the local allocated size for a given group.
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}


% Groups.c
\begin{FunctionDescription}{CCTK\_GroupName}{Given a group index, returns the group name}
\label{CCTK-GroupName}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}char * name = CCTK_GroupName( int index)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{name}
The group name
\end{Parameter}
\begin{Parameter}{index}
The group index
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The group name must be explicitly freed after it has been used.

No Fortran routine exists at the moment.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
index = CCTK_GroupIndex("evolve::scalars");
name = CCTK_GroupName(index);
printf ("Group name: %s", name);
free (name);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


% Groups.c
\begin{FunctionDescription}{CCTK\_GroupNameFromVarI}{Given a variable index, return the name of the associated group}
\label{CCTK-GroupNameFromVarI}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}char * group = CCTK_GroupNameFromVarI( int varindex)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{group}
The name of the group
\end{Parameter}
\begin{Parameter}{varindex}
The index of the variable
\end{Parameter}
\end{ParameterSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
index = CCTK_VarIndex("evolve::phi");
group = CCTK_GroupNameFromVarI(index) ;
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}



%Entering a function description for CCTK_GroupnghostzonesGI, CCTK\_GroupnghostzonesGN
\begin{FunctionDescription}{CCTK\_GroupnghostzonesGI, CCTK\_GroupnghostzonesGN}
\label{CCTK-GroupnghostzonesGI}
\label{CCTK-GroupnghostzonesGN}
  Given a group index or name, return an array with the number of ghostzones in each dimension of the group
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_GroupnghostzonesGI(const cGH *cctkGH,
                                     int dim,
                                     int *nghostzones,
                                     int groupindex)

int status = CCTK_GroupnghostzonesGN(const cGH *cctkGH,
                                     int dim,
                                     int *nghostzones,
                                     const char *groupname)
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_GroupnghostzonesGI(status, cctkGH, dim, nghostzones, groupindex)

call CCTK_GroupnghostzonesGN(status, cctkGH, dim, nghostzones, groupname)

integer       status
CCTK_POINTER  cctkGH
integer       dim
integer       nghostzones(dim)
integer       groupindex
character*(*) groupname
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{-1} incorrect dimension supplied \end{Result}
\begin{Result}{-2} data not available from driver \end{Result}
\begin{Result}{-3} called on a scalar group \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{status} Return value. \end{Parameter}
\begin{Parameter}{cctkGH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter}
\begin{Parameter}{dim ($\ge 1$)} Number of dimensions of group. \end{Parameter}
\begin{Parameter}{nghostzones ($\ne$ NULL)} Pointer to array which will hold the return values. \end{Parameter}
\begin{Parameter}{groupindex} Group index. \end{Parameter}
\begin{Parameter}{groupname} Group name. \end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The number of ghostzones in each dimension for a given group is returned in a user-supplied array buffer.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GroupnghostzonesVI, CCTK\_GroupnghostzonesVN}
Returns the number of ghostzones for a given variable.
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}


%Entering a function description for CCTK\_GroupnghostzonesVI, CCTK\_GroupnghostzonesVN
\begin{FunctionDescription}{CCTK\_GroupnghostzonesVI, CCTK\_GroupnghostzonesVN}
\label{CCTK-GroupnghostzonesVI}
\label{CCTK-GroupnghostzonesVN}
  Given a variable index or its full name, return an array with the number of ghostzones in each dimension of the variable

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_GroupnghostzonesVI(const cGH *cctkGH,
                                     int dim,
                                     int *nghostzones,
                                     int varindex)

int status = CCTK_GroupnghostzonesVN(const cGH *cctkGH,
                                     int dim,
                                     int *nghostzones,
                                     const char *varname)
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_GroupnghostzonesVI(status, cctkGH, dim, nghostzones, varindex)

call CCTK_GroupnghostzonesVN(status, cctkGH, dim, nghostzones, varname)

integer       status
CCTK_POINTER  cctkGH
integer       dim
integer       nghostzones(dim)
integer       varindex
character*(*) varname
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{-1} incorrect dimension supplied \end{Result}
\begin{Result}{-2} data not available from driver \end{Result}
\begin{Result}{-3} called on a scalar group \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{status} Return value. \end{Parameter}
\begin{Parameter}{cctkGH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter}
\begin{Parameter}{dim ($\ge 1$)} Number of dimensions of group. \end{Parameter}
\begin{Parameter}{nghostzones ($\ne$ NULL)} Pointer to array which will hold the return values. \end{Parameter}
\begin{Parameter}{varindex} Variable index. \end{Parameter}
\begin{Parameter}{varname} Variable's full name. \end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The number of ghostzones in each dimension for a given variable is returned in a user-supplied array buffer.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GroupnghostzonesGI, CCTK\_GroupnghostzonesGN}
Returns the number of ghostzones for a given group.
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}


%Entering a function description for CCTK\_GroupSizesI
\begin{FunctionDescription}{CCTK\_GroupSizesI}
\label{CCTK-GroupSizesI}
Given a group index, return a pointer to an array containing the sizes of the group in each dimension.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

CCTK_INT **ghostsizes = CCTK_GroupSizesI(int groupindex);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{non-NULL} a pointer to the size array\end{Result}
\begin{Result}{NULL} invalid group index \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{groupindex}Group index\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The sizes in each dimension for a given group are returned as a pointer reference.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GroupDimI}
Returns the dimension for a group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupGhostsizesI}
Returns the size arrays for a group.
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_GroupStorageDecrease}
\label{CCTK-GroupStorageDecrease}
Decrease the number of timelevels allocated for the given variable
groups.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int numTL = CactusDefaultGroupStorageDecrease (const cGH *GH, int n_groups, const int *groups, const int *timelevels, int *status);\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{}
  The new total number of timelevels with storage enabled for all
  groups queried or modified.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{GH}
pointer to grid hierarchy
\end{Parameter}
\begin{Parameter}{n\_groups}
Number of groups
\end{Parameter}
\begin{Parameter}{groups}
list of group indices to reduce storage for
\end{Parameter}
\begin{Parameter}{timelevels}
number of time levels to reduce storage for for each group
\end{Parameter}
\begin{Parameter}{groups}
list of group indices to allocate storage for
\end{Parameter}
\begin{Parameter}{status}
  optional return array which, if not NULL, will, on return, contain
  the number of timelevels which were previously allocated storage for
  each group
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
  The decrease group storage routine decreases the memory allocated to
  the specified number of timelevels for each listed group, returning
  the previous number of timelevels enabled for that group in the
  status array, if that is not NULL.  It never increases the number of
  timelevels enabled, i.e., if it is asked to reduce to more
  timelevels than are enabled, it does not change the storage for that
  group.

  There is a default implementation which checks for the presence of
  the older DisableGroupStorage function, and if that is not available
  it flags an error.  If it is available it makes a call to it, and
  puts its return value in the status flag for the group.  Usually, a
  driver has overloaded the default implementation.

  A driver should replace the appropriate GV pointers on the cGH
  structure when it changes the storage state of a GV.
\end{Discussion}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_GroupStorageIncrease}
\label{CCTK-GroupStorageIncrease}
Increases the number of timelevels allocated for the given variable groups.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int numTL = CactusDefaultGroupStorageIncrease (const cGH *GH, int n_groups, const int *groups, const int *timelevels, int *status);\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{}
  The new total number of timelevels with storage enabled for all
  groups queried or modified.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{GH}
pointer to grid hierarchy
\end{Parameter}
\begin{Parameter}{n\_groups}
Number of groups
\end{Parameter}
\begin{Parameter}{groups}
list of group indices to allocate storage for
\end{Parameter}
\begin{Parameter}{timelevels}
number of time levels to allocate storage for for each group
\end{Parameter}
\begin{Parameter}{groups}
list of group indices to allocate storage for
\end{Parameter}
\begin{Parameter}{status}
  optional return array which, if not NULL, will, on return, contain
  the number of timelevels which were previously allocated storage for
  each group
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
  The increase group storage routine increases the allocated memory to
  the specified number of timelevels of each listed group, returning
  the previous number of timelevels enabled for that group in the
  status array, if that is not NULL.  It never decreases the number of
  timelevels enabled, i.e., if it is asked to enable less timelevels
  than are already enabled it does not change the storage for that
  group.

  There is a default implementation which checks for the presence of
  the older EnableGroupStorage function, and if that is not available
  it flags an error.  If it is available it makes a call to it, and
  puts its return value in the status flag for the group.  Usually, a
  driver has overloaded the default implementation.

  A driver should replace the appropriate GV pointers on the cGH
  structure when it changes the storage state of a GV.
\end{Discussion}
\end{FunctionDescription}



\begin{FunctionDescription}{CCTK\_GroupTagsTable}
\label{CCTK-GroupTagsTable}
Given a group name, return the table handle of the group's tags table.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int table_handle = CCTK_GroupTagsTable(const char* group_name);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"
integer table_handle
character*(*) group_name
call CCTK_VarIndex(table_handle, group_name)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{table\_handle}
The table handle of the group's tags table.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{group\_name}
The character-string name of group.  This should be given in its fully 
qualified form, that is \verb|implementation::group_name| or
\verb|thorn_name::group_name|.
\end{Parameter}
\end{ParameterSection}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_GroupData}{CCTK-GroupData}
This function returns a variety of ``static'' information about a group
(``static'' in the sense that it doesn't change during a Cactus run).
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_GroupDynamicData}{CCTK-GroupDynamicData}
This function returns a variety of ``dynamic'' information about a group
(``dynamic'' in the sense that a driver can (and often does) change this
information during a Cactus run).
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{-1}
no group exists with the specified name
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}




\begin{FunctionDescription}{CCTK\_GroupTagsTableI}
\label{CCTK-GroupTagsTableI}
Given a group name, return the table handle of the group's tags table.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int table_handle = CCTK_GroupTagsTableI(int group_index);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"
integer table_handle
integer group_index
call CCTK_VarIndex(table_handle, group_index)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{table\_handle}
The table handle of the group's tags table.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{group\_index}
The group index of the group.
\end{Parameter}
\end{ParameterSection}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_GroupData}{CCTK-GroupData}
This function returns a variety of ``static'' information about a group
(``static'' in the sense that it doesn't change during a Cactus run).
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_GroupDynamicData}{CCTK-GroupDynamicData}
This function returns a variety of ``dynamic'' information about a group
(``dynamic'' in the sense that a driver can (and often does) change this
information during a Cactus run).
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_GroupIndex}{CCTK-GroupIndex}
Get the group index for a specified group name.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_GroupIndexFromVar}{CCTK-GroupIndexFromVar}
Get the group index for the group containing the variable with
a specified name.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_GroupIndexFromVarI}{CCTK-GroupIndexFromVarI}
Get the group index for the group containing the variable with
a specified variable index.
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{-1}
no group exists with the specified name
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}



% Groups.c
\begin{FunctionDescription}{CCTK\_GroupTypeFromVarI}{Provides a group's group type
               index given a variable index}
\label{CCTK-GroupTypeFromVarI}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int type = CCTK_GroupTypeFromVarI( int index)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_GroupTypeFromVarI(type , index )

integer type
integer index\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{type}
The group's group type index
\end{Parameter}
\begin{Parameter}{group}
The variable index
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
  The group's group type index indicates the type of variables in the
  group.  Either scalars, grid functions or arrays.  The group type
  can be checked with the Cactus provided macros for
  \code{CCTK\_SCALAR}, \code{CCTK\_GF}, \code{CCTK\_ARRAY}.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
index = CCTK_GroupIndex("evolve::scalars")
array = (CCTK_ARRAY == CCTK_GroupTypeFromVarI(index));
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_GROUPTYPEFROMVARI(type,3)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%Entering a function description for CCTK_GroupTypeI}{
\begin{FunctionDescription}{CCTK\_GroupTypeI}{}
\label{CCTK-GroupTypeI}
Provides a group's group type index given a group index
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int group_type = CCTK_GroupTypeI(int group);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{-1}
-1 is returned if the given group index is invalid.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{group}
Group index.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
A group's group type index indicates the type of variables in the
group.  The three group types are scalars, grid functions, and grid
arrays. The group type can be checked with the Cactus provided macros
for \code{CCTK\_SCALAR}, \code{CCTK\_GF}, \code{CCTK\_ARRAY}.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2} {CCTK\_GroupTypeFromVarI} {CCTK-GroupTypeFromVarI}
This function takes a variable index rather than a group index as its argument.
\end{SeeAlso2}
\end{SeeAlsoSection}
%\begin{ErrorSection}
%\end{ErrorSection}
%\begin{ExampleSection}
%\end{ExampleSection}
\end{FunctionDescription}


%Entering a function description for CCTK_GroupubndGI, CCTK_GroupubndGN
\begin{FunctionDescription}{CCTK\_GroupubndGI, CCTK\_GroupubndGN}
\label{CCTK-GroupubndGI}
\label{CCTK-GroupubndGN}
Given a group index or name, return an array of the upper bounds of the group in each dimension

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_GroupubndGI(const cGH *cctkGH,
                              int dim,
                              int *ubnd,
                              int groupindex);

int status = CCTK_GroupubndGN(const cGH *cctkGH,
                              int dim,
                              int *ubnd,
                              const char *groupname);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_GroupubndGI(status, cctkGH, dim, ubnd, groupindex)

call CCTK_GroupubndGN(status, cctkGH, dim, ubnd, groupname)

integer       status
CCTK_POINTER  cctkGH
integer       dim
integer       ubnd(dim)
integer       groupindex
character*(*) groupname
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{-1} incorrect dimension supplied \end{Result}
\begin{Result}{-2} data not available from driver \end{Result}
\begin{Result}{-3} called on a scalar group \end{Result}
\begin{Result}{-4} invalid group index \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{status} Return value. \end{Parameter}
\begin{Parameter}{cctkGH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter}
\begin{Parameter}{dim ($\ge 1$)} Number of dimensions of group. \end{Parameter}
\begin{Parameter}{ubnd ($\ne$ NULL)} Pointer to array which will hold the return values. \end{Parameter}
\begin{Parameter}{groupindex} Group index. \end{Parameter}
\begin{Parameter}{groupname} Group's full name. \end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The upper bounds in each dimension for a given group is returned in a user-supplied array buffer.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GrouplbndGI, CCTK\_GrouplbndGN}
Returns the lower bounds for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GrouplbndVI, CCTK\_GrouplbndVN}
Returns the lower bounds for a given variable.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupubndVI, CCTK\_GroupubndVN}
Returns the upper bounds for a given variable.
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}


%Entering a function description for CCTK\_GroupubndVI, CCTK\_GroupubndVN
\begin{FunctionDescription}{CCTK\_GroupubndVI, CCTK\_GroupubndVN}
\label{CCTK-GroupubndVI}
\label{CCTK-GroupubndVN}
Given a variable index or name, return an array of the upper bounds of the variable in each dimension

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_GroupubndVI(const cGH *cctkGH,
                              int dim,
                              int *ubnd,
                              int varindex);

int status = CCTK_GroupubndVN(const cGH *cctkGH,
                              int dim,
                              int *ubnd,
                              const char *varname);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_GroupubndVI(status, cctkGH, dim, ubnd, varindex)

call CCTK_GroupubndVN(status, cctkGH, dim, ubnd, varname)

integer       status
CCTK_POINTER  cctkGH
integer       dim
integer       ubnd(dim)
integer       varindex
character*(*) varname
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{-1} incorrect dimension supplied \end{Result}
\begin{Result}{-2} data not available from driver \end{Result}
\begin{Result}{-3} called on a scalar group \end{Result}
\begin{Result}{-4} invalid variable index \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{status} Return value. \end{Parameter}
\begin{Parameter}{cctkGH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter}
\begin{Parameter}{dim ($\ge 1$)} Number of dimensions of variable. \end{Parameter}
\begin{Parameter}{ubnd ($\ne$ NULL)} Pointer to array which will hold the return values. \end{Parameter}
\begin{Parameter}{varindex} Group index. \end{Parameter}
\begin{Parameter}{varname} Group's full name. \end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The upper bounds in each dimension for a given variable is returned in a user-supplied array buffer.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_GrouplbndGI, CCTK\_GrouplbndGN}
Returns the lower bounds for a given group.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GrouplbndVI, CCTK\_GrouplbndVN}
Returns the lower bounds for a given variable.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_GroupubndGI, CCTK\_GroupubndGN}
Returns the upper bounds for a given group.
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}


%%%%%
% HHH
%%%%%

%%%%%
% III
%%%%%


% Groups.c
\begin{FunctionDescription}{CCTK\_ImpFromVarI}{Given a variable index, returns the implementation name}
\label{CCTK-ImpFromVarI}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}char * implementation = CCTK_ImpFromVarI( int index)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{implementation}
The implementation name
\end{Parameter}
\begin{Parameter}{index}
The variable index
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
No Fortran routine exists at the moment
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
index = CCTK_VarIndex("evolve::phi");
implementation = CCTK_ImpFromVarI(index);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}



% cctk_ActiveThorns.c
%Entering a function description for CCTK\_ImplementationRequires
\begin{FunctionDescription}{CCTK\_ImplementationRequires}
\label{CCTK-ImplementationRequires}
Return the ancestors for an implementation.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

uStringList *imps = CCTK_ImplementationRequires(const char *imp);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{imps}
(not documented)
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{imp}
(not documented)
\end{Parameter}
\end{ParameterSection}

%\begin{Discussion}
%\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ActivatingThorn}{CCTK-ActivatingThorn}
  Finds the thorn which activated a particular implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompiledImplementation}{CCTK-CompiledImplementation}
  Return the name of the compiled implementation with given index
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompiledThorn}{CCTK-CompiledThorn}
  Return the name of the compiled thorn with given index
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImplementationThorn}{CCTK-ImplementationThorn}
  Returns the name of one thorn providing an implementation.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImpThornList}{CCTK-ImpThornList}
  Return the thorns for an implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive}
  Reports whether an implementation was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled}
  Reports whether an implementation was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive}
  Reports whether a thorn was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled}
  Reports whether a thorn was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_NumCompiledImplementations}{CCTK-NumCompiledImplementations}
  Return the number of implementations compiled in
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_NumCompiledThorns}{CCTK-NumCompiledThorns}
  Return the number of thorns compiled in
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ThornImplementation}{CCTK-ThornImplementation}
  Returns the implementation provided by the thorn
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{}
(not documented)
\end{Error}
\end{ErrorSection}

%\begin{ExampleSection}
%\end{ExampleSection}
\end{FunctionDescription}



% cctk_ActiveThorns.c
%Entering a function description for CCTK\_ImplementationThorn
\begin{FunctionDescription}{CCTK\_ImplementationThorn}
\label{CCTK-ImplementationThorn}
Returns the name of one thorn providing an implementation.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

const char *thorn = CCTK_ImplementationThorn(const char *name);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{thorn}
Name of the thorn or \code{NULL}
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{name}
Name of the implementation
\end{Parameter}
\end{ParameterSection}

%\begin{Discussion}
%\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ActivatingThorn}{CCTK-ActivatingThorn}
  Finds the thorn which activated a particular implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompiledImplementation}{CCTK-CompiledImplementation}
  Return the name of the compiled implementation with given index
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompiledThorn}{CCTK-CompiledThorn}
  Return the name of the compiled thorn with given index
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImplementationRequires}{CCTK-ImplementationRequires}
  Return the ancestors for an implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImpThornList}{CCTK-ImpThornList}
  Return the thorns for an implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive}
  Reports whether an implementation was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled}
  Reports whether an implementation was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive}
  Reports whether a thorn was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled}
  Reports whether a thorn was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_NumCompiledImplementations}{CCTK-NumCompiledImplementations}
  Return the number of implementations compiled in
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_NumCompiledThorns}{CCTK-NumCompiledThorns}
  Return the number of thorns compiled in
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ThornImplementation}{CCTK-ThornImplementation}
  Returns the implementation provided by the thorn
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{NULL}
Error.
\end{Error}
\end{ErrorSection}

%\begin{ExampleSection}
%\end{ExampleSection}
\end{FunctionDescription}



% cctk_ActiveThorns.c
%Entering a function description for CCTK\_ImpThornList
\begin{FunctionDescription}{CCTK\_ImpThornList}
\label{CCTK-ImpThornList}
Return the thorns for an implementation.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

t_sktree *thorns = CCTK_ImpThornList(const char *name);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{thorns}
(not documented)
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{name}
Name of implementation
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
(not documented)
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ActivatingThorn}{CCTK-ActivatingThorn}
  Finds the thorn which activated a particular implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompiledImplementation}{CCTK-CompiledImplementation}
  Return the name of the compiled implementation with given index
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompiledThorn}{CCTK-CompiledThorn}
  Return the name of the compiled thorn with given index
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImplementationRequires}{CCTK-ImplementationRequires}
  Return the ancestors for an implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImplementationThorn}{CCTK-ImplementationThorn}
  Returns the name of one thorn providing an implementation.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive}
  Reports whether an implementation was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled}
  Reports whether an implementation was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive}
  Reports whether a thorn was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled}
  Reports whether a thorn was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_NumCompiledImplementations}{CCTK-NumCompiledImplementations}
  Return the number of implementations compiled in
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_NumCompiledThorns}{CCTK-NumCompiledThorns}
  Return the number of thorns compiled in
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ThornImplementation}{CCTK-ThornImplementation}
  Returns the implementation provided by the thorn
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{}
(not documented)
\end{Error}
\end{ErrorSection}

%\begin{ExampleSection}
%\end{ExampleSection}
\end{FunctionDescription}



% WarnLevel.c
%Entering a function description for CCTK\_INFO
\begin{FunctionDescription}{CCTK\_INFO}
\label{CCTK-INFO}
Macro to print a single string as an information message to screen

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include <cctk.h>

CCTK_INFO(const char *message);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"

call CCTK_INFO(message)
character*(*) message
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{message}
The string to print as an info message
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This macro can be used by thorns to print a single string as an info message
to screen.

The macro \code{CCTK\_INFO(message)} expands to a call to the
underlying function \code{CCTK\_Info}:

\begin{verbatim}
CCTK_Info(CCTK_THORNSTRING, message)
\end{verbatim}

So the macro automatically includes the name of the originating thorn in the
info message. It is recommended that the macro \code{CCTK\_INFO} is used
to print a message rather than calling \code{CCTK\_Info} directly.

To include variables in an info message from C, you can use the routine
\code{CCTK\_VInfo} which accepts a variable argument list.
To include variables from Fortran, a string must be constructed and passed
in a \code{CCTK\_INFO} macro.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2} {CCTK\_ERROR} {CCTK-ERROR}
macro to print an error message with a single string argument and stop
the code
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_VError} {CCTK-VError}
prints a formatted string with a variable argument list as error
message and stops the code
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_VInfo()} {CCTK-VInfo}
prints a formatted string with a variable argument list as an info message to
screen
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_VWarn} {CCTK-VWarn}
prints a warning message with a variable argument list
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_WARN} {CCTK-WARN}
macro to print a warning message with a single string argument and
possibly stop the code
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
#include <cctk.h>

CCTK_INFO("Output is disabled");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
#include "cctk.h"

integer       myint
real          myreal
character*200 message

write(message, '(A32, G12.7, A5, I8)')
&     'Your info message, including ', myreal, ' and ', myint
call CCTK_INFO(message)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%Entering a function description for CCTK\_Info
\begin{FunctionDescription}{CCTK\_Info}
\label{CCTK-Info}
Function to print a single string as an information message to screen

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include <cctk.h>

CCTK_Info(const char *thorn, const char *message);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"

call CCTK_INFO(thorn, message)
character*(*) thorn, message
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{message}
The string to print as an info message
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The macro \verb|CCTK_INFO| automatically includes the name of the originating
thorn in the info message. It is recommended that the macro \code{CCTK\_INFO}
is used to print a message rather than calling \code{CCTK\_Info} directly.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2} {CCTK\_ERROR} {CCTK-ERROR}
macro to print an error message with a single string argument and stop
the code
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_VError} {CCTK-VError}
prints a formatted string with a variable argument list as error
message and stops the code
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_VInfo()} {CCTK-VInfo}
prints a formatted string with a variable argument list as an info message to
screen
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_VWarn} {CCTK-VWarn}
prints a warning message with a variable argument list
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_WARN} {CCTK-WARN}
macro to print a warning message with a single string argument and
possibly stop the code
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
#include <cctk.h>

CCTK_INFO("Output is disabled");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
#include "cctk.h"

integer       myint
real          myreal
character*200 message

write(message, '(A32, G12.7, A5, I8)')
&     'Your info message, including ', myreal, ' and ', myint
call CCTK_INFO(message)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_InfoCallbackRegister}
\label{CCTK-INFOCallbackRegister}
Register one or more routines for dealing with information messages in
addition to printing them to screen
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include <cctk.h>

CCTK_InfoCallbackRegister(void *data, cctk_infofunc callback);

\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{data}
The void pointer holding extra information about the registered call back
routine
\end{Parameter}

\begin{Parameter}{callback}
The function pointer pointing to the call back function dealing with
information messages. The definition of the function pointer is:
\begin{verbatim}

typedef void (*cctk_infofunc)(const char *thorn,
                              const char *message,
                              void *data);

\end{verbatim}

The argument list is the same as those in \verb|CCTK_Info()|
(see the discussion of \verb|CCTK_INFO()| page~\pageref{CCTK-INFO})
except an extra void pointer to hold the information about the call
back routine.

\end{Parameter}

\end{ParameterSection}

\begin{Discussion}

This function can be used by thorns to register their own routines to
deal with information messages. The registered function pointers will be
stored in a pointer chain. When \verb|CCTK_VInfo()| is called, the
registered routines will be called in the same order as they get
registered in addition to dumping warning messages to \code{stderr}.

The function can only be called in C.

\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_VInfo()}
prints a formatted string with a variable argument list as an info message to
screen
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_WarnCallbackRegister}
Register one or more routines for dealing with warning messages in addition
to printing them to standard error
\end{SeeAlso}

\end{SeeAlsoSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
/*DumpInfo will dump information messages to a file*/

void DumpInfo(const char *thorn,
              const char *message,
              void *data)
{
  DECLARE_CCTK_PARAMETERS
  FILE *fp;
  char *str = (char *)malloc((strlen(thorn)
                            +strlen(message)
                            +100)*sizeof(char));

  /*info_dump_file is a string set in the parameter file*/

  if((fp = fopen (info_dump_file, "a"))==0)
  {
    fprintf(stderr, "fatal error: can not open the file %s\n",info_dump_file);
    return;
  }

  sprintf(str, "\n[INFO]\nThorn->%s\nMsg->%s\n",thorn,message);

  fprintf(fp, "%s", str);
  free(str);
  fclose(fp);
}

...

/*data = NULL; callback = DumpInfo*/

CCTK_InfoCallbackRegister(NULL,DumpInfo);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%Entering a function description for CCTK\_InterpGridArrays
\begin{FunctionDescription}{CCTK\_InterpGridArrays}
\label{CCTK-InterpGridArrays}
Interpolate a list of distributed grid variables

The computation is optimized for the case of interpolating a
number of grid variables at a time; in this case all the interprocessor
communication can be done together, and the same interpolation
coefficients can be used for all the variables.  A grid variable can
be either a grid function or a grid array.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status =
     CCTK_InterpGridArrays(const cGH *cctkGH,
                           int N_dims,
                           int local_interp_handle, int param_table_handle,
                           int coord_system_handle,
                           int N_interp_points,
                             const int interp_coords_type_code,
                             const void *const interp_coords[],
                           int N_input_arrays,
                             const CCTK_INT input_array_variable_indices[],
                           int N_output_arrays,
                             const CCTK_INT output_array_type_codes[],
                             void *const output_arrays[]);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_InterpGridArrays(status,
.                          cctkGH,
.                          N_dims,
.                          local_interp_handle, param_table_handle,
.                          coord_system_handle,
.                          N_interp_points,
.                            interp_coords_type_code, interp_coords,
.                          N_input_arrays, input_array_variable_indices,
.                          N_output_arrays, output_array_type_codes,
.                          output_arrays)
integer      status
CCTK_POINTER cctkGH
integer      local_interp_handle, param_table_handle, coord_system_handle
integer      N_dims, N_interp_points, N_input_arrays, N_output_arrays
CCTK_POINTER interp_coords(N_dims)
integer      interp_coords_type_code
CCTK_INT     input_array_variable_indices(N_input_arrays)
CCTK_INT     output_array_type_codes(N_output_arrays)
CCTK_POINTER output_arrays(N_output_arrays)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{< 0} indicates an error condition (see {\bf Errors}) \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{cctkGH ($\ne$ NULL)}
Pointer to a valid Cactus grid hierarchy.
\end{Parameter}
\begin{Parameter}{N\_dims ($\ge 1$)}
Number of dimensions in which to interpolate.
This must be $\leq$ the dimensionality of the coordinate system defined
by \code{coord\_system\_handle}.  The default case is that it's $=$; see
the discussion of the \code{interpolation\_hyperslab\_handle} parameter-table
entry for the $<$ case.
\end{Parameter}
\begin{Parameter}{local\_interp\_handle ($\ge 0$)}
Handle to the local interpolation operator as returned by
\code{CCTK\_InterpHandle}.
\end{Parameter}
\begin{Parameter}{param\_table\_handle ($\ge 0$)}
Handle to a key-value table containing zero or more additional parameters
for the interpolation operation. The table is allowed to be modified by the
local and/or global interpolation routine(s).
\end{Parameter}
\begin{Parameter}{coord\_system\_handle ($\ge 0$)}
Cactus coordinate system handle defining the mapping between
(usually floating-point) coordinates and integer grid subscripts, as returned by
\code{CCTK\_CoordSystemHandle}.
\end{Parameter}
\begin{Parameter}{N\_interp\_points ($\ge 0$)}
The number of interpolation points requested by this processor.
\end{Parameter}
\begin{Parameter}{interp\_coords\_type\_code}
One of the \code{CCTK\_VARIABLE\_*} type codes, giving the data type of the
interpolation-point coordinate arrays pointed to by \code{interp\_coords[]}.
All interpolation-point coordinate arrays must be of the same data type.
(In practice, this data type will almost always be \code{CCTK\_REAL}
or one of the \code{CCTK\_REAL*} types.)
\end{Parameter}
\begin{Parameter}{interp\_coords ($\ne$ NULL)}
(Pointer to) an array of \code{N\_dims} pointers to 1-D arrays giving the
coordinates of the interpolation points requested by this processor.
These coordinates are with respect to the coordinate system defined by
\code{coord\_system\_handle}.
\end{Parameter}
\begin{Parameter}{N\_input\_arrays ($\ge 0$)}
The number of input variables to be interpolated.
If \code{N\_input\_arrays} is zero then no interpolation is done; such a call
may be useful for setup, interpolator querying, etc.
Note that if the parameter table entry \code{operand\_indices} is used to specify
a nontrivial (e.g.\ one-to-many) mapping of input variables to output arrays,
only the
unique set of input variables should be given here.
\end{Parameter}
\begin{Parameter}{input\_array\_variable\_indices ($\ne$ NULL)}
(Pointer to) an array of \code{N\_input\_arrays} CCTK grid variable indices (as
returned by \code{CCTK\_VarIndex}) specifying the input grid variables for the
interpolation. For any element with an index value of -1 in the grid variable
indices array, that interpolation is skipped. This may be useful if the main
purpose of the call is e.g.\ to do some query or setup computation.
\end{Parameter}
\begin{Parameter}{N\_output\_arrays ($\ge 0$)}
The number of output arrays to be returned from the interpolation.
If \code{N\_output\_arrays} is zero then no interpolation is done; such a call
may be useful for setup, interpolator querying, etc.
Note that \code{N\_output\_arrays} may differ from \code{N\_input\_arrays}, e.g.\
if the \code{operand\_indices} parameter-table entry is used to specify a
nontrivial (e.g.\ many-to-one) mapping of input variables to output arrays.
If such a mapping is specified, only the unique set of output arrays
should be given in the \code{output\_arrays} argument.
\end{Parameter}
\begin{Parameter}{output\_array\_type\_codes ($\ne$ NULL)}
(Pointer to) an array of \code{N\_output\_arrays} \code{CCTK\_VARIABLE\_*}
type codes giving the data types of the 1-D output arrays pointed to by
\code{output\_arrays[]}.
\end{Parameter}
\begin{Parameter}{output\_arrays ($\ne$ NULL)}
(Pointer to) an array of \code{N\_output\_arrays} pointers to the
(user-supplied) 1-D output arrays for the interpolation.
If any of the pointers in the \code{output\_arrays} array is NULL, then that
interpolation is skipped. This may be useful if the main purpose of the call
is e.g.\ to do some query or setup computation.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This function interpolates a list of CCTK grid variables (in a multiprocessor run
these are generally distributed over processors) on a list of interpolation
points. The grid topology and coordinates are implicitly specified via a Cactus
coordinate system.
The interpolation points may be anywhere in the global Cactus grid.
In a multiprocessor run they may vary from processor to processor;
each processor will get whatever interpolated data it asks for.
The routine \code{CCTK\_InterpGridArrays} does not do the actual interpolation
itself but rather takes care of whatever interprocessor communication may be
necessary, and -- for each processor's local patch of the domain-decomposed grid
variables -- calls \code{CCTK\_InterpLocalUniform} to invoke an external
local interpolation operator (as identified by an interpolation handle).

Additional parameters for the interpolation operation of both
\code{CCTK\_InterpGridArrays} and \code{CCTK\_InterpLocalUniform} can be
passed in via a handle to a key/value options table.
All interpolation operators should check for a parameter table entry with the
key \code{suppress\_warnings} which -- if present -- indicates that the
caller wants the interpolator to be silent in case of an error condition and
only return an appropriate error code.
One common parameter-table option, which a number of interpolation
operators are likely to support, is \code{order}, a \code{CCTK\_INT}
specifying the order of the (presumably polynomial) interpolation
(1=linear, 2=quadratic, 3=cubic, etc).
As another example, a table might be used to specify that the local interpolator
should take derivatives, by specifying
\begin{verbatim}
const CCTK_INT operand_indices[N_output_arrays];
const CCTK_INT operation_codes[N_output_arrays];
\end{verbatim}
Also, the global interpolator will typically need to specify some options
of its own for the local interpolator.\footnote{
It is the caller's responsibility to ensure that the specified local
interpolator supports any optional parameter-table entries that
\code{CCTK\_InterpGridArrays} passes to it. Each thorn providing a
\code{CCTK\_InterpLocalUniform} interpolator should document what options it
requires from the global interpolator.
}
These will overwrite any entries
with the same keys in the \code{param\_table\_handle} table.
Finally, the parameter table can be used to pass back arbitrary information
by the local and/or global interpolation routine(s) by adding/modifying
appropriate key/value pairs.

Note that \code{CCTK\_InterpGridArrays} is a collective operation, so in the
multiprocessor case you {\em must\/} call this function in parallel on
{\em each\/} processor, passing identical arguments except for the number of
interpolation points, the interpolation coordinates, and the output array
pointers.  You may (and typically will) specify a different set of
interpolation points on each processor's call -- you may even specify
an empty set on some processors.  The interpolation points may be
``owned'' by any processors (this function takes care of all
interprocessor-communication issues), though it may be more efficient
to have most or all of the interpolation points ``owned'' by the
current processor.

In the multiprocessor case, the result returned by
\code{CCTK\_InterpGridArrays} is guaranteed to be the same on all
processors.  (All current implementations simply take the minimum
of the per-processor results over all processors; this gives a
result which is 0 if all processors succeeded, or which is the most
negative error code encountered by any processor otherwise.)

The semantics of \code{CCTK\_InterpGridArrays} are mostly independent of
which Cactus driver is being used, but an implementation will most likely
depend on, and make use of, driver-specific internals. For that reason,
\code{CCTK\_InterpGridArrays} is made an overloadable function. The Cactus
flesh will supply only a dummy routine for it which -- if called -- does
nothing but print a warning message saying that it wasn't overloaded by
another thorn, and stop the code. So one will always need to compile in
and activate a driver-specific thorn which provides an interpolation routine
for CCTK grid variables and properly overloads \code{CCTK\_InterpGridArrays}
with it at startup.

Details of the operation performed, and what (if any) inputs and/or
outputs are specified in the parameter table, depend on which driver-specific
interpolation thorn and interpolation operator (provided by a local
interpolation thorn) you use.  See the documentation on individual interpolator
thorns (e.g.\ \code{PUGHInterp} in the \code{CactusPUGH} arrangement,
\code{CarpetInterp} in the \code{Carpet} arrangement,
\code{LocalInterp} in the \code{CactusBase} arrangement, and/or
\code{AEILocalInterp} in the \code{AEIThorns} arrangement) for details.

Note that in a multiprocessor Cactus run, it's the user's responsibility
to choose the interprocessor ghost-zone size (\code{driver::ghost\_size})
large enough so that the local interpolator never has to off-center
its molecules near interprocessor boundaries.  (This ensures that the
interpolation results are independent of the interprocessor decomposition,
at least up to floating-point roundoff errors.)
If the ghost-zone size is too small, the interpolator should return
the \code{CCTK\_ERROR\_INTERP\_GHOST\_SIZE\_TOO\_SMALL} error code.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_InterpHandle()}
Get the interpolator handle for a given character-string name.
\end{SeeAlso}
%notyet \begin{SeeAlso}{CCTK\_InterpLocalNonUniform()}
%notyet Interpolate a list of processor-local arrays
%notyet which define a nonuniformly spaced data grid (not implemented yet)
%notyet \end{SeeAlso}
\begin{SeeAlso}{CCTK\_InterpLocalUniform()}
Interpolate a list of processor-local arrays
which define a uniformly-spaced data grid
\end{SeeAlso}
%notyet \begin{SeeAlso}{CCTK\_InterpLocalWarped()}
%notyet Interpolate a list of processor-local arrays
%notyet which define a curvilinearly-warped data grid (not implemented yet)
%notyet \end{SeeAlso}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{}
The following list of error
codes indicates specific error conditions. For the complete list of possible
error return codes you should refer to the ThornGuide's chapter of the
corresponding interpolation thorn(s) you are using.  To find the numerical
values of the error codes (or more commonly, to find which error code
corresponds to a given numerical value), look in the files
\code{cctk\_Interp.h}, \code{util\_ErrorCodes.h}, and/or \code{util\_Table.h}
in the \code{src/include/} directory in the Cactus flesh.
\end{Error}
\begin{Error}{CCTK\_ERROR\_INTERP\_POINT\_OUTSIDE}
one or more of the interpolation points is out of range
(in this case additional information about the out-of-range point
may be reported through the parameter table; see the Thorn Guide for
whatever thorn provides the local interpolation operator for further
details)
\end{Error}
\begin{Error}{CCTK\_ERROR\_INTERP\_GRID\_TOO\_SMALL}
one or more of the dimensions of the input arrays is/are smaller than
the molecule size chosen by the interpolator (based on the parameter-table
options, e.g.\ the interpolation order)
\end{Error}
\begin{Error}{CCTK\_ERROR\_INTERP\_GHOST\_SIZE\_TOO\_SMALL}
for a multi-processor run, the size of the interprocessor boundaries (the {\em ghostzone} size) is smaller than the molecule size chosen by the interpolator
(based on the parameter-table options, e.g.\ the interpolation order).\\
This error code is also returned if a processor's chunk of the global grid
is smaller than the actual molecule size.
\end{Error}
\begin{Error}{UTIL\_ERROR\_BAD\_INPUT}
one or more of the input arguments is invalid (e.g.~\code{NULL} pointer)
\end{Error}
\begin{Error}{UTIL\_ERROR\_NO\_MEMORY}
unable to allocate memory
\end{Error}
\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
parameter table handle is invalid
\end{Error}
\begin{Error}{other error codes}
this function may also return any error codes returned by the
\code{Util\_Table*} routines used to get parameters from
(and/or set results in) the parameter table
\end{Error}
\end{ErrorSection}

\begin{ExampleSection}
\begin{ExampleDescription}
Here's a simple example to do quartic 3-D interpolation of a real
and a complex grid array, at 1000 interpolation points:
\end{ExampleDescription}
\begin{Example}{C}
\begin{verbatim}
#include "cctk.h"
#include "util_Table.h"

#define N_DIMS          3
#define N_INTERP_POINTS 1000
#define N_INPUT_ARRAYS  2
#define N_OUTPUT_ARRAYS 2

const cGH *GH;
int operator_handle, coord_system_handle;

/* interpolation points */
CCTK_REAL interp_x[N_INTERP_POINTS],
          interp_y[N_INTERP_POINTS],
          interp_z[N_INTERP_POINTS];
const void *interp_coords[N_DIMS];

/* input and output arrays */
CCTK_INT input_array_variable_indices[N_INPUT_ARRAYS];
static const CCTK_INT output_array_type_codes[N_OUTPUT_ARRAYS]
        = { CCTK_VARIABLE_REAL, CCTK_VARIABLE_COMPLEX };
void *output_arrays[N_OUTPUT_ARRAYS];
CCTK_REAL    output_for_real_array   [N_INTERP_POINTS];
CCTK_COMPLEX output_for_complex_array[N_INTERP_POINTS];

operator_handle = CCTK_InterpHandle("generalized polynomial interpolation");
if (operator_handle < 0)
{
  CCTK_WARN(CCTK_WARN_ABORT, "can't get operator handle!");
}

coord_system_handle = CCTK_CoordSystemHandle("cart3d");
if (coord_system_handle < 0)
{
  CCTK_WARN(CCTK_WARN_ABORT, "can't get coordinate-system handle!");
}

interp_coords[0] = (const void *) interp_x;
interp_coords[1] = (const void *) interp_y;
interp_coords[2] = (const void *) interp_z;
input_array_variable_indices[0] = CCTK_VarIndex("my_thorn::real_array");
input_array_variable_indices[1] = CCTK_VarIndex("my_thorn::complex_array");
output_arrays[0] = (void *) output_for_real_array;
output_arrays[1] = (void *) output_for_complex_array;

if (CCTK_InterpGridArrays(GH, N_DIMS,
                          operator_handle,
                          Util_TableCreateFromString("order=4"),
                          coord_system_handle,
                          N_INTERP_POINTS, CCTK_VARIABLE_REAL,
                                           interp_coords,
                          N_INPUT_ARRAYS, input_array_variable_indices,
                          N_OUTPUT_ARRAYS, output_array_type_codes,
                                           output_arrays) < 0)
{
  CCTK_WARN(CCTK_WARN_ABORT, "error return from interpolator!");
}
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Interp.c
\begin{FunctionDescription}{CCTK\_InterpHandle}{Return the handle for a given interpolation operator}
\label{CCTK-InterpHandle}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int handle = CCTK_InterpHandle( const char * operator)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_InterpHandle(handle , operator )

integer handle
character*(*) operator\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{handle}
Handle for the interpolation operator
\end{Parameter}
\begin{Parameter}{operator}
Name of interpolation operator
\end{Parameter}
\end{ParameterSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
handle =  CCTK_InterpHandle("my interpolation operator");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_InterpHandle(handle,"my interpolation operator")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\begin{ErrorSection}
\begin{Error}{negative}
A negative value is returned for invalid/unregistered interpolation operator names.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%notyet % Interp.c
%Entering a function description for CCTK\_InterpLocalNonUniform
%notyet \begin{FunctionDescription}{CCTK\_InterpLocalNonUniform}
%notyet \label{CCTK-InterpLocalNonUniform}
%notyet Interpolate a list of processor-local arrays
%notyet which define a nonuniformly spaced data grid (not implemented yet)
%notyet
%notyet (\code{CCTK\_InterpLocalNonUniform}, \code{CCTK\_InterpLocalUniform},
%notyet and \code{CCTK\_InterpLocalWarped} will eventually replace
%notyet \code{CCTK\_InterpLocal}.)
%notyet
%notyet The computation is optimized for the case of interpolating a
%notyet number of arrays at a time; in this case the same interpolation
%notyet coefficients can be used for all the arrays.
%notyet
%notyet \begin{SynopsisSection}
%notyet \begin{Synopsis}{C}
%notyet \begin{verbatim}
%notyet #include "util_ErrorCodes.h"
%notyet #include "cctk.h"
%notyet int status
%notyet    = CCTK_InterpLocalNonUniform(int N_dims,
%notyet                                 int operator_handle,
%notyet                                 int param_table_handle,
%notyet                                 int coord_arrays_type_code,
%notyet                                 const CCTK_INT coord_array_dims[],
%notyet                                 const void *const coord_arrays[],
%notyet                                 int N_interp_points,
%notyet                                 int interp_coords_type_code,
%notyet                                 const void *const interp_coords[],
%notyet                                 int N_input_arrays,
%notyet                                 const CCTK_INT input_array_dims[],
%notyet                                 const CCTK_INT input_array_type_codes[],
%notyet                                 const void *const input_arrays[],
%notyet                                 int N_output_arrays,
%notyet                                 const CCTK_INT output_array_type_codes[],
%notyet                                 void *const output_arrays[]);
%notyet \end{verbatim}
%notyet \end{Synopsis}
%notyet \end{SynopsisSection}
%notyet
%notyet \begin{ResultSection}
%notyet \begin{Result}{0}
%notyet success
%notyet \end{Result}
%notyet \end{ResultSection}
%notyet
%notyet \begin{ParameterSection}
%notyet \begin{Parameter}{N\_dims ($\ge 1$)}
%notyet Number of dimensions in which to interpolate.
%notyet Note that this may be less than the number of dimensions of the
%notyet input arrays if the storage is set up appropriately.  For example,
%notyet we might want to interpolate along 1-D lines or in 2-D planes of a
%notyet 3-D input array; here \code{N\_dims} would be 1 or 2 respectively.
%notyet For details, see the section on ``Non-Contiguous Input Arrays''
%notyet in the Thorn Guide for thorn AEILocalInterp.
%notyet \end{Parameter}
%notyet \begin{Parameter}{operator\_handle ($\ge 0$)}
%notyet \hbox{}
%notyet Handle to the interpolation operator as returned by
%notyet \code{CCTK\_InterpHandle}.
%notyet \end{Parameter}
%notyet \begin{Parameter}{param\_table\_handle ($\ge 0$)}
%notyet
%notyet Handle to a key-value table containing additional parameters for
%notyet the interpolator.
%notyet
%notyet One common parameter-table option, which a number of interpolation
%notyet operators are likely to support, is \code{order}, a \code{CCTK\_INT}
%notyet specifying the order of the (presumably polynomial) interpolation
%notyet (1=linear, 2=quadratic, 3=cubic, etc).
%notyet
%notyet See the Thorn Guide for the AEILocalInterp thorn for other parameters.
%notyet \end{Parameter}
%notyet \begin{Parameter}{coord\_arrays\_type\_code}
%notyet \hbox{}
%notyet One of the \code{CCTK\_VARIABLE\_*} type codes, giving the data type of the
%notyet 1-D coordinate arrays pointed to by \code{coord\_arrays[]}.
%notyet \end{Parameter}
%notyet \begin{Parameter}{coord\_array\_dims ($\ne$ NULL)}
%notyet \hbox{}
%notyet (Pointer to) an array of \code{N\_dims} integers giving the dimensions
%notyet of the corresponding 1-D coordinate arrays.
%notyet \end{Parameter}
%notyet \begin{Parameter}{coord\_arrays ($\ne$ NULL)}
%notyet \hbox{}
%notyet (Pointer to) an array of \code{N\_dims} pointers to 1-D arrays giving the
%notyet coordinates of the interpolation points.  See the ``Discussion'' section
%notyet below for more on the semantics of this.
%notyet \end{Parameter}
%notyet \begin{Parameter}{N\_interp\_points ($\ge 0$)}
%notyet \hbox{}
%notyet The number of points at which interpolation is to be done.
%notyet \end{Parameter}
%notyet \begin{Parameter}{interp\_coords\_type\_code}
%notyet \hbox{}
%notyet One of the \code{CCTK\_VARIABLE\_*} type codes, giving the data type
%notyet of the 1-D interpolation-point-coordinate arrays pointed to by
%notyet \code{interp\_coords[]}.
%notyet \end{Parameter}
%notyet \begin{Parameter}{interp\_coords ($\ne$ NULL)}
%notyet \hbox{}
%notyet (Pointer to) an array of \code{N\_dims} pointers to 1-D arrays giving the
%notyet coordinates of the interpolation points.  These coordinates are with
%notyet respect to the coordinate system defined by \code{coord\_arrays[]}.
%notyet \end{Parameter}
%notyet \begin{Parameter}{N\_input\_arrays ($\ge 0$)}
%notyet \hbox{}
%notyet The number of input arrays to be interpolated.
%notyet Note that if the parameter table entry \code{operand\_indices}
%notyet is used to specify a 1-to-many mapping of input arrays to output arrays,
%notyet only the unique set of input arrays should be given here.
%notyet \end{Parameter}
%notyet \begin{Parameter}{input\_array\_dims ($\ne$ NULL)}
%notyet \hbox{}
%notyet (Pointer to) an array of \code{N\_dims} integers giving the dimensions
%notyet of the \code{N\_dims}-D input arrays.  By default all the input arrays
%notyet are taken to have these dimensions, with \code{[0]} the most contiguous
%notyet axis and \code{[N\_dims-1]} the least contiguous axis, and array subscripts
%notyet in the range \code{0 <= subscript < input\_array\_dims[axis]}.  See the
%notyet discussion of the \code{input\_array\_strides} optional parameter (passed
%notyet in the parameter table) for details of how this can be overridden.
%notyet \end{Parameter}
%notyet \begin{Parameter}{input\_array\_type\_codes ($\ne$ NULL)}
%notyet \hbox{}
%notyet (Pointer to) an array of \code{N\_input\_arrays} \code{CCTK\_VARIABLE\_*}
%notyet type codes giving the data types of the \code{N\_dims}-D input arrays
%notyet pointed to by \code{input\_arrays[]}.
%notyet \end{Parameter}
%notyet \begin{Parameter}{input\_arrays ($\ne$ NULL)}
%notyet \hbox{}
%notyet (Pointer to) an array of \code{N\_input\_arrays} pointers to the
%notyet \code{N\_dims}-D input arrays for the interpolation.
%notyet \end{Parameter}
%notyet \begin{Parameter}{N\_output\_arrays ($\ge 0$)}
%notyet \hbox{}
%notyet The number of output arrays to be returned from the interpolation.
%notyet \end{Parameter}
%notyet \begin{Parameter}{output\_array\_type\_codes ($\ne$ NULL)}
%notyet \hbox{}
%notyet (Pointer to) an array of \code{N\_output\_arrays} \code{CCTK\_VARIABLE\_*}
%notyet type codes giving the data types of the 1-D output arrays pointed to by
%notyet \code{output\_arrays[]}.
%notyet \end{Parameter}
%notyet \begin{Parameter}{output\_arrays ($\ne$ NULL)}
%notyet \hbox{}
%notyet (Pointer to) an array of \code{N\_output\_arrays} pointers to the
%notyet (user-supplied) 1-D output arrays for the interpolation.
%notyet \end{Parameter}
%notyet \end{ParameterSection}
%notyet
%notyet \begin{Discussion}
%notyet \code{CCTK\_InterpLocalNonUniform} is a generic API for interpolating
%notyet processor-local arrays when the data points' coordinates~$xyz$ are
%notyet {\em nonlinear\/} (but still single-variable) functions of the integer
%notyet array subscripts~\code{ijk} (we're describing this for 3-D, but the
%notyet generalization to other numbers of dimensions should be obvious),
%notyet \begin{flushleft}
%notyet $x = x(\code{i})$       \\
%notyet $y = y(\code{j})$       \\
%notyet $z = z(\code{k})$       %%%\\
%notyet \end{flushleft}
%notyet These nonlinear functions are specified by setting up 1-D arrays
%notyet giving their (the coordinates) values at the grid points, then passing
%notyet pointers to these 1-D arrays in the \code{coord\_arrays[]} argument:
%notyet \begin{flushleft}
%notyet $x = \code{coord\_arrays[0][i]}$ \\
%notyet $y = \code{coord\_arrays[1][j]}$ \\
%notyet $z = \code{coord\_arrays[2][k]}$ \\
%notyet \end{flushleft}
%notyet
%notyet [If these nonlinear functions are known analytically, then it's
%notyet probably more efficient to analytically transform to coordinates
%notyet which are linear functions of the subscripts, then use
%notyet \code{CCTK\_InterpLocalUniform}.]
%notyet
%notyet The $(x,y,z)$ coordinates are used for the interpolation
%notyet (\ie{}~the interpolator may internally use polynomials in these
%notyet coordinates); \code{interp\_coords[]} specifies coordinates in this
%notyet same coordinate system.
%notyet
%notyet Details of the operation performed, and what (if any) inputs and/or
%notyet outputs are specified in the parameter table, depend on which interpolation
%notyet operator you use.  See the Thorn Guide for the AEILocalInterp thorn for
%notyet further discussion.
%notyet \end{Discussion}
%notyet
%notyet \begin{SeeAlsoSection}
%notyet \begin{SeeAlso}{CCTK\_InterpHandle()}
%notyet Get the interpolator handle for a given character-string name.
%notyet \end{SeeAlso}
%notyet \begin{SeeAlso}{CCTK\_InterpLocalUniform()}
%notyet Interpolate a list of processor-local arrays,
%notyet with uniformly spaced data points
%notyet \end{SeeAlso}
%notyet \begin{SeeAlso}{CCTK\_InterpRegisterOpLocalNonUniform()}
%notyet \hbox{}
%notyet Register a \code{CCTK\_InterpLocalNonUniform} interpolation operator.
%notyet \end{SeeAlso}
%notyet \end{SeeAlsoSection}
%notyet
%notyet \begin{ErrorSection}
%notyet \begin{Error}{}
%notyet To find the numerical
%notyet values of the error codes (or more commonly, to find which error code
%notyet corresponds to a given numerical value), look in the files
%notyet \code{cctk\_Interp.h}, \code{util\_ErrorCodes.h}, and/or \code{util\_Table.h}
%notyet in the \code{src/include/} directory in the Cactus flesh.
%notyet \end{Error}
%notyet \begin{Error}{CCTK\_ERROR\_INTERP\_POINT\_OUTSIDE}
%notyet one or more of the interpolation points is out of range
%notyet (in this case additional information about the out-of-range point
%notyet may be reported through the parameter table; see the Thorn Guide for
%notyet the AEILocalInterp thorn for further details)
%notyet \end{Error}
%notyet \begin{Error}{UTIL\_ERROR\_BAD\_INPUT}
%notyet one or more of the inputs is invalid (e.g.~\code{NULL} pointer)
%notyet \end{Error}
%notyet \begin{Error}{UTIL\_ERROR\_NO\_MEMORY}
%notyet unable to allocate memory
%notyet \end{Error}
%notyet \begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
%notyet parameter table handle is invalid
%notyet \end{Error}
%notyet \begin{Error}{other error codes}
%notyet this function may also return any error codes returned by the
%notyet \code{Util\_Table*} routines used to get parameters from
%notyet (and/or set results in) the parameter table
%notyet \end{Error}
%notyet \end{ErrorSection}
%notyet
%notyet \begin{ExampleSection}
%notyet \begin{Example}{C}
%notyet \begin{verbatim}
%notyet Here's a simple example of interpolating a \code{CCTK\_REAL} and a
%notyet \code{CCTK\_COMPLEX} $10 \times 20$ 2-D array, at 5 interpolation points,
%notyet using cubic interpolation.
%notyet
%notyet \begin{verbatim}
%notyet #define N_DIMS   2
%notyet #define N_INTERP_POINTS   5
%notyet #define N_INPUT_ARRAYS    2
%notyet #define N_OUTPUT_ARRAYS   2
%notyet
%notyet /* (x,y) coordinates of data grid points */
%notyet #define NX   10
%notyet #define NY   20
%notyet const CCTK_REAL x_coords[NX];
%notyet const CCTK_REAL y_coords[NY];
%notyet const void *const coord_arrays[N_DIMS]
%notyet         = { (const void *) x_coords, (const void *) y_coords };
%notyet
%notyet /* (x,y) coordinates of interpolation points */
%notyet const CCTK_REAL interp_x[N_INTERP_POINTS];
%notyet const CCTK_REAL interp_y[N_INTERP_POINTS];
%notyet const void *const interp_coords[N_DIMS]
%notyet         = { (const void *) interp_x, (const void *) interp_y };
%notyet
%notyet /* input arrays */
%notyet /* ... note Cactus uses Fortran storage ordering, i.e.\ X is contiguous */
%notyet const CCTK_REAL    input_real   [NY][NX];
%notyet const CCTK_COMPLEX input_complex[NY][NX];
%notyet const CCTK_INT input_array_dims[N_DIMS] = { NX, NY };
%notyet const CCTK_INT input_array_type_codes[N_INPUT_ARRAYS]
%notyet         = { CCTK_VARIABLE_REAL, CCTK_VARIABLE_COMPLEX };
%notyet const void *const input_arrays[N_INPUT_ARRAYS]
%notyet         = { (const void *) input_real, (const void *) input_complex };
%notyet
%notyet /* output arrays */
%notyet CCTK_REAL    output_real   [N_INTERP_POINTS];
%notyet CCTK_COMPLEX output_complex[N_INTERP_POINTS];
%notyet const CCTK_INT output_array_type_codes[N_OUTPUT_ARRAYS]
%notyet         = { CCTK_VARIABLE_REAL, CCTK_VARIABLE_COMPLEX };
%notyet void *const output_arrays[N_OUTPUT_ARRAYS]
%notyet         = { (void *) output_real, (void *) output_complex };
%notyet
%notyet int operator_handle, param_table_handle;
%notyet operator_handle = CCTK_InterpHandle("my interpolation operator");
%notyet if (operator_handle < 0)
%notyet         CCTK_WARN(CCTK_WARN_ABORT, "can't get interpolation handle!");
%notyet param_table_handle = Util_TableCreateFromString("order=3");
%notyet if (param_table_handle < 0)
%notyet         CCTK_WARN(CCTK_WARN_ABORT, "can't create parameter table!");
%notyet if (CCTK_InterpLocalNonUniform(N_DIMS,
%notyet                                operator_handle, param_table_handle,
%notyet                                CCTK_VARIABLE_REAL, coord_arrays,
%notyet                                N_INTERP_POINTS,
%notyet                                   CCTK_VARIABLE_REAL,
%notyet                                   interp_coords,
%notyet                                N_INPUT_ARRAYS,
%notyet                                   input_array_dims,
%notyet                                   input_array_type_codes,
%notyet                                   input_arrays,
%notyet                                N_OUTPUT_ARRAYS,
%notyet                                   output_array_type_codes,
%notyet                                   output_arrays) < 0)
%notyet         CCTK_WARN(CCTK_WARN_ABORT, "error return from interpolator!");
%notyet \end{verbatim}
%notyet \end{verbatim}
%notyet \end{Example}
%notyet \end{ExampleSection}
%notyet \end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Interp.c
%Entering a function description for CCTK\_InterpLocalUniform
\begin{FunctionDescription}{CCTK\_InterpLocalUniform}
\label{CCTK-InterpLocalUniform}
Interpolate a list of processor-local arrays
which define a uniformly-spaced data grid

The computation is optimized for the case of interpolating a
number of arrays at a time; in this case the same interpolation
coefficients can be used for all the arrays.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "util_ErrorCodes.h"
#include "cctk.h"
int status
   = CCTK_InterpLocalUniform(int N_dims,
                             int operator_handle,
                             int param_table_handle,
                             const CCTK_REAL coord_origin[],
                             const CCTK_REAL coord_delta[],
                             int N_interp_points,
                               int interp_coords_type_code,
                               const void *const interp_coords[],
                             int N_input_arrays,
                               const CCTK_INT input_array_dims[],
                               const CCTK_INT input_array_type_codes[],
                               const void *const input_arrays[],
                             int N_output_arrays,
                               const CCTK_INT output_array_type_codes[],
                               void *const output_arrays[]);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_InterpLocalUniform(status,
.                            N_dims,
.                            operator_handle,
.                            param_table_handle,
.                            coord_origin,
.                            coord_delta,
.                            N_interp_points,
.                              interp_coords_type_code,
.                              interp_coords,
.                            N_input_arrays,
.                              input_array_dims,
.                              input_array_type_codes,
.                              input_arrays,
.                            N_output_arrays,
.                              output_array_type_codes,
.                              output_arrays)
integer      status
integer      operator_handle, param_table_handle
integer      N_dims, N_interp_points, N_input_arrays, N_output_arrays
CCTK_REAL    coord_origin(N_dims), coord_delta(N_dims)
integer      interp_coords_type_code
CCTK_POINTER interp_coords(N_dims)
CCTK_INT     input_array_dims(N_dims), input_array_type_codes(N_input_arrays)
CCTK_POINTER input_arrays(N_input_arrays)
CCTK_INT     output_array_type_codes(N_output_arrays)
CCTK_POINTER output_arrays(N_output_arrays)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0}
success
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{N\_dims ($\ge 1$)}
Number of dimensions in which to interpolate.
Note that this may be less than the number of dimensions of the
input arrays if the storage is set up appropriately.  For example,
we might want to interpolate along 1-D lines or in 2-D planes of a
3-D input array; here \code{N\_dims} would be 1 or 2 respectively.
For details, see the section on ``Non-Contiguous Input Arrays''
in the Thorn Guide for thorn AEILocalInterp.
\end{Parameter}
\begin{Parameter}{operator\_handle ($\ge 0$)}
\hbox{}
Handle to the interpolation operator as returned by
\code{CCTK\_InterpHandle}.
\end{Parameter}
\begin{Parameter}{param\_table\_handle ($\ge 0$)}
Handle to a key-value table containing additional parameters for
the interpolator.

One common parameter-table option, which a number of interpolation
operators are likely to support, is \code{order}, a \code{CCTK\_INT}
specifying the order of the (presumably polynomial) interpolation
(1=linear, 2=quadratic, 3=cubic, etc).

See the Thorn Guide for the AEILocalInterp thorn for other parameters.
\end{Parameter}
\begin{Parameter}{coord\_origin ($\ne$ NULL)}
\hbox{}
(Pointer to) an array giving the coordinates of the data point with
integer array subscripts 0, 0, \dots, 0, or more generally (if the actual
array bounds don't include the all-zeros-subscript point) the coordinates
which this data point would have if it existed.  See the ``Discussion''
section below for more on how \code{coord\_origin[]} is actually used.
\end{Parameter}
\begin{Parameter}{coord\_delta ($\ne$ NULL)}
\hbox{}
(Pointer to) an array giving the coordinate spacing of the data arrays.
See the ``Discussion'' section below for more on how \code{coord\_delta[]}
is actually used.
\end{Parameter}
\begin{Parameter}{N\_interp\_points ($\ge 0$)}
\hbox{}
The number of points at which interpolation is to be done.
\end{Parameter}
\begin{Parameter}{interp\_coords\_type\_code}
\hbox{}
One of the \code{CCTK\_VARIABLE\_*} type codes, giving the data type
of the 1-D interpolation-point-coordinate arrays pointed to by
\code{interp\_coords[]}.  (In practice, this data type will almost
always be \code{CCTK\_REAL} or one of the \code{CCTK\_REAL*} types.)
\end{Parameter}
\begin{Parameter}{interp\_coords ($\ne$ NULL)}
\hbox{}
(Pointer to) an array of \code{N\_dims} pointers to 1-D arrays giving the
coordinates of the interpolation points.  These coordinates are with
respect to the coordinate system defined by \code{coord\_origin[]} and
\code{coord\_delta[]}.
\end{Parameter}
\begin{Parameter}{N\_input\_arrays ($\ge 0$)}
\hbox{}
The number of input arrays to be interpolated.
Note that if the parameter table entry \code{operand\_indices}
is used to specify a 1-to-many mapping of input arrays to output arrays,
only the unique set of input arrays should be given here.
\end{Parameter}
\begin{Parameter}{input\_array\_dims ($\ne$ NULL)}
\hbox{}
(Pointer to) an array of \code{N\_dims} integers giving the dimensions
of the \code{N\_dims}-D input arrays.  By default all the input arrays
are taken to have these dimensions, with \code{[0]} the most contiguous
axis and \code{[N\_dims-1]} the least contiguous axis, and array subscripts
in the range \code{0 <= subscript < input\_array\_dims[axis]}.  See the
discussion of the \code{input\_array\_strides} optional parameter (passed
in the parameter table) for details of how this can be overridden.
\end{Parameter}
\begin{Parameter}{input\_array\_type\_codes ($\ne$ NULL)}
\hbox{}
(Pointer to) an array of \code{N\_input\_arrays} \code{CCTK\_VARIABLE\_*}
type codes giving the data types of the \code{N\_dims}-D input arrays
pointed to by \code{input\_arrays[]}.
\end{Parameter}
\begin{Parameter}{input\_arrays ($\ne$ NULL)}
\hbox{}
(Pointer to) an array of \code{N\_input\_arrays} pointers to the
\code{N\_dims}-D input arrays for the interpolation.  If any
\code{input\_arrays[in]} pointer is NULL, that interpolation is skipped.
\end{Parameter}
\begin{Parameter}{N\_output\_arrays ($\ge 0$)}
\hbox{}
The number of output arrays to be returned from the interpolation.
\end{Parameter}
\begin{Parameter}{output\_array\_type\_codes ($\ne$ NULL)}
\hbox{}
(Pointer to) an array of \code{N\_output\_arrays} \code{CCTK\_VARIABLE\_*}
type codes giving the data types of the 1-D output arrays pointed to by
\code{output\_arrays[]}.
\end{Parameter}
\begin{Parameter}{output\_arrays ($\ne$ NULL)}
\hbox{}
(Pointer to) an array of \code{N\_output\_arrays} pointers to the
(user-supplied) 1-D output arrays for the interpolation.  If any
\code{output\_arrays[out]} pointer is NULL, that interpolation is skipped.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
\code{CCTK\_InterpLocalUniform} is a generic API for interpolating
processor-local arrays when the data points'~$xyz$ coordinates are
{\em linear\/} functions of the integer array subscripts~\code{ijk}
(we're describing this for 3-D, but the generalization to other numbers
of dimensions should be obvious).  The \code{coord\_origin[]} and
\code{coord\_delta[]} arguments specify these linear functions:
\begin{flushleft}
$x = \code{coord\_origin[0] + i*coord\_delta[0]}$ \\
$y = \code{coord\_origin[1] + j*coord\_delta[1]}$ \\
$z = \code{coord\_origin[2] + k*coord\_delta[2]}$ %%%\\
\end{flushleft}
The $(x,y,z)$ coordinates are used for the interpolation
(\ie{}~the interpolator may internally use polynomials in these
coordinates); \code{interp\_coords[]} specifies coordinates in this
same coordinate system.

Details of the operation performed, and what (if any) inputs and/or
outputs are specified in the parameter table, depend on which interpolation
operator you use.  See the Thorn Guide for the AEILocalInterp thorn for
further discussion.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_InterpHandle()}
Get the interpolator handle for a given character-string name.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_InterpGridArrays()}
Interpolate a list of Cactus grid arrays
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_InterpRegisterOpLocalUniform()}
\hbox{}
Register a \code{CCTK\_InterpLocalUniform} interpolation operator
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_InterpLocalNonUniform()}
Interpolate a list of processor-local arrays,
with non-uniformly spaced data points.
\end{SeeAlso}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{}
To find the numerical
values of the error codes (or more commonly, to find which error code
corresponds to a given numerical value), look in the files
\code{cctk\_Interp.h}, \code{util\_ErrorCodes.h}, and/or \code{util\_Table.h}
in the \code{src/include/} directory in the Cactus flesh.
\end{Error}
\begin{Error}{CCTK\_ERROR\_INTERP\_POINT\_OUTSIDE}
one or more of the interpolation points is out of range
(in this case additional information about the out-of-range point
may be reported through the parameter table; see the Thorn Guide for
the AEILocalInterp thorn for further details)
\end{Error}
\begin{Error}{CCTK\_ERROR\_INTERP\_GRID\_TOO\_SMALL}
one or more of the dimensions of the input arrays is/are smaller than
the molecule size chosen by the interpolator (based on the parameter-table
options, e.g.\ the interpolation order)
\end{Error}
\begin{Error}{UTIL\_ERROR\_BAD\_INPUT}
one or more of the inputs is invalid (e.g.~\code{NULL} pointer)
\end{Error}
\begin{Error}{UTIL\_ERROR\_NO\_MEMORY}
unable to allocate memory
\end{Error}
\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
parameter table handle is invalid
\end{Error}
\begin{Error}{other error codes}
this function may also return any error codes returned by the
\code{Util\_Table*} routines used to get parameters from
(and/or set results in) the parameter table
\end{Error}
\end{ErrorSection}

\begin{ExampleSection}
\begin{ExampleDescription}
Here's a simple example of interpolating a \code{CCTK\_REAL} and a
\end{ExampleDescription}
\code{CCTK\_COMPLEX} $10 \times 20$ 2-D array, at 5 interpolation points,
using cubic interpolation.

Note that since C allows arrays to be initialized only if the
initializer values are compile-time constants, we have to declare the
\code{interp\_coords[]}, \code{input\_arrays[]}, and \code{output\_arrays[]}
arrays as non-\code{const}, and set their values with ordinary (run-time)
assignment statements.  In \Cplusplus, there's no restriction on
initializer values, so we could declare the arrays \code{const} and
initialize them as part of their declarations.

\begin{Example}{C}
\begin{verbatim}
#define N_DIMS   2
#define N_INTERP_POINTS   5
#define N_INPUT_ARRAYS    2
#define N_OUTPUT_ARRAYS   2

/* (x,y) coordinates of data grid points */
#define X_ORIGIN   ...
#define X_DELTA    ...
#define Y_ORIGIN   ...
#define Y_DELTA    ...
const CCTK_REAL origin[N_DIMS] = { X_ORIGIN, Y_ORIGIN };
const CCTK_REAL delta [N_DIMS] = { X_DELTA,  Y_DELTA  };

/* (x,y) coordinates of interpolation points */
const CCTK_REAL interp_x[N_INTERP_POINTS];
const CCTK_REAL interp_y[N_INTERP_POINTS];
const void *interp_coords[N_DIMS];              /* see note above */

/* input arrays */
/* ... note Cactus uses Fortran storage ordering, i.e.\ X is contiguous */
#define NX   10
#define NY   20
const CCTK_REAL    input_real   [NY][NX];
const CCTK_COMPLEX input_complex[NY][NX];
const CCTK_INT input_array_dims[N_DIMS] = { NX, NY };
const CCTK_INT input_array_type_codes[N_INPUT_ARRAYS]
        = { CCTK_VARIABLE_REAL, CCTK_VARIABLE_COMPLEX };
const void *input_arrays[N_INPUT_ARRAYS];       /* see note above */

/* output arrays */
CCTK_REAL    output_real   [N_INTERP_POINTS];
CCTK_COMPLEX output_complex[N_INTERP_POINTS];
const CCTK_INT output_array_type_codes[N_OUTPUT_ARRAYS]
        = { CCTK_VARIABLE_REAL, CCTK_VARIABLE_COMPLEX };
void *const output_arrays[N_OUTPUT_ARRAYS];     /* see note above */

int operator_handle, param_table_handle;
operator_handle = CCTK_InterpHandle("my interpolation operator");
if (operator_handle < 0)
        CCTK_WARN(CCTK_WARN_ABORT, "can't get interpolation handle!");
param_table_handle = Util_TableCreateFromString("order=3");
if (param_table_handle < 0)
        CCTK_WARN(CCTK_WARN_ABORT, "can't create parameter table!");

/* initialize the rest of the parameter arrays */
interp_coords[0] = (const void *) interp_x;
interp_coords[1] = (const void *) interp_y;
input_arrays[0] = (const void *) input_real;
input_arrays[1] = (const void *) input_complex;
output_arrays[0] = (void *) output_real;
output_arrays[1] = (void *) output_complex;

/* do the actual interpolation, and check for error returns */
if (CCTK_InterpLocalUniform(N_DIMS,
                            operator_handle, param_table_handle,
                            origin, delta,
                            N_INTERP_POINTS,
                               CCTK_VARIABLE_REAL,
                               interp_coords,
                            N_INPUT_ARRAYS,
                               input_array_dims,
                               input_array_type_codes,
                               input_arrays,
                            N_OUTPUT_ARRAYS,
                               output_array_type_codes,
                               output_arrays) < 0)
        CCTK_WARN(CCTK_WARN_ABORT, "error return from interpolator!");
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%notyet % Interp.c
%Entering a function description for CCTK\_InterpLocalWarped
%notyet \begin{FunctionDescription}{CCTK\_InterpLocalWarped}
%notyet \label{CCTK-InterpLocalWarped}
%notyet Interpolate a list of processor-local arrays
%notyet which define a curvilinearly-warped data grid
%notyet
%notyet The computation is optimized for the case of interpolating a
%notyet number of arrays at a time; in this case the same interpolation
%notyet coefficients can be used for all the arrays.
%notyet
%notyet \begin{SynopsisSection}
%notyet \begin{Synopsis}{C}
%notyet \begin{verbatim}
%notyet #include "util_ErrorCodes.h"
%notyet #include "cctk.h"
%notyet int status = CCTK_InterpLocalWarped(int N_dims,
%notyet                                     int operator_handle,
%notyet                                     int param_table_handle,
%notyet                                     int coord_arrays_type_code,
%notyet                                     const CCTK_INT coord_array_dims[],
%notyet                                     const void *const coord_arrays[],
%notyet                                     int N_interp_points,
%notyet                                     int interp_coords_type_code,
%notyet                                     const void *const interp_coords[],
%notyet                                     int N_input_arrays,
%notyet                                     const CCTK_INT input_array_dims[],
%notyet                                     const CCTK_INT input_array_type_codes[],
%notyet                                     const void *const input_arrays[],
%notyet                                     int N_output_arrays,
%notyet                                     const CCTK_INT output_array_type_codes[],
%notyet                                     void *const output_arrays[]);
%notyet \end{verbatim}
%notyet \end{Synopsis}
%notyet \end{SynopsisSection}
%notyet
%notyet \begin{ResultSection}
%notyet \begin{Result}{0}
%notyet success
%notyet \end{Result}
%notyet \end{ResultSection}
%notyet
%notyet \begin{ParameterSection}
%notyet \begin{Parameter}{N\_dims ($\ge 1$)}
%notyet Number of dimensions in which to interpolate.
%notyet Note that this may be less than the number of dimensions of the
%notyet input arrays if the storage is set up appropriately.  For example,
%notyet we might want to interpolate along 1-D lines or in 2-D planes of a
%notyet 3-D input array; here \code{N\_dims} would be 1 or 2 respectively.
%notyet For details, see the section on ``Non-Contiguous Input Arrays''
%notyet in the Thorn Guide for thorn AEILocalInterp.
%notyet \end{Parameter}
%notyet \begin{Parameter}{operator\_handle ($\ge 0$)}
%notyet \hbox{}
%notyet Handle to the interpolation operator as returned by
%notyet \code{CCTK\_InterpHandle}.
%notyet \end{Parameter}
%notyet \begin{Parameter}{param\_table\_handle ($\ge 0$)}
%notyet
%notyet Handle to a key-value table containing additional parameters for
%notyet the interpolator.
%notyet
%notyet One common parameter-table option, which a number of interpolation
%notyet operators are likely to support, is \code{order}, a \code{CCTK\_INT}
%notyet specifying the order of the (presumably polynomial) interpolation
%notyet (1=linear, 2=quadratic, 3=cubic, etc).
%notyet
%notyet See the Thorn Guide for the AEILocalInterp thorn for other parameters.
%notyet \end{Parameter}
%notyet \begin{Parameter}{coord\_arrays\_type\_code}
%notyet \hbox{}
%notyet One of the \code{CCTK\_VARIABLE\_*} type codes, giving the data type of the
%notyet \code{N\_dims}-D coordinate arrays pointed to by \code{coord\_arrays[]}.
%notyet \end{Parameter}
%notyet \begin{Parameter}{coord\_array\_dims ($\ne$ NULL)}
%notyet \hbox{}
%notyet (Pointer to) an array of \code{N\_dims} integers giving the dimensions
%notyet of the coordinate arrays.  All the coordinate arrays are taken to have
%notyet these dimensions, with (by default) \code{[0]} the most contiguous axis
%notyet and \code{[N\_dims-1]} the least contiguous axis, and array subscripts
%notyet in the range \code{0 <= subscript < coord\_array\_dims[axis]}.  See the
%notyet discussion of the \code{coord\_array\_strides} optional parameter (passed
%notyet in the parameter table) for details of how this can be overridden.
%notyet \end{Parameter}
%notyet \begin{Parameter}{coord\_arrays ($\ne$ NULL)}
%notyet \hbox{}
%notyet (Pointer to) an array of \code{N\_dims} pointers to \code{N\_dims}-D arrays
%notyet giving the coordinates of the interpolation points.  See the ``Discussion''
%notyet section below for more on the semantics of this.
%notyet \end{Parameter}
%notyet \begin{Parameter}{N\_interp\_points ($\ge 0$)}
%notyet \hbox{}
%notyet The number of points at which interpolation is to be done.
%notyet \end{Parameter}
%notyet \begin{Parameter}{interp\_coords\_type\_code}
%notyet \hbox{}
%notyet One of the \code{CCTK\_VARIABLE\_*} type codes, giving the data type
%notyet of the 1-D interpolation-point-coordinate arrays pointed to by
%notyet \code{interp\_coords[]}.
%notyet \end{Parameter}
%notyet \begin{Parameter}{interp\_coords ($\ne$ NULL)}
%notyet \hbox{}
%notyet (Pointer to) an array of \code{N\_dims} pointers to \code{N\_dims}-D arrays
%notyet giving the coordinates of the interpolation points.  These coordinates are
%notyet with respect to the coordinate system defined by \code{coord\_arrays[]}.
%notyet \end{Parameter}
%notyet \begin{Parameter}{N\_input\_arrays ($\ge 0$)}
%notyet \hbox{}
%notyet The number of input arrays to be interpolated.
%notyet Note that if the parameter table entry \code{operand\_indices}
%notyet is used to specify a 1-to-many mapping of input arrays to output arrays,
%notyet only the unique set of input arrays should be given here.
%notyet \end{Parameter}
%notyet \begin{Parameter}{input\_array\_dims ($\ne$ NULL)}
%notyet \hbox{}
%notyet (Pointer to) an array of \code{N\_dims} integers giving the dimensions
%notyet of the input arrays.  By default all the input arrays are taken to have
%notyet these dimensions, with \code{[0]} the most contiguous axis and
%notyet \code{[N\_dims-1]} the least contiguous axis, and array subscripts in the
%notyet range \code{0 <= subscript < input\_array\_dims[axis]}.  See the discussion
%notyet of the \code{input\_array\_strides} optional parameter (passed in the
%notyet parameter table) for details of how this can be overridden.
%notyet \end{Parameter}
%notyet \begin{Parameter}{input\_array\_type\_codes ($\ne$ NULL)}
%notyet \hbox{}
%notyet (Pointer to) an array of \code{N\_input\_arrays} \code{CCTK\_VARIABLE\_*}
%notyet type codes giving the data types of the \code{N\_dims}-D input arrays
%notyet pointed to by \code{input\_arrays[]}.
%notyet \end{Parameter}
%notyet \begin{Parameter}{input\_arrays ($\ne$ NULL)}
%notyet \hbox{}
%notyet (Pointer to) an array of \code{N\_input\_arrays} pointers to the
%notyet \code{N\_dims}-D input arrays for the interpolation.
%notyet \end{Parameter}
%notyet \begin{Parameter}{N\_output\_arrays ($\ge 0$)}
%notyet \hbox{}
%notyet The number of output arrays to be returned from the interpolation.
%notyet \end{Parameter}
%notyet \begin{Parameter}{output\_array\_type\_codes ($\ne$ NULL)}
%notyet \hbox{}
%notyet (Pointer to) an array of \code{N\_output\_arrays} \code{CCTK\_VARIABLE\_*}
%notyet type codes giving the data types of the 1-D output arrays pointed to by
%notyet \code{output\_arrays[]}.
%notyet \end{Parameter}
%notyet \begin{Parameter}{output\_arrays ($\ne$ NULL)}
%notyet \hbox{}
%notyet (Pointer to) an array of \code{N\_output\_arrays} pointers to the
%notyet (user-supplied) 1-D output arrays for the interpolation.
%notyet \end{Parameter}
%notyet \end{ParameterSection}
%notyet
%notyet \begin{Discussion}
%notyet This function is a generic API for interpolating processor-local arrays
%notyet when the data points' coordinates~$xyz$ are generic {\em multivariable
%notyet nonlinear\/} functions of the integer array subscripts~\code{ijk}
%notyet (we're describing this for 3-D, but the generalization to other
%notyet numbers of dimensions should be obvious),
%notyet \begin{flushleft}
%notyet $x = x(\code{i}, \code{j}, \code{k})$   \\
%notyet $y = y(\code{i}, \code{j}, \code{k})$   \\
%notyet $z = z(\code{i}, \code{j}, \code{k})$   %%%\\
%notyet \end{flushleft}
%notyet These nonlinear functions are specified by setting up 3-D arrays
%notyet giving their (the coordinates) values at the grid points, then passing
%notyet pointers to these 3-D arrays in the \code{coord\_arrays} argument:
%notyet \begin{flushleft}
%notyet $x = \code{coord\_arrays[0][i,j,k]}$     \\
%notyet $y = \code{coord\_arrays[1][i,j,k]}$     \\
%notyet $z = \code{coord\_arrays[2][i,j,k]}$     \\
%notyet \end{flushleft}
%notyet where \code{[i,j,k]} refers to \code{N\_dims}-D array subscripting.
%notyet
%notyet [If these nonlinear functions are known analytically, then it's
%notyet probably more efficient to analytically transform to coordinates
%notyet which are linear functions of the subscripts, then use
%notyet \code{CCTK\_InterpLocalUniform}.]
%notyet
%notyet The $(x,y,z)$ coordinates are used for the interpolation
%notyet (\ie{}~the interpolator may internally use polynomials in these
%notyet coordinates); \code{interp\_coords} specifies coordinates in this
%notyet same coordinate system.
%notyet
%notyet Details of the operation performed, and what (if any) inputs and/or
%notyet outputs are specified in the parameter table, depend on which interpolation
%notyet operator you use.  See the Thorn Guide for the AEILocalInterp thorn for
%notyet further discussion.
%notyet \end{Discussion}
%notyet
%notyet \begin{SeeAlsoSection}
%notyet \begin{SeeAlso}{CCTK\_InterpHandle()}
%notyet Get the interpolator handle for a given character-string name.
%notyet \end{SeeAlso}
%notyet \begin{SeeAlso}{CCTK\_InterpLocalUniform()}
%notyet Interpolate a list of processor-local arrays,
%notyet with uniformly spaced data points
%notyet \end{SeeAlso}
%notyet \begin{SeeAlso}{CCTK\_InterpRegisterOpLocalWarped()}
%notyet \hbox{}
%notyet Register a \code{CCTK\_InterpLocalWarped} interpolation operator.
%notyet \end{SeeAlso}
%notyet \end{SeeAlsoSection}
%notyet
%notyet \begin{ErrorSection}
%notyet \begin{Error}{}
%notyet To find the numerical
%notyet values of the error codes (or more commonly, to find which error code
%notyet corresponds to a given numerical value), look in the files
%notyet \code{cctk\_Interp.h}, \code{util\_ErrorCodes.h}, and/or \code{util\_Table.h}
%notyet in the \code{src/include/} directory in the Cactus flesh.
%notyet \end{Error}
%notyet \begin{Error}{CCTK\_ERROR\_INTERP\_POINT\_OUTSIDE}
%notyet one or more of the interpolation points is out of range
%notyet (in this case additional information about the out-of-range point
%notyet may be reported through the parameter table; see the Thorn Guide for
%notyet the AEILocalInterp thorn for further details)
%notyet \end{Error}
%notyet \begin{Error}{UTIL\_ERROR\_BAD\_INPUT}
%notyet one or more of the inputs is invalid (e.g.~\code{NULL} pointer)
%notyet \end{Error}
%notyet \begin{Error}{UTIL\_ERROR\_NO\_MEMORY}
%notyet unable to allocate memory
%notyet \end{Error}
%notyet \begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
%notyet parameter table handle is invalid
%notyet \end{Error}
%notyet \begin{Error}{other error codes}
%notyet this function may also return any error codes returned by the
%notyet \code{Util\_Table*} routines used to get parameters from
%notyet (and/or set results in) the parameter table
%notyet \end{Error}
%notyet \end{ErrorSection}
%notyet
%notyet \begin{ExampleSection}
%notyet \begin{Example}{C}
%notyet \begin{verbatim}
%notyet Here's a simple example of interpolating a \code{CCTK\_REAL} and a
%notyet \code{CCTK\_COMPLEX} $10 \times 20$ 2-D array, at 5 interpolation points,
%notyet using cubic interpolation.
%notyet
%notyet \begin{verbatim}
%notyet #define N_DIMS   2
%notyet #define N_INTERP_POINTS   5
%notyet #define N_INPUT_ARRAYS    2
%notyet #define N_OUTPUT_ARRAYS   2
%notyet
%notyet /* (x,y) coordinates of data grid points */
%notyet /* ... note Cactus uses Fortran storage ordering, i.e.\ X is contiguous */
%notyet #define NX   10
%notyet #define NY   20
%notyet const CCTK_INT coord_array_dims[N_DIMS] = { NX, NY };
%notyet const CCTK_REAL x_coords[NY][NX];
%notyet const CCTK_REAL y_coords[NY][NX];
%notyet const void *const coord_arrays[N_DIMS]
%notyet         = { (const void *) x_coords, (const void *) y_coords };
%notyet

%notyet const CCTK_REAL interp_x[N_INTERP_POINTS];
%notyet const CCTK_REAL interp_y[N_INTERP_POINTS];
%notyet const void *const interp_coords[N_DIMS]
%notyet         = { (const void *) interp_x, (const void *) interp_y };
%notyet
%notyet /* input arrays */
%notyet /* ... note Cactus uses Fortran storage ordering, i.e.\ X is contiguous */
%notyet const CCTK_REAL    input_real   [NY][NX];
%notyet const CCTK_COMPLEX input_complex[NY][NX];
%notyet const CCTK_INT input_array_dims[N_DIMS] = { NX, NY };
%notyet const CCTK_INT input_array_type_codes[N_INPUT_ARRAYS]
%notyet         = { CCTK_VARIABLE_REAL, CCTK_VARIABLE_COMPLEX };
%notyet const void *const input_arrays[N_INPUT_ARRAYS]
%notyet         = { (const void *) input_real, (const void *) input_complex };
%notyet
%notyet /* output arrays */
%notyet CCTK_REAL    output_real   [N_INTERP_POINTS];
%notyet CCTK_COMPLEX output_complex[N_INTERP_POINTS];
%notyet const CCTK_INT output_array_type_codes[N_OUTPUT_ARRAYS]
%notyet         = { CCTK_VARIABLE_REAL, CCTK_VARIABLE_COMPLEX };
%notyet void *const output_arrays[N_OUTPUT_ARRAYS]
%notyet         = { (void *) output_real, (void *) output_complex };
%notyet
%notyet int operator_handle, param_table_handle;
%notyet operator_handle = CCTK_InterpHandle("my interpolation operator");
%notyet if (operator_handle < 0)
%notyet         CCTK_WARN(CCTK_WARN_ABORT, "can't get interpolation handle!");
%notyet param_table_handle = Util_TableCreateFromString("order=3");
%notyet if (param_table_handle < 0)
%notyet         CCTK_WARN(CCTK_WARN_ABORT, "can't create parameter table!");
%notyet if (CCTK_InterpLocalWarped(N_DIMS,
%notyet                            operator_handle, param_table_handle,
%notyet                            CCTK_VARIABLE_REAL,
%notyet                               coord_array_dims,
%notyet                               coord_arrays,
%notyet                            N_INTERP_POINTS,
%notyet                               CCTK_VARIABLE_REAL,
%notyet                               interp_coords,
%notyet                            N_INPUT_ARRAYS,
%notyet                               input_array_dims,
%notyet                               input_array_type_codes,
%notyet                               input_arrays,
%notyet                            N_OUTPUT_ARRAYS,
%notyet                               output_array_type_codes,
%notyet                               output_arrays) < 0)
%notyet         CCTK_WARN(CCTK_WARN_ABORT, "error return from interpolator!");
%notyet \end{verbatim}
%notyet \end{verbatim}
%notyet \end{Example}
%notyet \end{ExampleSection}
%notyet \end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% here should be CCTK\_InterpRegisterOpLocalNonUniform

% Interp.c
%Entering a function description for CCTK\_InterpRegisterOpLocalUniform
\begin{FunctionDescription}{CCTK\_InterpRegisterOpLocalUniform}
\label{CCTK-InterpRegisterOpLocalUniform}
Register a \code{CCTK\_InterpLocalUniform} interpolation operator.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int CCTK_InterpRegisterOpLocalUniform(cInterpOpLocalUniform operator_ptr,
                                      const char *operator_name,
                                      const char *thorn_name);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{handle ($\ge 0$)}
A cactus handle to refer to all interpolation operators registered
under this operator name.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{operator\_ptr ($\ne$ NULL)}
\hbox{}
Pointer to the \code{CCTK\_InterpLocalUniform} interpolation operator.
This argument must be a C function pointer of the appropriate type;
the typedef can be found in \code{src/include/cctk\_Interp.h} in the
Cactus source code.
\end{Parameter}
\begin{Parameter}{operator\_name ($\ne$ NULL)}
\hbox{}
(Pointer to) a (C-style null-terminated) character string giving
the name under which to register the operator.
\end{Parameter}
\begin{Parameter}{thorn\_name ($\ne$ NULL)}
\hbox{}
(Pointer to) a (C-style null-terminated) character string giving
the name of the thorn which provides the interpolation operator.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Only C functions (or other routines with C-compatible calling sequences)
can be registered as interpolation operators.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_InterpHandle()}
Get the interpolator handle for a given character-string name.
\end{SeeAlso}
\begin{SeeAlso}{CCTK\_InterpLocalUniform()}
Interpolate a list of processor-local arrays, with uniformly spaced
data points.
\end{SeeAlso}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{-1}
NULL pointer was passed as interpolation operator routine
\end{Error}
\begin{Error}{-2}
interpolation handle could not be allocated
\end{Error}
\begin{Error}{-3}
Interpolation operator with this name already exists
\end{Error}
\end{ErrorSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
/* prototype for function we want to register */
int AEILocalInterp_InterpLocalUniform(int N_dims,
                                      int param_table_handle,
                                    /***** coordinate system *****/
                                      const CCTK_REAL coord_origin[],
                                      const CCTK_REAL coord_delta[],
                                    /***** interpolation points *****/
                                      int N_interp_points,
                                      int interp_coords_type_code,
                                      const void *const interp_coords[],
                                    /***** input arrays *****/
                                      int N_input_arrays,
                                      const CCTK_INT input_array_dims[],
                                      const CCTK_INT input_array_type_codes[],
                                      const void *const input_arrays[],
                                    /***** output arrays *****/
                                      int N_output_arrays,
                                      const CCTK_INT output_array_type_codes[],
                                      void *const output_arrays[]);

/* register it! */
CCTK_InterpRegisterOpLocalUniform(AEILocalInterp_InterpLocalUniform,
                                  "generalized polynomial interpolation",
                                  CCTK_THORNSTRING);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% CCTK\_InterpRegisterOpLocalWarped here

% lib/sbin/CreateFunctionBindings.pl
\begin{FunctionDescription}{CCTK\_IsFunctionAliased}{Reports whether an aliased function has been provided}
\label{CCTK-IsFunctionAliased}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_IsFunctionAliased( const char * functionname)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_IsFunctionAliased(istat , functionname )

integer istat
character*(*) functionname\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{istat}
the return status
\end{Parameter}
\begin{Parameter}{functionname}
the name of the function to check
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
This function returns a non-zero value if the function given by
\code{functionname} is provided by any active thorn, and zero
otherwise.
\end{Discussion}
\end{FunctionDescription}

% ActiveThorns.c
\begin{FunctionDescription}{CCTK\_IsImplementationActive}{Reports whether an implementation was activated in a parameter file}
\label{CCTK-IsImplementationActive}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_IsImplementationActive( const char * implementationname)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}CCTK_IsImplementationActive( istat, implementationname ) 

integer istat
character*(*) implementationname \end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{istat}
the return status
\end{Parameter}
\begin{Parameter}{implementationname}
the name of the implementation to check
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
This function returns a non-zero value if the implementation given by
\code{implementationname} was activated in a parameter file, and zero
otherwise.
See also
\code{CCTK\_ActivatingThorn} [\pageref{CCTK-ActivatingThorn}],
\code{CCTK\_CompiledImplementation} [\pageref{CCTK-CompiledImplementation}],
\code{CCTK\_CompiledThorn} [\pageref{CCTK-CompiledThorn}],
\code{CCTK\_ImplementationRequires} [\pageref{CCTK-ImplementationRequires}],
\code{CCTK\_ImplementationThorn} [\pageref{CCTK-ImplementationThorn}],
\code{CCTK\_ImpThornList} [\pageref{CCTK-ImpThornList}],
\code{CCTK\_IsImplementationCompiled} [\pageref{CCTK-IsImplementationCompiled}],
\code{CCTK\_IsThornActive} [\pageref{CCTK-IsThornActive}],
\code{CCTK\_NumCompiledImplementations} [\pageref{CCTK-NumCompiledImplementations}],
\code{CCTK\_NumCompiledThorns} [\pageref{CCTK-NumCompiledThorns}],
\code{CCTK\_ThornImplementation} [\pageref{CCTK-ThornImplementation}].
\end{Discussion}
\end{FunctionDescription}

% ActiveThorns.c
\begin{FunctionDescription}{CCTK\_IsImplementationCompiled}{Reports whether an
implementation was compiled into the configuration}
\label{CCTK-IsImplementationCompiled}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_IsImplementationCompiled(  const char * implementationname)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}istat = CCTK_IsImplementationCompiled( implementationname )

integer istat
character*(*) implementationname\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{istat}
the return status
\end{Parameter}
\begin{Parameter}{implementationname}
the name of the implementation to check
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
This function returns a non-zero value if the implementation given by
\code{implementationname} was compiled into the configuration, and zero
otherwise.
See also
\code{CCTK\_ActivatingThorn} [\pageref{CCTK-ActivatingThorn}],
\code{CCTK\_CompiledImplementation} [\pageref{CCTK-CompiledImplementation}],
\code{CCTK\_CompiledThorn} [\pageref{CCTK-CompiledThorn}],
\code{CCTK\_ImplementationRequires} [\pageref{CCTK-ImplementationRequires}],
\code{CCTK\_ImplementationThorn} [\pageref{CCTK-ImplementationThorn}],
\code{CCTK\_ImpThornList} [\pageref{CCTK-ImpThornList}],
\code{CCTK\_IsImplementationActive} [\pageref{CCTK-IsImplementationActive}],
\code{CCTK\_IsThornActive} [\pageref{CCTK-IsThornActive}],
\code{CCTK\_IsThornCompiled} [\pageref{CCTK-IsThornCompiled}],
\code{CCTK\_NumCompiledImplementations} [\pageref{CCTK-NumCompiledImplementations}],
\code{CCTK\_NumCompiledThorns} [\pageref{CCTK-NumCompiledThorns}],
\code{CCTK\_ThornImplementation} [\pageref{CCTK-ThornImplementation}].
\end{Discussion}
\end{FunctionDescription}

% ActiveThorns.c
%Entering a function description for CCTK\_IsThornActive
\begin{FunctionDescription}{CCTK\_IsThornActive}
\label{CCTK-IsThornActive}
Reports whether a thorn was activated in a parameter file

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_IsThornActive(const char* thorn_name);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"

integer status
character *(*) thorn_name

status = CCTK_IsThornActive(thorn_name)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{status}
This function returns a non-zero value if thorn
\code{thorn\_name} was activated in a parameter file,
and zero otherwise.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{thorn\_name}
The character-string name of the thorn, for example "SymBase".
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This function lets you find out at run-time whether or not a given
thorn is active in the current Cactus run.
\end{Discussion}

%%\code{CCTK\_ActivatingThorn} [\pageref{CCTK-ActivatingThorn}],
%%\code{CCTK\_CompiledImplementation} [\pageref{CCTK-CompiledImplementation}],
%%\code{CCTK\_CompiledThorn} [\pageref{CCTK-CompiledThorn}],
%%\code{CCTK\_ImplementationRequires} [\pageref{CCTK-ImplementationRequires}],
%%\code{CCTK\_ImplementationThorn} [\pageref{CCTK-ImplementationThorn}],
%%\code{CCTK\_ImpThornList} [\pageref{CCTK-ImpThornList}],
%%\code{CCTK\_IsImplementationActive} [\pageref{CCTK-IsImplementationActive}],
%%\code{CCTK\_IsImplementationCompiled} [\pageref{CCTK-IsImplementationCompiled}],
%%\code{CCTK\_IsThornActive} [\pageref{CCTK-IsThornActive}],
%%\code{CCTK\_NumCompiledImplementations} [\pageref{CCTK-NumCompiledImplementations}],
%%\code{CCTK\_NumCompiledThorns} [\pageref{CCTK-NumCompiledThorns}],
%%\code{CCTK\_ThornImplementation} [\pageref{CCTK-ThornImplementation}].
\end{FunctionDescription}

% ActiveThorns.c
\begin{FunctionDescription}{CCTK\_IsThornCompiled}{Reports whether a thorn was activated in a parameter file}
\label{CCTK-IsThornCompiled}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_IsThornCompiled( const char * thornname)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}istat = CCTK_IsThornCompiled(  thornname )

integer istat
character*(*) thornname\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{istat}
the return status
\end{Parameter}
\begin{Parameter}{thorname}
the name of the thorn to check
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
This function returns a non-zero value if the implementation given by
\code{thornname} was compiled into the configuration, and zero
otherwise.
\end{Discussion}
\end{FunctionDescription}


%%%%%
% JJJ
%%%%%

%%%%%
% KKK
%%%%%

%%%%%
% LLL
%%%%%

% Reduction.c

\begin{FunctionDescription}{CCTK\_LocalArrayReduceOperator}
\label{CCTK-LocalArrayReduceOperator}
Returns the name of a registered reduction operator

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

const char *name = CCTK_LocalArrayReduceOperator(int handle);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{name}
Returns the name of a registered local reduction operator of handle \newline \code{handle}
or NULL if the handle is invalid
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{handle}
The handle of a registered local reduction operator
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This function returns the name of a registered reduction operator given
its handle. NULL is returned if the handle is invalid
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_ReduceLocalArrays()}
Reduces a list of local arrays (new local array reduction API)
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_LocalArrayReductionHandle()}
Returns the handle of a given local array reduction operator
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_RegisterLocalArrayReductionOperator()}
Registers a function as a reduction operator of a certain name
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_LocalArrayReduceOperatorImplementation()}
Provide the implementation which provides an local array reduction operator
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_NumLocalArrayReduceOperators()}
The number of local reduction operators registered
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}

%Reduction.c
%Entering a function description for CCTK\_LocalArrayReduceOperatorImplementation
\begin{FunctionDescription}{CCTK\_LocalArrayReduceOperatorImplementation}
\label{CCTK-LocalArrayReduceOperatorImplementation}
Provide the implementation which provides an local array reduction operator

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

const char *implementation = CCTK_LocalArrayReduceOperatorImplementation(
                            int handle);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{implementation}
The name of the implementation implementing the local reduction operator of handle \newline \code{handle}
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{handle}
The handle of a registered local reduction operator
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This function returns the implementation name of a registered reduction operator given
its handle or NULL if the handle is invalid
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_ReduceLocalArrays()}
Reduces a list of local arrays (new local array reduction API)
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_LocalArrayReductionHandle()}
Returns the handle of a given local array reduction operator
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_RegisterLocalArrayReductionOperator()}
Registers a function as a reduction operator of a certain name
\end{SeeAlso}
%notyet /* (x,y) coordinates of interpolation points */
\begin{SeeAlso}{CCTK\_LocalArrayReduceOperator()}
Returns the name of a registered reduction operator
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_NumLocalArrayReduceOperators()}
The number of local reduction operators registered
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}

%Reduction.c
%Entering a function description for CCTK\_LocalArrayReductionHandle
\begin{FunctionDescription}{CCTK\_LocalArrayReductionHandle}
\label{CCTK-LocalArrayReductionHandle}
Returns the handle of a given local array reduction operator

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int handle = CCTK_LocalArrayReductionHandle(const char *operator);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{handle}
The handle corresponding to the local reduction operator
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{operator}
The reduction operation to be performed. If no matching registered operator
is found, a warning is issued and an error returned.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This function returns the handle of the local array reduction operator. The local
reduction handle is also used in the grid array reduction.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_ReduceLocalArrays()}
Reduces a list of local arrays (new local array reduction API)
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_RegisterLocalArrayReductionOperator()}
Registers a function as a reduction operator of a certain name
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_LocalArrayReduceOperatorImplementation()}
Provide the implementation which provides an local array reduction operator
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_LocalArrayReduceOperator()}
Returns the name of a registered reduction operator
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_NumLocalArrayReduceOperators()}
The number of local reduction operators registered
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}

%%%%%
% MMM
%%%%%


% Groups.c
\begin{FunctionDescription}{CCTK\_MaxDim}{Get the maximum dimension of any grid variable }
\label{CCTK-MaxDim}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int dim = CCTK_MaxDim()\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_MaxDim(dim )

integer dim\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{dim}
The maximum dimension
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
Note that the maximum dimension will depend only on the active thorn list,
and not the compiled thorn list.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
dim = CCTK_MaxDim()
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call  CCTK_MaxDim(dim)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_MaxGFDim}{Get the maximum dimension of all grid
    functions }
\label{CCTK-MaxGFDim}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int dim = CCTK_MaxGFDim()\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_MaxGFDim(dim )

integer dim\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{dim}
The maximum dimension of all grid functions
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
Note that the maximum dimension will depend only on the active thorn list,
and not the compiled thorn list.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
dim = CCTK_MaxGFDim();
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call  CCTK_MaxGFDim(dim)}
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}



\begin{FunctionDescription}{CCTK\_MaxTimeLevels}{Gives the number of timelevels for a group}
\label{CCTK-MaxTimeLevels}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int numlevels = CCTK_MaxTimeLevels( const char * name)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_MaxTimeLevels(numlevels , name )

integer numlevels
character*(*) name\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{name}
The full group name
\end{Parameter}
\begin{Parameter}{numlevels}
The number of timelevels
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The group name should be in the form \code{<implementation>::<group>}
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
numlevels = CCTK_MaxTimeLevels("evolve::phivars");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_MAXTIMELEVELS(numlevels,"evolve::phivars")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

% Groups.c
\begin{FunctionDescription}{CCTK\_MaxTimeLevelsGI}{Gives the number of timelevels for a group}
\label{CCTK-MaxTimeLevelsGI}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int numlevels = CCTK_MaxTimeLevelsGI( int index)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_MaxTimeLevelsGI(numlevels , index )

integer numlevels
integer index\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{numlevels}
The number of timelevels
\end{Parameter}
\begin{Parameter}{index}
The group index
\end{Parameter}
\end{ParameterSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
index = CCTK_GroupIndex("evolve::phivars")
numlevels = CCTK_MaxTimeLevelsGI(index);
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_MAXTIMELEVELSGI(numlevels,3)}
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


% Groups.c
\begin{FunctionDescription}{CCTK\_MaxTimeLevelsGN}
\label{CCTK-MaxTimeLevelsGN}
Gives the number of timelevels for a group
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int retval = CCTK_MaxTimeLevelsGN(const char *group);\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{}
The maximum number of timelevels this group has, or -1 if the group name is incorrect.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{group}
The variable group's name
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This function and its relatives return the maximum number of timelevels that the given variable group can have active.  This function does not tell you anything about how many time levels are active at the time.
\end{Discussion}
\end{FunctionDescription}



% Groups.c
\begin{FunctionDescription}{CCTK\_MaxTimeLevelsVI}{Gives the number of timelevels for a variable}
\label{CCTK-MaxTimeLevelsVI}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int numlevels = CCTK_MaxTimeLevelsVI( int index)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_MaxTimeLevelsVI(numlevels , index )

integer numlevels
integer index\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{numlevels}
The number of timelevels
\end{Parameter}
\begin{Parameter}{index}
The variable index
\end{Parameter}
\end{ParameterSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
index = CCTK_VarIndex("evolve::phi")
numlevels = CCTK_MaxTimeLevelsVI(index);
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_MAXTIMELEVELSVI(numlevels,3)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_MaxTimeLevelsVN}{Gives the number of timelevels for a variable}
\label{CCTK-MaxTimeLevelsVN}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int numlevels = CCTK_MaxTimeLevelsVN( const char * name)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_MaxTimeLevelsVN(numlevels , name )

integer numlevels
character*(*) name\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{name}
The full variable name
\end{Parameter}
\begin{Parameter}{numlevels}
The number of timelevels
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The variable name should be in the form \code{<implementation>::<variable>}
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
numlevels = CCTK_MaxTimeLevelsVN("evolve::phi")
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_MAXTIMELEVELSVN(numlevels,"evolve::phi")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

% CommOverloadables.c
\begin{FunctionDescription}{CCTK\_MyProc}{Returns the number of the local processor for a parallel run}
\label{CCTK-MyProc}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int myproc = CCTK_MyProc( const cGH * cctkGH)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
For a single processor run this call will return zero. For multiprocessor
runs, this call will return 0 $\leq$ myproc $<$ \code{CCTK\_nProcs(cctkGH)}.

Calling \code{CCTK\_MyProc(NULL)} is safe (it will not crash).
Current drivers (PUGH, Carpet) handle this case correctly
(i.e.\ \code{CCTK\_MyProc(NULL)} returns a correct result), but only
a ``best effort'' is guaranteed for future drivers (or future revisions
of current drivers).
\end{Discussion}
\end{FunctionDescription}



%%%%%
% NNN
%%%%%



% CommOverloadables.c
\begin{FunctionDescription}{CCTK\_nProcs}{Returns the number of processors being used for a parallel run}
\label{CCTK-nProcs}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int nprocs = CCTK_nProcs( const cGH * cctkGH)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}nprocs = CCTK_nProcs(  cctkGH )

integer nprocs
CCTK_POINTER cctkGH\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
For a single processor run this call will return one.

Calling \code{CCTK\_nProcs(NULL)} is safe (it will not crash).
Current drivers (PUGH, Carpet) handle this case correctly
(i.e.\ \code{CCTK\_nProcs(NULL)} returns a correct result), but only
a ``best effort'' is guaranteed for future drivers (or future revisions
of current drivers).
\end{Discussion}
\end{FunctionDescription}


% util/Misc.c
%Entering a function description for CCTK\_NullPointer
\begin{FunctionDescription}{CCTK\_NullPointer}%%%
\label{CCTK-NullPointer}
Returns a C-style NULL pointer value.

\begin{SynopsisSection}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"

CCTK_POINTER pointer_var

pointer_var = CCTK_NullPointer()
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{pointer\_var}
a CCTK\_POINTER type variable which is initialized with a C-style NULL pointer
\end{Result}
\end{ResultSection}

\begin{Discussion}
Fortran doesn't know the concept of pointers so problems arise when a C function
is to be called which expects a pointer as one (or more) of it(s) argument(s).

In order to pass a NULL pointer from Fortran to C, a local CCTK\_POINTER variable should be used which has been initialized before with \code{CCTK\_NullPointer}.

Note that there is only a Fortran wrapper available for \code{CCTK\_NullPointer}.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_PointerTo()}
Returns the address of a variable passed in by reference from a Fortran routine.
\end{SeeAlso}
\end{SeeAlsoSection}

\begin{ExampleSection}
\begin{Example}{Fortran}
\begin{verbatim}
#include "cctk.h"

integer      ierror, table_handle
CCTK_POINTER pointer_var

pointer_var = CCTK_NullPointer()

call Util_TableCreate(table_handle, 0)
call Util_TableSetPointer(ierror, table_handle, pointer_var, "NULL pointer")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}



% cctk_ActiveThorns.c
%Entering a function description for CCTK\_NumCompiledImplementations
\begin{FunctionDescription}{CCTK\_NumCompiledImplementations}
\label{CCTK-NumCompiledImplementations}
Return the number of implementations compiled in.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int numimpls = CCTK_NumCompiledImplementations();
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{numimpls}
Number of implementations compiled in.
\end{Result}
\end{ResultSection}

%\begin{ParameterSection}
%\end{ParameterSection}

%\begin{Discussion}
%\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ActivatingThorn}{CCTK-ActivatingThorn}
  Finds the thorn which activated a particular implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompiledImplementation}{CCTK-CompiledImplementation}
  Return the name of the compiled implementation with given index
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompiledThorn}{CCTK-CompiledThorn}
  Return the name of the compiled thorn with given index
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImplementationRequires}{CCTK-ImplementationRequires}
  Return the ancestors for an implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImplementationThorn}{CCTK-ImplementationThorn}
  Returns the name of one thorn providing an implementation.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImpThornList}{CCTK-ImpThornList}
  Return the thorns for an implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive}
  Reports whether an implementation was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled}
  Reports whether an implementation was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive}
  Reports whether a thorn was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled}
  Reports whether a thorn was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_NumCompiledThorns}{CCTK-NumCompiledThorns}
  Return the number of thorns compiled in
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ThornImplementation}{CCTK-ThornImplementation}
  Returns the implementation provided by the thorn
\end{SeeAlso2}
\end{SeeAlsoSection}

%\begin{ErrorSection}
%\end{ErrorSection}

%\begin{ExampleSection}
%\end{ExampleSection}
\end{FunctionDescription}



% cctk_ActiveThorns.c
%Entering a function description for CCTK\_NumCompiledThorns
\begin{FunctionDescription}{CCTK\_NumCompiledThorns}
\label{CCTK-NumCompiledThorns}
Return the number of thorns compiled in.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int numthorns = CCTK_NumCompiledThornss();
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{numthorns}
Number of thorns compiled in.
\end{Result}
\end{ResultSection}

%\begin{ParameterSection}
%\end{ParameterSection}

%\begin{Discussion}
%\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ActivatingThorn}{CCTK-ActivatingThorn}
  Finds the thorn which activated a particular implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompiledImplementation}{CCTK-CompiledImplementation}
  Return the name of the compiled implementation with given index
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompiledThorn}{CCTK-CompiledThorn}
  Return the name of the compiled thorn with given index
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImplementationRequires}{CCTK-ImplementationRequires}
  Return the ancestors for an implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImplementationThorn}{CCTK-ImplementationThorn}
  Returns the name of one thorn providing an implementation.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImpThornList}{CCTK-ImpThornList}
  Return the thorns for an implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive}
  Reports whether an implementation was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled}
  Reports whether an implementation was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive}
  Reports whether a thorn was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled}
  Reports whether a thorn was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_NumCompiledImplementations}{CCTK-NumCompiledImplementations}
  Return the number of implementations compiled in
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ThornImplementation}{CCTK-ThornImplementation}
  Returns the implementation provided by the thorn
\end{SeeAlso2}
\end{SeeAlsoSection}

%\begin{ErrorSection}
%\end{ErrorSection}

%\begin{ExampleSection}
%\end{ExampleSection}
\end{FunctionDescription}


%Reduction.c
%Entering a function description for CCTK\_NumGridArrayReductionOperators
\begin{FunctionDescription}{CCTK\_NumGridArrayReductionOperators}
\label{CCTK-NumGridArrayReductionOperators}
The number of grid array reduction operators registered

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int num_ga_reduc = CCTK_NumGridArrayReductionOperators();
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{num\_ga\_reduc}
The number of registered grid array reduction operators (currently either \code{1}
 or \code{0})
\end{Result}
\end{ResultSection}

%\begin{ParameterSection}
%\end{ParameterSection}

\begin{Discussion}
This function returns the number of grid array reduction operators. Since we only allow one grid array reduction operator currently, this function can be used to check if a
grid array reduction operator has been registered or not.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_ReduceGridArrays()}
Performs reduction on a list of distributed grid arrays
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_RegisterGridArrayReductionOperator()}
Registers a function as a grid array reduction operator of a certain name
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_GridArrayReductionOperator()}
The name of the grid reduction operator, or NULL if none is registered
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}


% Groups.c
\begin{FunctionDescription}{CCTK\_NumGroups}{Get the number of groups of variables compiled in the code}
\label{CCTK-NumGroups}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int number = CCTK_NumGroups()\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_NumGroups(number )

integer number\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{number}
The number of groups compiled from the thorns \code{interface.ccl} files
\end{Parameter}
\end{ParameterSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
number = CCTK_NumGroups();
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_NumGroups(number);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%Entering a function description for CCTK\_NumIOMethods
\begin{FunctionDescription}{CCTK\_NumIOMethods}
\label{CCTK-NumIOMethods}
Find the total number of I/O methods registered with the flesh

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int num_methods = CCTK_NumIOMethods (void);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_NumIOMethods (num_methods)
integer num_methods
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{num\_methods}number of registered IO methods\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Returns the total number of IO methods registered with the flesh.
\end{Discussion}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


%Reduction.c
\begin{FunctionDescription}{CCTK\_NumLocalArrayReduceOperators}
\label{CCTK-NumLocalArrayReduceOperators}
The number of local reduction operators registered

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int num_ga_reduc = CCTK_NumLocalArrayReduceOperators();
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{num\_ga\_reduc}
The number of registered local array operators
\end{Result}
\end{ResultSection}

%\begin{ParameterSection}
%\end{ParameterSection}

\begin{Discussion}
This function returns the total number of registered local array
reduction operators
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_ReduceLocalArrays()}
Reduces a list of local arrays (new local array reduction API)
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_LocalArrayReductionHandle()}
Returns the handle of a given local array reduction operator
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_RegisterLocalArrayReductionOperator()}
Registers a function as a reduction operator of a certain name
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_LocalArrayReduceOperatorImplementation()}
Provide the implementation which provides an local array reduction operator
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_LocalArrayReduceOperator()}
Returns the name of a registered reduction operator
\end{SeeAlso}

\end{SeeAlsoSection}
\end{FunctionDescription}

%Reduction.c
\begin{FunctionDescription}{CCTK\_NumReductionArraysGloballyOperators}
\label{CCTK-NumReductionArraysGloballyOperators}
The number of global array reduction operators registered, either 1 or 0.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int num_reduc = CCTK_NumReductionArraysGloballyOperators();
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{num\_reduc}
The number of registered global array operators
\end{Result}
\end{ResultSection}

%\begin{ParameterSection}
%\end{ParameterSection}

\begin{Discussion}
This function returns the total number of registered global array
reduction operators, it is either 1 or 0 as we do not allow multiple
array reductions.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_ReduceArraysGlobally()}
Reduces a list of arrays globally
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_LocalArrayReductionHandle()}
Returns the handle of a given local array reduction operator
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_RegisterReduceArraysGloballyOperator()}
Registers a function as a reduction operator of a certain name
\end{SeeAlso}

\end{SeeAlsoSection}
\end{FunctionDescription}


% cctk_GroupsOnGH.h
%Entering a function description for CCTK\_NumTimeLevels
\begin{FunctionDescription}{CCTK\_NumTimeLevels}
\label{CCTK-NumTimeLevels}
Returns the number of active time levels for a group (deprecated).

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int timelevels = CCTK_NumTimeLevels(const cGH *cctkGH,
                                    const char *groupname);

int timelevels = CCTK_NumTimeLevelsGI(const cGH *cctkGH,
                                      int groupindex);

int timelevels = CCTK_NumTimeLevelsGN(const cGH *cctkGH,
                                      const char *groupname);

int timelevels = CCTK_NumTimeLevelsVI(const cGH *cctkGH,
                                      int varindex);

int timelevels = CCTK_NumTimeLevelsVN(const cGH *cctkGH,
                                      const char *varname);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"

subroutine CCTK_NumTimeLevels(timelevels, cctkGH, groupname)
   integer       timelevels
   CCTK_POINTER  cctkGH
   character*(*) groupname
end subroutine CCTK_NumTimeLevels

subroutine CCTK_NumTimeLevelsGI(timelevels, cctkGH, groupindex)
   integer       timelevels
   CCTK_POINTER  cctkGH
   integer       groupindex
end subroutine CCTK_NumTimeLevelsGI

subroutine CCTK_NumTimeLevelsGN(timelevels, cctkGH, groupname)
   integer       timelevels
   CCTK_POINTER  cctkGH
   character*(*) groupname
end subroutine CCTK_NumTimeLevelsGN

subroutine CCTK_NumTimeLevelsVI(timelevels, cctkGH, varindex)
   integer       timelevels
   CCTK_POINTER  cctkGH
   integer       varindex
end subroutine CCTK_NumTimeLevelsVI

subroutine CCTK_NumTimeLevelsVN(timelevels, cctkGH, varname)
   integer       timelevels
   CCTK_POINTER  cctkGH
   character*(*) varname
end subroutine CCTK_NumTimeLevelsVN
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{timelevels}
The currently active number of timelevels for the group.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{GH ($\ne$ NULL)}
Pointer to a valid Cactus grid hierarchy.
\end{Parameter}
\begin{Parameter}{groupname}
Name of the group.
\end{Parameter}
\begin{Parameter}{groupindex}
Index of the group.
\end{Parameter}
\begin{Parameter}{varname}
Name of a variable in the group.
\end{Parameter}
\begin{Parameter}{varindex}
Index of a variable in the group.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This function returns the number of timelevels for which storage has
been activated, which is always equal to or less than the maximum
number of timelevels which may have storage provided by
\code{CCTK\_MaxTimeLevels}.

This function has been superceded by \code{CCTK\_ActiveTimeLevels} and
should not be used any more.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ActiveTimeLevels}{CCTK-ActiveTimeLevels}
Returns the number of active time levels for a group.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_MaxTimeLevels}{CCTK-MaxTimeLevels}
Return the maximum number of active timelevels.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_GroupStorageDecrease}{CCTK-GroupStorageDecrease}
Base function, overloaded by the driver, which decreases the number of
active timelevels, and also returns the number of active timelevels.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_GroupStorageIncrease}{CCTK-GroupStorageIncrease}
Base function, overloaded by the driver, which increases the number of
active timelevels, and also returns the number of active timelevels.
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{timelevels $<$ 0}
Illegal arguments given.
\end{Error}
\end{ErrorSection}

%\begin{ExampleSection}
%\end{ExampleSection}
\end{FunctionDescription}


%Entering a function description for CCTK\_NumTimerClocks
\begin{FunctionDescription}{CCTK\_NumTimerClocks}
\label{CCTK-NumTimerClocks}
Given a {\tt cTimerData} structure, returns its number of clocks.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int err = CCTK_NumTimerClocks(info)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter} {const cTimerData * info}
The timer information structure whose clocks are to be counted.
\end{Parameter}
\end{ParameterSection}
\end{FunctionDescription}


% Groups.c
\begin{FunctionDescription}{CCTK\_NumVars}{Get the number of grid variables compiled in the code}
\label{CCTK-NumVars}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int number = CCTK_NumVars()\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_NumVars(number )

integer number\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{number}
The number of grid variables compiled from the thorn's \code{interface.ccl} files
\end{Parameter}
\end{ParameterSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
number = CCTK_NumVars();
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_NumVars(number)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}




% Groups.c
\begin{FunctionDescription}{CCTK\_NumVarsInGroup}{Provides the number of variables in a group from the group name}
\label{CCTK-NumVarsInGroup}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int num = CCTK_NumVarsInGroup( const char * name)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_NumVarsInGroup(num , name )

integer num
character*(*) name\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{num}
The number of variables in the group
\end{Parameter}
\begin{Parameter}{group}
The full group name
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The group name should be given in the form \code{<implementation>::<group>}
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
numvars = CCTK_NumVarsInGroup("evolve::scalars")
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_NUMVARSINGROUP(numvars,"evolve::scalars")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}



% Groups.c
\begin{FunctionDescription}{CCTK\_NumVarsInGroupI}{Provides the number of variables in a group from the group index}
\label{CCTK-NumVarsInGroupI}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int num = CCTK_NumVarsInGroupI( int index)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_NumVarsInGroupI(num , index )

integer num
integer index\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{num}
The number of variables in the group
\end{Parameter}
\begin{Parameter}{group}
The group index
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}

\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
index = CCTK_GroupIndex("evolve::scalars")}
firstvar = CCTK_NumVarsInGroupI(index)
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_NUMVARSINGROUPI(firstvar,3)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}






%%%%%
% OOO
%%%%%


% IOOverloadables.h
\begin{FunctionDescription}{CCTK\_OutputGH}
\label{CCTK-OutputGH}
Output all variables living on the GH looping over all registered IO methods.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int istat = CCTK_OutputGH (const cGH *cctkGH);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_OutputGH (istat, cctkGH)
integer istat
CCTK_POINTER cctkGH
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{istat}
total number of variables for which output was done by all IO methods
\end{Parameter}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The IO methods decide themselfes whether it is time to do output now or not.
\end{Discussion}

\begin{ErrorSection}
\begin{Error}{0}
it wasn't time to output anything yet by any IO method
\end{Error}
\begin{Error}{-1}
if no IO methods were registered
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% IOOverloadables.h
\begin{FunctionDescription}{CCTK\_OutputVar}
Output a single variable by all I/O methods
\label{CCTK-OutputVar}

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int istat = CCTK_OutputVar (const cGH *cctkGH,
                            const char *variable);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_OutputVar (istat, cctkGH, variable)
integer istat
CCTK_POINTER cctkGH
character*(*) variable
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{istat}return status\end{Parameter}
\begin{Parameter}{cctkGH}pointer to CCTK grid hierarchy\end{Parameter}
\begin{Parameter}{variable}full name of variable to output, with an optional
options string in curly braces\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The output should take place if at all possible.
If the appropriate file exists the data is appended, otherwise a new
file is created.
\end{Discussion}

\begin{ErrorSection}
\begin{Error}{0}
for success
\end{Error}
\begin{Error}{negative}
for some error condition (e.g.\ IO method is not registered)
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% IOOverloadables.h
\begin{FunctionDescription}{CCTK\_OutputVarAs}
Output a single variable as an alias by all I/O methods
\label{CCTK-OutputVarAs}

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int istat = CCTK_OutputVarAs (const cGH *cctkGH,
                              const char *variable,
                              const char *alias);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_OutputVarAsByMethod (istat, cctkGH, variable, alias)
integer istat
CCTK_POINTER cctkGH
character*(*) variable
character*(*) alias
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{istat}return status\end{Parameter}
\begin{Parameter}{cctkGH}pointer to CCTK grid hierarchy\end{Parameter}
\begin{Parameter}{variable}full name of variable to output, with an optional
options string in curly braces\end{Parameter}
\begin{Parameter}{alias}alias name to base the output filename on\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The output should take place if at all possible.
If the appropriate file exists the data is appended, otherwise a new
file is created. Uses \code{alias} as the name of the variable for the purpose
of constructing a filename.
\end{Discussion}

\begin{ErrorSection}
\begin{Error}{positive}the number of IO methods which did output of \code{variable}\end{Error}
\begin{Error}{0}for success\end{Error}
\begin{Error}{negative}if no IO methods were registered\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% IOOverloadables.h
\begin{FunctionDescription}{CCTK\_OutputVarAsByMethod}
\label{CCTK-OutputVarAsByMethod}

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int istat = CCTK_OutputVarAsByMethod (const cGH *cctkGH,
                                      const char *variable,
                                      const char *method,
                                      const char *alias);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_OutputVarAsByMethod (istat, cctkGH, variable, method, alias)
integer istat
CCTK_POINTER cctkGH
character*(*) variable
character*(*) method
character*(*) alias
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{istat}return status\end{Parameter}
\begin{Parameter}{cctkGH}pointer to CCTK grid hierarchy\end{Parameter}
\begin{Parameter}{variable}full name of variable to output, with an optional
options string in curly braces\end{Parameter}
\begin{Parameter}{method}method to use for output\end{Parameter}
\begin{Parameter}{alias}alias name to base the output filename on\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Output a variable \code{variable} using the method \code{method} if it is
registered. Uses \code{alias} as the name of the variable for the purpose
of constructing a filename. The output should take place if at all possible.
If the appropriate file exists the data is appended, otherwise a new
file is created.
\end{Discussion}

\begin{ErrorSection}
\begin{Error}{0}for success\end{Error}
\begin{Error}{negative}indicating some error (e.g.\ IO method is not registered)\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% IOOverloadables.h
\begin{FunctionDescription}{CCTK\_OutputVarByMethod}
\label{CCTK-OutputVarByMethod}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int istat = CCTK_OutputVarByMethod (const cGH *cctkGH,
                                    const char *variable,
                                    const char *method);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_OutputVarByMethod (istat, cctkGH, variable, method)
integer istat
CCTK_POINTER cctkGH
character*(*) variable
character*(*) method
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{istat}return status\end{Parameter}
\begin{Parameter}{cctkGH}pointer to CCTK grid hierarchy\end{Parameter}
\begin{Parameter}{variable}full name of variable to output, with an optional
options string in curly braces\end{Parameter}
\begin{Parameter}{method}method to use for output\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Output a variable \code{variable} using the IO method \code{method} if it is
registered. The output should take place if at all possible.
if the appropriate file exists the data is appended, otherwise a new
file is created.
\end{Discussion}

\begin{ErrorSection}
\begin{Error}{0}for success\end{Error}
\begin{Error}{negative}indicating some error (e.g.\ IO method is not registered)\end{Error}
\end{ErrorSection}
\end{FunctionDescription}



%%%%%
% PPP
%%%%%

% CommOverloadables.c
\begin{FunctionDescription}{CCTK\_ParallelInit}{Initialize the parallel subsystem}
\label{CCTK-ParallelInit}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_ParallelInit( cGH * cctkGH)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
Initializes the parallel subsystem.
\end{Discussion}
\end{FunctionDescription}


% Parameters.c
\begin{FunctionDescription}{CCTK\_ParameterData}
\label{CCTK-ParameterData}
Get parameter properties for given parameter/thorn pair.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

const cParamData *paramdata = CCTK_ParameterData (const char *name,
                                                  const char *thorn);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{paramdata}
Pointer to parameter data structure
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{name}
Parameter name
\end{Parameter}
\begin{Parameter}{thorn}
Thorn name (for private parameters) or implementation name (for
restricted parameters)
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The thorn or implementation name must be the name of the place where
the parameter is originally defined.  It is not possible to pass the
thorn or implementation name of a thorn that merely declares the
parameter as used.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ParameterGet}{CCTK-ParameterGet}
  Get the data pointer to and type of a parameter's value
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterLevel}{CCTK-ParameterLevel}
  Return the parameter checking level
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterQueryTimesSet}{CCTK-ParameterQueryTimesSet}
  Return number of times a parameter has been set
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterSet}{CCTK-ParameterSet}
  Sets the value of a parameter
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterValString}{CCTK-ParameterValString}
  Get the string representation of a parameter's value
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterWalk}{CCTK-ParameterWalk}
  Walk through list of parameters
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{NULL}
No parameter with that name was found.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


% Parameters.c
%Entering a function description for CCTK\_ParameterGet
\begin{FunctionDescription}{CCTK\_ParameterGet}
\label{CCTK-ParameterGet}
Get the data pointer to and type of a parameter's value.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

const void *paramval = CCTK_ParameterGet (const char *name,
                                          const char *thorn,
                                          int *type);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{paramval}
Pointer to the parameter value
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{name}
Parameter name
\end{Parameter}
\begin{Parameter}{thorn}
Thorn name (for private parameters) or implementation name (for
restricted parameters)
\end{Parameter}
\begin{Parameter}{type}
If not NULL, a pointer to an integer which will hold the type of the
parameter
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The thorn or implementation name must be the name of the place where
the parameter is originally defined.  It is not possible to pass the
thorn or implementation name of a thorn that merely declares the
parameter as used.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ParameterData}{CCTK-ParameterData}
  Get parameter properties for given parameter/thorn pair
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterLevel}{CCTK-ParameterLevel}
  Return the parameter checking level
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterQueryTimesSet}{CCTK-ParameterQueryTimesSet}
  Return number of times a parameter has been set
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterSet}{CCTK-ParameterSet}
  Sets the value of a parameter
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterValString}{CCTK-ParameterValString}
  Get the string representation of a parameter's value
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterWalk}{CCTK-ParameterWalk}
  Walk through list of parameters
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{NULL}
No parameter with that name was found.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


% WaveLevel.c
%Entering a function description for CCTK\_ParameterLevel
\begin{FunctionDescription}{CCTK\_ParameterLevel}
\label{CCTK-ParameterLevel}
Return the parameter checking level.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int level = CCTK_ParameterLevel (void);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{level}
Parameter checking level now being used.
\end{Result}
\end{ResultSection}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ParameterData}{CCTK-ParameterData}
  Get parameter properties for given parameter/thorn pair
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterGet}{CCTK-ParameterGet}
  Get the data pointer to and type of a parameter's value
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterQueryTimesSet}{CCTK-ParameterQueryTimesSet}
  Return number of times a parameter has been set
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterSet}{CCTK-ParameterSet}
  Sets the value of a parameter
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterValString}{CCTK-ParameterValString}
  Get the string representation of a parameter's value
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterWalk}{CCTK-ParameterWalk}
  Walk through list of parameters
\end{SeeAlso2}
\end{SeeAlsoSection}
\end{FunctionDescription}


% Parameters.c
%Entering a function description for CCTK\_ParameterQueryTimesSet
\begin{FunctionDescription}{CCTK\_ParameterQueryTimesSet}
\label{CCTK-ParameterQueryTimesSet}
Return number of times a parameter has been set.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int nset = CCTK_ParameterQueryTimesSet (const char *name,
                                        const char *thorn);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{nset}
Number of times the parameter has been set.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{name}
Parameter name
\end{Parameter}
\begin{Parameter}{thorn}
Thorn name (for private parameters) or implementation name (for
restricted parameters)
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The number of times that a parameter has been set is 0 if the
parameter was not set in a parameter file.  The number increases when
\code{CCTK\_ParameterSet} is called.

The thorn or implementation name must be the name of the place where
the parameter is originally defined.  It is not possible to pass the
thorn or implementation name of a thorn that merely declares the
parameter as used.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ParameterData}{CCTK-ParameterData}
  Get parameter properties for given parameter/thorn pair
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterGet}{CCTK-ParameterGet}
  Get the data pointer to and type of a parameter's value
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterLevel}{CCTK-ParameterLevel}
  Return the parameter checking level
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterSet}{CCTK-ParameterSet}
  Sets the value of a parameter
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterValString}{CCTK-ParameterValString}
  Get the string representation of a parameter's value
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterWalk}{CCTK-ParameterWalk}
  Walk through list of parameters
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{$-1$}
No parameter with that name exists.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


% Parameters.c
%Entering a function description for CCTK\_ParameterSet
\begin{FunctionDescription}{CCTK\_ParameterSet}
\label{CCTK-ParameterSet}
Sets the value of a parameter.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int ierr = CCTK_ParameterSet (const char *name,
                              const char *thorn,
                              const char *value);
\end{verbatim}
\end{Synopsis}

\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_ParameterSet (ierr, name, thorn, value)
CCTK_INT ierr
character*(*) name
character*(*) thorn
character*(*) value
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{ierr}
Error code
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{name}
Parameter name
\end{Parameter}
\begin{Parameter}{thorn}
Thorn name (for private parameters) or implementation name (for restricted parameters)
\end{Parameter}
\begin{Parameter}{value}
The new (stringified) value for the parameter parameter
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The thorn or implementation name must be the name of the place where
the parameter is originally defined.  It is not possible to pass the
thorn or implementation name of a thorn that merely declares the
parameter as used.

While setting a new parameter value is immediately reflected in
Cactus' database, the value of the parameter is not changed
immediately in the routine that sets the new value: It is updated only
the next time a routine is entered (or rather, when the
\code{DECLARE\_CCTK\_PARAMETERS} is encountered the next time). It is
therefore advisable to set the new parameter value in a routine
scheduled at a time earlier to when the new value is required.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ParameterData}{CCTK-ParameterData}
  Get parameter properties for given parameter/thorn pair
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterLevel}{CCTK-ParameterLevel}
  Return the parameter checking level
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterQueryTimesSet}{CCTK-ParameterQueryTimesSet}
  Return number of times a parameter has been set
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterSetNotifyRegister}{CCTK-ParameterSetNotifyRegister}
  Registers a parameter set operation notify callback
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterSetNotifyUnregister}{CCTK-ParameterSetNotifyUnregister}
  Unregisters a parameter set operation notify callback
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterValString}{CCTK-ParameterValString}
  Get the string representation of a parameter's value
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterWalk}{CCTK-ParameterWalk}
  Walk through list of parameters
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{ierr}
\begin{description}
\item[$0$] success
\item[$-1$] parameter is out of range
\item[$-2$] parameter was not found
\item[$-3$] trying to steer a non-steerable parameter
\item[$-6$] not a valid integer or float
\item[$-7$] tried to set an accumulator parameter directly
\item[$-8$] tried to set an accumulator parameter directly
\item[$-9$] final value of accumulator out of range
\end{description}
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


% Parameters.c
%Entering a function description for CCTK\_ParameterSetNotifyRegister
\begin{FunctionDescription}{CCTK\_ParameterSetNotifyRegister}
\label{CCTK-ParameterSetNotifyRegister}
Registers a parameter set operation notify callback

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int handle =
    CCTK_ParameterSetNotifyRegister (cParameterSetNotifyCallbackFn callback,
                                     void *data,
                                     const char *name,
                                     const char *thorn_regex,
                                     const char *param_regex
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_ParameterSetNotifyRegister (handle, callback, data,
.                                     name, thorn_regex, param_regex)
integer       handle
external      callback
integer       callback
CCTK_POINTER  data
character*(*) name
character*(*) thorn_regex
character*(*) param_regex
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0}
success
\end{Result}
\begin{Result}{-1}
another callback has already been registered under the given name
\end{Result}
\begin{Result}{-2}
memory allocation error
\end{Result}
\begin{Result}{-3}
invalid regular expression given for thorn\_regex / param\_regex
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{callback}
Function pointer of the notify callback to be registered
\end{Parameter}
\begin{Parameter}{data}
optional user-defined data pointer to associate with the notify callback
\end{Parameter}
\begin{Parameter}{name}
Unique name under which the notify callback is to be registered
\end{Parameter}
\begin{Parameter}{thorn\_regex}
Optional regular expression string to match a thorn name in a full parameter name
\end{Parameter}
\begin{Parameter}{param\_regex}
Optional regular expression string to match a parameter name in a full parameter name
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Declaring a parameter steerable at runtime in its {\tt param.ccl} definition
requires a thorn writer to add extra logic to the code which checks
if a parameter value has changed, either periodically in a scheduled function,
or by direct notification from the flesh's parameter set routine
{\tt CCTK\_ParameterSet()}.

With {\tt CCTK\_ParameterSetNotifyRegister()} thorns can register a callback
function which in turn is automatically invoked by {\tt CCTK\_ParameterSet()}
whenever a parameter is being steered. 
Each callback function gets passed the triple of thorn name, parameter 
name, and (stringified) new parameter value (as passed to 
{\tt CCTK\_ParameterSet()}), plus an optional callback data pointer defined by 
the user at registration time. When a callback function is registered 
with {\tt CCTK\_ParameterSetNotify()}, the calling routine may also pass an 
optional regular expression string for both a thorn name and a parameter 
name to match against in a parameter set notification; leave them empty 
or pass a NULL pointer to get notified about changes of {\em any} parameter.

Registered notification callbacks would be invoked by 
{\tt CCTK\_ParameterSet()} only {\em after} initial parameter setup from the 
parfile, and -- in case of recovery -- only {\em after} all parameters have 
been restored from the checkpoint file. The callbacks are then invoked 
just {\em before} the parameter is set to its new value so that they can 
still query its old value if necessary.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ParameterSet}{CCTK-ParameterSet}
  Sets the value of a parameter
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterSetNotifyUnregister}{CCTK-ParameterSetNotifyUnregister}
  Unregisters a parameter set operation notify callback
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
#include <stdio.h>

#include "cctk.h"

static void ParameterSetNotify (void *unused,
                                const char *thorn,
                                const char *parameter,
                                const char *new_value)
{
  printf ("parameter set notification: %s::%s is set to '%s'\n",
          thorn, parameter, new_value);
}

void RegisterNotifyCallback (void)
{
  /* we are interested only in this thorn's parameters
     so pass the thorn name in the 'thorn_regex' argument */
  if (CCTK_ParameterSetNotifyRegister (ParameterSetNotify, NULL, CCTK_THORNSTRING,
                                       CCTK_THORNSTRING, NULL))
  {
    CCTK_VWarn (0, __LINE__, __FILE__, CCTK_THORNSTRING,
                "Couldn't register parameter set notify callback");
  }
}
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


% Parameters.c
%Entering a function description for CCTK\_ParameterSetNotifyUnregister
\begin{FunctionDescription}{CCTK\_ParameterSetNotifyUnregister}
\label{CCTK-ParameterSetNotifyUnregister}
Unregisters a parameter set operation notify callback

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int ierr = CCTK_ParameterSetNotifyUnregister (const char *name);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_ParameterSetNotifyUnregister (ierr, name)
integer       ierr
character*(*) name
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0}
success
\end{Result}
\begin{Result}{-1}
no callback was registered under the given name
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{name}
Unique name under which the notify callback was registered
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Notify callbacks should be unregistered when not needed anymore.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ParameterSet}{CCTK-ParameterSet}
  Sets the value of a parameter
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterSetNotifyRegister}{CCTK-ParameterSetNotifyRegister}
  Registers a parameter set operation notify callback
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ExampleSection}
\begin{Example}{Fortran}
\begin{verbatim}
#include "cctk.h"

call CCTK_ParameterSetNotifyUnregister (CCTK_THORNSTRING)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


% Parameters.c
%Entering a function description for CCTK\_ParameterValString
\begin{FunctionDescription}{CCTK\_ParameterValString}
\label{CCTK-ParameterValString}
Get the string representation of a parameter's value.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

char *valstring = CCTK_ParameterValString (const char *name,
                                           const char *thorn);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
subroutine CCTK_ParameterValString (nchars, name, thorn, value)
   integer       nchars
   character*(*) name
   character*(*) thorn
   character*(*) value
end subroutine
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{valstring}
Pointer to parameter value as string.  \emph{The memory for this string
must be released with a call to} \code{free()} \emph{after it has been used.}
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{name}
Parameter name
\end{Parameter}
\begin{Parameter}{thorn}
Thorn name (for private parameters) or implementation name (for
restricted parameters)
\end{Parameter}
\begin{Parameter}{nchars}
On exit, the number of characters in the stringified parameter value,
or $-1$ if the parameter doesn't exist
\end{Parameter}
\begin{Parameter}{value}
On exit, contains as many characters of the stringified parameter value as
fit into the Fortran string provided.
You should check for truncation by comparing \code{nchars} against the length
of your Fortran string.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
In C, the string \code{valstring} must be freed afterwards.

The thorn or implementation name must be the name of the place where
the parameter is originally defined.  It is not possible to pass the
thorn or implementation name of a thorn that merely declares the
parameter as used.

Real variables are formatted according to the C \code{"\%.20g"} format.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ParameterData}{CCTK-ParameterData}
  Get parameter properties for given parameter/thorn pair
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterGet}{CCTK-ParameterGet}
  Get the data pointer to and type of a parameter's value
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterLevel}{CCTK-ParameterLevel}
  Return the parameter checking level
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterQueryTimesSet}{CCTK-ParameterQueryTimesSet}
  Return number of times a parameter has been set
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterSet}{CCTK-ParameterSet}
  Sets the value of a parameter
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterWalk}{CCTK-ParameterWalk}
  Walk through list of parameters
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{NULL}
No parameter with that name was found.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


% Parameters.c
%Entering a function description for CCTK\_ParameterWalk
\begin{FunctionDescription}{CCTK\_ParameterWalk}
\label{CCTK-ParameterWalk}
Walk through the list of parameters.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
%
int istat = CCTK_ParameterWalk (int first,
                                const char *origin,
                                char **fullname,
                                const cParamData **paramdata);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{istat}
Zero for success, positive if parameter was not found, negative if
initial startpoint was not set.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{origin}
Thorn name, or \code{NULL} for all thorns.
\end{Parameter}
\begin{Parameter}{fullname}
Address of a pointer that will point to the full parameter name.  This
name must be freed after use.
\end{Parameter}
\begin{Parameter}{paramdata}
Address of a pointer that will point to the parameter data structure.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Gets parameters in order, restricted to ones from \code{origin}, or
all if \code{origin} is \code{NULL}.  Starts with the first parameter
if \code{first} is true, otherwise gets the next one.  Can be used for
generating full help file, or for walking the list and checkpointing.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ParameterData}{CCTK-ParameterData}
  Get parameter properties for given parameter/thorn pair
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterGet}{CCTK-ParameterGet}
  Get the data pointer to and type of a parameter's value
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterLevel}{CCTK-ParameterLevel}
  Return the parameter checking level
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterQueryTimesSet}{CCTK-ParameterQueryTimesSet}
  Return number of times a parameter has been set
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterSet}{CCTK-ParameterSet}
  Sets the value of a parameter
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ParameterValString}{CCTK-ParameterValString}
  Get the string representation of a parameter's value
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{negative}
The initial startpoint was not set.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


% WarnLevel.c
\begin{FunctionDescription}{CCTK\_PARAMWARN}{Prints a warning from parameter checking, and possibly stops the code}
\label{CCTK-PARAMWARN}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}= CCTK_PARAMWARN( const char * message)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_PARAMWARN( , message )

character*(*) message\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{message}
The warning message
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The call should be used in routines registered at the schedule point \code{CCTK\_PARAMCHECK}
to indicate that there is parameter error or conflict and the code should
terminate. The code will terminate only after all the parameters have been
checked.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
CCTK_PARAMWARN("Mass cannot be negative");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call  CCTK_PARAMWARN("Inside interpolator")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


% util/Misc.c
%Entering a function description for CCTK\_PointerTo
\begin{FunctionDescription}{CCTK\_PointerTo}%%%
\label{CCTK-PointerTo}
Returns a pointer to a Fortran variable.

\begin{SynopsisSection}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"

CCTK_POINTER addr, var

addr = CCTK_PointerTo(var)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{addr}
the address of variable {\it var}
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{var}
variable in the Fortran context from which to take the address
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Fortran doesn't know the concept of pointers so problems arise when a C function
is to be called which expects a pointer as one (or more) of it(s) argument(s).

To obtain the pointer to a variable in Fortran, one can use \code{CCTK\_PointerTo()} which takes the variable itself as a single argument and returns the
pointer to it.

Note that there is only a Fortran wrapper available for \code{CCTK\_PointerTo}.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_NullPointer()}
Returns a C-style NULL pointer value.
\end{SeeAlso}
\end{SeeAlsoSection}

\begin{ExampleSection}
\begin{Example}{Fortran}
\begin{verbatim}
#include "cctk.h"

integer      ierror, table_handle
CCTK_POINTER addr, var

addr = CCTK_PointerTo(var)

call Util_TableCreate(table_handle, 0)
call Util_TableSetPointer(ierror, table_handle, addr, "variable")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


% Groups.c
\begin{FunctionDescription}{CCTK\_PrintGroup}{Prints a group name from its index}
\label{CCTK-PrintGroup}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}= CCTK_PrintGroup( int index)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_PrintGroup( , index )

integer index\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{index}
The group index
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
This routine is for debugging purposes for Fortran programmers.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
CCTK_PrintGroup(1)
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_PRINTGROUP(1)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

% Groups.c
\begin{FunctionDescription}{CCTK\_PrintString}{Prints a Cactus string}
\label{CCTK-PrintString}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}= CCTK_PrintString( char * string)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_PrintString(  , string )

CCTK_STRING string\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{string}
The string to print
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
This routine can be used to print Cactus string variables and parameters
from Fortran.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
CCTK_PrintString(string_param)
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_PRINTSTRING(string_param)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}




% Groups.c
\begin{FunctionDescription}{CCTK\_PrintVar}{Prints a variable name from its index}
\label{CCTK-PrintVar}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}= CCTK_PrintVar( int index)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_PrintVar( , index )

integer index\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{index}
The variable index
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
This routine is for debugging purposes for Fortran programmers.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
CCTK_PrintVar(1)
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_PRINTVAR(1)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}





%%%%%
% QQQ
%%%%%


% cctk_Comm.h
\begin{FunctionDescription}{CCTK\_QueryGroupStorage}{Query storage for a group given by its group name}
\label{CCTK-QueryGroupStorage}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_QueryGroupStorage( const cGH * cctkGH, const char * groupname)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_QueryGroupStorage(istat , cctkGH, groupname )

integer istat
CCTK_POINTER cctkGH
character*(*) groupname\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\begin{Parameter}{groupname}
the group to query, given by its full name
\end{Parameter}
\begin{Parameter}{istat}
the return code
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
This routine queries whether the variables in a group have storage assigned.
If so it returns true (a positive value), otherwise false (zero).
\end{Discussion}
\begin{ErrorSection}
\begin{Error}{negative}
A negative error code is returned for an invalid group name.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


% CommOverloadables.h
\begin{FunctionDescription}{CCTK\_QueryGroupStorageB}{}
\label{CCTK-QueryGroupStorageB}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int storage = CCTK_QueryGroupStorageB( const cGH * cctkGH, int groupindex, const char * groupname)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\begin{Parameter}{groupindex}
the group to query, given by its index
\end{Parameter}
\begin{Parameter}{groupname}
the group to query, given by its full name
\end{Parameter}
\begin{Parameter}{istat}
the return code
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
This routine queries whether the variables in a group have storage assigned.
If so it returns true (a positive value), otherwise false (zero).

The group can be specified either through the group index
\code{groupindex}, or through the group name \code{groupname}.  The groupname
takes precedence; only if it is passed as \code{NULL}, the group index
is used.
\end{Discussion}
\begin{ErrorSection}
\begin{Error}{negative}
A negative error code is returned for an invalid group name.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

% cctk_Comm.h
\begin{FunctionDescription}{CCTK\_QueryGroupStorageI}{Query storage for a group given by its group index}
\label{CCTK-QueryGroupStorageI}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_QueryGroupStorageI( const cGH * cctkGH, int groupindex)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_QueryGroupStorageI(istat , cctkGH, groupindex )

integer istat
cctkGH
integer groupindex\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\begin{Parameter}{groupindex}
the group to query, given by its index
\end{Parameter}
\begin{Parameter}{istat}
the return code
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
This routine queries whether the variables in a group have storage assigned.
If so it returns true (a positive value), otherwise false (zero).
\end{Discussion}
\begin{ErrorSection}
\begin{Error}{negative}
A negative error code is returned for an invalid group name.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}




%%%%%
% RRR
%%%%%

%Entering a function description for CCTK\_ReduceArraysGlobally
\begin{FunctionDescription}{CCTK\_ReduceArraysGlobally}
\label{CCTK-ReduceArraysGlobally}
Performs global reduction on a list of arrays

The computation is optimized for the case of reducing a
number of grid arrays at a time; in this case all the interprocessor
communication can be done together.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int CCTK_ReduceArraysGlobally(const cGH *GH,
                          int dest_proc,
                          int local_reduce_handle,
                          int param_table_handle,
                          int N_input_arrays,
                          const void * const input_arrays[],
                          int input_dims,
                          const CCTK_INT input_array_dims[],
                          const CCTK_INT input_array_type_codes[],
                          int M_output_values,
                          const CCTK_INT output_value_type_codes[],
                          void* const output_values[]);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_ReduceArraysGlobally(status,
.                              GH,
.                              dest_proc,
.                              local_reduce_handle,
.                              param_table_handle,
.                              N_input_arrays,
.                              input_arrays,
.                              input_dims,
.                              input_array_dims,
.                              input_array_type_codes,
.                              M_output_values,
.                              output_value_type_codes,
.                              output_values)
integer               status
CCTK_POINTER_TO_CONST GH
integer               dest_proc,
integer               local_reduce_handle
integer               param_table_handle
integer               N_input_arrays
CCTK_INT              input_arrays(N_input_arrays)
integer               input_dims
CCTK_INT              input_array_dims(input_dims)
CCTK_INT              input_array_type_codes(N_input_arrays)
integer               M_output_values
CCTK_INT              output_value_type_codes(M_output_values)
CCTK_POINTER          output_values(M_output_values)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{< 0} indicates an error condition \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{cctkGH ($\ne$ NULL)}
Pointer to a valid Cactus grid hierarchy.
\end{Parameter}
\begin{Parameter}{dest\_processor}
The destination processor. $-1$ will distribute the result to all processors.
\end{Parameter}
\begin{Parameter}{local\_reduce\_handle ($\ge 0$)}
Handle to the local reduction operator as returned by \newline
\code{CCTK\_LocalArrayReductionHandle()}. It is the caller's responsibility
to ensure that the specified reducer supports any optional
parameter-table entries that \newline \code{CCTK\_ReduceGridArrays()} passes to it.
Each thorn providing a \newline \code{CCTK\_ReduceGridArrays()} reducer should
document what options it requires from the local reducer.
\end{Parameter}
\begin{Parameter}{param\_table\_handle ($\ge 0$)}
Handle to a key-value table containing zero or more additional parameters
for the reduction operation. The table can be modified by the local
and/or global reduction routine(s).

Also, the global reducer will typically need to specify some options
of its own for the local reducer.  These will override any entries
with the same keys in the  param\_table\_handle  table.  The discussion
of individual table entries below says if these are modified in this
manner.

Finally, the  param\_table\_handle  table can be used to pass back arbitrary
information by the local and/or global reduction routine(s) by
adding/modifying appropriate key/value pairs.
\end{Parameter}
\begin{Parameter}{N\_input\_arrays ($\ge 0$)}
The number of input arrays to be reduced.  If  N\_input\_arrays is zero,
then no reduction is done; such a call may be useful for setup,
reducer querying, etc.  If the  operand\_indices  parameter table
entry is used to specify a nontrivial (eg 1-to-many) mapping of input
arrays to output values, only the unique set of input arrays should
be given here.
\end{Parameter}
\begin{Parameter}{input\_arrays}
(Pointer to) an array of  \code{N\_input\_arrays}  local arrays specifying the input arrays
for the reduction.
\end{Parameter}
\begin{Parameter}{input\_dims ($\ge 0$)}
The number of dimensions of the input arrays
\end{Parameter}
\begin{Parameter}{input\_array\_dims ($\ge 0$)}
(Pointer to) an array  of size \code{input\_dims} containing the dimensions of the arrays to be reduced.
\end{Parameter}
\begin{Parameter}{input\_array\_type\_codes ($\ge 0$)}
(Pointer to) an array  of \code{input\_dims} \code{CCTK\_VARIABLE\_*}  type
codes giving the data types of the arrays to be reduced.
\end{Parameter}
\begin{Parameter}{M\_output\_values ($\ge 0$)}
The number of output values to be returned from the reduction.
If \code{N\_input\_arrays == 0}  then no reduction is done; such a call
may be useful for setup, reducer querying, etc.  Note that
\code{M\_output\_values}  may differ from  \code{N\_input\_arrays} , eg if the
\code{operand\_indices}  parameter table entry is used to specify a
nontrivial (eg many-to-1) mapping of input arrays to output values,
If such a mapping is specified, only the unique set of output values
should be given here.
\end{Parameter}
\begin{Parameter}{output\_value\_type\_codes}
(Pointer to) an array of  \code{M\_output\_values} \code{CCTK\_VARIABLE\_*}  type
codes giving the data types of the output values pointed to by
\code{output\_values[]}.
\end{Parameter}
\begin{Parameter}{output\_values}
(Pointer to) an array of  \code{M\_output\_values}  pointers to the
(caller-supplied) output values for the reduction.
If \code{output\_values[out]}  is \code{NULL} for some index or indices  \code{out} ,
then that reduction is skipped.  (This may be useful if the main
purpose of the call is (eg) to do some query or setup computation.)
These pointers may (and typically will) vary from processor to
processor in a multiprocessor Cactus run.  However, any given pointer
must be either \code{NULL} on all processors, or non-\code{NULL} on all processors.
\end{Parameter}
\end{ParameterSection}4

\begin{Discussion}
This function reduces a list of CCTK local arrays globally. This function does not perform the actual reduction, it only handles interprocessor communication. The actual reduction is performed by the local reduction implementation, that is passed arguments and parameters
from the grid array reduction implementation.

Note that \code{CCTK\_ReduceArraysGlobally} is a collective operation, so in the
multiprocessor case you {\em must\/} call this function in parallel on
{\em each\/} processor, passing identical arguments.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_LocalArrayReductionHandle()}
Returns the handle of a given local array reduction operator
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_RegisterGridArrayReductionOperator()}
Registers a function as a grid array reduction operator of a certain name
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_GridArrayReductionOperator()}
The name of the grid reduction operator, or NULL if the handle is invalid
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_GridArrayReductionOperator()}
The number of grid array reduction operators registered
\end{SeeAlso}
\end{SeeAlsoSection}

\begin{ExampleSection}
\begin{ExampleDescription}
Here's a simple example to perform grid array reduction of two grids arrays of different types.
\end{ExampleDescription}
\begin{Example}{C}
\begin{verbatim}

#include "cctk.h"
#include "util_Table.h"

#define N_INPUT_ARRAYS  2
#define M_OUTPUT_VALUES 2
const cGH *GH;                                                  /* input */

/* create empty parameter table */
const int param_table_handle = Util_CreateTable(UTIL_TABLE_FLAGS_CASE_INSENSITIVE);
/* input arrays and output values */
const CCTK_INT input_array_variable_indices[N_INPUT_ARRAYS]
        = { CCTK_VarIndex("my_thorn::real_array"),      /* no error checking */
            CCTK_VarIndex("my_thorn::complex_array") }; /* here  */
const CCTK_INT output_value_type_codes[M_OUTPUT_VALUES]
        = { CCTK_VARIABLE_REAL, CCTK_VARIABLE_COMPLEX };
void *const output_numbers[M_OUTPUT_values]
        = { (void *) output_for_real_values,
            (void *) output_for_complex_values };

const int status
  = CCTK_ReduceGridArrays(GH,
                          0,
                          param_table_handle,
                          N_INPUT_ARRAYS, input_array_variable_indices,
                          M_OUTPUT_VALUES, output_value_type_codes,
                                           output_values);

Util_TableDestroy(param_table_handle);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


% CCTK\_Reduce here
%Reduction.c

% CCTK\_Reduce1 here
%Reduction.c

%Entering a function description for CCTK\_ReduceGridArrays
\begin{FunctionDescription}{CCTK\_ReduceGridArrays}
\label{CCTK-ReduceGridArrays}
Performs reduction on a list of distributed grid arrays

The computation is optimized for the case of reducing a
number of grid arrays at a time; in this case all the interprocessor
communication can be done together.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_ReduceGridArrays(const cGH *GH,
                          int dest_processor,
                          int local_reduce_handle,
                          int param_table_handle,
                          int N_input_arrays,
                          const CCTK_INT input_array_variable_indices[],
                          int M_output_values,
                          const CCTK_INT output_value_type_codes[],
                          void* const output_values[]);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_ReduceGridArrays(status,
.                          GH,
.                          dest_processor,
.                          local_reduce_handle,
.                          param_table_handle,
.                          N_input_arrays,
.                          input_array_variable_indices,
.                          M_output_values,
.                          output_value_type_codes,
.                          output_values)
integer                  status
CCTK_POINTER_TO_CONST    GH
integer                  dest_processor
integer                  local_reduce_handle
integer                  param_table_handle
integer                  N_input_arrays
CCTK_INT                 input_array_variable_indices(N_input_arrays)
integer                  M_output_values
CCTK_INT                 output_value_type_codes(M_output_values)
CCTK_POINTER             output_values(M_output_values)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{< 0} indicates an error condition \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{cctkGH ($\ne$ NULL)}
Pointer to a valid Cactus grid hierarchy.
\end{Parameter}
\begin{Parameter}{dest\_processor}
The destination processor. $-1$ will distribute the result to all processors.
\end{Parameter}
\begin{Parameter}{local\_reduce\_handle ($\ge 0$)}
Handle to the local reduction operator as returned by \newline
\code{CCTK\_LocalArrayReductionHandle()}. It is the caller's responsibility
to ensure that the specified reducer supports any optional
parameter-table entries that \newline \code{CCTK\_ReduceGridArrays()} passes to it.
Each thorn providing a \newline \code{CCTK\_ReduceGridArrays()} reducer should
document what options it requires from the local reducer.
\end{Parameter}
\begin{Parameter}{param\_table\_handle ($\ge 0$)}
Handle to a key-value table containing zero or more additional parameters
for the reduction operation. The table can be modified by the local
and/or global reduction routine(s).

Also, the global reducer will typically need to specify some options
of its own for the local reducer.  These will override any entries
with the same keys in the  param\_table\_handle  table.  The discussion
of individual table entries below says if these are modified in this
manner.

Finally, the  param\_table\_handle  table can be used to pass back arbitrary
information by the local and/or global reduction routine(s) by
adding/modifying appropriate key/value pairs.
\end{Parameter}
\begin{Parameter}{N\_input\_arrays ($\ge 0$)}
The number of input arrays to be reduced.  If  N\_input\_arrays is zero,
then no reduction is done; such a call may be useful for setup,
reducer querying, etc.  If the  operand\_indices  parameter table
entry is used to specify a nontrivial (eg 1-to-many) mapping of input
arrays to output values, only the unique set of input arrays should
be given here.
\end{Parameter}
\begin{Parameter}{input\_array\_variable\_indices}
(Pointer to) an array of  \code{N\_input\_arrays}  Cactus variable indices
(as returned by  \code{CCTK\_VarIndex()} ) specifying the input grid arrays
for the reduction.  If  \newline \code{input\_array\_variable\_indices[in] == -1}
for some index or indices  \code{in} , then that reduction is skipped.
(This may be useful if the main purpose of the call is (eg) to do
some query or setup computation.)
\end{Parameter}
\begin{Parameter}{M\_output\_values ($\ge 0$)}
The number of output values to be returned from the reduction.
If \code{N\_input\_arrays == 0}  then no reduction is done; such a call
may be useful for setup, reducer querying, etc.  Note that
\code{M\_output\_values}  may differ from  \code{N\_input\_arrays} , eg if the
\code{operand\_indices}  parameter table entry is used to specify a
nontrivial (eg many-to-1) mapping of input arrays to output values,
If such a mapping is specified, only the unique set of output values
should be given here.
\end{Parameter}
\begin{Parameter}{output\_value\_type\_codes}
(Pointer to) an array of  \code{M\_output\_values} \code{CCTK\_VARIABLE\_*}  type
codes giving the data types of the output values pointed to by
\code{output\_values[]}.
\end{Parameter}
\begin{Parameter}{output\_values}
(Pointer to) an array of  \code{M\_output\_values}  pointers to the
(caller-supplied) output values for the reduction.
If \code{output\_values[out]}  is \code{NULL} for some index or indices  \code{out} ,
then that reduction is skipped.  (This may be useful if the main
purpose of the call is (eg) to do some query or setup computation.)
These pointers may (and typically will) vary from processor to
processor in a multiprocessor Cactus run.  However, any given pointer
must be either \code{NULL} on all processors, or non-\code{NULL} on all processors.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This function reduces a list of CCTK grid arrays (in a multiprocessor run
these are generally distributed over processors). This function does not perform the actual reduction, it only handles interprocessor communication. The actual reduction is performed by the local reduction implementation, that is passed arguments and parameters
from the grid array reduction implementation.

Note that \code{CCTK\_ReduceGridArrays} is a collective operation, so in the
multiprocessor case you {\em must\/} call this function in parallel on
{\em each\/} processor, passing identical arguments.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_LocalArrayReductionHandle()}
Returns the handle of a given local array reduction operator
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_RegisterGridArrayReductionOperator()}
Registers a function as a grid array reduction operator of a certain name
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_GridArrayReductionOperator()}
The name of the grid reduction operator, or NULL if the handle is invalid
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_GridArrayReductionOperator()}
The number of grid array reduction operators registered
\end{SeeAlso}
\end{SeeAlsoSection}

\begin{ExampleSection}
\begin{ExampleDescription}
Here's a simple example to perform grid array reduction of two grids arrays of different types.
\end{ExampleDescription}
\begin{Example}{C}
\begin{verbatim}

#include "cctk.h"
#include "util_Table.h"

#define N_INPUT_ARRAYS  2
#define M_OUTPUT_VALUES 2
const cGH *GH;                                                  /* input */

/* create empty parameter table */
const int param_table_handle = Util_CreateTable(UTIL_TABLE_FLAGS_CASE_INSENSITIVE);
/* input arrays and output values */
const CCTK_INT input_array_variable_indices[N_INPUT_ARRAYS]
        = { CCTK_VarIndex("my_thorn::real_array"),      /* no error checking */
            CCTK_VarIndex("my_thorn::complex_array") }; /* here  */
const CCTK_INT output_value_type_codes[M_OUTPUT_VALUES]
        = { CCTK_VARIABLE_REAL, CCTK_VARIABLE_COMPLEX };
void *const output_numbers[M_OUTPUT_values]
        = { (void *) output_for_real_values,
            (void *) output_for_complex_values };

const int status
  = CCTK_ReduceGridArrays(GH,
                          0,
                          param_table_handle,
                          N_INPUT_ARRAYS, input_array_variable_indices,
                          M_OUTPUT_VALUES, output_value_type_codes,
                                           output_values);

Util_TableDestroy(param_table_handle);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%Reduction.c
%Entering a function description for CCTK\_ReduceLocalArrays
\begin{FunctionDescription}{CCTK\_ReduceLocalArrays}
\label{CCTK-ReduceLocalArrays}
Performs reduction on a list of local grid arrays

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_ReduceLocalArrays(int N_dims, int operator_handle,
                          int param_table_handle,   int N_input_arrays,
                          const CCTK_INT input_array_dims[],
                          const CCTK_INT input_array_type_codes[],
                          const void *const input_arrays[],
                          int M_output_numbers,
                          const CCTK_INT output_number_type_codes[],
                          void *const output_values[]);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_ReduceLocalArrays(status,
.                          N_dims, operator_handle,
.                          param_table_handle, N_input_arrays,
.                          input_array_dims,
.                          input_array_type_codes,
.                          input_arrays,
.                          M_output_numbers,
.                          output_number_type_codes,
.                          output_values)
integer                  status
integer                  N_dims
integer                  operator_handle
integer                  param_table_handle
integer                  N_input_arrays
CCTK_INT                 input_array_dims(N_dims)
CCTK_INT                 input_array_type_codes(N_input_arrays)
CCTK_POINTER             input_arrays(N_input_arrays)
integer                  M_output_values
CCTK_INT                 output_value_type_codes(M_output_values)
CCTK_POINTER             output_values(M_output_values)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{< 0} indicates an error condition \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{N\_dims}
Number of dimensions of input arrays. This is required to find proper indices
for arrays in memory
\end{Parameter}
\begin{Parameter}{operator\_handle}
Handle to the local reduction operator as returned by \newline
\code{CCTK\_LocalArrayReductionHandle()}.
\end{Parameter}
\begin{Parameter}{param\_table\_handle}
Handle to a key-value table containing zero or more additional parameters
for the reduction operation. The table can be modified by the local
and/or global reduction routine(s).

The parameter table may be used to specify non-default storage indexing
for input or output arrays, and/or various options for the reduction
itself.  Some reducers may not implement all of these options.
\begin{Parameter}{N\_input\_arrays ($\ge 0$)}
The number of input arrays to be reduced.  If  \code{N\_input\_arrays} is zero,
then no reduction is done; such a call may be useful for setup,
reducer querying, etc.  If the  operand\_indices  parameter table
entry is used to specify a nontrivial (eg 1-to-many) mapping of input
arrays to output values, only the unique set of input arrays should
be given here.
\end{Parameter}
\begin{Parameter}{input\_array\_dims}
array of input array dimensions (common to all input arrays) and of size \code{N\_dims}
\end{Parameter}
\end{Parameter}
\begin{Parameter}{input\_array\_type\_codes}
array of input array dimensions (common to all input arrays) and of size \code{N\_input\_arrays}
\end{Parameter}
\begin{Parameter}{M\_output\_values ($\ge 0$)}
The number of output values to be returned from the reduction.
If \code{N\_input\_arrays == 0}  then no reduction is done; such a call
may be useful for setup, reducer querying, etc.  Note that
\code{M\_output\_values}  may differ from  \code{N\_input\_arrays} , eg if the
\code{operand\_indices}  parameter table entry is used to specify a
nontrivial (eg many-to-1) mapping of input arrays to output values,
If such a mapping is specified, only the unique set of output values
should be given here.
\end{Parameter}
\begin{Parameter}{output\_value\_type\_codes}
(Pointer to) an array of  \code{M\_output\_values} \code{CCTK\_VARIABLE\_*}  type
codes giving the data types of the output values pointed to by
\code{output\_values[]}.
\end{Parameter}
\begin{Parameter}{output\_values}
(Pointer to) an array of  \code{M\_output\_values}  pointers to the
(caller-supplied) output values for the reduction.
If \code{output\_values[out]}  is \code{NULL} for some index or indices  \code{out} ,
then that reduction is skipped.  (This may be useful if the main
purpose of the call is (eg) to do some query or setup computation.)
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Sometimes one of the arrays used by the reduction isn't contiguous
in memory. So, we use several optional table entries
(these should be supported by all reduction operators):

For the input arrays, we use
\begin{verbatim}
  const CCTK_INT input_array_offsets[N_input_arrays];
  /* next 3 table entries are shared by all input arrays */
  const CCTK_INT input_array_strides       [N_dims];
  const CCTK_INT input_array_min_subscripts[N_dims];
  const CCTK_INT input_array_max_subscripts[N_dims];
\end{verbatim}

Then for input array number a, the generic subscripting expression for
the 3-D case is
\begin{verbatim}
  data_pointer[offset + i*istride + j*jstride + k*kstride]
\end{verbatim}
where
\begin{verbatim}
  data_pointer = input_arrays[a]
  offset = input_array_offsets[a]
  (istride,jstride,kstride) = input_array_stride[]
\end{verbatim}
and where \code{(i,j,k)} run from \code{input\_array\_min\_subscripts[]} to
\code{input\_array\_max\_subscripts[]} inclusive.

The defaults are \code{offset=0}, \code{stride=}determined from
\code{input\_array\_dims[]} in the usual Fortran manner,
\code{input\_array\_min\_subscripts[] = 0},
\code{input\_array\_max\_subscripts[] = input\_array\_dims[]-1}.
 If the stride and max subscript are both specified explicitly, then the
\code{input\_array\_dims[]} function argument is ignored.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_LocalArrayReductionHandle()}
Returns the handle of a given local array reduction operator
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_RegisterLocalArrayReductionOperator()}
Registers a function as a reduction operator of a certain name
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_LocalArrayReduceOperatorImplementation()}
Provide the implementation which provides an local array reduction operator
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_LocalArrayReduceOperator()}
Returns the name of a registered reduction operator
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_NumLocalArrayReduceOperators()}
The number of local reduction operators registered
\end{SeeAlso}
\end{SeeAlsoSection}

\begin{ExampleSection}
\begin{ExampleDescription}
Here's a simple example, written in Fortran 77, to do reduction
of a real and a complex local array in 3-D:
\end{ExampleDescription}
\begin{Example}{Fortran 77}
\begin{verbatim}

c input arrays:
        integer ni, nj, nk
        parameter (ni=..., nj=..., nk=...)
        CCTK_REAL    real_array   (ni,nj,nk)
        CCTK_COMPLEX complex_array(ni,nj,nk)

c output numbers:
        CCTK_REAL    My_real   (M_reduce)
        CCTK_COMPLEX My_complex(M_reduce)

        integer status, dummy
        CCTK_INT input_array_type_codes(2)
        data input_array_type_codes /CCTK_VARIABLE_REAL,
     $                               CCTK_VARIABLE_COMPLEX/
        CCTK_INT input_array_dims(3)
        CCTK_POINTER input_arrays(2)
        CCTK_POINTER output_numbers(2)

        input_array_dims(1) = ni
        input_array_dims(2) = nj
        input_array_dims(3) = nk
        output_numbers(1) = Util_PointerTo(My_real)
        output_numbers(2) = Util_PointerTo(My_complex)

        call CCTK_ReduceLocalArrays
     $          (status,                ! return code
                 3,                     ! number of dimensions
                 operator_handle,
                 N_reduce,
                 2,                     ! number of input arrays
                 input_array_type_codes, input_array_dims, input_arrays,
                 2,                     ! number of output numbers
                 output_numbers_type_codes, output_numbers)

        if (status .lt. 0) then
                call CCTK_WARN(CCTK_WARN_ABORT, "Error return from reducer!")
        end if

\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}



\begin{FunctionDescription}{CCTK\_ReductionHandle}{Handle for given reduction method}
\label{CCTK-ReductionHandle}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int handle = CCTK_ReductionHandle( const char * reduction)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}handle = CCTK_ReductionHandle(  reduction )

integer handle
character*(*) reduction\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{handle}
handle returned for this method
\end{Parameter}
\begin{Parameter}{name}
name of the reduction method required
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
Reduction methods should be registered at \code{CCTK\_STARTUP}. Note that
integer reduction handles are used to call \code{CCTK\_Reduce} to avoid
problems with passing Fortran strings. Note that the name of the reduction
operator is case dependent.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
handle = CCTK_ReductionHandle("maximum");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_ReductionHandle(handle,"maximum")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

% Misc.c
\begin{FunctionDescription}{CCTK\_RegexMatch}{Perform a regular expression match of string against pattern}
\label{CCTK-RegexMatch}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}success = CCTK_RegexMatch( const char *string, const char *pattern,
                          const int nmatch, regmatch_t *pmatch)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{string}
String to match against
\end{Parameter}
\begin{Parameter}{pattern}
Regex pattern
\end{Parameter}
\begin{Parameter}{nmatch}
The size of the pmatch array
\end{Parameter}
\begin{Parameter}{pmatch}
Array in which to place the matches
\end{Parameter}
\end{ParameterSection}
\begin{ResultSection}
\begin{Result}{0} pattern does not match\end{Result}
\begin{Result}{1} pattern matches\end{Result}
\begin{Result}{< 0} indicates an error condition (pattern did not compile as a
    regular expression) \end{Result}
\end{ResultSection}
\begin{Discussion}
Perform a regular expression match of string against pattern.
Also returns the specified number of matched substrings as
give by regexec.
This is a modified form of the example routine given in the SGI
man page for regcomp.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
#define R_BEGIN "(\\[|\\()?"
#define R_VALUE "([^]):]*)"
#define R_SEP   ":"
#define R_END   "(\\]|\\))?"
#define R_MAYBE(x) "(" x ")?"

  int matched;
  const char pattern[] =
    R_BEGIN
    R_VALUE
    R_MAYBE(R_SEP R_VALUE R_MAYBE(R_SEP R_VALUE))
    R_END;

  if( (matched = CCTK_RegexMatch(range, pattern, 8, pmatch)) > 0) {
      CCTK_VInfo(CCTK_THORNSTRING, "'%s' is a valid range specifier",
                 range);
  } else if(!matched) {
      CCTK_VInfo(CCTK_THORNSTRING, "'%s' is not a valid range specifier",
                 range);
  } else {
      CCTK_VInfo(CCTK_THORNSTRING, "invalid pattern '%s'", pattern);
  }
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

% Coord.c
\begin{FunctionDescription}{CCTK\_RegisterBanner}{Register a banner for a thorn}
\label{CCTK-RegisterBanner}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}void = CCTK_RegisterBanner( const char * message)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_RegisterBanner(  , message )

character*(*) message\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{message}
String which will be displayed as a banner
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The banner must be registered during \code{CCTK\_STARTUP}. The banners are
displayed in the order in which they are registered.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
CCTK_RegisterBanner("My Thorn: Does Something Useful");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_REGISTERBANNER("*** MY THORN ***")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

% cctk_GHExtensions.h
\begin{FunctionDescription}{CCTK\_RegisterGHExtension}{Register an extension to the CactusGH}
\label{CCTK-RegisterGHExtension}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_RegisterGHExtension( const char * name)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\end{FunctionDescription}

% cctk_GHExtensions.h
\begin{FunctionDescription}{CCTK\_RegisterGHExtensionInitGH}{Register a function which will initialise a given extension to the Cactus GH}
\label{CCTK-RegisterGHExtensionInitGH}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_RegisterGHExtensionInitGH(  int handle, void * (*func)(cGH *))\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\end{FunctionDescription}

% cctk_GHExtensions.h
\begin{FunctionDescription}{CCTK\_RegisterGHExtensionScheduleTraverseGH}{Register a GH extension schedule traversal routine}
\label{CCTK-RegisterGHExtensionScheduleTraverseGH}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_RegisterGHExtensionScheduleTraverseGH( int handle, int (*func)(cGH *,const char *))\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\end{FunctionDescription}

% cctk_GHExtensions.h
\begin{FunctionDescription}{CCTK\_RegisterGHExtensionSetupGH}{Register a function which will set up a given extension to the Cactus GH}
\label{CCTK-RegisterGHExtensionSetupGH}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_RegisterGHExtensionSetupGH(  int handle, void * (*func)(tFleshConfig *, int, cGH *))\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\end{FunctionDescription}

%Reduction.c
%Entering a function description for CCTK\_RegisterGridArrayReductionOperator
\begin{FunctionDescription}{CCTK\_RegisterGridArrayReductionOperator}
\label{CCTK-RegisterGridArrayReductionOperator}
Registers a function as a grid array reduction operator of a certain name

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int status = CCTK_RegisterGridArrayReductionOperator(
                  cGridArrayReduceOperator operator)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} success \end{Result}
\begin{Result}{< 0} indicates an error condition \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{operator}
The function to register as a global reduction function.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This function simply registers a function as the grid array reduction. Currently
we support a single function as a global reduction function (this can be
modified to accomodate more functions if need be).
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_ReduceGridArrays()}
Performs reduction on a list of distributed grid arrays
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_GridArrayReductionOperator()}
The name of the grid reduction operator, or NULL if none is registered
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_NumGridArrayReductionOperators()}
The number of grid array reduction operators registered
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_RegisterIOMethod}{Register a new I/O method}
\label{CCTK-RegisterIOMethod}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int handle = CCTK_RegisterIOMethod( const char * name)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}handle = CCTK_RegisterIOMethod( name )

integer handle
name\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{handle}
handle returned by registration
\end{Parameter}
\begin{Parameter}{name}
name of the I/O method
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
IO methods should be registered at \code{CCTK\_STARTUP}.
\end{Discussion}
\end{FunctionDescription}


% cctk_IOMethods.h
\begin{FunctionDescription}{CCTK\_RegisterIOMethodOutputGH}{Register a routine for an I/O method which will be called from \code{CCTK\_OutputGH}.}
\label{CCTK-RegisterIOMethodOutputGH}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_RegisterIOMethodOutputGH(  int handle, int (* func)(const cGH *))\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\end{FunctionDescription}


% cctk_IOMethods.h
\begin{FunctionDescription}{CCTK\_RegisterIOMethodOutputVarAs}{Register a routine for an I/O method which will provide aliased variable output}
\label{CCTK-RegisterIOMethodOutputVarAs}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_RegisterIOMethodOutputVarAs(  int handle, int (* func)(const cGH *,const char*, const char *))\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\end{FunctionDescription}


% cctk_IOMethods.h
\begin{FunctionDescription}{CCTK\_RegisterIOMethodTimeToOutput}{Register a routine for an I/O method which will decide if it is time for the method to output.}
\label{CCTK-RegisterIOMethodTimeToOutput}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_RegisterIOMethodTimeToOutput(  int handle, int (* func)(const cGH *,int))\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\end{FunctionDescription}

% cctk_IOMethods.h
\begin{FunctionDescription}{CCTK\_RegisterIOMethodTriggerOutput}{Register a routine for an I/O method which will handle trigger output}
\label{CCTK-RegisterIOMethodTriggerOutput}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int istat = CCTK_RegisterIOMethodTriggerOutput(  int handle, int (* func)(const cGH *,int))\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\end{FunctionDescription}

%Reduction.c
%Entering a function description for CCTK\_RegisterLocalArrayReductionOperator
\begin{FunctionDescription}{CCTK\_RegisterLocalArrayReductionOperator}
\label{CCTK-RegisterLocalArrayReductionOperator}
Registers a function as a reduction operator of a certain name

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int handle = CCTK_RegisterLocalArrayReductionOperator(
                cLocalArrayReduceOperator operator, const char *name);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{handle}
The handle corresponding to the registered local reduction operator, \code{-1}
if an error occured.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{operator}
The function to be registered as a local reduction operator
\end{Parameter}
\begin{Parameter}{name}
The name under which the operator is registered as a local reduction operator
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This function registers a local array reduction operator. It registers an \code{operator}
under a \code{name} with the flesh and returns its assigned handle. If another reduction
operator exists with the same \code{name}, an error is returned.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_ReduceLocalArrays()}
Reduces a list of local arrays (new local array reduction API)
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_LocalArrayReductionHandle()}
Returns the handle of a given local array reduction operator
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_LocalArrayReduceOperatorImplementation()}
Provide the implementation which provides an local array reduction operator
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_LocalArrayReduceOperator()}
Returns the name of a registered reduction operator
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_NumLocalArrayReduceOperators()}
The number of local reduction operators registered
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}

%Entering a function description for CCTK\_RegisterReduceArraysGloballyOperator
\begin{FunctionDescription}{CCTK\_RegisterReduceArraysGloballyOperator}
\label{CCTK-RegisterReduceArraysGloballyOperator}
Registers a function as a reduction operator of a certain name

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int handle = CCTK_RegisterReduceArraysGloballyOperator(
                cReduceArraysGloballyOperator operator, const char *name);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{handle}
The handle corresponding to the registered global array reduction operator, \code{-1}
if an error occured.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{operator}
The function to be registered as a global array reduction operator
\end{Parameter}
\begin{Parameter}{name}
The name under which the operator is registered as a global array reduction operator
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This function registers a global array reduction operator. It registers an \code{operator}
under a \code{name} with the flesh and returns its assigned handle. If another reduction
operator exists with the same \code{name}, an error is returned.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_ReduceArraysGlobally()}
Reduces a list of local arrays globally
\end{SeeAlso}
\end{SeeAlsoSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_RegisterReductionOperator}{}
\label{CCTK-RegisterReductionOperator}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}CCTK_RegisterReductionOperator()\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\end{FunctionDescription}


%%%%%
% SSS
%%%%%



% ScheduleInterface.c
\begin{FunctionDescription}{CCTK\_SchedulePrintTimes}
  \label{CCTK-SchedulePrintTimes}
  Output the timing results for a certain schedule item to stdout
  
  \begin{SynopsisSection}
    \begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int status = CCTK_SchedulePrintTimes(const char *where)
\end{verbatim}
    \end{Synopsis}
  \end{SynopsisSection}
  
  \begin{ResultSection}
    \begin{ResultNote}
      Return code of \texttt{DoScheduleTraverse}, or
    \end{ResultNote}
    \begin{Result}{0}
      Success.
    \end{Result}
  \end{ResultSection}
  
  \begin{ParameterSection}
    \begin{Parameter}{where}
      Name of schedule item, or \texttt{NULL} to print the whole
      schedule
    \end{Parameter}
  \end{ParameterSection}
  
  \begin{Discussion}
    Output the timing results for a certain schedule item to stdout.
    The schedule item is traversed recursively if it is a schedule
    group or a schedule bin.
    
    This routine is used to produce the timing output when the
    parameter \texttt{Cactus::cctk\_timer\_output} is set to
    \texttt{yes}.
  \end{Discussion}
  
  \begin{SeeAlsoSection}
    \begin{SeeAlso}{CCTK\_SchedulePrintTimesToFile}
      Output the timing results for a certain schedule item to a file
    \end{SeeAlso}
  \end{SeeAlsoSection}
  
  \begin{ExampleSection}
    \begin{Example}{C}
      Output the timer results for the Analysis bin:
\begin{verbatim}
#include "cctk.h"
int status = CCTK_SchedulePrintTimes("CCTK_ANALYSIS")
\end{verbatim}
\end{Example}
  \end{ExampleSection}
  
\end{FunctionDescription}



% ScheduleInterface.c
\begin{FunctionDescription}{CCTK\_SchedulePrintTimesToFile}
  \label{CCTK-SchedulePrintTimesToFile}
  Output the timing results for a certain schedule item to stdout
  
  \begin{SynopsisSection}
    \begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int status = CCTK_SchedulePrintTimesToFile(const char *where)
\end{verbatim}
    \end{Synopsis}
  \end{SynopsisSection}
  
  \begin{ResultSection}
    \begin{ResultNote}
      Return code of \texttt{DoScheduleTraverse}, or
    \end{ResultNote}
    \begin{Result}{0}
      Success.
    \end{Result}
  \end{ResultSection}
  
  \begin{ParameterSection}
    \begin{Parameter}{where}
      Name of schedule item, or \texttt{NULL} to print the whole
      schedule
    \end{Parameter}
    \begin{Parameter}{file}
      File to which the results are output; the file must be open for
      writing
    \end{Parameter}
  \end{ParameterSection}
  
  \begin{Discussion}
    Output the timing results for a certain schedule item to a file.
    The schedule item is traversed recursively if it is a schedule
    group or a schedule bin.
    
    Note that each processor will output its results.  You should
    either call this routine on only a single processor, or you should
    pass different files on different processors.
  \end{Discussion}
  
  \begin{SeeAlsoSection}
    \begin{SeeAlso}{CCTK\_SchedulePrintTimes}
      Output the timing results for a certain schedule item to stdout
    \end{SeeAlso}
  \end{SeeAlsoSection}

  \begin{ExampleSection}
    \begin{Example}{C}
      Output the timer results of processor 3 for the Analysis bin to
      a file:
\begin{verbatim}
#include <stdio.h>
#include "cctk.h"
if (CCTK_MyProc(cctkGH)==3)
{
  FILE *file = fopen("timing-results.txt", "a");
  int status = CCTK_SchedulePrintTimesToFile("CCTK_ANALYSIS", file)
  fclose(file);
}
\end{verbatim}
\end{Example}
  \end{ExampleSection}
  
\end{FunctionDescription}



% ScheduleInterface.c
\begin{FunctionDescription}{CCTK\_ScheduleQueryCurrentFunction}
  \label{CCTK-ScheduleQueryCurrentFunction}
   Return the cFunctionData of the function currently executing via
   \texttt{CCTK\_CallFunction}.
  
  \begin{SynopsisSection}
    \begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
const cFunctionData *CCTK_ScheduleQueryCurrentFunction(const cGH *GH)
\end{verbatim}
    \end{Synopsis}
  \end{SynopsisSection}
  
  \begin{ResultSection}
    \begin{ResultNote}
      Data of last call to \texttt{CCTK\_CallFunction}, or
    \end{ResultNote}
    \begin{Result}{NULL}
      if not within a scheduled function.
    \end{Result}
  \end{ResultSection}
  
  \begin{ParameterSection}
    \begin{Parameter}{cctkGH}
      Pointer to a Cactus grid hierarchy.
    \end{Parameter}
  \end{ParameterSection}
  
  \begin{Discussion}
    Returns a data structure containing the thorn and routine name of the
    currently executing function as well as the Cactus bin name. If no
    function is currently executing, returns \code{NULL}. This is intended to
    be used by thorns providing callable functions to identify their caller
    when reporting errors.
  \end{Discussion}
  
  \begin{SeeAlsoSection}
    \begin{SeeAlso}{CCTK\_CallFunction}
      Calls a function depending upon the data passed in the the fdata
      structure.
    \end{SeeAlso}
  \end{SeeAlsoSection}

  \begin{ExampleSection}
    \begin{Example}{C}
      Output the name of the currently scheduled function:
\begin{verbatim}
#include <stdio.h>
#include "cctk.h"
const cFunctionData *fdata = CCTK_ScheduleQueryCurrentFunction(cctkGH);
printf("scheduled function: %s::%s AT %s\n",
       fdata->thorn, fdata->routine, fdata->where);
\end{verbatim}
\end{Example}
  \end{ExampleSection}
  
\end{FunctionDescription}




% CommOverloadables.c
\begin{FunctionDescription}{CCTK\_SetupGH}{Setup a new GH}
\label{CCTK-SetupGH}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}cGH * cctkGH = CCTK_SetupGH( tFleshConfig config, int convlevel)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\end{FunctionDescription}




% CactusSync.c
\begin{FunctionDescription}{CCTK\_SyncGroup}
\label{CCTK-SyncGroup}
Synchronise the ghostzones for a group of grid variables
(identified by the group name)

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int status = CCTK_SyncGroup(const cGH* GH, const char* group_name)
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"
integer status
CCTK_POINTER GH
character*(*) group_name
call CCTK_SyncGroup(status, GH, group_name)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0}
Success.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{GH}
A pointer to a Cactus grid hierarchy.
\end{Parameter}
\begin{Parameter}{group\_name}
The full name (Implementation::group or Thorn::group) of the group
to be synchronized.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Only those grid variables which have communication enabled
will be synchronised. This is usually equivalent to the variables
which have storage assigned, unless communication has been explicitly
turned off with a call to \code{CCTK\_DisableGroupComm}.

Note that an alternative to calling \code{CCTK\_SyncGroup} explicitly
from within a thorn, is to use the \code{SYNC} keyword in a thorns
\code{schedule.ccl} file to indicate which groups of variables need
to be synchronised on exit from the routine. This latter method is
the preferred method from synchronising variables.

Note that \code{CCTK\_SyncGroup} is a collective operation, so in the
multiprocessor case you {\em must\/} call this function in parallel on
{\em each\/} processor, passing the same \code{group\_name} argument.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_SyncGroupI}{CCTK-SyncGroupI}
Synchronise the ghostzones for a group of grid variables
(identified by the group index)
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_SyncGroupsI}{CCTK-SyncGroupsI}
Synchronise the ghostzones for a list of groups of grid variables
(identified by their group indices)
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{-1}
\code{group\_name} was invalid.
\end{Error}
\begin{Error}{-2}
The driver returned an error on syncing the group.
\end{Error}
\end{ErrorSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
#include "cctk.h"
#include "cctk_Arguments.h"

/* this function synchronizes the ADM metric */
void synchronize_ADM_metric(CCTK_ARGUMENTS)
{
DECLARE_CCTK_ARGUMENTS      /* defines "magic variable" cctkGH */

const int status = CCTK_SyncGroup(cctkGH, "ADMBase::metric");
if (status < 0)
        CCTK_VWarn(CCTK_WARN_ABORT, __LINE__, __FILE__, CCTK_THORNSTRING,
"***** synchronize_ADM_metric():\n"
"        failed to synchronize ADM metric!\n"
"        (CCTK_SyncGroup() returned error code %d)\n"
                  ,
                  status);                                 /*NOTREACHED*/
}
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}



% CactusSync.c
\begin{FunctionDescription}{CCTK\_SyncGroupI}
\label{CCTK-SyncGroupI}
Synchronise the ghostzones for a group of grid variables
(identified by the group index)

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int status = CCTK_SyncGroupI(const cGH* GH, int group_index)
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"
integer status
CCTK_POINTER GH
integer group_index
call CCTK_SyncGroupI(status, GH, group_index)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0}
Success.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{GH}
A pointer to a Cactus grid hierarchy.
\end{Parameter}
\begin{Parameter}{group\_index}
The group index of the group to be synchronized.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Only those grid variables which have communication enabled
will be synchronised. This is usually equivalent to the variables
which have storage assigned, unless communication has been explicitly
turned off with a call to \code{CCTK\_DisableGroupComm}.

Note that an alternative to calling \code{CCTK\_SyncGroupI} explicitly
from within a thorn, is to use the \code{SYNC} keyword in a thorns
\code{schedule.ccl} file to indicate which groups of variables need
to be synchronised on exit from the routine. This latter method is
the preferred method from synchronising variables.

Note that \code{CCTK\_SyncGroupI} is a collective operation, so in the
multiprocessor case you {\em must\/} call this function in parallel on
{\em each\/} processor, passing the same \code{group\_name} argument.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_SyncGroup}{CCTK-SyncGroup}
Synchronise the ghostzones for a group of grid variables
(identified by the group name)
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_SyncGroupsI}{CCTK-SyncGroupsI}
Synchronise the ghostzones for a list of groups of grid variables
(identified by their group indices)
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_GroupIndex}{CCTK-GroupIndex}
Gets the group index for a given group name.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_GroupIndexFromVar}{CCTK-GroupIndexFromVar}
Gets the group index for a given variable name.
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{-1}
\code{group\_name} was invalid.
\end{Error}
\begin{Error}{-2}
The driver returned an error on syncing the group.
\end{Error}
\end{ErrorSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
#include "cctk.h"
#include "cctk_Arguments.h"

/* this function synchronizes the ADM metric */
void synchronize_ADM_metric(CCTK_ARGUMENTS)
{
DECLARE_CCTK_ARGUMENTS      /* defines "magic variable" cctkGH */

int group_index, status;

group_index = CCTK_GroupIndex("ADMBase::metric");
if (group_index < 0)
        CCTK_VWarn(CCTK_WARN_ABORT, __LINE__, __FILE__, CCTK_THORNSTRING,
"***** synchronize_ADM_metric():\n"
"        couldn't get group index for ADM metric!\n"
"        (CCTK_GroupIndex() returned error code %d)\n"
                  ,
                  group_index);                            /*NOTREACHED*/

status = CCTK_SyncGroupI(cctkGH, group_index);
if (status < 0)
        CCTK_VWarn(CCTK_WARN_ABORT, __LINE__, __FILE__, CCTK_THORNSTRING,
"***** synchronize_ADM_metric():\n"
"        failed to synchronize ADM metric!\n"
"        (CCTK_SyncGroupI() returned error code %d)\n"
                  ,
                  status);                                 /*NOTREACHED*/
}
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}



% CactusSync.c
\begin{FunctionDescription}{CCTK\_SyncGroupsI}
\label{CCTK-SyncGroupsI}
Synchronise the ghostzones for a list of groups of grid variables
(identified by their group indices)

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int status = CCTK_SyncGroupsI(const cGH* GH, int num_groups, const int *groups)
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"
integer status
CCTK_POINTER GH
integer num_groups
integer groups(num_groups)
call CCTK_SyncGroupsI(status, GH, num_groups, groups)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0}
Returns the number of groups that have been synchronised.
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{GH}
A pointer to a Cactus grid hierarchy.
\end{Parameter}
\begin{Parameter}{num\_groups}
The number of groups to be synchronised.
\end{Parameter}
\begin{Parameter}{groups}
The group indices of the groups to be synchronized.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Only those grid variables which have communication enabled
will be synchronised. This is usually equivalent to the variables
which have storage assigned, unless communication has been explicitly
turned off with a call to \code{CCTK\_DisableGroupComm}.

Note that an alternative to calling \code{CCTK\_SyncGroupsI} explicitly
from within a thorn, is to use the \code{SYNC} keyword in a thorns
\code{schedule.ccl} file to indicate which groups of variables need
to be synchronised on exit from the routine. This latter method is
the preferred method from synchronising variables.

Note that \code{CCTK\_SyncGroupsI} is a collective operation, so in the
multiprocessor case you {\em must\/} call this function in parallel on
{\em each\/} processor, passing the same number of groups in the same order.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_SyncGroup}{CCTK-SyncGroup}
Synchronise the ghostzones for a single group of grid variables
(identified by the group name)
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_SyncGroupI}{CCTK-SyncGroupI}
Synchronise the ghostzones for a single group of grid variables
(identified by the group index)
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_GroupIndex}{CCTK-GroupIndex}
Gets the group index for a given group name.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_GroupIndexFromVar}{CCTK-GroupIndexFromVar}
Gets the group index for a given variable name.
\end{SeeAlso2}
\end{SeeAlsoSection}

%\begin{ErrorSection}
%\begin{Error}{-1}
%\code{group\_name} was invalid.
%\end{Error}
%\begin{Error}{-2}
%The driver returned an error on syncing the group.
%\end{Error}
%\end{ErrorSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
#include "cctk.h"
#include "cctk_Arguments.h"

/* this function synchronizes the ADM metric and lapse */
void synchronize_ADM_metric_and_lapse(CCTK_ARGUMENTS)
{
DECLARE_CCTK_ARGUMENTS      /* defines "magic variable" cctkGH */

int group_indices[2], status;

group_indices[0] = CCTK_GroupIndex("ADMBase::metric");
group_indices[1] = CCTK_GroupIndex("ADMBase::lapse");
if (group_indices[0] < 0)
        CCTK_VWarn(CCTK_WARN_ABORT, __LINE__, __FILE__, CCTK_THORNSTRING,
"***** synchronize_ADM_metric():\n"
"        couldn't get group index for ADM metric!\n"
"        (CCTK_GroupIndex() returned error code %d)\n"
                  ,
                  group_indices[0]);                            /*NOTREACHED*/
if (group_indices[1] < 0)
        CCTK_VWarn(CCTK_WARN_ABORT, __LINE__, __FILE__, CCTK_THORNSTRING,
"***** synchronize_ADM_metric_and_lapse():\n"
"        couldn't get group index for ADM lapse!\n"
"        (CCTK_GroupIndex() returned error code %d)\n"
                  ,
                  group_indices[1]);                            /*NOTREACHED*/

status = CCTK_SyncGroupsI(cctkGH, 2, group_indices);
if (status != 2)
        CCTK_VWarn(CCTK_WARN_ABORT, __LINE__, __FILE__, CCTK_THORNSTRING,
"***** synchronize_ADM_metric_and_lapse():\n"
"        failed to synchronize ADM metric and lapse!\n"
"        (CCTK_SyncGroupsI() returned error code %d)\n"
                  ,
                  status);                                 /*NOTREACHED*/
}
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}




%%%%%
% TTT
%%%%%

%Entering a function description for CCTK\_TerminateNext
\begin{FunctionDescription}{CCTK\_TerminateNext}
\label{CCTK-TerminateNext}
Causes a Cactus simulation to terminate after present iteration finishes

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

void CCTK_TerminateNext (const cGH *cctkGH)
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"

call CCTK_TerminateNext (cctkGH)
CCTK_POINTER_TO_CONST    cctkGH
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{cctkGH}
Pointer to a Cactus grid hierarchy.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This function triggers unconditional termination of Cactus after the
present iteration.
It bypasses all other termination conditions specified in the
{\t Cactus::terminate} keyword parameter.

At this time, the {\tt cctkGH} parameter does nothing.
\end{Discussion}
\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_TerminationReached}{CCTK-TerminationReached}
  Returns true if {\tt CCTK\_TerminateNext} has been called.
\end{SeeAlso2}
\end{SeeAlsoSection}
\end{FunctionDescription}


%Entering a function description for CCTK\_TerminationReached
\begin{FunctionDescription}{CCTK\_TerminationReached}
\label{CCTK-TerminationReached}
Returns true if {\tt CCTK\_TerminateNext} has been called.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

void CCTK_TerminationReached (const cGH *cctkGH)
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"

call CCTK_TerminationReached (cctkGH)
CCTK_POINTER_TO_CONST    cctkGH
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{cctkGH}
Pointer to a Cactus grid hierarchy.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Returns true if Cactus has been requested to terminate after the present
iteration by the {\tt CCTK\_TerminateNext} function.

At this time, the {\tt cctkGH} parameter does nothing.
\end{Discussion}
\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_TerminateNext}{CCTK-TerminateNext}
  Causes a Cactus simulation to terminate after the present iteration.
\end{SeeAlso2}
\end{SeeAlsoSection}
\end{FunctionDescription}


% cctk_ActiveThorns.c
\begin{FunctionDescription}{CCTK\_ThornImplementation}
\label{CCTK-ThornImplementation}
Returns the implementation provided by the thorn.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

const char *imp = CCTK_ThornImplementationThorn(const char *name);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{imp}
Name of the implementation or \code{NULL}
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{name}
Name of the thorn
\end{Parameter}
\end{ParameterSection}

%\begin{Discussion}
%\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_ActivatingThorn}{CCTK-ActivatingThorn}
  Finds the thorn which activated a particular implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompiledImplementation}{CCTK-CompiledImplementation}
  Return the name of the compiled implementation with given index
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_CompiledThorn}{CCTK-CompiledThorn}
  Return the name of the compiled thorn with given index
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImplementationRequires}{CCTK-ImplementationRequires}
  Return the ancestors for an implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImplementationThorn}{CCTK-ImplementationThorn}
  Returns the name of one thorn providing an implementation.
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_ImpThornList}{CCTK-ImpThornList}
  Return the thorns for an implementation
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive}
  Reports whether an implementation was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled}
  Reports whether an implementation was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive}
  Reports whether a thorn was activated in a parameter file
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled}
  Reports whether a thorn was compiled into a configuration
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_NumCompiledImplementations}{CCTK-NumCompiledImplementations}
  Return the number of implementations compiled in
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_NumCompiledThorns}{CCTK-NumCompiledThorns}
  Return the number of thorns compiled in
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ErrorSection}
\begin{Error}{NULL}
Error.
\end{Error}
\end{ErrorSection}

%\begin{ExampleSection}
%\end{ExampleSection}
\end{FunctionDescription}



%Entering a function description for CCTK\_Timer
\begin{FunctionDescription}{CCTK\_Timer}
\label{CCTK-Timer}
Fills a {\tt cTimerData}
structure with timer clock info, for the timer specified by name.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int err = CCTK_Timer(name,info)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter} {const char * name}
Timer name
\end{Parameter}

\begin{Parameter} {cTimerData * info}
Timer clock info pointer
\end{Parameter}
\end{ParameterSection}

\begin{ErrorSection}
\begin{Error}
A negative return value indicates an error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_TimerCreate}
\label{CCTK-TimerCreate}
Creates a timer with a given name,
returns an index to the timer.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int index = CCTK_TimerCreate(name)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter} {const char * name}
timer name
\end{Parameter}
\end{ParameterSection}

\begin{ErrorSection}
\begin{Error}{< 0}
A negative return value indicates an error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_TimerCreateData}
\label{CCTK-TimerCreateData}
Allocates the {\tt cTimerData}
structure, which is used to store timer clock info.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
cTimerData * info = CCTK_TimerCreateData()
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ErrorSection}
\begin{Error}{NULL}
A null return value indicates an error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_TimerCreateI}
\label{CCTK-TimerCreateI}
Creates an unnamed timer, returns an index to the timer.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int index = CCTK_TimerCreate()
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ErrorSection}
\begin{Error}{< 0}
A negative return value indicates an error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_TimerDestroy}
\label{CCTK-TimerDestroy}
Reclaims resources used by the
given timer, specified by name.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int err = CCTK_TimerDestroy(name)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter} {const char * name}
timer name
\end{Parameter}
\end{ParameterSection}

\begin{ErrorSection}
\begin{Error}{< 0}
A negative return value indicates an error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_TimerDestroyData}
\label{CCTK-TimerDestroyData}
Releases resources from the {\tt cTimerData}
structure, created by {\tt CCTK\_TimerCreateData}.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int err = CCTK_TimerDestroyData(info)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter} {cTimerData * info}
Timer clock info pointer
\end{Parameter}
\end{ParameterSection}

\begin{ErrorSection}
\begin{Error}{< 0}
A negative return value indicates an error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_TimerDestroyI}
\label{CCTK-TimerDestroyI}
Reclaims resources used by the
given timer, specified by index.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int err = CCTK_TimerDestroyI(index)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter} {int index}
timer index
\end{Parameter}
\end{ParameterSection}

\begin{ErrorSection}
\begin{Error}{< 0}
A negative return value indicates an error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_TimerI}
\label{CCTK-TimerI}
Fills a {\tt cTimerData}
structure with timer clock info, for the timer specified by index.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int err = CCTK_TimerI(index,info)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter} {int index}
Timer index
\end{Parameter}

\begin{Parameter} {cTimerData * info}
Timer clock info pointer
\end{Parameter}
\end{ParameterSection}

\begin{ErrorSection}
\begin{Error}{< 0}
A negative return value indicates an error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_TimerReset}
% new local array reduction API

\label{CCTK-TimerReset}
Gets values from all the clocks in the
given timer, specified by name.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int err = CCTK_TimerReset(name)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter} {const char * name}
timer name
\end{Parameter}
\end{ParameterSection}

\begin{ErrorSection}
\begin{Error}{< 0}
A negative return value indicates an error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_TimerResetI}
\label{CCTK-TimerResetI}
Gets values from all the clocks in the
given timer, specified by index.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int err = CCTK_TimerResetI(index)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter} {int index}
timer index
\end{Parameter}
\end{ParameterSection}

\begin{ErrorSection}
\begin{Error}{< 0}
A negative return value indicates an error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_TimerStart}
\label{CCTK-TimerStart}
Initialises all the clocks in the
given timer, specified by name.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int err = CCTK_TimerStart(name)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter} {const char * name}
timer name
\end{Parameter}
\end{ParameterSection}

\begin{ErrorSection}
\begin{Error}{< 0}
A negative return value indicates an error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_TimerStartI}
\label{CCTK-TimerStartI}
Initialises all the clocks in the
given timer, specified by index.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int err = CCTK_TimerStartI(index)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter} {int index}
timer index
\end{Parameter}
\end{ParameterSection}

\begin{ErrorSection}
\begin{Error}{< 0}
A negative return value indicates an error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_TimerStop}
\label{CCTK-TimerStop}
Gets values from all the clocks in the
given timer, specified by name.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int err = CCTK_TimerStop(name)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter} {int name}
timer name
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Call this before getting the values from any of the timer's clocks.
\end{Discussion}

\begin{ErrorSection}
\begin{Error}{< 0}
A negative return value indicates an error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_TimerStopI}
\label{CCTK-TimerStopI}
Gets values from all the clocks in the
given timer, specified by index.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int err = CCTK_TimerStopI(index)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter} {int index}
timer index
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Call this before getting the values from any of the timer's clocks.
\end{Discussion}

\begin{ErrorSection}
\begin{Error}{< 0}
A negative return value indicates an error.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_TimerIsRunning}
\label{CCTK-TimerIsRunning}
Checks if a Cactus timer is running, given its name.
Returns 0 of not (or in case of errors) and 1 if the timer is running.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int err = CCTK_TimerIsRunning(name)
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_TimerIsRunning(isrunning, name)
  integer isrunning
  character*(*) name
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter} {char* name}
timer name
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Errors are treated as non-running timers: 0 is returned.
\end{Discussion}

\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_TimerIsRunningI}
\label{CCTK-TimerIsRunningI}
Checks if a Cactus timer is running, given its handle.
Returns 0 of not (or in case of errors) and 1 if the timer is running.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int err = CCTK_TimerIsRunningI(index)
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_TimerIsRunningI(isrunning , index )
  integer isrunning
  integer index
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter} {int index}
timer index
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Errors are treated as non-running timers: 0 is returned.
\end{Discussion}

\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_TraverseString}
\label{CCTK-TraverseString}
Traverse through all variables and/or groups whose names appear in the given
string, and call the callback routine with those indices and an optional
option string appended to the variable/group name enclosed in square braces.
The special keyword "all" in the string can be used to indicate that the
callback should be called for all variables/groups.

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
int err = CCTK_TraverseString(traverse_string, callback, callback_arg,
                              selection)
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
   \begin{Parameter} {const char * traverse\_string}
   List of variable and/or group names
   \end{Parameter}
   \begin{Parameter} {void (*callback) (int idx, const char *optstring, void *callback\_arg)}
   Routine to call for every variable and/or group found. \code{idx} is the
   Cactus variable index, \code{optstring} is the optional `\verb|{}|'
   enclosed option string after the variable name, and \code{callback\_arg} is
   the arbitrary argument passed to \code{CCTK\_TraverseString}.
   \end{Parameter}
   \begin{Parameter} {void *callback\_arg}
   An arbitrary argument which gets passed to the callback routine
   \end{Parameter}
   \begin{Parameter} {int selection}
   Decides whether group and/or variable names are accepted in the string.
   Possible values are: \code{CCTK\_VAR}, \code{CCTK\_GROUP} or
   \code{CCTK\_GROUP\_OR\_VAR}.
   \end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Use this to loop over a list of variables passed in by the user.
\end{Discussion}

\begin{ResultSection}
\begin{Result}{number of variables}
positive for the number of traversed variables
\end{Result}
\end{ResultSection}

\begin{ErrorSection}
\begin{Error}{-1}
no callback routine was given
\end{Error}
\begin{Error}{-2}
option string is not associated with a group or variable
\end{Error}
\begin{Error}{-3}
unterminated option string
\end{Error}
\begin{Error}{-4}
garbage found at end of option string
\end{Error}
\begin{Error}{-5}
invalid token in traversed string found
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


%%%%%

%%%%%
% UUU
%%%%%

%%%%%
% VVV
%%%%%

\begin{FunctionDescription}{CCTK\_VarDataPtr}{Returns the data pointer for a grid variable}
\label{CCTK-VarDataPtr}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}void * ptr = CCTK_VarDataPtr( const cGH * cctkGH, int timelevel, char * name)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_VarDataPtr(ptr, cctkGH, timelevel, varname)
                     CCTK_POINTER vardataptr
                     CCTK_POINTER_TO_CONST cctkGH
                     integer timelevel
                     character*(*) varname
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{ptr}
a void pointer to the grid variable data
\end{Parameter}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\begin{Parameter}{timelevel}
The timelevel of the grid variable
\end{Parameter}
\begin{Parameter}{name}
The full name of the variable
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The variable name should be in the form \code{<implementation>::<variable>}.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
myVar = (CCTK_REAL *)(CCTK_VarDataPtr(GH,0,"imp::realvar"))
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
CCTK_REAL, dimension(cctk_ash(1),cctk_ash(2),cctk_ash(3)) :: var
CCTK_POINTER myVar
pointer (myVar, var)
call CCTK_VarDataPtr(myVar,GH,0,"imp::realvar")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

\begin{FunctionDescription}{CCTK\_VarDataPtrB}{Returns the data pointer for a grid variable from the variable index or the variable name}
\label{CCTK-VarDataPtrB}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}void * ptr = CCTK_VarDataPtrB( const cGH * cctkGH, int timelevel, int index, char * name)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{ptr}
a void pointer to the grid variable data
\end{Parameter}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\begin{Parameter}{timelevel}
The timelevel of the grid variable
\end{Parameter}
\begin{Parameter}{index}
The index of the variable
\end{Parameter}
\begin{Parameter}{name}
The full name of the variable
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
If the name is \code{NULL} the index will be used, if the index is negative the name will be used.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
myVar = (CCTK_REAL *)(CCTK_VarDataPtrB(GH,0,CCTK_VarIndex("imp::realvar"),NULL));
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_VarDataPtrI}{Returns the data pointer for a grid variable from the variable index}
\label{CCTK-VarDataPtrI}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}void * ptr = CCTK_VarDataPtrI( const cGH * cctkGH, int timelevel, int index)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_VarDataPtrI(ptr, cctkGH, timelevel, index)
                      CCTK_POINTER vardataptr
                      CCTK_POINTER_TO_CONST cctkGH
                      integer timelevel
                      integer index
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{cctkGH}
pointer to CCTK grid hierarchy
\end{Parameter}
\begin{Parameter}{timelevel}
The timelevel of the grid variable
\end{Parameter}
\begin{Parameter}{index}
The index of the variable
\end{Parameter}
\end{ParameterSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
myVar = (CCTK_REAL *)(CCTK_VarDataPtr(GH,0,CCTK_VarIndex("imp::realvar")));
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
CCTK_REAL, dimension(cctk_ash(1),cctk_ash(2),cctk_ash(3)) :: var
CCTK_POINTER myVar
pointer (myVar, var)
call CCTK_VarDataPtr(myVar,GH,0,CCTK_VarIndex("imp::realvar"))
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


% Groups.c
\begin{FunctionDescription}{CCTK\_VarIndex}{}
\label{CCTK-VarIndex}
Get the index for a variable.
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"
int index = CCTK_VarIndex(const char *varname);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
call CCTK_VarIndex(index, varname)
                   integer index
                   character*(*) varname
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{varname}
The name of the variable.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The variable name should be the given in its fully qualified form,
that is \code{<implementation>::<variable>} for a public or protected
variable, and \code{<thornname>::<variable>} for a private variable.
For vector variables, the zero-based component index should be included
in square brackets after the variable name.
\end{Discussion}

%\begin{SeeAlsoSection}
%\end{SeeAlsoSection}
\begin{ErrorSection}
\begin{Error}{-1}
no variable of this name exists
\end{Error}
\begin{Error}{-2}
failed to catch error code from \code{Util\_SplitString}
\end{Error}
\begin{Error}{-3}
given full name is in wrong format
\end{Error}
\begin{Error}{-4}
memory allocation failed
\end{Error}
\end{ErrorSection}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
index = CCTK_VarIndex("evolve::phi");
index = CCTK_VarIndex("evolve::vect[0]");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_VarIndex(index,"evolve::phi")
call CCTK_VarIndex(index,"evolve::vect[0]")
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


% Groups.c
\begin{FunctionDescription}{CCTK\_VarName}{Given a variable index, returns the variable name}
\label{CCTK-VarName}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}const char * name = CCTK_VarName( int index)\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{name}
The variable name
\end{Parameter}
\begin{Parameter}{index}
The variable index
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The pointer returned is part of a structure managed by Cactus
and so must {\em not} be freed after use.

No Fortran routine exists at the moment.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
index = CCTK_VarIndex("evolve::phi");
name = CCTK_VarName(index);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


% Groups.c
\begin{FunctionDescription}{CCTK\_VarTypeI}{Provides variable type index from the variable index}
\label{CCTK-VarTypeI}
\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}int type = CCTK_VarTypeI( int index)\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}call CCTK_VarTypeI(type , index )

integer type
integer index\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}
\begin{ParameterSection}
\begin{Parameter}{type}
The variable type index
\end{Parameter}
\begin{Parameter}{group}
The variable index
\end{Parameter}
\end{ParameterSection}
\begin{Discussion}
The variable type index indicates the type of the variable.
Either character, int, complex or real. The group type can be checked
with the Cactus provided macros for \code{CCTK\_VARIABLE\_INT}, \code{CCTK\_VARIABLE\_REAL}, \code{CCTK\_VARIABLE\_COMPLEX} or \code{CCTK\_VARIABLE\_CHAR}.
\end{Discussion}
\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
index = CCTK_VarIndex("evolve::phi")
real = (CCTK_VARIABLE_REAL == CCTK_VarTypeI(index)) ;
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
call CCTK_VARTYPEI(type,3)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%Entering a function description for CCTK_VarTypeSize
\begin{FunctionDescription}{CCTK\_VarTypeSize}
\label{CCTK-VarTypeSize}
Provides variable type size in bytes from the variable type index

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include "cctk.h"

int CCTK_VarTypeSize(int vtype);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"

CCTK_INT size, vtype
call CCTK_VarTypeSize(size, vtype);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{vtype}
Variable type index.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
Given a \verb|CCTK_VARIABLE_*| type code (e.g.~\verb|CCTK_VARIABLE_INT|,
\verb|CCTK_VARIABLE_REAL|, \verb|CCTK_VARIABLE_COMPLEX|, etc.), this
function returns the size in bytes of the corresponding data type
(\code{CCTK\_INT}, \code{CCTK\_REAL}, \code{CCTK\_COMPLEX}, etc.).
\end{Discussion}

\begin{ErrorSection}
\begin{Error}{-1}
\verb|vtype| is not one of the \verb|CCTK_VARIABLE_*| values.
\end{Error}
\end{ErrorSection}
\end{FunctionDescription}


%Entering a function description for CCTK_VError
\begin{FunctionDescription}{CCTK\_VError}
\label{CCTK-VError}
Prints a formatted string with a variable argument list as error
message and stops the code

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include <cctk.h>

void CCTK_VError(int line,
                 const char *file,
                 const char *thorn,
                 const char *format,
                 ...);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{line}
The line number in the originating source file where the \code{CCTK\_VError} call
occured. You can use the standardized \code{\_\_LINE\_\_} preprocessor macro here.
\end{Parameter}
\begin{Parameter}{file}
The file name of the originating source file where the \code{CCTK\_VError} call
occured. You can use the standardized \code{\_\_FILE\_\_} preprocessor macro here.
\end{Parameter}
\begin{Parameter}{thorn}
The thorn name of the originating source file where the \code{CCTK\_VError} call occured. You can use the \code{CCTK\_THORNSTRING} macro here (defined in \code{cctk.h}).
\end{Parameter}
\begin{Parameter}{format}
The \code{printf}-like format string to use for printing the warning message.
\end{Parameter}
\begin{Parameter}{...}
The variable argument list.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This routine can be used by thorns to print a formatted string
followed by a variable argument list as error message to
\code{stderr}. After printing the message, Cactus aborts the run (and
\code{CCTK\_VError} does \emph{not} return to the caller).
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_Abort}{CCTK-Abort}
Abort the code
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_ERROR} {CCTK-ERROR}
macro to print an error message with a single string argument
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_Exit}{CCTK-Exit}
Exit the code cleanly
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_VWarn} {CCTK-VWarn}
Possibly prints a formatted string with a variable argument list as
warning message and/or stops the code
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_WARN} {CCTK-WARN}
macro to print a warning message with a single string argument
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
#include <cctk.h>

const char *outdir;

CCTK_VError(__LINE__, __FILE__, CCTK_THORNSTRING,
           "Output directory '%s' could not be created", outdir);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


\begin{FunctionDescription}{CCTK\_VInfo}
\label{CCTK-VInfo}
Prints a formatted string with a variable argument list as an info message
to sceen

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include <cctk.h>

int status = CCTK_VInfo(const char *thorn,
                        const char *format,
                        ...);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0} ok \end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{thorn}
The name of the thorn printing this info message. You can use the
\code{CCTK\_THORNSTRING} macro here (defined in \code{cctk.h}).
\end{Parameter}
\begin{Parameter}{format}
The \code{printf}-like format string to use for printing the info message.
\end{Parameter}
\begin{Parameter}{...}
The variable argument list.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This routine can be used by thorns to print a formatted string with a variable
argument list as an info message to screen.
The message will include the name of the originating thorn, otherwise its
semantics is equivalent to \code{printf}.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2} {CCTK\_INFO} {CCTK-INFO}
macro to print an info message with a single string argument
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_ERROR} {CCTK-ERROR}
macro to print an error message with a single string argument and stop
the code
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_VError} {CCTK-VError}
prints a formatted string with a variable argument list as error
message and stops the code
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_VWarn} {CCTK-VWarn}
prints a warning message with a variable argument list
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_WARN} {CCTK-WARN}
macro to print a warning message with a single string argument and
possibly stop the code
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
#include "cctk.h"

const char *outdir;

CCTK_VInfo(CCTK_THORNSTRING, "Output files will go to '%s'", outdir);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}


%Entering a function description for CCTK_VWarn
\begin{FunctionDescription}{CCTK\_VWarn}
\label{CCTK-VWarn}
Possibly prints a formatted string with a variable argument list as
warning message and/or stops the code

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include <cctk.h>

int status = CCTK_VWarn(int level,
                        int line,
                        const char *file,
                        const char *thorn,
                        const char *format,
                        ...);
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ResultSection}
\begin{Result}{0}
ok%%%
\footnote{%%%
         When this function is called, the calling code almost
         always ignores the return result.  However, it's still
         useful for this function to be declared as returning a
         value, rather than having type \texttt{void}, since this
         allows it to be used in C conditional expressions.
         }%%%
\end{Result}
\end{ResultSection}

\begin{ParameterSection}
\begin{Parameter}{level ($\ge 0$)}
The warning level for the message to print, with level~0 being the
severest level and greater levels being less severe.
\end{Parameter}
\begin{Parameter}{line}
The line number in the originating source file where the \code{CCTK\_VWarn} call
occured. You can use the standardized \code{\_\_LINE\_\_} preprocessor macro here.
\end{Parameter}
\begin{Parameter}{file}
The file name of the originating source file where the \code{CCTK\_VWarn} call
occured. You can use the standardized \code{\_\_FILE\_\_} preprocessor macro here.
\end{Parameter}
\begin{Parameter}{thorn}
The thorn name of the originating source file where the \code{CCTK\_VWarn} call occured. You can use the \code{CCTK\_THORNSTRING} macro here (defined in \code{cctk.h}).
\end{Parameter}
\begin{Parameter}{format}
The \code{printf}-like format string to use for printing the warning message.
\end{Parameter}
\begin{Parameter}{...}
The variable argument list.
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This routine can be used by thorns to print a formatted string followed
by a variable argument list as a warning message to \code{stderr}.  If
the message's ``warning level'' is severe enough, then after printing
the message Cactus aborts the run (and \code{CCTK\_VWarn} does {\em not\/}
return to the caller).

Cactus's behavior when \code{CCTK\_VWarn} is called depends on the
\code{-W} and \code{-E} command-line options:
\begin{itemize}
\item   Cactus prints any warning with a warning level $\le$
        the \code{-W} level to standard error (any warnings with
        warning levels $>$ the \code{-W} level are silently discarded).
        The default \code{-W} level is~1, \ie{} only level~0 and level~1
        warnings will be printed.
\item   Cactus stops (aborts) the current run for any warning
        with a warning level $\le$ the \code{-E} level.
        The default \code{-W} level is~0, \ie{} only level~0
        warnings will abort the run.
\end{itemize}

Cactus guarantees that
$\hbox{the \code{-W}~level} \ge \hbox{the \code{-E}~level} \ge 0$.
This implies that a message will always be printed for any warning that's
severe enough to halt the Cactus run.  It also implies that a level~0
warning is guaranteed (to be printed and) to halt the Cactus run.

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.

In any case, the Boolean flesh parameter \code{cctk\_full\_warnings}
determines whether all the details about the warning origin (processor~ID,
line number, source file, source thorn) are shown. The default is to
print everything.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_Abort}{CCTK-Abort}
Abort the code
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_ERROR} {CCTK-ERROR}
macro to print an error message with a single string argument and stop
the code
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_Exit}{CCTK-Exit}
Exit the code cleanly
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_INFO} {CCTK-INFO}
macro to print an info message with a single string argument
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_VInfo()} {CCTK-VInfo}
prints a formatted string with a variable argument list as an info message to
screen
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_VError} {CCTK-VError}
prints a formatted string with a variable argument list as error
message and stops the code
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_WARN} {CCTK-WARN}
macro to print a warning message with a single string argument
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
#include <cctk.h>

const char *outdir;

CCTK_VWarn(CCTK_WARN_ALERT, __LINE__, __FILE__, CCTK_THORNSTRING,
           "Output directory '%s' could not be created", outdir);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


%%%%%
% WWW
%%%%%



% WarnLevel.c
%Entering a function description for CCTK_WARN
\begin{FunctionDescription}{CCTK\_WARN}
\label{CCTK-WARN}
Macro to print a single string as a warning message and possibly stop the code

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include <cctk.h>

CCTK_WARN(int level, const char *message);
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"

call CCTK_WARN(level, message)
integer       level
character*(*) message
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{level}
The warning level to use;
see the description of \verb|CCTK_VWarn()| on page~\pageref{CCTK-VInfo}
for a detailed discussion of this parameter and the Cactus macros
for standard warning levels
\end{Parameter}
\begin{Parameter}{message}
The warning message to print
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
This macro can be used by thorns to print a single string as a warning message
to \code{stderr}.

\code{CCTK\_WARN(level, message)} expands to a call to \verb|CCTK_Warn()| 
function which is equivalent to \verb|CCTK_VWarn()|, but without the
variable-number-of-arguments feature (so it can be used from Fortran).%%%
\footnote{%%%
         Some code calls this function directly.
         For reference, the function is:\\
         \texttt{\hbox{}int CCTK\_Warn(int level,}\\
         \texttt{\hbox{}~~~~~~~~~~~~~~int line\_number, const char* file\_name, const char* thorn\_name,}\\
         \texttt{\hbox{}~~~~~~~~~~~~~~const char* message)}
         }%%%
{}  The macro automatically includes details about the origin of the warning
(the thorn name, the source code file name and the line number where the macro
occurs).

To include variables in a warning message from C, you can use the routine
\code{CCTK\_VWarn} which accepts a variable argument list.
To include variables from Fortran, a string must be constructed and passed
in a \code{CCTK\_WARN} macro.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_Abort}{CCTK-Abort}
Abort the code
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_ERROR} {CCTK-ERROR}
macro to print an error message with a single string argument and stop
the code
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_Exit}{CCTK-Exit}
Exit the code cleanly
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_INFO} {CCTK-INFO}
macro to print an info message with a single string argument
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_VError} {CCTK-VError}
prints a formatted string with a variable argument list as error
message and stops the code
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_VInfo()} {CCTK-VInfo}
prints a formatted string with a variable argument list as an info message to
screen
\end{SeeAlso2}
\begin{SeeAlso2} {CCTK\_VWarn} {CCTK-VWarn}
prints a warning message with a variable argument list
\end{SeeAlso2}
\end{SeeAlsoSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
#include "cctk.h"

CCTK_WARN(CCTK_WARN_ABORT, "Divide by 0");
\end{verbatim}
\end{Example}
\begin{Example}{Fortran}
\begin{verbatim}
#include "cctk.h"

integer       myint
real          myreal
character*200 message

write(message, '(A32, G12.7, A5, I8)')
&     'Your warning message, including ', myreal, ' and ', myint
call CCTK_WARN(CCTK_WARN_ALERT, message)
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%Entering a function description for CCTK_Warn
\begin{FunctionDescription}{CCTK\_Warn}
\label{CCTK-Warn}
Function to print a single string as error message and possibly stop the code

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include <cctk.h>

void CCTK_Warn(int level, int line_number, const char* file_name,
               const char* thorn_name,const char* message)
\end{verbatim}
\end{Synopsis}
\begin{Synopsis}{Fortran}
\begin{verbatim}
#include "cctk.h"

call CCTK_Warn(level, line_number, file_name, thorn_name, message)
integer level, line_number
character*(*) file_name, thorn_name, message
\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{level ($\ge 0$)}
The warning level for the message to print, with level~0 being the
severest level and greater levels being less severe.
\end{Parameter}
\begin{Parameter}{line\_number}
The line number in the originating source file where the \code{CCTK\_VWarn} call
occured. You can use the standardized \code{\_\_LINE\_\_} preprocessor macro here.
\end{Parameter}
\begin{Parameter}{file\_name}
The file name of the originating source file where the \code{CCTK\_VWarn} call
occured. You can use the standardized \code{\_\_FILE\_\_} preprocessor macro here.
\end{Parameter}
\begin{Parameter}{thorn\_name}
The thorn name of the originating source file where the \code{CCTK\_VWarn} call occured. You can use the \code{CCTK\_THORNSTRING} macro here (defined in \code{cctk.h}).
\end{Parameter}
\begin{Parameter}{message}
The error message to print
\end{Parameter}
\end{ParameterSection}

\begin{Discussion}
The macro \verb|CCTK_WARN| automatically includes the line number, file name
and the name of the originating thorn in the
info message. It is recommended that the macro \code{CCTK\_WARN} is used
to print a message rather than calling \code{CCTK\_Warn} directly.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso2}{CCTK\_Abort}{CCTK-Abort}
Abort the code
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_Exit}{CCTK-Exit}
Exit the code cleanly
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_VWarn}{CCTK-VWarn}
prints an error message with a variable argument list
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_VWarn}{CCTK-VWarn}
Prints a formatted string with a variable argument list as a warning
message to standard error and possibly stops the code
\end{SeeAlso2}
\begin{SeeAlso2}{CCTK\_WARN}{CCTK-WARN}
Macro to print a single string as a warning message and possibly stop the code
\end{SeeAlso2}
\end{SeeAlsoSection}
\end{FunctionDescription}



\begin{FunctionDescription}{CCTK\_WarnCallbackRegister}
\label{CCTK-WARNCallbackRegister}
Register one or more routines for dealing with warning messages in
addition to printing them to standard error

\begin{SynopsisSection}
\begin{Synopsis}{C}
\begin{verbatim}
#include <cctk.h>

CCTK_WarnCallbackRegister(int minlevel,
                          int maxlevel,
                          void *data,
                          cctk_warnfunc callback);

\end{verbatim}
\end{Synopsis}
\end{SynopsisSection}

\begin{ParameterSection}
\begin{Parameter}{minlevel}
The minimum warning level to use.

You can find a detailed discussion of the Cactus macros for standard
warning levels on page~\pageref{CCTK-VInfo}. Both minlevel and maxlevel follow
that definition.

\end{Parameter}

\begin{Parameter}{maxlevel}
The maximum warning level to use

\end{Parameter}

\begin{Parameter}{data}
The void pointer holding extra information about the registered call back
routine
\end{Parameter}

\begin{Parameter}{callback}
The function pointer pointing to the call back function dealing with
warning messages. The definition of the function pointer is:
\begin{verbatim}

typedef void (*cctk_warnfunc)(int level,
                              int line,
                              const char *file,
                              const char *thorn,
                              const char *message,
                              void *data);

\end{verbatim}

The argument list is the same as those in \verb|CCTK_Warn()|
(see the footnote of \verb|CCTK_WARN()| page~\pageref{CCTK-WARN})
except an extra void pointer to hold the information about the call
back routine.

\end{Parameter}

\end{ParameterSection}

\begin{Discussion}
This function can be used by thorns to register their own routines to
deal with warning messages. The registered function pointers will be
stored in a pointer chain. When \verb|CCTK_VWarn()| is called, the
registered routines will be called in the same order as they get
registered in addition to dumping warning messages to \code{stderr}.

The function can only be called in C.
\end{Discussion}

\begin{SeeAlsoSection}
\begin{SeeAlso}{CCTK\_InfoCallbackRegister()}
Register one or more routines for dealing with information messages in
addition to printing them to screen
\end{SeeAlso}

\begin{SeeAlso}{CCTK\_VWarn()}
Prints a formatted string with a variable argument list as a warning message
to standard error and possibly stops the code
\end{SeeAlso}

\end{SeeAlsoSection}

\begin{ExampleSection}
\begin{Example}{C}
\begin{verbatim}
/*DumpWarn will dump warning messages to a file*/

void DumpWarn(int level,
              int line,
              const char *file,
              const char *thorn,
              const char *message,
              void *data)
{
  DECLARE_CCTK_PARAMETERS
  FILE *fp;
  char *str = (char *)malloc((strlen(file)+strlen(thorn)+strlen(message)+100);

  /*warn_dump_file is a string set in the parameter file*/

  if((fp = fopen (warn_dump_file, "a"))==0)
  {
    fprintf(stderr, "fatal error: can not open the file %s\n",warn_dump_file);
    return;
  }
  sprintf(str, "\n[WARN]\nLevel->%d\nLine->%d\nFile->%s\nThorn->%s\nMsg->%s\n",
               level,line,file,thorn,message);
  fprintf(fp, "%s", str);
  free(str);
  fclose(fp);
}

...

/*minlevel = 0; maxlevel = 5; data = NULL; callback = DumpWarn*/

CCTK_WarnCallbackRegister(0,5,NULL,DumpWarn);
\end{verbatim}
\end{Example}
\end{ExampleSection}
\end{FunctionDescription}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\end{cactuspart}
