initial draft of Cactus Reference Manual

FunctionReference.tex copied from ../UsersGuide/FunctionReference.tex;
 see there for older CVS history


git-svn-id: http://svn.cactuscode.org/flesh/trunk@3325 17b73243-c579-4c4c-a9d2-2d5706c11dac

3 files changed, 11052 insertions, 0 deletions

diff --git a/doc/ReferenceManual/FunctionReference.tex b/doc/ReferenceManual/FunctionReference.tex
new file mode 100644
index 00000000..df7eb0c3
--- /dev/null
+++ b/doc/ReferenceManual/FunctionReference.tex
@@ -0,0 +1,10852 @@
+% /*@@
+%   @file      FunctionReference.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
+% @@*/
+
+\begin{cactuspart}{FunctionReference}{$RCSfile$}{$Revision$}
+\label{part:FunctionReference}
+\renewcommand{\thepage}{\Alph{part}\arabic{page}}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapter{Cactus Functions}
+
+In this section all \hbox{{\tt 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.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Functions Alphabetically}
+
+\begin{Lentry}
+
+\item[CCTK\_Abort]
+  [\pageref{CCTK-Abort}]
+  Causes abnormal Cactus termination
+
+\item[CCTK\_ActiveTimeLevels]
+  [\pageref{CCTK-ActiveTimeLevels}]
+  Returns the number of active timelevels from a group name
+
+\item[CCTK\_ActiveTimeLevelsGN]
+  [\pageref{CCTK-ActiveTimeLevels}]
+  Returns the number of active timelevels from a group name
+
+\item[CCTK\_ActiveTimeLevelsGI]
+  [\pageref{CCTK-ActiveTimeLevels}]
+  Returns the number of active timelevels from a group index
+
+\item[CCTK\_ActiveTimeLevelsVN]
+  [\pageref{CCTK-ActiveTimeLevels}]
+  Returns the number of active timelevels from a variable name
+
+\item[CCTK\_ActiveTimeLevelsVI]
+  [\pageref{CCTK-ActiveTimeLevels}]
+  Returns the number of active timelevels from a variable index
+
+\item[CCTK\_ArrayGroupSize]
+  [\pageref{CCTK-ArrayGroupSize}]
+  Returns a pointer to the local size for a group, given by its group name
+
+\item[CCTK\_ArrayGroupSizeI]
+  [\pageref{CCTK-ArrayGroupSizeI}]
+  Returns a pointer to the local size for a group, given by its group index
+
+\item[CCTK\_Barrier]
+  [\pageref{CCTK-Barrier}]
+  Synchronizes all processors
+
+\item[CCTK\_Cmplx]
+  [\pageref{CCTK-Cmplx}]
+  Turns two real numbers into a complex number (only C)
+
+\item[CCTK\_CmplxAbs]
+  [\pageref{CCTK-CmplxAbs}]
+  Returns the absolute value of a complex number (only C)
+
+\item[CCTK\_CmplxAdd]
+  [\pageref{CCTK-CmplxAdd}]
+  Returns the sum of two complex numbers (only C)
+
+\item[CCTK\_CmplxConjg]
+  [\pageref{CCTK-CmplxConjg}]
+  Returns the complex conjugate of a complex number (only C)
+
+\item[CCTK\_CmplxCos]
+  [\pageref{CCTK-CmplxCos}]
+  Returns the Cosine of a complex number (only C) [not yet available]
+
+\item[CCTK\_CmplxDiv]
+  [\pageref{CCTK-CmplxDiv}]
+  Returns the division of two complex numbers (only C)
+
+\item[CCTK\_CmplxExp]
+  [\pageref{CCTK-CmplxExp}]
+  Returns the Exponentiation of a complex number (only C) [not yet available]
+
+\item[CCTK\_CmplxImag]
+  [\pageref{CCTK-CmplxImag}]
+  Returns the imaginary part of a complex number (only C)
+
+\item[CCTK\_CmplxLog]
+  [\pageref{CCTK-CmplxLog}]
+  Returns the Logarithm of a complex number (only C) [not yet available]
+
+\item[CCTK\_CmplxMul]
+  [\pageref{CCTK-CmplxMul}]
+  Returns the multiplication of two complex numbers (only C)
+
+\item[CCTK\_CmplxReal]
+  [\pageref{CCTK-CmplxReal}]
+  Returns the real part of a complex number (only C)
+
+\item[CCTK\_CmplxSin]
+  [\pageref{CCTK-CmplxSin}]
+  Returns the Sine of a complex number (only C) [not yet available]
+
+\item[CCTK\_CmplxSqrt]
+  [\pageref{CCTK-CmplxSqrt}]
+  Returns the square root of a complex number (only C) [not yet available]
+
+\item[CCTK\_CmplxSub]
+  [\pageref{CCTK-CmplxSub}]
+  Returns the subtraction of two complex numbers (only C)
+
+\item[CCTK\_CoordDir]
+  [\pageref{CCTK-CoordDir}]
+  Give the direction for a given coordinate name.
+
+\item[CCTK\_CoordIndex]
+  [\pageref{CCTK-CoordIndex}]
+  Give the grid variable index for a given coordinate.
+
+\item[CCTK\_CoordRange]
+  [\pageref{CCTK-CoordRange}]
+  Return the global upper and lower bounds for a given coordinate name on a cctkGH
+
+\item[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
+
+\item[CCTK\_CoordRegisterRange]
+  [\pageref{CCTK-CoordRegisterRange}]
+  Saves the global upper and lower bounds for a given coordinate name on a cctkGH
+
+\item[CCTK\_CoordRegisterSystem]
+  [\pageref{CCTK-CoordRegisterSystem}]
+  Registers a coordinate system with a given dimension
+
+\item[CCTK\_CoordSystemDim]
+  [\pageref{CCTK-CoordDim}]
+  Provides the dimension of a given coordinate system
+
+\item[CCTK\_CoordSystemHandle]
+  [\pageref{CCTK-CoordSystemHandle}]
+  Get the handle associated with a registered coordinate system
+
+\item[CCTK\_CoordSystemName]
+  [\pageref{CCTK-CoordSystemName}]
+  Provides the name of the coordinate system identified by its handle
+
+\item[CCTK\_CreateDirectory]
+  [\pageref{CCTK-CreateDirectory}]
+  Creates a directory
+
+\item[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[CCTK\_DisableGroupComm]
+  [\pageref{CCTK-DisableGroupComm}]
+  Disable the communication for a group
+
+\item[CCTK\_DisableGroupCommI]
+  [\pageref{CCTK-DisableGroupCommI}]
+  Disable the communication for a group
+
+\item[CCTK\_DisableGroupStorage]
+  [\pageref{CCTK-DisableGroupStorage}]
+  Disable the storage for a group
+
+\item[CCTK\_DisableGroupStorageI]
+  [\pageref{CCTK-DisableGroupStorageI}]
+  Disable the storage for a group
+
+\item[CCTK\_EnableGroupComm]
+  [\pageref{CCTK-EnableGroupComm}]
+  Enable the communication for a group
+
+\item[CCTK\_EnableGroupCommI]
+  [\pageref{CCTK-EnableGroupComm}]
+  Enable the communication for a group
+
+\item[CCTK\_EnableGroupStorage]
+  [\pageref{CCTK-EnableGroupStorage}]
+  Enable the storage for a group
+
+\item[CCTK\_EnableGroupStorageI]
+  [\pageref{CCTK-EnableGroupStorage}]
+  Enable the storage for a group
+
+\item[CCTK\_Equals]
+  [\pageref{CCTK-Equals}]
+  Check a STRING or KEYWORD parameter for equality equality with a given string
+
+\item[CCTK\_Exit]
+  [\pageref{CCTK-Exit}]
+  Causes normal Cactus termination
+
+\item[CCTK\_FirstVarIndex]
+  [\pageref{CCTK-FirstVarIndex}]
+  Given a group name returns the first variable index in the group
+
+\item[CCTK\_FirstVarIndexI]
+  [\pageref{CCTK-FirstVarIndexI}]
+  Given a group index returns the first variable index in the group
+
+\item[CCTK\_FortranString]
+  [\pageref{CCTK-FortranString}]
+  Changes a C string into a Fortran string
+
+\item[CCTK\_FullName]
+  [\pageref{CCTK-FullName}]
+  Given a variable index, returns the full name of the variable
+
+\item[CCTK\_GHExtension]
+  [\pageref{CCTK-GHExtension}]
+  Get the pointer to a registered extension to the Cactus GH structure
+
+\item[CCTK\_GHExtensionHandle]
+  [\pageref{CCTK-GHExtensionHandle}]
+  Get the handle associated with a extension to the Cactus GH structure
+
+\item[CCTK\_GroupbboxGI] [\pageref{CCTK-GroupbboxGI}]
+  Given a group index, return an array of the bounding box of the group for each face
+
+\item[CCTK\_GroupbboxGN] [\pageref{CCTK-GroupbboxGN}]
+  Given a group name, return an array of the bounding box of the group for each face
+
+\item[CCTK\_GroupbboxVI] [\pageref{CCTK-GroupbboxVI}]
+  Given a variable index, return an array of the bounding box of the variable for each face
+
+\item[CCTK\_GroupbboxVN] [\pageref{CCTK-GroupbboxVN}]
+  Given a variable name, return an array of the bounding box of the variable for each face
+
+\item[CCTK\_GroupData]
+  [\pageref{CCTK-GroupData}]
+  Given a group index, returns information about the variables held in the group
+
+\item[CCTK\_GroupDynamicData]
+  [\pageref{CCTK-GroupDynamicData}]
+  Given a group index, returns information about the variables held in the group
+
+\item[CCTK\_GroupgshGI] [\pageref{CCTK-GroupgshGI}]
+  Given a group index, return an array of the global size of the group in each dimension
+
+\item[CCTK\_GroupgshGN] [\pageref{CCTK-GroupgshGN}]
+  Given a group name, return an array of the global size of the group in each dimension
+
+\item[CCTK\_GroupgshVI] [\pageref{CCTK-GroupgshVI}]
+  Given a variable index, return an array of the global size of the variable in each dimension
+
+\item[CCTK\_GroupgshVN] [\pageref{CCTK-GroupgshVN}]
+  Given a variable name, return an array of the global size of the variable in each dimension
+
+\item[CCTK\_GroupIndex]
+  [\pageref{CCTK-GroupIndex}]
+  Get the index number for a group name
+
+\item[CCTK\_GroupIndexFromVar]
+  [\pageref{CCTK-GroupIndexFromVar}]
+  Given a variable name, returns the index of the associated group
+
+\item[CCTK\_GroupIndexFromVarI]
+  [\pageref{CCTK-GroupIndexFromVarI}]
+  Given a variable index, returns the index of the associated group
+
+\item[CCTK\_GrouplbndGI] [\pageref{CCTK-GrouplbndGI}]
+  Given a group index, return an array of the lower bounds of the group in each dimension
+
+\item[CCTK\_GrouplbndGN] [\pageref{CCTK-GrouplbndGN}]
+  Given a group name, return an array of the lower bounds of the group in each dimension
+
+\item[CCTK\_GrouplbndVI] [\pageref{CCTK-GrouplbndVI}]
+  Given a variable index, return an array of the lower bounds of the variable in each dimension
+
+\item[CCTK\_GrouplbndVN] [\pageref{CCTK-GrouplbndVN}]
+  Given a variable name, return an array of the lower bounds of the variable in each dimension
+
+\item[CCTK\_GrouplshGI] [\pageref{CCTK-GrouplshGI}]
+  Given a group index, return an array of the local size of the group in each dimension
+
+\item[CCTK\_GrouplshGN] [\pageref{CCTK-GrouplshGN}]
+  Given a group name, return an array of the local size of the group in each dimension
+
+\item[CCTK\_GrouplshVI] [\pageref{CCTK-GrouplshVI}]
+  Given a variable index, return an array of the local size of the variable in each dimension
+
+\item[CCTK\_GrouplshVN] [\pageref{CCTK-GrouplshVN}]
+  Given a variable name, return an array of the local size of the variable in each dimension
+
+\item[CCTK\_GroupName]
+  [\pageref{CCTK-GroupName}]
+  Given a group index, returns the group name
+
+\item[CCTK\_GroupNameFromVarI]
+  [\pageref{CCTK-GroupNameFromVarI}]
+  Given a variable index, return the name of the associated group
+
+\item[CCTK\_GroupnghostzonesGI] [\pageref{CCTK-GroupnghostzonesGI}]
+  Given a group index, return an array with the number of ghostzones in each dimension of the group
+
+\item[CCTK\_GroupnghostzonesGN] [\pageref{CCTK-GroupnghostzonesGN}]
+  Given a group name, return an array with the number of ghostzones in each dimension of the group
+
+\item[CCTK\_GroupTypeFromVarI]
+  [\pageref{CCTK-GroupTypeFromVarI}]
+  Provides a group's group type index given a variable index
+
+\item[CCTK\_GroupTypeI]
+  [\pageref{CCTK-GroupTypeI}]
+  Provides a group's group type index given a group index
+
+\item[CCTK\_GroupubndGI] [\pageref{CCTK-GroupubndGI}]
+  Given a group index, return an array of the upper bounds of the group in each dimension
+
+\item[CCTK\_GroupubndGN] [\pageref{CCTK-GroupubndGN}]
+  Given a group name, return an array of the upper bounds of the group in each dimension
+
+\item[CCTK\_GroupubndVI] [\pageref{CCTK-GroupubndVI}]
+  Given a variable index, return an array of the upper bounds of the variable in each dimension
+
+\item[CCTK\_GroupubndVN] [\pageref{CCTK-GroupubndVN}]
+  Given a variable name, return an array of the upper bounds of the variable in each dimension
+
+\item[CCTK\_ImpFromVarI]
+  [\pageref{CCTK-ImpFromVarI}]
+  Given a variable index, returns the implementation name
+
+\item[CCTK\_INFO]
+  [\pageref{CCTK-INFO}]
+  Macro to print a single string as an information message to screen
+
+\item[CCTK\_InterpGridArrays]
+  [\pageref{CCTK-InterpGridArrays}]
+  Performs an interpolation on a list of CCTK grid arrays,
+  using a chosen external local interpolation operator
+
+\item[CCTK\_InterpGV]
+  [\pageref{CCTK-InterpGV}]
+  Performs an interpolation on a list of CCTK grid arrays,
+  using a chosen build-in local interpolation operator
+  (this function is being phased out;
+  it will eventually be replaced by \verb|CCTK_InterpGridArrays()|)
+
+\item[CCTK\_InterpHandle]
+  [\pageref{CCTK-InterpHandle}]
+  Returns the handle for a given interpolation operator
+
+\item[CCTK\_InterpLocal]
+  [\pageref{CCTK-InterpLocal}]
+  Performs an interpolation on a list of processor-local arrays,
+  using a chosen interpolation operator
+  (this function is being phased out; it will
+   eventually be replaced by \verb|CCTK_InterpLocalUniform()|,
+   \verb|CCTK_InterpLocalNonUniform()|, and \verb|CCTK_InterpLocalWarped()|.)
+
+%notyet \item[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[CCTK\_InterpLocalUniform]
+  [\pageref{CCTK-InterpLocalUniform}]
+  Interpolate a list of processor-local arrays
+  which define a uniformly-spaced data grid
+
+%notyet \item[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)
+
+\item[CCTK\_InterpRegisterOperatorGV]
+  [\pageref{CCTK-InterpRegisterOperatorGV}]
+  Registers a routine as a \verb|CCTK_InterpGV()|
+  interpolation operator
+
+\item[CCTK\_InterpRegisterOperatorLocal]
+  [\pageref{CCTK-InterpRegisterOperatorLocal}]
+  Registers a routine as a \verb|CCTK_InterpLocal()|
+  interpolation operator
+
+%notyet \item[CCTK\_InterpRegisterOpLocalNonUniform]
+%notyet   [\pageref{CCTK-InterpRegisterOpLocalNonUniform}]
+%notyet   Registers a routine as a \verb|CCTK_InterpLocalNonUniform()|
+%notyet   interpolation operator
+
+\item[CCTK\_InterpRegisterOpLocalUniform]
+  [\pageref{CCTK-InterpRegisterOpLocalUniform}]
+  Registers a routine as a \verb|CCTK_InterpLocalUniform()|
+  interpolation operator
+
+%notyet \item[CCTK\_InterpRegisterOpLocalWarped]
+%notyet   [\pageref{CCTK-InterpRegisterOpLocalWarped}]
+%notyet   Registers a routine as a \verb|CCTK_InterpLocalWarped()|
+%notyet   interpolation operator
+
+\item[CCTK\_IsImplementationActive]
+  [\pageref{CCTK-IsImplementationActive}]
+  Reports whether an implementation was activated in a parameter file
+
+\item[CCTK\_IsImplementationCompiled]
+  [\pageref{CCTK-IsImplementationCompiled}]
+  Reports whether an implementation was compiled into a configuration
+
+\item[CCTK\_IsThornActive]
+  [\pageref{CCTK-IsThornActive}]
+  Reports whether a thorn was activated in a parameter file
+
+\item[CCTK\_IsThornCompiled]
+  [\pageref{CCTK-IsThornActive}]
+  Reports whether a thorn was activated in a parameter file
+
+\item[CCTK\_MaxDim]
+  [\pageref{CCTK-MaxDim}]
+  Get the maximum dimension of any grid variable
+
+\item[CCTK\_MaxTimeLevels]
+  [\pageref{CCTK-MaxTimeLevels}]
+  Gives the maximum number of timelevels for a group
+
+\item[CCTK\_MaxTimeLevelsGI]
+  [\pageref{CCTK-MaxTimeLevelsGI}]
+  Gives the maximum number of timelevels for a group
+
+\item[CCTK\_MaxTimeLevelsGN]
+  [\pageref{CCTK-MaxTimeLevelsGN}]
+  Gives the maximum number of timelevels for a group
+
+\item[CCTK\_MaxTimeLevelsVI]
+  [\pageref{CCTK-MaxTimeLevelsVarI}]
+  Gives the maximum number of timelevels for a variable
+
+\item[CCTK\_MaxTimeLevelsVN]
+  [\pageref{CCTK-MaxTimeLevelsVN}]
+  Gives the maximum number of timelevels for a variable
+
+\item[CCTK\_MyProc]
+  [\pageref{CCTK-MyProc}]
+  Get the local processor number
+
+\item[CCTK\_nProcs]
+  [\pageref{CCTK-nProcs}]
+  Get the total number of processors used
+
+\item[CCTK\_NullPointer]
+  [\pageref{CCTK-NullPointer}]
+  Returns a C-style NULL pointer value
+
+\item[CCTK\_NumGroups]
+  [\pageref{CCTK-NumGroups}]
+  Get the number of groups of variables compiled in the code
+
+\item[CCTK\_NumIOMethods]
+  [\pageref{CCTK-NumIOMethods}]
+  Returns the total number of I/O methods registered with the flesh
+
+\item[CCTK\_NumVars]
+  [\pageref{CCTK-NumVars}]
+  Get the number of grid variables compiled in the code
+
+\item[CCTK\_NumVarsInGroup]
+  [\pageref{CCTK-NumVarsInGroup}]
+  Provides the number of variables in a group from the group name
+
+\item[CCTK\_NumVarsInGroupI]
+  [\pageref{CCTK-NumVarsInGroupI}]
+  Provides the number of variables in a group from the group index
+
+\item[CCTK\_OutputGH]
+  [\pageref{CCTK-OutputGH}]
+  Conditional output of all variables on a GH by all I/O methods
+
+\item[CCTK\_OutputVar]
+  [\pageref{CCTK-OutputVar}]
+  Output of a single variable by all I/O methods
+
+\item[CCTK\_OutputVarAs]
+  [\pageref{CCTK-OutputVarAs}]
+  Output of a single variable as an alias by all I/O methods
+
+\item[CCTK\_OutputVarAsByMethod]
+  [\pageref{CCTK-OutputVarAsByMethod}]
+  Output of a single variable as an alias by a single I/O method
+
+\item[CCTK\_OutputVarByMethod]
+  [\pageref{CCTK-OutputVarByMethod}]
+  Output of a single variable by a single I/O method
+
+\item[CCTK\_ParallelInit]
+  [\pageref{CCTK-ParallelInit}]
+  Initializes the parallel subsystem
+
+\item[CCTK\_PARAMWARN]
+  [\pageref{CCTK-PARAMWARN}]
+  Prints a warning from parameter checking, and possibly stops the code
+
+\item[CCTK\_PointerTo]
+  [\pageref{CCTK-PointerTo}]
+  Returns the address of a variable passed in by reference from a fortran routine
+
+\item[CCTK\_PrintGroup]
+  [\pageref{CCTK-PrintGroup}]
+  Prints a group name from its index
+
+\item[CCTK\_PrintString]
+  [\pageref{CCTK-PrintString}]
+  Prints a Cactus string to screen (from Fortran)
+
+\item[CCTK\_PrintVar]
+  [\pageref{CCTK-PrintVar}]
+  Prints a variable name from its index
+
+\item[CCTK\_QueryGroupStorage]
+  [\pageref{CCTK-QueryGroupStorage}]
+  Queries storage for a group given by its group name
+
+\item[CCTK\_QueryGroupStorageB]
+  [\pageref{CCTK-QueryGroupStorageB}]
+
+
+\item[CCTK\_QueryGroupStorageI]
+  [\pageref{CCTK-QueryGroupStorageI}]
+  Queries storage for a group given by its group index
+
+
+%\item[CCTK\_Reduce]
+%  [\pageref{CCTK-Reduce}]
+%  Perform a reduction operation using a registered operator
+
+\item[CCTK\_ReductionHandle]
+  [\pageref{CCTK-ReductionHandle}]
+  Get the handle for a registered reduction operator
+
+\item[CCTK\_RegisterBanner]
+  [\pageref{CCTK-RegisterBanner}]
+  Register a banner for a thorn
+
+\item[CCTK\_RegisterGHExtension]
+  [\pageref{CCTK-RegisterGHExtension}]
+  Register the name of an extension to the Cactus GH.
+
+\item[CCTK\_RegisterGHExtensionInitGH]
+  [\pageref{CCTK-RegisterGHExtensionInitGH}]
+  Register a routine for providing initialisation for an extension to the Cactus GH
+
+\item[CCTK\_RegisterGHExtensionScheduleTraverseGH]
+  [\pageref{CCTK-RegisterGHExtensionScheduleTraverseGH}]
+  Register a GH extension schedule traversal routine
+
+\item[CCTK\_RegisterGHExtensionSetupGH]
+  [\pageref{CCTK-RegisterGHExtensionSetupGH}]
+  Register a routine for setting up an extension to the Cactus GH
+
+\item[CCTK\_RegisterIOMethod]
+  [\pageref{CCTK-RegisterIOMethod}]
+  Registers a new I/O method
+
+\item[CCTK\_RegisterIOMethodOutputGH]
+  [\pageref{CCTK-RegisterIOMethodOutputGH}]
+  Registers an I/O method's routine for conditional output
+
+\item[CCTK\_RegisterIOMethodOutputVarAs]
+  [\pageref{CCTK-RegisterIOMethodOutputVarAs}]
+  Registers an I/O method's routine for unconditional output
+
+\item[CCTK\_RegisterIOMethodTimeToOutput]
+  [\pageref{CCTK-RegisterIOMethodTimeToOutput}]
+  Register a routine for deciding if it is time to output for an IO method
+
+\item[CCTK\_RegisterIOMethodTriggerOutput]
+  [\pageref{CCTK-RegisterIOMethodTriggerOutput}]
+  Register a routine for dealing with trigger output for an IO method
+
+\item[CCTK\_RegisterReductionOperator]
+  [\pageref{CCTK-RegisterReductionOperator}]
+  Register a function as providing a reduction operation
+
+
+\item[CCTK\_SetupGH]
+  [\pageref{CCTK-SetupGH}]
+  Sets up a CCTK grid hierarchy
+
+\item[CCTK\_SyncGroup]
+  [\pageref{CCTK-SyncGroup}]
+  Synchronize the ghost zones for a group of variables
+
+
+\item[CCTK\_VarDataPtr]
+  [\pageref{CCTK-VarDataPtr}]
+  Returns the data pointer for a grid variable
+
+\item[CCTK\_VarDataPtrB]
+  [\pageref{CCTK-VarDataPtrB}]
+  Returns the data pointer for a grid variable from the variable index or name
+
+\item[CCTK\_VarDataPtrI]
+  [\pageref{CCTK-VarDataPtrI}]
+  Returns the data pointer for a grid variable from the variable index
+
+\item[CCTK\_VarIndex]
+   [\pageref{CCTK-VarIndex}]
+  Get the index for a variable
+
+\item[CCTK\_VarName]
+  [\pageref{CCTK-VarName}]
+  Given a variable index, returns the variable name
+
+\item[CCTK\_VarTypeI]
+  [\pageref{CCTK-VarTypeI}]
+  Provides variable type index from the variable index
+
+\item[CCTK\_VarTypeSize]
+  [\pageref{CCTK-VarTypeSize}]
+  Provides variable type size in bytes from the variable type index
+
+\item[CCTK\_VInfo]
+  [\pageref{CCTK-VInfo}]
+  Prints a formatted string with a variable argument list as an information
+  message to screen
+
+\item[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[CCTK\_WARN]
+  [\pageref{CCTK-WARN}]
+  Macro to print a single string as a warning message to standard error and
+  possibly stop the code
+
+\end{Lentry}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Full Description of Functions}
+
+%%%%%
+% AAA
+%%%%%
+
+% CommOverloadables.c
+\begin{CCTKFunc}{CCTK\_Abort}{Abnormal Cactus termination}
+\label{CCTK-Abort}
+\subroutine{int}{integer}{istat}
+\argument{cGH *}{CCTK\_POINTER}{cctkGH}
+\argument{int}{integer}{value}
+\showargs
+\begin{params}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\parameter{value}{the return code to abort with}
+\end{params}
+\begin{discussion}
+This routine causes an immediate, abnormal Cactus termination.
+It never returns to the caller.
+\end{discussion}
+\end{CCTKFunc}
+
+
+% cctk_GroupsOnGH.h
+\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);
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call CCTK_ActiveTimeLevels(timelevels, cctkGH, groupname)
+
+integer       timelevels
+CCTK_POINTER  cctkGH
+character*(*) groupname
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{NULL}
+The number of timelevels
+\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}
+\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 {\tt CCTK\_MaxTimeLevels}.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{CCTK-MaxTimeLevels}
+Return the maximum number of timelevels
+\end{SeeAlso}
+\begin{SeeAlso}{CCTK-GroupStorageIncrease}
+Base function overloaded by driver which increase the number of timelevels 
+with storage and also returns the number of active timelevels.
+\end{SeeAlso}
+\end{SeeAlsoSection}
+%\begin{ErrorSection}
+%\end{ErrorSection}
+%\begin{ExampleSection}
+%\end{ExampleSection}
+\end{FunctionDescription}
+
+
+
+% cctk_Comm.h
+\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 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 \texttt{CCTK\_GroupgshGN} instead.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{CCTK\_GroupgshGN}
+Returns an array with the array size in all dimensions.
+\end{SeeAlso}
+\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
+\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 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 \texttt{CCTK\_GroupgshGI} instead.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{CCTK\_GroupgshGI}
+Returns an array with the array size in all dimensions.
+\end{SeeAlso}
+\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{CCTKFunc}{CCTK\_Barrier}{Synchronizes all processors at a given execution point}
+\label{CCTK-Barrier}
+\subroutine{int}{integer}{istat}
+\argument{cGH *}{CCTK\_POINTER}{cctkGH}
+\showargs
+\begin{params}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\parameter{istat}{return code}
+\end{params}
+\begin{discussion}
+\end{discussion}
+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 {\t CCTK\_Barrier()}. Note that this is a collective operation --
+it must be called by all processors otherwise the code will hang.
+\end{CCTKFunc}
+
+
+%%%%%
+% CCC
+%%%%%
+
+\begin{CCTKFunc}{CCTK\_Cmplx}{Turns two real numbers into a complex number}
+\label{CCTK-Cmplx}
+\subroutine{CCTK\_COMPLEX}{}{cmpno}
+\argument{CCTK\_REAL}{}{realpart}
+\argument{CCTK\_REAL}{}{imagpart}
+\showcargs
+\begin{params}
+\parameter{cmpno}{The complex number}
+\parameter{realpart}{The real part of the complex number}
+\parameter{imagpart}{The imaginary part of the complex number}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t cmpno = CCTK\_Cmplx(re,im)};
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_CmplxAbs}{Absolute value of a complex number}
+\label{CCTK-CmplxAbs}
+\subroutine{CCTK\_COMPLEX}{}{absval}
+\argument{CCTK\_COMPLEX}{}{inval}
+\showcargs
+\begin{params}
+\parameter{absval}{The computed absolute value}
+\parameter{realpart}{The complex number who absolute value is to be returned}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t absval = CCTK\_CmplxAbs(inval)};
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_CmplxAdd}{Sum of two complex numbers}
+\label{CCTK-CmplxAdd}
+\subroutine{CCTK\_COMPLEX}{}{addval}
+\argument{CCTK\_COMPLEX}{}{inval1}
+\argument{CCTK\_COMPLEX}{}{inval2}
+\showcargs
+\begin{params}
+\parameter{addval}{The computed added value}
+\parameter{inval1}{The first complex number to be summed}
+\parameter{inval2}{The second complex number to be summed}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t addval = CCTK\_CmplxAdd(inval1,inval2)};
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_CmplxConjg}{Complex conjugate of a complex number}
+\label{CCTK-CmplxConjg}
+\subroutine{CCTK\_COMPLEX}{}{conjgval}
+\argument{CCTK\_COMPLEX}{}{inval}
+\showcargs
+\begin{params}
+\parameter{conjval}{The computed conjugate}
+\parameter{inval}{The complex number to be conjugated}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t conjgval = CCTK\_CmplxConjg(inval)};
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_CmplxCos}{Cosine of a complex number}
+\label{CCTK-CmplxCos}
+\subroutine{CCTK\_COMPLEX}{}{cosval}
+\argument{CCTK\_COMPLEX}{}{inval}
+\showcargs
+\begin{params}
+\parameter{cosval}{The computed cosine}
+\parameter{inval}{The complex number to be cosined}
+\end{params}
+\begin{discussion}
+{\bf NOT YET AVAILABLE}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t cosval = CCTK\_CmplxCos(inval)};
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_CmplxDiv}{Division of two complex numbers}
+\label{CCTK-CmplxDiv}
+\subroutine{CCTK\_COMPLEX}{}{divval}
+\argument{CCTK\_COMPLEX}{}{inval1}
+\argument{CCTK\_COMPLEX}{}{inval2}
+\showcargs
+\begin{params}
+\parameter{divval}{The divided value}
+\parameter{inval1}{The enumerator}
+\parameter{inval1}{The denominator}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t divval = CCTK\_CmplxDiv(inval1,inval2)};
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_CmplxExp}{Exponent of a complex number}
+\label{CCTK-CmplxExp}
+\subroutine{CCTK\_COMPLEX}{}{expval}
+\argument{CCTK\_COMPLEX}{}{inval}
+\showcargs
+\begin{params}
+\parameter{expval}{The computed exponent}
+\parameter{inval}{The complex number to be exponented}
+\end{params}
+\begin{discussion}
+{\bf NOT YET AVAILABLE}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t expval = CCTK\_CmplxExp(inval)};
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_CmplxImag}{Imaginary part of a complex number}
+\label{CCTK-CmplxImag}
+\subroutine{CCTK\_REAL}{}{imval}
+\argument{CCTK\_COMPLEX}{}{inval}
+\showcargs
+\begin{params}
+\parameter{imval}{The imaginary part}
+\parameter{inval}{The complex number}
+\end{params}
+\begin{discussion}
+The imaginary part of a complex number $z=a+bi$ is $b$.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t imval = CCTK\_CmplxImag(inval)};
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_CmplxLog}{Logarithm of a complex number}
+\label{CCTK-CmplxLog}
+\subroutine{CCTK\_COMPLEX}{}{logval}
+\argument{CCTK\_COMPLEX}{}{inval}
+\showcargs
+\begin{params}
+\parameter{logval}{The computed logarithm}
+\parameter{inval}{The complex number}
+\end{params}
+\begin{discussion}
+{\bf NOT YET AVAILABLE}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t logval = CCTK\_CmplxLog(inval)};
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_CmplxMul}{Multiplication of two complex numbers}
+\label{CCTK-CmplxMul}
+\subroutine{CCTK\_COMPLEX}{}{mulval}
+\argument{CCTK\_COMPLEX}{}{inval1}
+\argument{CCTK\_COMPLEX}{}{inval2}
+\showcargs
+\begin{params}
+\parameter{mulval}{The product}
+\parameter{inval1}{First complex number to be multiplied}
+\parameter{inval2}{Second complex number to be multiplied}
+\end{params}
+\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{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t mulval = CCTK\_CmplxMul(inval1,inval2)};
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+
+\begin{CCTKFunc}{CCTK\_CmplxReal}{Real part of a complex number}
+\label{CCTK-CmplxReal}
+\subroutine{CCTK\_REAL}{}{reval}
+\argument{CCTK\_COMPLEX}{}{inval}
+\showcargs
+\begin{params}
+\parameter{reval}{The real part}
+\parameter{inval}{The complex number}
+\end{params}
+\begin{discussion}
+The real part of a complex number $z=a+bi$ is $a$.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t reval = CCTK\_CmplxReal(inval)};
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_CmplxSin}{Sine of a complex number}
+\label{CCTK-CmplxSin}
+\subroutine{CCTK\_COMPLEX}{}{sinval}
+\argument{CCTK\_COMPLEX}{}{inval}
+\showcargs
+\begin{params}
+\parameter{sinval}{The computed sine}
+\parameter{inval}{The complex number to be Sined}
+\end{params}
+\begin{discussion}
+{\bf NOT YET AVAILABLE}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t sinval = CCTK\_CmplxSin(inval)};
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_CmplxSqrt}{Square root of a complex number}
+\label{CCTK-CmplxSqrt}
+\subroutine{CCTK\_COMPLEX}{}{sqrtval}
+\argument{CCTK\_COMPLEX}{}{inval}
+\showcargs
+\begin{params}
+\parameter{expval}{The computed square root}
+\parameter{inval}{The complex number to be square rooted}
+\end{params}
+\begin{discussion}
+{\bf NOT YET AVAILABLE}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t sqrtval = CCTK\_CmplxSqrt(inval)};
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_CmplxSub}{Subtraction of two complex numbers}
+\label{CCTK-CmplxSub}
+\subroutine{CCTK\_COMPLEX}{}{subval}
+\argument{CCTK\_COMPLEX}{}{inval1}
+\argument{CCTK\_COMPLEX}{}{inval2}
+\showcargs
+\begin{params}
+\parameter{addval}{The computed subtracted value}
+\parameter{inval1}{The complex number to be subtracted from}
+\parameter{inval2}{The complex number to subtract}
+\end{params}
+\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{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t subval = CCTK\_CmplxSub(inval1,inval2)};
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_CoordDir}{Give the direction for a given coordinate.}
+\label{CCTK-CoordDir}
+\subroutine{int}{integer}{dir}
+\argument{const char *}{character*(*)}{coordname}
+\argument{const char *}{character*(*)}{systemname}
+\showargs
+\begin{params}
+\parameter{dir}{The direction of the coordinate}
+\parameter{coordname}{The name assigned to this coordinate}
+\parameter{systemname}{The name of the coordinate system}
+\end{params}
+\begin{discussion}
+The coordinate name is independent of the grid function name.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t direction = CCTK\_CoordDir("xdir","cart3d")};
+\\
+\hfill {\bf Fortran} && {\t call  CCTK\_COORDDIR(direction,"radius","spher3d")}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_CoordIndex}{Give the grid variable index for a given coordinate.}
+\label{CCTK-CoordIndex}
+\subroutine{int}{integer}{index}
+\argument{int}{integer}{direction}
+\argument{const char *}{character*(*)}{coordname}
+\argument{const char *}{character*(*)}{systemname}
+\showargs
+\begin{params}
+\parameter{index}{The coordinates associated grid variable index}
+\parameter{direction}{The direction of the coordinate in this coordinate system}
+\parameter{coordname}{The name assigned to this coordinate}
+\parameter{systemname}{The coordinate system for this coordinate}
+\end{params}
+\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{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t index = CCTK\_CoordIndex(-1,"xdir","cart3d")};
+\\
+\hfill {\bf Fortran} && one = 1
+\\
+&& {\t call  CCTK\_COORDINDEX(index,one,"radius","spher2d")}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% Coord.c
+\begin{CCTKFunc}{CCTK\_CoordRange}{Return the global upper and lower bounds for a given coordinate}
+\label{CCTK-CoordRange}
+\subroutine{int}{integer}{ierr}
+\argument{const cGH *}{CCTK\_POINTER}{cctkGH}
+\argument{CCTK\_REAL *}{CCTK\_REAL}{lower}
+\argument{CCTK\_REAL *}{CCTK\_REAL}{upper}
+\argument{int}{integer}{direction}
+\argument{const char *}{character*(*)}{coordname}
+\argument{const char *}{character*(*)}{systemname}
+\showargs
+\begin{params}
+\parameter{ierr}{Error code}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\parameter{lower}{Global lower bound of the coordinate (POINTER in C)}
+\parameter{upper}{Global upper bound of the coordinate (POINTER in C)}
+\parameter{direction}{Direction of coordinate in coordinate system}
+\parameter{coordname}{Coordinate name}
+\parameter{systemname}{Coordinate system name}
+\end{params}
+\begin{discussion}
+The coordinate name is independent of the grid function name.
+The coordinate range is registered by {\t 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{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t ierr = CCTK\_CoordRange(cctkGH, \&xmin, \&xmax, -1, "xdir", "mysystem");}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_COORDRANGE(ierr, cctkGH, Rmin, Rmax, -1, "radius", "sphersystem")}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% Coord.c
+\begin{CCTKFunc}{CCTK\_CoordRegisterData}{Define a coordinate in a given coordinate
+system.}
+\label{CCTK-CoordRegisterData}
+\subroutine{int}{integer}{ierr}
+\argument{int}{integer}{direction}
+\argument{const char *}{character*(*)}{gvname}
+\argument{const char *}{character*(*)}{coordname}
+\argument{const char *}{character*(*)}{systemname}
+\showargs
+\begin{params}
+\parameter{ierr}{Error code}
+\parameter{direction}{Direction of coordinate in coordinate system}
+\parameter{gvname}{Name of grid variable associated with coordinate}
+\parameter{coordname}{Name of this coordinate}
+\parameter{systemname}{Name of this coordinate system}
+\end{params}
+\begin{discussion}
+There must already be a coordinate system registered,
+using {\tt CCTK\_CoordRegisterSystem}.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t ierr = CCTK\_CoordRegisterData(1,"coordthorn::myx","x2d","cart2d")};
+\\
+\hfill {\bf Fortran} && two = 2
+\\
+&&{\t call CCTK\_COORDREGISTERDATA(ierr,two,"coordthorn::mytheta","spher3d")}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% Coord.c
+\begin{CCTKFunc}{CCTK\_CoordRegisterRange}{Assign the global maximum and minimum
+values of a coordinate on a given grid hierachy}
+\label{CCTK-CoordRegisterRange}
+\subroutine{int}{integer}{ierr}
+\argument{const cGH *}{CCTK\_POINTER}{cctkGH}
+\argument{CCTK\_REAL}{CCTK\_REAL}{min}
+\argument{CCTK\_REAL}{CCTK\_REAL}{max}
+\argument{int}{integer}{direction}
+\argument{const char *}{character*(*)}{coordname}
+\argument{const char *}{character*(*)}{systemname}
+\showargs
+\begin{params}
+\parameter{ierr}{Error code}
+\parameter{dimension}{Pointer to CCTK grid hierachy}
+\parameter{min}{Global minimum of coordinate}
+\parameter{max}{Global maximum of coordinate}
+\parameter{direction}{Direction of coordinate in coordinate system}
+\parameter{coordname}{Name of coordinate in coordinate system}
+\parameter{systemname}{Name of this coordinate system}
+\end{params}
+\begin{discussion}
+There must already
+be a coordinate registered with the given name, with {\t CCTK\_CoordRegisterData}.
+The coordinate range
+can be accessed by {\t CCTK\_CoordRange}.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t ierr = CCTK\_CoordRegisterRange(cctkGH,-1.0,1.0,1,"x2d","cart2d")};
+\\
+\hfill {\bf Fortran} && min = 0
+\\
+&& max = 3.1415d0/2.0d0
+\\
+&& two = 2
+\\
+&&{\t call CCTK\_COORDREGISTERRANGE(ierr,min,max,two,"coordthorn::mytheta","spher3d")}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% Coord.c
+\begin{CCTKFunc}{CCTK\_CoordRegisterSystem}{Assigns a coordinate system with
+a chosen name and dimension}
+\label{CCTK-CoordRegisterSystem}
+\subroutine{int}{integer}{ierr}
+\argument{int}{integer}{dimension}
+\argument{const char *}{character*(*)}{systemname}
+\showargs
+\begin{params}
+\parameter{ierr}{Error code}
+\parameter{dimension}{Dimension of coordinate system}
+\parameter{systemname}{Unique name assigned to coordinate system}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t ierr = CCTK\_CoordRegisterSystem(3,"cart3d")};
+\\
+\hfill {\bf Fortran} && three = 3
+\\
+&&{\t call CCTK\_COORDREGISTERSYSTEM(ierr,three,"sphersystem")}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_CoordSystemDim}{Give the dimension for a given coordinate system.}
+\label{CCTK-CoordDim}
+\subroutine{int}{integer}{dim}
+\argument{const char *}{character*(*)}{systemname}
+\showargs
+\begin{params}
+\parameter{dim}{The dimension of the coordinate system}
+\parameter{systemname}{The name of the coordinate system}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t dim = CCTK\_CoordSystemDim("cart3d")};
+\\
+\hfill {\bf Fortran} && {\t call  CCTK\_COORDSYSTEMDIM(dim,"spher3d")}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% Coord.c
+\begin{CCTKFunc}{CCTK\_CoordSystemHandle}{Returns the handle associated with a registered coordinate system}
+\label{CCTK-CoordSystemHandle}
+\subroutine{int}{integer}{handle}
+\argument{const char *}{character*(*)}{systemname}
+\showargs
+\begin{params}
+\parameter{handle}{The coordinate system handle}
+\parameter{systemname}{Name of the coordinate system}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t handle =  CCTK\_CoordSystemHandle("my coordinate system");}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_CoordSystemHandle(handle,"my coordinate system")}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\begin{tabular}{l}
+A negative return code indicates an invalid coordinate system name.
+\end{tabular}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% Coord.c
+\begin{CCTKFunc}{CCTK\_CoordSystemName}{Returns the name of a registered coordinate system}
+\label{CCTK-CoordSystemName}
+\subroutine{const char *}{integer}{systemname}
+\argument{int}{integer}{handle}
+\showcargs
+\begin{params}
+\parameter{handle}{The coordinate system handle}
+\parameter{systemname}{The coordinate system name}
+\end{params}
+\begin{discussion}
+No Fortran routine exists at the moment.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t systemname = CCTK\_CoordSystemName(handle);}
+\\
+\hfill         && {\t handle =  CCTK\_CoordSystemHandle(systemname);}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\begin{tabular}{l}
+A NULL pointer is returned if an invalid handle was given.
+\end{tabular}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+% Coord.c
+\begin{CCTKFunc}{CCTK\_CreateDirectory}{Create a directory with required permissions}
+\label{CCTK-CreateDirectory}
+\subroutine{int}{integer}{ierr}
+\argument{const char *}{character*(*)}{pathname}
+\argument{int}{integer}{mode}
+\showargs
+\begin{params}
+\parameter{ierr}{Error code}
+\parameter{pathname}{Directory to create}
+\parameter{mode}{Permission mode for new directory as an octal number}
+\end{params}
+\begin{discussion}
+To create a directory readable by everyone, but writeable only by the user runnning the code, the permission mode would be 0755.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t ierr = CCTK\_CreateDirectory("Results/New",0755) };
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_CREATEDIRECTORY(ierr,"Results/New",0755)}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\begin{tabular}{ll}
+0 & Directory successfully created\\
+-1 & Memory allocation failed\\
+-2 & Failed to create directory\\
+-3 & pathname exists but is not a directory\\
+\end{tabular}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+%%%%%
+% DDD
+%%%%%
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_DecomposeName}{Given the full name of a variable/group, separates the name returning both the implementation and the variable/group}
+\label{CCTK-DecomposeName}
+\subroutine{int}{integer}{istat}
+\argument{const char *}{}{fullname}
+\argument{char **}{}{imp}
+\argument{char **}{}{name}
+\showcargs
+\begin{params}
+\parameter{istat}{Status flag returned by routine}
+\parameter{fullname}{The full name of the group/variable}
+\parameter{imp}{The implementation name}
+\parameter{name}{The group/variable name}
+\end{params}
+\begin{discussion}
+\fbox{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{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t istat = CCTK\_DecomposeName("evolve::scalars",imp,name)}\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+% CommOverloadables.c
+\begin{CCTKFunc}{CCTK\_DisableGroupComm}{Turn communications off for a group of grid variables}
+\label{CCTK-DisableGroupComm}
+\subroutine{int}{integer}{istat}
+\argument{cGH *}{CCTK\_POINTER}{cctkGH}
+\argument{const char *}{character*(*)}{group}
+\showcargs
+\begin{params}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\end{params}
+\begin{discussion}
+Turning off communications means that ghost zones will not be
+communicated during a call to {\tt CCTK\_SyncGroup}. By default
+communications are all off.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% CommOverloadables.c
+\begin{CCTKFunc}{CCTK\_DisableGroupStorage}{Free the storage associated with a group of grid variables}
+\label{CCTK-DisableGroupStorage}
+\subroutine{int}{integer}{istat}
+\argument{cGH *}{CCTK\_POINTER}{cctkGH}
+\argument{const char *}{character*(*)}{group}
+\showcargs
+\begin{params}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+%%%%%
+% EEE
+%%%%%
+
+% CommOverloadables.c
+\begin{CCTKFunc}{CCTK\_EnableGroupComm}{Turn communications on for a group of grid variables}
+\label{CCTK-EnableGroupComm}
+\subroutine{int}{integer}{istat}
+\argument{cGH *}{CCTK\_POINTER}{cctkGH}
+\argument{const char *}{character*(*)}{group}
+\showcargs
+\begin{params}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\end{params}
+\begin{discussion}
+Grid variables with communication enabled will have their ghost zones communicated during a call
+to {\tt 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 {\tt schedule.ccl}
+file.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% CommOverloadables.c
+\begin{CCTKFunc}{CCTK\_EnableGroupStorage}{Assign the storage for a group of grid variables}
+\label{CCTK-EnableGroupStorage}
+\subroutine{int}{integer}{istat}
+\argument{cGH *}{CCTK\_POINTER}{cctkGH}
+\argument{const char *}{character*(*)}{group}
+\showcargs
+\begin{params}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\end{params}
+\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 {\tt schedule.ccl} file.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% CommOverloadables.c
+\begin{CCTKFunc}{CCTK\_Equals}{Checks a STRING or KEYWORD parameter for equality with a given string}
+\label{CCTK-Equals}
+\function{int}{integer}{istat}
+\argument{const char *}{CCTK\_POINTER}{param}
+\argument{const char *}{character*(*)}{value}
+\showargs
+\begin{params}
+\parameter{istat}{returns success or failure of equality}
+\parameter{param}{the STRING or KEYWORD parameter to check}
+\parameter{value}{the string value to compare against}
+\end{params}
+\begin{discussion}
+This function compares a Cactus parameter of type STRING or KEYWORD against a
+given string value. The comparison is performed case-independent,
+returning a non-zero value if the strings are the same, 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 {\t CCTK\_Equals()}
+should be used to check the value of such a parameter.
+\end{discussion}
+\end{CCTKFunc}
+
+% CommOverloadables.c
+\begin{CCTKFunc}{CCTK\_Exit}{Exit the code cleanly}
+\label{CCTK-Exit}
+\subroutine{int}{integer}{istat}
+\argument{cGH *}{CCTK\_POINTER}{cctkGH}
+\argument{int}{integer}{value}
+\showargs
+\begin{params}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\parameter{value}{the return code to abort with}
+\end{params}
+\begin{discussion}
+This routine causes an immediate, regular termination of Cactus.
+It never returns to the caller.
+\end{discussion}
+\end{CCTKFunc}
+
+
+
+
+%%%%%
+% FFF
+%%%%%
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_FirstVarIndex}{Given a group name returns the first variable index in the group}
+\label{CCTK-FirstVarIndex}
+\subroutine{int}{integer}{firstvar}
+\argument{const char *}{character*(*)}{group}
+\showargs
+\begin{params}
+\parameter{firstvar}{The first variable index in the given group}
+\parameter{group}{The group name}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t firstvar = CCTK\_FirstVarIndex("evolve::scalars") ;}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_GroupIndex(index,"evolve::scalars")}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_FirstVarIndexI}{Given a group index returns the first variable index in the group}
+\label{CCTK-FirstVarIndexI}
+\subroutine{int}{integer}{firstvar}
+\argument{int}{integer}{group}
+\showargs
+\begin{params}
+\parameter{firstvar}{The first variable index in the given group}
+\parameter{group}{The group index}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t index = CCTK\_GroupIndex("evolve::scalars")}\\
+               &&{\t firstvar = CCTK\_FirstVarIndexI(index) ;}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_GroupIndex(index,3)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_FortranString}{Changes a C string into a Fortran string}
+\label{CCTK-FortranString}
+\subroutine{int}{integer}{nchar}
+\argument{const char *}{character*(*)}{strout}
+\argument{const char *}{CCTK\_STRING}{strin}
+\showargs
+\begin{params}
+\parameter{nchar}{The number of characters in the C string, not counting the null terminator}
+\parameter{strout}{The fortran string which on output contains the C string as the first nchar characters}
+\parameter{strin}{The (pointer to the) C string containing the null terminator}
+\end{params}
+\begin{discussion}
+String or keyword parameters in Cactus are passed into Fortran routines as
+pointers to C strings. This means that they cannot be directly used as Fortran
+strings. This routine allows a Fortran string to be created from such a C string. Note that the Fortran string must be defined to have at least the same expected length as the C string. This routine is only callable from Fortran.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf Fortran} && \\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_FullName}{Given a variable index, returns the full name of the variable}
+\label{CCTK-FullName}
+\subroutine{char *}{integer}{fullname}
+\argument{int}{integer}{index}
+\showcargs
+\begin{params}
+\parameter{implementation}{The full variable name}
+\parameter{index}{The variable index}
+\end{params}
+\begin{discussion}
+\fbox{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 {\t <implementation>::<variable>}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t index = CCTK\_VarIndex("evolve::phi");}\\
+               && {\t name = CCTK\_FullName(index);}\\
+               && {\t printf ("Variable name: \%s", name);}\\
+               && {\t free (name);}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+
+
+%%%%%
+% GGG
+%%%%%
+
+% cctk_GHExtensions.h
+\begin{CCTKFunc}{CCTK\_GHExtension}{Get the pointer to a registered extension to the Cactus GH structure}
+\label{CCTK-GHExtension}
+\subroutine{void *}{CCTK\_POINTER}{extension}
+\argument{const GH *}{CCTK\_POINTER}{cctkGH}
+\argument{const char *}{character*(*)}{name}
+\showcargs
+\begin{params}
+\parameter{extension}{The pointer to the GH extension}
+\parameter{cctkGH}{The pointer to the CCTK grid hierarchy}
+\parameter{name}{The name of the GH extension}
+\end{params}
+\begin{discussion}
+No Fortran routine exists at the moment.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t void *extension = CCTK\_GHExtension(GH, "myExtension");}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+NULL    & A NULL pointer is returned if an invalid extension name was given.
+\end{errorcodes}
+\end{CCTKFunc}
+
+% cctk_GHExtensions.h
+\begin{CCTKFunc}{CCTK\_GHExtensionHandle}{Get the handle associated with a extension to the Cactus GH structure}
+\label{CCTK-GHExtensionHandle}
+\subroutine{int}{integer}{handle}
+\argument{const char *}{character*(*)}{name}
+\showargs
+\begin{params}
+\parameter{handle}{The GH extension handle}
+\parameter{group}{The name of the GH extension}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t handle =  CCTK\_GHExtension("myExtension") ;}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_GHExtension(handle,"myExtension")}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+% GroupsOnGH.h
+\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}{\rm 0} success \end{Result}
+\begin{Result}{\rm -1} incorrect dimension supplied \end{Result}
+\begin{Result}{\rm -2} data not available from driver \end{Result}
+\begin{Result}{\rm -3} called on a scalar group \end{Result}
+\begin{Result}{\rm -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}
+
+
+\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}{\rm 0} success \end{Result}
+\begin{Result}{\rm -1} incorrect dimension supplied \end{Result}
+\begin{Result}{\rm -2} data not available from driver \end{Result}
+\begin{Result}{\rm -3} called on a scalar group \end{Result}
+\begin{Result}{\rm -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
+\begin{CCTKFunc}{CCTK\_GroupData}{Given a group index, returns information about the variables held in the group.}
+\label{CCTK-GroupData}
+\function{int}{}{ierr}
+\argument{int}{}{group}
+\argument{cGroup *}{}{pgroup}
+\showcargs
+\begin{params}
+\parameter{ierr}{0 for success, negative for failure}
+\parameter{group}{group index}
+\parameter{pgroup}{returns a pointer to a structure containing group information}
+\end{params}
+\begin{discussion}
+The cGroup structure contains the information
+\begin{itemize}
+\item grouptype: The group type
+\item vartype: The type of variables in the group
+\item stagtype: The type of grid staggering for arrays
+\item dim: The dimension of variables in the group
+\item numvars: The number of variables in the group
+\item ntimelevels: The number of timelevels for variables in the group
+\end{itemize}
+No Fortran routine exists at the moment.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t cGroup pgroup;}\\
+               && {\t index = CCTK\_GroupIndex("evolve::scalars");}\\
+               &&{\t ierr = CCTK\_GroupData(index,\&pgroup);}\\
+               && {\t vtype = pgroup.vartype;}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_GroupDynamicData}{Given a group index, returns information about the variables held in the group.}
+\label{CCTK-GroupDynamicData}
+\function{int}{}{ierr}
+\argument{const cGH *}{}{cctkGH}
+\argument{int}{}{group}
+\argument{cGroupDynamicData *}{}{pdata}
+\showcargs
+\begin{params}
+\parameter{ierr}{0 for success, negative for failure}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\parameter{group}{group index}
+\parameter{pdata}{returns a pointer to a structure containing group information}
+\end{params}
+\begin{discussion}
+The cGroupDynamicData structure contains the information
+\begin{itemize}
+\item dim: The dimension of variables in the group
+\item gsh[dim]: The global size of the group in each dimension
+\item lsh[dim]: The local size of the group in each dimension
+\item lbnd[dim]: The lower bounds of the group in each dimension
+\item ubnd[dim]: The upper bounds of the group in each dimension
+\item bbox[2*dim]: The bounding box of the group for each face
+\item nghostzones[dim]: The number of ghostzones in each dimension of the group
+\end{itemize}
+No Fortran routine exists at the moment.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t cGroupDynamicData pdata;}\\
+               && {\t index = CCTK\_GroupIndex("evolve::scalars");}\\
+               &&{\t ierr = CCTK\_GroupDynamicData(cctkGH,index,\&pgroup);}\\
+               && {\t vdim = pdata.dim;}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\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}{\rm 0} success \end{Result}
+\begin{Result}{\rm -1} incorrect dimension supplied \end{Result}
+\begin{Result}{\rm -2} data not available from driver \end{Result}
+\begin{Result}{\rm -3} called on a scalar group \end{Result}
+\begin{Result}{\rm -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}
+\end{SeeAlsoSection}
+
+\end{FunctionDescription}
+
+
+\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}{\rm 0} success \end{Result}
+\begin{Result}{\rm -1} incorrect dimension supplied \end{Result}
+\begin{Result}{\rm -2} data not available from driver \end{Result}
+\begin{Result}{\rm -3} called on a scalar group \end{Result}
+\begin{Result}{\rm -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}
+\end{SeeAlsoSection}
+
+\end{FunctionDescription}
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_GroupIndex}{Get the index number for a group name}
+\label{CCTK-GroupIndex}
+\subroutine{int}{integer}{index}
+\argument{const char *}{character*(*)}{groupname}
+\showargs
+\begin{params}
+\parameter{groupname}{The name of the group}
+\end{params}
+\begin{discussion}
+The group name should be the given in its fully qualified form, that is {\t <implementation>::<group>} for a public or protected group, and {\t <thornname>::<group>} for a private group.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t index = CCTK\_GroupIndex("evolve::scalars") };
+\\
+\hfill {\bf Fortran} && call {\t CCTK\_GroupIndex(index,"evolve::scalars")}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_GroupIndexFromVar}{Given a variable name, returns the index of the associated group}
+\label{CCTK-GroupIndexFromVar}
+\subroutine{int}{integer}{groupindex}
+\argument{const char *}{character*(*)}{name}
+\showargs
+\begin{params}
+\parameter{groupindex}{The index of the group}
+\parameter{name}{The full name of the variable}
+\end{params}
+\begin{discussion}
+The variable name should be in the form {\t <implementation>::<variable>}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t groupindex = CCTK\_GroupIndexFromVar("evolve::phi") ;}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_GROUPINDEXFROMVAR(groupindex,"evolve::phi")}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_GroupIndexFromVarI}{Given a variable index, returns the index of the associated group}
+\label{CCTK-GroupIndexFromVarI}
+\subroutine{int}{integer}{groupindex}
+\argument{int}{integer}{varindex}
+\showargs
+\begin{params}
+\parameter{groupindex}{The index of the group}
+\parameter{varindex}{The index of the variable}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t index = CCTK\_VarIndex("evolve::phi");} \\
+               && {\t groupindex = CCTK\_GroupIndexFromVarI(index) ;}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_VARINDEX("evolve::phi")}\\
+                     &&call {\t CCTK\_GROUPINDEXFROMVARI(groupindex,index)}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\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}{\rm 0} success \end{Result}
+\begin{Result}{\rm -1} incorrect dimension supplied \end{Result}
+\begin{Result}{\rm -2} data not available from driver \end{Result}
+\begin{Result}{\rm -3} called on a scalar group \end{Result}
+\begin{Result}{\rm -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}
+
+
+\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}{\rm 0} success \end{Result}
+\begin{Result}{\rm -1} incorrect dimension supplied \end{Result}
+\begin{Result}{\rm -2} data not available from driver \end{Result}
+\begin{Result}{\rm -3} called on a scalar group \end{Result}
+\begin{Result}{\rm -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}
+
+
+\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}{\rm 0} success \end{Result}
+\begin{Result}{\rm -1} incorrect dimension supplied \end{Result}
+\begin{Result}{\rm -2} data not available from driver \end{Result}
+\begin{Result}{\rm -3} called on a scalar group \end{Result}
+\begin{Result}{\rm -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\_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}
+\end{SeeAlsoSection}
+
+\end{FunctionDescription}
+
+
+\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}{\rm 0} success \end{Result}
+\begin{Result}{\rm -1} incorrect dimension supplied \end{Result}
+\begin{Result}{\rm -2} data not available from driver \end{Result}
+\begin{Result}{\rm -3} called on a scalar group \end{Result}
+\begin{Result}{\rm -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}
+\end{SeeAlsoSection}
+
+\end{FunctionDescription}
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_GroupName}{Given a group index, returns the group name}
+\label{CCTK-GroupName}
+\subroutine{char *}{integer}{name}
+\argument{int}{integer}{index}
+\showcargs
+\begin{params}
+\parameter{name}{The group name}
+\parameter{index}{The group index}
+\end{params}
+\begin{discussion}
+\fbox{The group name must be explicitly freed after it has been used.}
+
+No Fortran routine exists at the moment.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t index = CCTK\_GroupIndex("evolve::scalars");}\\
+               && {\t name = CCTK\_GroupName(index);}\\
+               && {\t printf ("Group name: \%s", name);}\\
+               && {\t free (name);}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_GroupNameFromVarI}{Given a variable index, return the name of the associated group}
+\label{CCTK-GroupNameFromVarI}
+\subroutine{char *}{character*(*)}{group}
+\argument{int}{integer}{varindex}
+\showcargs
+\begin{params}
+\parameter{group}{The name of the group}
+\parameter{varindex}{The index of the variable}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t index = CCTK\_VarIndex("evolve::phi");} \\
+               && {\t group = CCTK\_GroupNameFromVarI(index) ;}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+
+\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}{\rm 0} success \end{Result}
+\begin{Result}{\rm -1} incorrect dimension supplied \end{Result}
+\begin{Result}{\rm -2} data not available from driver \end{Result}
+\begin{Result}{\rm -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}
+
+
+\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}{\rm 0} success \end{Result}
+\begin{Result}{\rm -1} incorrect dimension supplied \end{Result}
+\begin{Result}{\rm -2} data not available from driver \end{Result}
+\begin{Result}{\rm -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}
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_GroupTypeFromVarI}{Provides a group's group type
+               index given a variable index}
+\label{CCTK-GroupTypeFromVarI}
+\subroutine{int}{integer}{type}
+\argument{int}{integer}{index}
+\showargs
+\begin{params}
+\parameter{type}{The group's group type index}
+\parameter{group}{The variable index}
+\end{params}
+\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 {\t CCTK\_SCALAR}, {\t CCTK\_GF}, {\t CCTK\_ARRAY}.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t index = CCTK\_GroupIndex("evolve::scalars")}\\
+               &&{\t array = (CCTK\_ARRAY == CCTK\_GroupTypeFromVarI(index)) ;}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_GROUPTYPEFROMVARI(type,3)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\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 {\t CCTK\_SCALAR}, {\t CCTK\_GF}, {\t CCTK\_ARRAY}.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{CCTK\_GroupTypeFromVarI}
+This function takes a variable index rather than a group index as its argument.
+\end{SeeAlso}
+\end{SeeAlsoSection}
+%\begin{ErrorSection}
+%\end{ErrorSection}
+%\begin{ExampleSection}
+%\end{ExampleSection}
+\end{FunctionDescription}
+
+
+\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}{\rm 0} success \end{Result}
+\begin{Result}{\rm -1} incorrect dimension supplied \end{Result}
+\begin{Result}{\rm -2} data not available from driver \end{Result}
+\begin{Result}{\rm -3} called on a scalar group \end{Result}
+\begin{Result}{\rm -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}
+
+
+\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}{\rm 0} success \end{Result}
+\begin{Result}{\rm -1} incorrect dimension supplied \end{Result}
+\begin{Result}{\rm -2} data not available from driver \end{Result}
+\begin{Result}{\rm -3} called on a scalar group \end{Result}
+\begin{Result}{\rm -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{CCTKFunc}{CCTK\_ImpFromVarI}{Given a variable index, returns the implementation name}
+\label{CCTK-ImpFromVarI}
+\subroutine{char *}{integer}{implementation}
+\argument{int}{integer}{index}
+\showcargs
+\begin{params}
+\parameter{implementation}{The implementation name}
+\parameter{index}{The variable index}
+\end{params}
+\begin{discussion}
+No Fortran routine exists at the moment
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t index = CCTK\_VarIndex("evolve::phi");}\\
+               &&{\t implementation = CCTK\_ImpFromVarI(index);}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+
+
+
+% WarnLevel.c
+\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"
+#include "cctk_WarnLevel.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.
+
+{\tt CCTK\_INFO(level, message)} expands to a call to the underlying function
+{\tt 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 {\tt CCTK\_INFO} is used
+to print a message rather than calling {\tt CCTK\_Info()} directly.
+
+To include variables in an info message from C, you can use the routine
+{\tt CCTK\_VInfo()} which accepts a variable argument list.
+To include variables from Fortran, a string must be constructed and passed
+in a {\tt CCTK\_INFO} macro.
+\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}
+\end{SeeAlsoSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "cctk.h"
+#include "cctk_WarningLevel.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\_InterpGridArrays}
+\label{CCTK-InterpGridArrays}
+Interpolate a list of distributed grid arrays
+
+(This function will eventually replace \verb|CCTK_InterpGV()|;
+see the Cactus web pages ``Development'' section for further details.)
+
+The computation is optimized for the case of interpolating a
+number of grid arrays 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 arrays.
+
+\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}{\rm 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 \verb|coord_system_handle|.  The default case is that it's $=$; see
+the discussion of the \verb|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
+\verb|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
+\verb|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 \verb|CCTK_VARIABLE_|* type codes, giving the data type of the
+interpolation-point coordinate arrays pointed to by \verb|interp_coords[]|.
+All interpolation-point coordinate arrays must be of the same data type.
+\end{Parameter}
+\begin{Parameter}{interp\_coords ($\ne$ NULL)}
+(Pointer to) an array of \verb|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
+\verb|coord_system_handle|.
+\end{Parameter}
+\begin{Parameter}{N\_input\_arrays ($\ge 0$)}
+The number of input arrays to be interpolated.
+If {\tt 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 \verb|operand_indices| is used to specify
+a nontrivial (eg. 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\_variable\_indices ($\ne$ NULL)}
+(Pointer to) an array of \verb|N_input_arrays| CCTK grid array indices (as
+returned by \verb|CCTK_VarIndex()|) specifying the input grid arrays for the
+interpolation. For any element with an index value of -1 in the grid array
+indices array, that interpolation 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}{N\_output\_arrays ($\ge 0$)}
+The number of output arrays to be returned from the interpolation.
+If {\tt N\_output\_arrays} is zero then no interpolation is done; such a call
+may be useful for setup, interpolator querying, etc.
+Note that {\tt N\_output\_arrays} may differ from {\tt N\_input\_arrays}, eg.
+if the {\tt operand\_indices} parameter-table entry is used to specify a
+nontrivial (eg. many-to-1) mapping of input arrays to output arrays.
+If such a mapping is specified, only the unique set of output arrays
+should be given in the {\tt output\_arrays} argument.
+\end{Parameter}
+\begin{Parameter}{output\_array\_type\_codes ($\ne$ NULL)}
+(Pointer to) an array of \verb|N_output_arrays| \verb|CCTK_VARIABLE_|*
+type codes giving the data types of the 1-D output arrays pointed to by
+\verb|output_arrays[]|.
+\end{Parameter}
+\begin{Parameter}{output\_arrays ($\ne$ NULL)}
+(Pointer to) an array of \verb|N_output_arrays| pointers to the
+(user-supplied) 1-D output arrays for the interpolation.
+If any of the pointers in the {\tt output\_arrays} array is NULL, then that
+interpolation 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}
+This function interpolates a list of CCTK grid arrays (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 {\tt 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
+arrays -- calls {\tt CCTK\_InterpLocalUniform()} to invoke an external
+local interpolation operator (as identified by an interpolation handle).
+
+Additional parameters for the interpolation operation of both
+{\tt CCTK\_InterpGridArrays()} and {\tt 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 \verb|"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 \verb|order|, a \verb|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
+{\tt CCTK\_InterpGridArrays()} passes to it. Each thorn providing a
+{\tt CCTK\_InterpLocalUniform()} interpolator should document what options it
+requires from the global interpolator.
+}
+These will overwrite any entries
+with the same keys in the \verb|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 {\tt 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.
+
+The semantics of {\tt 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,
+{\tt 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
+arrays and properly overloads {\tt 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 (eg. {\tt PUGHInterp} in the {\tt CactusPUGH} arrangement,
+{\tt LocalInterp} in the {\tt CactusBase} arrangement, and/or
+{\tt AEILocalInterp} in the {\tt AEIThorns} arrangement) for details.
+
+Note that in a multiprocessor Cactus run, it's the user's responsibility
+to choose the interprocessor ghost-zone size (\verb|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 \verb|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}
+\begin{SeeAlso}{CCTK\_InterpGV()}
+Older API to interpolate a list of Cactus grid arrays.
+\end{SeeAlso}
+\begin{SeeAlso}{CCTK\_InterpLocal()}
+Older API to interpolate a list of processor-local arrays.
+\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
+\verb|cctk_Interp.h|, \verb|util_ErrorCodes.h|, and/or \verb|util_Table.h|
+in the \verb|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 (eg.~\verb|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
+\verb|Util_Table*()| routines used to get parameters from
+(and/or set results in) the parameter table
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+Here's a simple example to do quartic 3-D interpolation of a real
+and a complex grid array, at 1000 interpolation points:
+\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];
+static const CCTK_INT interp_coord_type_codes[N_DIMS]
+        = { CCTK_VARIABLE_REAL, CCTK_VARIABLE_REAL, CCTK_VARIABLE_REAL };
+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(-1, "can't get operator handle!");
+}
+
+coord_system_handle = CCTK_CoordSystemHandle("cart3d");
+if (coord_system_handle < 0)
+{
+  CCTK_WARN(-1, "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, interp_coord_type_codes,
+                                           interp_coords,
+                          N_INPUT_ARRAYS, input_array_variable_indices,
+                          N_OUTPUT_ARRAYS, output_array_type_codes,
+                                           output_arrays) < 0)
+{
+  CCTK_WARN(-1, "error return from interpolator!");
+}
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% Interp.c
+\begin{CCTKFunc}{CCTK\_InterpGV}%%%
+{Perform an interpolation on a list of distributed CCTK grid variables,
+using a chosen interpolation operator
+\\[\baselineskip]
+This function is being phased out; it will eventually be replaced by
+{\t CCTK\_InterpGridArrays()}.}
+\label{CCTK-InterpGV}
+\subroutine{int}{integer}{ierr}
+\argument{cGH *}{CCTK\_POINTER}{cctkGH}
+\argument{int}{integer}{operator\_handle}
+\argument{int}{integer}{coord\_system\_handle}
+\argument{int}{integer}{num\_points}
+\argument{int}{integer}{num\_in\_array\_indices}
+\argument{int}{integer}{num\_out\_arrays}
+\argument{...}{...}{}
+\argument{{\it num\_dims} * void *}{{\it num\_dims} * CCTK\_POINTER}{interp\_coord\_arrays}
+\argument{{\it num\_dims} * int}{{\it num\_dims} * integer}{interp\_coord\_array\_types}
+\argument{{\it num\_array\_indices} * int}{{\it num\_array\_indices} * integer}{in\_array\_indices}
+\argument{{\it num\_out\_arrays} * void *}{{\it num\_out\_arrays} * CCTK\_POINTER}{out\_arrays}
+\argument{{\it num\_out\_arrays} * int}{{\it num\_out\_arrays} * integer}{out\_array\_types}
+\showargs
+\begin{params}
+\parameter{cctkGH}{Pointer to the CCTK grid hierarchy}
+\parameter{operator\_handle}{Handle for the interpolation operator}
+\parameter{coord\_system\_handle}{Handle for the coordinate system.\newline
+This handle denotes the coordinate system to use for locating the points to
+interpolate at.}
+\parameter{num\_points}{Number of points to be interpolated on this processor}
+\parameter{num\_in\_array\_indices}{Number of passed input array indices}
+\parameter{num\_out\_arrays}{Number of passed output arrays}
+\parameter{...}{Variable argument list, with arguments as following}
+\parameter{interp\_coord\_arrays}{List of coordinate arrays for points to interpolate at ({\it num\_dims} is the number of dimensions of the coordinate system)}
+\parameter{interp\_coord\_array\_types}{List of CCTK datatypes for coordinate arrays}
+\parameter{in\_array\_indices}{List of CCTK grid variables to interpolate (given by their indices)}
+\parameter{out\_arrays}{List of output arrays}
+\parameter{out\_array\_types}{List of CCTK datatypes for output arrays}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t
+int interp\_handle, coord\_system\_handle;
+CCTK\_REAL coord\_x[NUM\_POINTS], coord\_y[NUM\_POINTS];
+int my\_grid\_fn1,  my\_grid\_fn2;
+CCTK\_REAL my\_out\_array1[NUM\_POINTS];
+CCTK\_COMPLEX  my\_out\_array2[NUM\_POINTS];\linebreak
+interp\_handle =\vfill
+\hspace{2ex} CCTK\_InterpHandle("my interpolation operator");
+coord\_system\_handle =\vfill
+\hspace{2ex} CCTK\_CoordSystemHandle("my 2D coordinate system");
+my\_grid\_fn1 = CCTK\_VarIndex("myThorn::myGF1");
+my\_grid\_fn2 = CCTK\_VarIndex("myThorn::myGF2");\linebreak
+ierr = CCTK\_InterpGV(cctkGH,\vfill
+\hspace{2ex} interp\_handle, coord\_system\_handle,\vfill
+\hspace{2ex} NUM\_POINTS, 2, 2,\vfill
+\hspace{2ex} coord\_x, coord\_y,\vfill
+\hspace{2ex} CCTK\_VARIABLE\_REAL, CCTK\_VARIABLE\_REAL,\vfill
+\hspace{2ex} my\_grid\_fn1,  my\_grid\_fn2,\vfill
+\hspace{2ex} my\_out\_array1, my\_out\_array2,\vfill
+\hspace{2ex} CCTK\_VARIABLE\_REAL, CCTK\_VARIABLE\_COMPLEX);
+}
+\\
+\hfill {\bf Fortran} && {\t
+integer interp\_handle, coord\_system\_handle
+CCTK\_REAL coord(NUM\_POINTS)
+integer my\_grid\_fn1,  my\_grid\_fn2, my\_grid\_fn3
+CCTK\_REAL my\_out\_array1(NUM\_POINTS)
+CCTK\_COMPLEX  my\_out\_array2(NUM\_POINTS)
+CCTK\_INT my\_out\_array3(NUM\_POINTS)\linebreak
+call CCTK\_InterpHandle(interp\_handle,\vfill\hspace{2ex}"my interpolation operator")
+call CCTK\_CoordSystemHandle(coord\_system\_handle,\vfill\hspace{2ex}"my 1D coordinate system")
+call CCTK\_VarIndex(my\_grid\_fn1, "myThorn::myGF1")
+call CCTK\_VarIndex(my\_grid\_fn2, "myThorn::myGF2")
+call CCTK\_VarIndex(my\_grid\_fn2, "myThorn::myGF3")\linebreak
+call CCTK\_InterpGV(ierr, cctkGH,\vfill
+\hspace{2ex} interp\_handle, coord\_system\_handle,\vfill
+\hspace{2ex} NUM\_POINTS, 3, 3,\vfill
+\hspace{2ex} coord,\vfill
+\hspace{2ex} CCTK\_VARIABLE\_REAL,\vfill
+\hspace{2ex} my\_grid\_fn1,  my\_grid\_fn2, my\_grid\_fn3,\vfill
+\hspace{2ex} my\_out\_array1, my\_out\_array2, my\_out\_array3,\vfill
+\hspace{2ex} CCTK\_VARIABLE\_REAL, CCTK\_VARIABLE\_COMPLEX, CCTK\_VARIABLE\_INT)
+}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\begin{tabular}{l}
+A negative return code indicates an error condition:
+\end{tabular}
+\begin{tabular}{ll}
+-1 & Invalid interpolation operator handle passed\\
+-2 & Invalid coordinate system handle passed\\
+\end{tabular}
+\end{errorcodes}
+\end{CCTKFunc}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% Interp.c
+\begin{CCTKFunc}{CCTK\_InterpHandle}{Return the handle for a given interpolation operator}
+\label{CCTK-InterpHandle}
+\subroutine{int}{integer}{handle}
+\argument{const char *}{character*(*)}{operator}
+\showargs
+\begin{params}
+\parameter{handle}{Handle for the interpolation operator}
+\parameter{operator}{Name of interpolation operator}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t handle =  CCTK\_InterpHandle("my interpolation operator");}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_InterpHandle(handle,"my interpolation operator")}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\begin{tabular}{l}
+A negative value is returned for invalid/unregistered interpolation operator names.
+\end{tabular}
+\end{errorcodes}
+\end{CCTKFunc}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% Interp.c
+\begin{CCTKFunc}{CCTK\_InterpLocal}%%%
+{Perform an interpolation on a list of processor-local arrays,
+using a chosen interpolation operator
+\\[\baselineskip]
+This function is being phased out; it will eventually be replaced by
+{\t CCTK\_InterpLocalUniform()} et al.}
+\label{CCTK-InterpLocal}
+\subroutine{int}{integer}{ierr}
+\argument{cGH *}{CCTK\_POINTER}{cctkGH}
+\argument{int}{integer}{operator\_handle}
+\argument{int}{integer}{num\_points}
+\argument{int}{integer}{num\_dims}
+\argument{int}{integer}{num\_in\_arrays}
+\argument{int}{integer}{num\_out\_arrays}
+\argument{...}{...}{}
+\argument{{\it num\_dims} * int}{{\it num\_dims} * integer}{dims}
+\argument{{\it num\_dims} * void *}{{\it num\_dims} * CCTK\_POINTER}{coord\_arrays}
+\argument{{\it num\_dims} * int}{{\it num\_dims} * integer}{coord\_array\_types}
+\argument{{\it num\_dims} * void *}{{\it num\_dims} * CCTK\_POINTER}{interp\_coord\_arrays}
+\argument{{\it num\_dims} * int}{{\it num\_dims} * integer}{interp\_coord\_array\_types}
+\argument{{\it num\_in\_arrays} * void *}{{\it num\_in\_arrays} * CCTK\_POINTER}{in\_arrays}
+\argument{{\it num\_in\_arrays} * int}{{\it num\_in\_arrays} * integer}{in\_array\_types}
+\argument{{\it num\_out\_arrays} * void *}{{\it num\_out\_arrays} * CCTK\_POINTER}{out\_arrays}
+\argument{{\it num\_out\_arrays} * int}{{\it num\_out\_arrays} * integer}{out\_array\_types}
+\showargs
+\begin{params}
+\parameter{cctkGH}{Pointer to the CCTK grid hierarchy}
+\parameter{operator\_handle}{Handle for the interpolation operator}
+\parameter{num\_points}{Number of points to be interpolated on this processor}
+\parameter{num\_dims}{Number of dimensions of the coordinate system}
+\parameter{num\_in\_arrays}{Number of passed input arrays}
+\parameter{num\_out\_arrays}{Number of passed output arrays}
+\parameter{...}{Variable argument list, with arguments as following}
+\parameter{dims}{Dimensions of the underlying coordinate system}
+\parameter{coord\_arrays}{List of coordinate arrays describing the coordinate system}
+\parameter{coord\_array\_types}{List of CCTK datatypes for coordinate arrays}
+\parameter{interp\_coord\_arrays}{List of interpolation coordinate arrays}
+\parameter{interp\_coord\_array\_types}{List of CCTK datatypes for interpolation coordinate arrays}
+\parameter{in\_arrays}{List of input arrays to interpolate}
+\parameter{in\_array\_types}{List of CCTK datatypes for input arrays}
+\parameter{out\_arrays}{List of output arrays}
+\parameter{out\_array\_types}{List of CCTK datatypes for output arrays}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t
+int interp\_handle;
+CCTK\_REAL coord\_x[XDIM], coord\_y[YDIM];
+CCTK\_REAL interp\_coord\_x[NUM\_POINTS], interp\_coord\_y[NUM\_POINTS];
+CCTK\_REAL my\_in\_array1[NUM\_POINTS];
+CCTK\_COMPLEX  my\_in\_array2[NUM\_POINTS];
+CCTK\_REAL my\_out\_array1[NUM\_POINTS];
+CCTK\_COMPLEX  my\_out\_array2[NUM\_POINTS];\linebreak
+interp\_handle =\vfill
+\hspace{2ex} CCTK\_InterpHandle("my interpolation operator");
+ierr = CCTK\_InterpLocal(cctkGH,\vfill
+\hspace{2ex} interp\_handle, NUM\_POINTS, 2, 2, 2,\vfill
+\hspace{2ex} XDIM, YDIM, coord\_x, coord\_y,\vfill
+\hspace{2ex} CCTK\_VARIABLE\_REAL, CCTK\_VARIABLE\_REAL,\vfill
+\hspace{2ex} interp\_coord\_x, interp\_coord\_y,\vfill
+\hspace{2ex} CCTK\_VARIABLE\_REAL, CCTK\_VARIABLE\_REAL,\vfill
+\hspace{2ex} my\_in\_array1, my\_in\_array2,\vfill
+\hspace{2ex} CCTK\_VARIABLE\_REAL, CCTK\_VARIABLE\_COMPLEX);
+\hspace{2ex} my\_out\_array1, my\_out\_array2,\vfill
+\hspace{2ex} CCTK\_VARIABLE\_REAL, CCTK\_VARIABLE\_COMPLEX);
+}
+\\
+\hfill {\bf Fortran} && {\t
+integer interp\_handle
+CCTK\_REAL coord(XDIM)
+CCTK\_REAL interp\_coord(NUM\_POINTS)
+CCTK\_REAL my\_in\_array1(NUM\_POINTS), my\_out\_array1(NUM\_POINTS)
+CCTK\_COMPLEX my\_in\_array2(NUM\_POINTS), my\_out\_array2(NUM\_POINTS)
+CCTK\_INT my\_in\_array3(NUM\_POINTS), my\_out\_array3(NUM\_POINTS)\linebreak
+call CCTK\_InterpHandle(interp\_handle,\vfill\hspace{2ex}"my interpolation operator")
+call CCTK\_InterpLocal(ierr, cctkGH,\vfill
+\hspace{2ex} interp\_handle, NUM\_POINTS, 1, 3, 3,\vfill
+\hspace{2ex} XDIM, coord,\vfill
+\hspace{2ex} CCTK\_VARIABLE\_REAL,\vfill
+\hspace{2ex} interp\_coord,\vfill
+\hspace{2ex} CCTK\_VARIABLE\_REAL,\vfill
+\hspace{2ex} my\_in\_array1, my\_in\_array2, my\_in\_array3,\vfill
+\hspace{2ex} CCTK\_VARIABLE\_REAL, CCTK\_VARIABLE\_COMPLEX,\vfill
+\hspace{2ex} CCTK\_VARIABLE\_INT,\vfill
+\hspace{2ex} my\_out\_array1, my\_out\_array2, my\_out\_array3,\vfill
+\hspace{2ex} CCTK\_VARIABLE\_REAL, CCTK\_VARIABLE\_COMPLEX,\vfill
+\hspace{2ex} CCTK\_VARIABLE\_INT)
+}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\begin{tabular}{l}
+A negative return code indicates an error condition:
+\end{tabular}
+\begin{tabular}{ll}
+-1 & Invalid interpolation operator handle passed\\
+\end{tabular}
+\end{errorcodes}
+\end{CCTKFunc}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%notyet % Interp.c
+%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 (\verb|CCTK_InterpLocalNonUniform()|, \verb|CCTK_InterpLocalUniform()|,
+%notyet and \verb|CCTK_InterpLocalWarped()| will eventually replace
+%notyet \verb|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}{\rm 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 \verb|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 \verb|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 \verb|order|, a \verb|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 \verb|CCTK_VARIABLE_|* type codes, giving the data type of the
+%notyet 1-D coordinate arrays pointed to by \verb|coord_arrays[]|.
+%notyet \end{Parameter}
+%notyet \begin{Parameter}{coord\_array\_dims ($\ne$ NULL)}
+%notyet \hbox{}
+%notyet (Pointer to) an array of \verb|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 \verb|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 \verb|CCTK_VARIABLE_|* type codes, giving the data type
+%notyet of the 1-D interpolation-point-coordinate arrays pointed to by
+%notyet \verb|interp_coords[]|.
+%notyet \end{Parameter}
+%notyet \begin{Parameter}{interp\_coords ($\ne$ NULL)}
+%notyet \hbox{}
+%notyet (Pointer to) an array of \verb|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 \verb|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 \verb|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 \verb|N_dims| integers giving the dimensions
+%notyet of the \verb|N_dims|-D input arrays.  By default all the input arrays
+%notyet are taken to have these dimensions, with \verb|[0]| the most contiguous
+%notyet axis and \verb|[N_dims-1]| the least contiguous axis, and array subscripts
+%notyet in the range \verb|0 <= subscript < input_array_dims[axis]|.  See the
+%notyet discussion of the \verb|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 \verb|N_input_arrays| \verb|CCTK_VARIABLE_|*
+%notyet type codes giving the data types of the \verb|N_dims|-D input arrays
+%notyet pointed to by \verb|input_arrays[]|.
+%notyet \end{Parameter}
+%notyet \begin{Parameter}{input\_arrays ($\ne$ NULL)}
+%notyet \hbox{}
+%notyet (Pointer to) an array of \verb|N_input_arrays| pointers to the
+%notyet \verb|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 \verb|N_output_arrays| \verb|CCTK_VARIABLE_|*
+%notyet type codes giving the data types of the 1-D output arrays pointed to by
+%notyet \verb|output_arrays[]|.
+%notyet \end{Parameter}
+%notyet \begin{Parameter}{output\_arrays ($\ne$ NULL)}
+%notyet \hbox{}
+%notyet (Pointer to) an array of \verb|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 \verb|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~\verb|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(\verb|i|)$       \\
+%notyet $y = y(\verb|j|)$       \\
+%notyet $z = z(\verb|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 \verb|coord_arrays[]| argument:
+%notyet \begin{flushleft}
+%notyet $x = \verb|coord_arrays[0][i]|$ \\
+%notyet $y = \verb|coord_arrays[1][j]|$ \\
+%notyet $z = \verb|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 \verb|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); \verb|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\_InterpGV()}
+%notyet Interpolate a list of Cactus grid arrays.
+%notyet \end{SeeAlso}
+%notyet \begin{SeeAlso}{CCTK\_InterpLocal()}
+%notyet Older API to interpolate a list of processor-local arrays.
+%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 \verb|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	\verb|cctk_Interp.h|, \verb|util_ErrorCodes.h|, and/or \verb|util_Table.h|
+in the \verb|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 (eg.~\verb|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 \verb|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 Here's a simple example of interpolating a \verb|CCTK_REAL| and a
+%notyet \verb|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(-1, "can't get interpolation handle!");
+%notyet param_table_handle = Util_TableCreateFromString("order=3");
+%notyet if (param_table_handle < 0)
+%notyet         CCTK_WARN(-1, "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(-1, "error return from interpolator!");
+%notyet \end{verbatim}
+%notyet \end{Example}
+%notyet \end{ExampleSection}
+%notyet \end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% Interp.c
+\begin{FunctionDescription}{CCTK\_InterpLocalUniform}
+\label{CCTK-InterpLocalUniform}
+Interpolate a list of processor-local arrays
+which define a uniformly-spaced data grid
+
+(\verb|CCTK_InterpLocalNonUniform()|, \verb|CCTK_InterpLocalUniform()|,
+and \verb|CCTK_InterpLocalWarped()| will eventually replace
+\verb|CCTK_InterpLocal()|.)
+
+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}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{\rm 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 \verb|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
+\verb|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 \verb|order|, a \verb|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 \verb|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 \verb|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 \verb|CCTK_VARIABLE_|* type codes, giving the data type
+of the 1-D interpolation-point-coordinate arrays pointed to by
+\verb|interp_coords[]|.
+\end{Parameter}
+\begin{Parameter}{interp\_coords ($\ne$ NULL)}
+\hbox{}
+(Pointer to) an array of \verb|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 \verb|coord_origin[]| and
+\verb|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 \verb|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 \verb|N_dims| integers giving the dimensions
+of the \verb|N_dims|-D input arrays.  By default all the input arrays
+are taken to have these dimensions, with \verb|[0]| the most contiguous
+axis and \verb|[N_dims-1]| the least contiguous axis, and array subscripts
+in the range \verb|0 <= subscript < input_array_dims[axis]|.  See the
+discussion of the \verb|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 \verb|N_input_arrays| \verb|CCTK_VARIABLE_|*
+type codes giving the data types of the \verb|N_dims|-D input arrays
+pointed to by \verb|input_arrays[]|.
+\end{Parameter}
+\begin{Parameter}{input\_arrays ($\ne$ NULL)}
+\hbox{}
+(Pointer to) an array of \verb|N_input_arrays| pointers to the
+\verb|N_dims|-D input arrays for the interpolation.  If any
+\verb|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 \verb|N_output_arrays| \verb|CCTK_VARIABLE_|*
+type codes giving the data types of the 1-D output arrays pointed to by
+\verb|output_arrays[]|.
+\end{Parameter}
+\begin{Parameter}{output\_arrays ($\ne$ NULL)}
+\hbox{}
+(Pointer to) an array of \verb|N_output_arrays| pointers to the
+(user-supplied) 1-D output arrays for the interpolation.  If any
+\verb|output_arrays[out]| pointer is NULL, that interpolation is skipped.
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+\verb|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~\verb|ijk|
+(we're describing this for 3-D, but the generalization to other numbers
+of dimensions should be obvious).  The \verb|coord_origin[]| and
+\verb|coord_delta[]| arguments specify these linear functions:
+\begin{flushleft}
+$x = \verb|coord_origin[0] + i*coord_delta[0]|$ \\
+$y = \verb|coord_origin[1] + j*coord_delta[1]|$ \\
+$z = \verb|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); \verb|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\_InterpGV()}
+Older API to Interpolate a list of Cactus grid arrays
+\end{SeeAlso}
+\begin{SeeAlso}{CCTK\_InterpLocal()}
+Older API to interpolate a list of processor-local arrays
+\end{SeeAlso}
+\begin{SeeAlso}{CCTK\_InterpRegisterOpLocalUniform()}
+\hbox{}
+Register a \verb|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
+\verb|cctk_Interp.h|, \verb|util_ErrorCodes.h|, and/or \verb|util_Table.h|
+in the \verb|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 (eg.~\verb|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
+\verb|Util_Table*()| routines used to get parameters from
+(and/or set results in) the parameter table
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+Here's a simple example of interpolating a \verb|CCTK_REAL| and a
+\verb|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
+\verb|interp_coords[]|, \verb|input_arrays[]|, and \verb|output_arrays[]|
+arrays as non-\verb|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 \verb|const| and
+initialize them as part of their declarations.
+
+\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(-1, "can't get interpolation handle!");
+param_table_handle = Util_TableCreateFromString("order=3");
+if (param_table_handle < 0)
+        CCTK_WARN(-1, "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(-1, "error return from interpolator!");
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%notyet % Interp.c
+%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 (\verb|CCTK_InterpLocalWarped()|, \verb|CCTK_InterpLocalUniform()|,
+%notyet and \verb|CCTK_InterpLocalWarped()| will eventually replace
+%notyet \verb|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 = 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}{\rm 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 \verb|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 \verb|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 \verb|order|, a \verb|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 \verb|CCTK_VARIABLE_|* type codes, giving the data type of the
+%notyet \verb|N_dims|-D coordinate arrays pointed to by \verb|coord_arrays[]|.
+%notyet \end{Parameter}
+%notyet \begin{Parameter}{coord\_array\_dims ($\ne$ NULL)}
+%notyet \hbox{}
+%notyet (Pointer to) an array of \verb|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) \verb|[0]| the most contiguous axis
+%notyet and \verb|[N_dims-1]| the least contiguous axis, and array subscripts
+%notyet in the range \verb|0 <= subscript < coord_array_dims[axis]|.  See the
+%notyet discussion of the \verb|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 \verb|N_dims| pointers to \verb|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 \verb|CCTK_VARIABLE_|* type codes, giving the data type
+%notyet of the 1-D interpolation-point-coordinate arrays pointed to by
+%notyet \verb|interp_coords[]|.
+%notyet \end{Parameter}
+%notyet \begin{Parameter}{interp\_coords ($\ne$ NULL)}
+%notyet \hbox{}
+%notyet (Pointer to) an array of \verb|N_dims| pointers to \verb|N_dims|-D arrays
+%notyet giving the coordinates of the interpolation points.  These coordinates are
+%notyet with respect to the coordinate system defined by \verb|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 \verb|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 \verb|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 \verb|[0]| the most contiguous axis and
+%notyet \verb|[N_dims-1]| the least contiguous axis, and array subscripts in the
+%notyet range \verb|0 <= subscript < input_array_dims[axis]|.  See the discussion
+%notyet of the \verb|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 \verb|N_input_arrays| \verb|CCTK_VARIABLE_|*
+%notyet type codes giving the data types of the \verb|N_dims|-D input arrays
+%notyet pointed to by \verb|input_arrays[]|.
+%notyet \end{Parameter}
+%notyet \begin{Parameter}{input\_arrays ($\ne$ NULL)}
+%notyet \hbox{}
+%notyet (Pointer to) an array of \verb|N_input_arrays| pointers to the
+%notyet \verb|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 \verb|N_output_arrays| \verb|CCTK_VARIABLE_|*
+%notyet type codes giving the data types of the 1-D output arrays pointed to by
+%notyet \verb|output_arrays[]|.
+%notyet \end{Parameter}
+%notyet \begin{Parameter}{output\_arrays ($\ne$ NULL)}
+%notyet \hbox{}
+%notyet (Pointer to) an array of \verb|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~\verb|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(\verb|i|, \verb|j|, \verb|k|)$   \\
+%notyet $y = y(\verb|i|, \verb|j|, \verb|k|)$   \\
+%notyet $z = z(\verb|i|, \verb|j|, \verb|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 \verb|coord_arrays| argument:
+%notyet \begin{flushleft}
+%notyet $x = \verb|coord_arrays[0][i,j,k]|$     \\
+%notyet $y = \verb|coord_arrays[1][i,j,k]|$     \\
+%notyet $z = \verb|coord_arrays[2][i,j,k]|$     \\
+%notyet \end{flushleft}
+%notyet where \verb|[i,j,k]| refers to \verb|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 \verb|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); \verb|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\_InterpGV()}
+%notyet Interpolate a list of Cactus grid arrays.
+%notyet \end{SeeAlso}
+%notyet \begin{SeeAlso}{CCTK\_InterpLocal()}
+%notyet Older API to interpolate a list of processor-local arrays.
+%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 \verb|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	\verb|cctk_Interp.h|, \verb|util_ErrorCodes.h|, and/or \verb|util_Table.h|
+in the \verb|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 (eg.~\verb|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 \verb|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 Here's a simple example of interpolating a \verb|CCTK_REAL| and a
+%notyet \verb|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 /* (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(-1, "can't get interpolation handle!");
+%notyet param_table_handle = Util_TableCreateFromString("order=3");
+%notyet if (param_table_handle < 0)
+%notyet         CCTK_WARN(-1, "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(-1, "error return from interpolator!");
+%notyet \end{verbatim}
+%notyet \end{Example}
+%notyet \end{ExampleSection}
+%notyet \end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% Interp.c
+\begin{CCTKFunc}{CCTK\_InterpRegisterOperatorGV}%%%
+{Register a routine as a {\tt CCTK\_InterpGV()} interpolation operator}
+\label{CCTK-InterpRegisterOperatorGV}
+\subroutine{int}{}{ierr}
+\argument{cInterpOperatorGV}{}{operator}
+\argument{const char *}{}{name}
+\showcargs
+\begin{params}
+\parameter{operator}{Routine to be registered as the interpolation operator}
+\parameter{name}{Name of interpolation operator}
+\end{params}
+\begin{discussion}
+Only C routines can be registered as interpolation operators.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t
+extern int my\_operator (cGH *GH,\vfill
+\hspace{29ex}const char *coord\_system,\vfill
+\hspace{29ex}int num\_points,\vfill
+\hspace{29ex}int num\_in\_array\_indices,\vfill
+\hspace{29ex}int num\_out\_arrays,\vfill
+\hspace{29ex}void *interp\_coord\_arrays[],\vfill
+\hspace{29ex}int interp\_coord\_array\_types[],\vfill
+\hspace{29ex}int in\_array\_indices[],\vfill
+\hspace{29ex}void *out\_arrays[],\vfill
+\hspace{29ex}int out\_array\_types[]);\linebreak
+ierr = CCTK\_InterpRegisterOperatorGV(my\_operator,\vfill
+\hspace{2ex}"my interpolation operator");}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\begin{tabular}{l}
+A negative return code indicates an error condition:
+\end{tabular}
+\begin{tabular}{ll}
+-1 & NULL pointer was passed as interpolation operator routine\\
+-2 & interpolation handle could not be allocated\\
+-3 & Interpolation operator with this name already exists\\
+\end{tabular}
+\end{errorcodes}
+\end{CCTKFunc}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% Interp.c
+\begin{CCTKFunc}{CCTK\_InterpRegisterOperatorLocal}%%%
+{Register a routine as a {\tt CCTK\_InterpLocal()} interpolation operator}
+\label{CCTK-InterpRegisterOperatorLocal}
+\subroutine{int}{}{ierr}
+\argument{cInterpOperatorLocal}{}{operator}
+\argument{const char *}{}{name}
+\showcargs
+\begin{params}
+\parameter{operator}{Routine to be registered as the interpolation operator}
+\parameter{name}{Name of interpolation operator}
+\end{params}
+\begin{discussion}
+Only C routines can be registered as interpolation operators.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t
+extern int my\_operator (cGH *GH,\vfill
+\hspace{29ex}int num\_points,\vfill
+\hspace{29ex}int num\_dims,\vfill
+\hspace{29ex}int num\_in\_arrays,\vfill
+\hspace{29ex}int num\_out\_arrays,\vfill
+\hspace{29ex}int coord\_dims[],\vfill
+\hspace{29ex}void *coord\_arrays[],\vfill
+\hspace{29ex}int coord\_array\_types[],\vfill
+\hspace{29ex}void *interp\_coord\_arrays[],\vfill
+\hspace{29ex}int interp\_coord\_array\_types[],\vfill
+\hspace{29ex}void *in\_arrays[],\vfill
+\hspace{29ex}int in\_array\_types[],\vfill
+\hspace{29ex}void *out\_arrays[],\vfill
+\hspace{29ex}int out\_array\_types[]);\linebreak
+ierr = CCTK\_InterpRegisterOperatorLocal(my\_operator,\vfill
+\hspace{2ex}"my interpolation operator");}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\begin{tabular}{l}
+A negative return code indicates an error condition:
+\end{tabular}
+\begin{tabular}{ll}
+-1 & NULL pointer was passed as interpolation operator routine\\
+-2 & interpolation handle could not be allocated\\
+-3 & Interpolation operator with this name already exists\\
+\end{tabular}
+\end{errorcodes}
+\end{CCTKFunc}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% here should be CCTK\_InterpRegisterOpLocalNonUniform
+
+% Interp.c
+\begin{FunctionDescription}{CCTK\_InterpRegisterOpLocalUniform}
+\label{CCTK-InterpRegisterOpLocalUniform}
+Register a \verb|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 \verb|CCTK_InterpLocalUniform()| interpolation operator.
+This argument must be a C function pointer of the appropriate type;
+the typedef can be found in \verb|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
+
+% ActiveThorns.c
+\begin{CCTKFunc}{CCTK\_IsImplementationActive}{Reports whether an implementation was activated in a parameter file}
+\label{CCTK-IsImplementationActive}
+\function{int}{integer}{istat}
+\argument{const char *}{character*(*)}{implementationname}
+\showargs
+\begin{params}
+\parameter{istat}{the return status}
+\parameter{implementationname}{the name of the implementation to check}
+\end{params}
+\begin{discussion}
+This function returns a non-zero value if the implementation given by
+{\tt implementationname} was activated in a parameter file, and zero
+otherwise.
+\end{discussion}
+\end{CCTKFunc}
+
+% ActiveThorns.c
+\begin{CCTKFunc}{CCTK\_IsImplementationCompiled}{Reports whether an
+implementation was compiled into the configuration}
+\label{CCTK-IsImplementationCompiled}
+\function{int}{integer}{istat}
+\argument{const char *}{character*(*)}{implementationname}
+\showargs
+\begin{params}
+\parameter{istat}{the return status}
+\parameter{implementationname}{the name of the implementation to check}
+\end{params}
+\begin{discussion}
+This function returns a non-zero value if the implementation given by
+{\tt implementationname} was compiled into the configuration, and zero
+otherwise.
+\end{discussion}
+\end{CCTKFunc}
+
+% ActiveThorns.c
+\begin{CCTKFunc}{CCTK\_IsThornActive}{Reports whether a thorn was activated in a parameter file}
+\label{CCTK-IsThornActive}
+\function{int}{integer}{istat}
+\argument{const char *}{character*(*)}{thornname}
+\showargs
+\begin{params}
+\parameter{istat}{the return status}
+\parameter{thorname}{the name of the thorn to check}
+\end{params}
+\begin{discussion}
+This function returns a non-zero value if the thorn given by {\tt thornname}
+was activated in a parameter file, and zero otherwise.
+\end{discussion}
+\end{CCTKFunc}
+
+% ActiveThorns.c
+\begin{CCTKFunc}{CCTK\_IsThornCompiled}{Reports whether a thorn was activated in a parameter file}
+\label{CCTK-IsThornCompiled}
+\function{int}{integer}{istat}
+\argument{const char *}{character*(*)}{thornname}
+\showargs
+\begin{params}
+\parameter{istat}{the return status}
+\parameter{thorname}{the name of the thorn to check}
+\end{params}
+\begin{discussion}
+This function returns a non-zero value if the implementation given by
+{\tt thornname} was compiled into the configuration, and zero
+otherwise.
+\end{discussion}
+\end{CCTKFunc}
+
+
+%%%%%
+% JJJ
+%%%%%
+
+%%%%%
+% KKK
+%%%%%
+
+%%%%%
+% LLL
+%%%%%
+
+%%%%%
+% MMM
+%%%%%
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_MaxDim}{Get the maximum dimension of any grid variable }
+\label{CCTK-MaxDim}
+\subroutine{int}{integer}{dim}
+\showargs
+\begin{params}
+\parameter{dim}{The maximum dimension}
+\end{params}
+\begin{discussion}
+Note that the maximum dimension will depend on the compiled thorn list,
+and not the active thorn list.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t dim = CCTK\_MaxDim() };
+\\
+\hfill {\bf Fortran} && {\t call  CCTK\_MaxDim(dim)}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% CommOverloadables.c
+\begin{CCTKFunc}{CCTK\_MyProc}{Returns the number of the local processor for a parallel run}
+\label{CCTK-MyProc}
+\function{int}{integer}{myproc}
+\argument{const cGH *}{CCTK\_POINTER}{cctkGH}
+\showargs
+\begin{params}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\end{params}
+\begin{discussion}
+For a single processor run this call will return zero. For multiprocessor
+runs, this call will return $0\leq myproc < {\t CCTK\_nProcs(cctkGH)}$.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+
+\begin{CCTKFunc}{CCTK\_MaxTimeLevels}{Gives the number of timelevels for a group}
+\label{CCTK-MaxTimeLevels}
+\subroutine{int}{integer}{numlevels}
+\argument{const char *}{character*(*)}{name}
+\showargs
+\begin{params}
+\parameter{name}{The full group name}
+\parameter{numlevels}{The number of timelevels}
+\end{params}
+\begin{discussion}
+The group name should be in the form {\t <implementation>::<group>}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t numlevels = CCTK\_MaxTimeLevels("evolve::phivars") ;}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_MAXTIMELEVELS(numlevels,"evolve::phivars")}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_MaxTimeLevelsVN}{Gives the number of timelevels for a variable}
+\label{CCTK-MaxTimeLevelsVN}
+\subroutine{int}{integer}{numlevels}
+\argument{const char *}{character*(*)}{name}
+\showargs
+\begin{params}
+\parameter{name}{The full variable name}
+\parameter{numlevels}{The number of timelevels}
+\end{params}
+\begin{discussion}
+The variable name should be in the form {\t <implementation>::<variable>}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t numlevels = CCTK\_MaxTimeLevelsVN("evolve::phi") ;}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_MAXTIMELEVELSVN(numlevels,"evolve::phi")}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_MaxTimeLevelsVI}{Gives the number of timelevels for a variable}
+\label{CCTK-MaxTimeLevelsVI}
+\subroutine{int}{integer}{numlevels}
+\argument{int}{integer}{index}
+\showargs
+\begin{params}
+\parameter{numlevels}{The number of timelevels}
+\parameter{index}{The variable index}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t index = CCTK\_VarIndex("evolve::phi")}\\
+               &&{\t numlevels = CCTK\_MaxTimeLevelsVI(index) ;}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_MAXTIMELEVELSVI(numlevels,3)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_MaxTimeLevelsGI}{Gives the number of timelevels for a group}
+\label{CCTK-MaxTimeLevelsGI}
+\subroutine{int}{integer}{numlevels}
+\argument{int}{integer}{index}
+\showargs
+\begin{params}
+\parameter{numlevels}{The number of timelevels}
+\parameter{index}{The group index}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t index = CCTK\_GroupIndex("evolve::phivars")}\\
+               &&{\t numlevels = CCTK\_MaxTimeLevelsGI(index) ;}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_MAXTIMELEVELSGI(numlevels,3)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+
+%%%%%
+% NNN
+%%%%%
+
+
+
+% CommOverloadables.c
+\begin{CCTKFunc}{CCTK\_nProcs}{Returns the number of processors being used for a parallel run}
+\label{CCTK-nProcs}
+\function{int}{integer}{nprocs}
+\argument{const cGH *}{CCTK\_POINTER}{cctkGH}
+\showargs
+\begin{params}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\end{params}
+\begin{discussion}
+For a single processor run this call will return one.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+% util/Misc.c
+\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 {\t CCTK\_NullPointer()}.
+
+Note that there is only a fortran wrapper available for {\t 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}
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_NumGroups}{Get the number of groups of variables compiled in the code}
+\label{CCTK-NumGroups}
+\subroutine{int}{integer}{number}
+\showargs
+\begin{params}
+\parameter{number}{The number of groups compiled from the thorns {\t interface.ccl} files}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t number = CCTK\_NumGroups() };
+\\
+\hfill {\bf Fortran} && call {\t CCTK\_NumGroups(number)};
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\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}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% Groups.c
+
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_NumVars}{Get the number of grid variables compiled in the code}
+\label{CCTK-NumVars}
+\subroutine{int}{integer}{number}
+\showargs
+\begin{params}
+\parameter{number}{The number of grid variables compiled from the thorn's {\t interface.ccl} files}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t number = CCTK\_NumVars() };
+\\
+\hfill {\bf Fortran} && call {\t CCTK\_NumVars(number)}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_NumVarsInGroup}{Provides the number of variables in a group from the group name}
+\label{CCTK-NumVarsInGroup}
+\subroutine{int}{integer}{num}
+\argument{const char *}{character*(*)}{name}
+\showargs
+\begin{params}
+\parameter{num}{The number of variables in the group}
+\parameter{group}{The full group name}
+\end{params}
+\begin{discussion}
+The group name should be given in the form {\t <implementation>::<group>}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t numvars = CCTK\_NumVarsInGroup("evolve::scalars") ;}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_NUMVARSINGROUP(numvars,"evolve::scalars")}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_NumVarsInGroupI}{Provides the number of variables in a group from the group index}
+\label{CCTK-NumVarsInGroupI}
+\subroutine{int}{integer}{num}
+\argument{int}{integer}{index}
+\showargs
+\begin{params}
+\parameter{num}{The number of variables in the group}
+\parameter{group}{The group index}
+\end{params}
+\begin{discussion}
+
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t index = CCTK\_GroupIndex("evolve::scalars")}\\
+               &&{\t firstvar = CCTK\_NumVarsInGroupI(index) ;}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_NUMVARSINGROUPI(firstvar,3)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+
+
+
+
+%%%%%
+% 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}{\rm 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\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}{\rm 0}
+for success
+\end{Error}
+\begin{Error}{negative}
+for some error condition (eg. 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\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 {\t 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 {\t variable}\end{Error}
+\begin{Error}{\rm 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\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 {\t variable} using the method {\t method} if it is
+registered. Uses {\t 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}{\rm 0}for success\end{Error}
+\begin{Error}{negative}indicating some error (eg. 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\end{Parameter}
+\begin{Parameter}{method}method to use for output\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+Output a variable {\t variable} using the IO method {\t 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}{\rm 0}for success\end{Error}
+\begin{Error}{negative}indicating some error (eg. IO method is not registered)\end{Error}
+\end{ErrorSection}
+\end{FunctionDescription}
+
+
+
+%%%%%
+% PPP
+%%%%%
+
+% CommOverloadables.c
+\begin{CCTKFunc}{CCTK\_ParallelInit}{Initialize the parallel subsystem}
+\label{CCTK-ParallelInit}
+\subroutine{int}{integer}{istat}
+\argument{cGH *}{CCTK\_POINTER}{cctkGH}
+\showcargs
+\begin{params}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\end{params}
+\begin{discussion}
+Initializes the parallel subsystem.
+\end{discussion}
+\end{CCTKFunc}
+
+
+% WarnLevel.c
+\begin{CCTKFunc}{CCTK\_PARAMWARN}{Prints a warning from parameter checking, and possibly stops the code}
+\label{CCTK-PARAMWARN}
+\subroutine{}{}{}
+\argument{const char *}{character*(*)}{message}
+\showargs
+\begin{params}
+\parameter{message}{The warning message}
+\end{params}
+\begin{discussion}
+The call should be used in routines registered at the schedule point {\t 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{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t CCTK\_PARAMWARN("Mass cannot be negative") };
+\\
+\hfill {\bf Fortran} && {\t call  CCTK\_PARAMWARN("Inside interpolator")}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+% util/Misc.c
+\begin{FunctionDescription}{CCTK\_PointerTo}%%%
+\label{CCTK-PointerTo}
+Returns the address of a variable passed in by reference from a fortran routine.
+
+\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 {\t 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 {\t 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{CCTKFunc}{CCTK\_PrintGroup}{Prints a group name from its index}
+\label{CCTK-PrintGroup}
+\subroutine{}{}{}
+\argument{int}{integer}{index}
+\showargs
+\begin{params}
+\parameter{index}{The group index}
+\end{params}
+\begin{discussion}
+This routine is for debugging purposes for Fortran programmers.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t CCTK\_PrintGroup(1) ;}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_PRINTGROUP(1)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_PrintString}{Prints a Cactus string}
+\label{CCTK-PrintString}
+\subroutine{}{}{}
+\argument{char *}{CCTK\_STRING}{string}
+\showargs
+\begin{params}
+\parameter{string}{The string to print}
+\end{params}
+\begin{discussion}
+This routine can be used to print Cactus string variables and parameters
+from Fortran.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t CCTK\_PrintString(string\_param) ;}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_PRINTSTRING(string\_param)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_PrintVar}{Prints a variable name from its index}
+\label{CCTK-PrintVar}
+\subroutine{}{}{}
+\argument{int}{integer}{index}
+\showargs
+\begin{params}
+\parameter{index}{The variable index}
+\end{params}
+\begin{discussion}
+This routine is for debugging purposes for Fortran programmers.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t CCTK\_PrintVar(1) ;}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_PRINTVAR(1)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+
+
+
+%%%%%
+% QQQ
+%%%%%
+
+
+% cctk_Comm.h
+\begin{CCTKFunc}{CCTK\_QueryGroupStorage}{Query storage for a group given by its group name}
+\label{CCTK-QueryGroupStorage}
+\subroutine{int}{integer}{istat}
+\argument{const cGH *}{CCTK\_POINTER}{cctkGH}
+\argument{const char *}{character*(*)}{groupname}
+\showargs
+\begin{params}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\parameter{groupname}{the group to query, given by its full name}
+\parameter{istat}{the return code}
+\end{params}
+\begin{discussion}
+This routine queries whether the variables in a group have storage assigned.
+If so it returns true (a non-zero value), otherwise false (zero).
+\end{discussion}
+\begin{errorcodes}
+\begin{tabular}{l}
+A negative error code is returned for an invalid group name.
+\end{tabular}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+% CommOverloadables.h
+\begin{CCTKFunc}{CCTK\_QueryGroupStorageB}{}
+\label{CCTK-QueryGroupStorageB}
+\subroutine{int}{}{storage}
+\argument{const cGH *}{}{cctkGH}
+\argument{int}{}{groupindex}
+\argument{const char *}{}{groupname}
+\showcargs
+\begin{params}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% cctk_Comm.h
+\begin{CCTKFunc}{CCTK\_QueryGroupStorageI}{Query storage for a group given by its group index}
+\label{CCTK-QueryGroupStorageI}
+\subroutine{int}{integer}{istat}
+\argument{const cGH *}{}{cctkGH}
+\argument{int}{integer}{groupindex}
+\showargs
+\begin{params}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\parameter{groupindex}{the group to query, given by its index}
+\parameter{istat}{the return code}
+\end{params}
+\begin{discussion}
+This routine queries whether the variables in a group have storage assigned.
+If so it returns true (a non-zero value), otherwise false (zero).
+\end{discussion}
+\begin{errorcodes}
+\begin{tabular}{l}
+A negative error code is returned for an invalid group name.
+\end{tabular}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+
+
+%%%%%
+% RRR
+%%%%%
+
+% CCTK\_Reduce here
+
+
+\begin{CCTKFunc}{CCTK\_ReductionHandle}{Handle for given reduction method}
+\label{CCTK-ReductionHandle}
+\function{int}{integer}{handle}
+% This gives the wrong Fortran binding!!
+\argument{const char *}{character*(*)}{reduction}
+\showargs
+\begin{params}
+\parameter{handle}{handle returned for this method}
+\parameter{name}{name of the reduction method required}
+\end{params}
+\begin{discussion}
+Reduction methods should be registered at {\t CCTK\_STARTUP}. Note that
+integer reduction handles are used to call {\t CCTK\_Reduce} to avoid
+problems with passing Fortran strings. Note that the name of the reduction
+operator is case dependent.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t handle = CCTK\_ReductionHandle("maximum") };
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_ReductionHandle(handle,"maximum")}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% Coord.c
+\begin{CCTKFunc}{CCTK\_RegisterBanner}{Register a banner for a thorn}
+\label{CCTK-RegisterBanner}
+\subroutine{void}{}{}
+\argument{const char *}{character*(*)}{message}
+\showargs
+\begin{params}
+\parameter{message}{String which will be displayed as a banner}
+\end{params}
+\begin{discussion}
+The banner must be registered during {\t CCTK\_STARTUP}. The banners are
+displayed in the order in which they are registered.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t CCTK\_RegisterBanner("My Thorn: Does Something Useful")};
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_REGISTERBANNER("*** MY THORN ***")}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% cctk_GHExtensions.h
+\begin{CCTKFunc}{CCTK\_RegisterGHExtension}{Register an extension to the CactusGH}
+\label{CCTK-RegisterGHExtension}
+\function{int}{}{istat}
+\argument{const char *}{}{name}
+\showcargs
+\begin{params}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% cctk_GHExtensions.h
+\begin{CCTKFunc}{CCTK\_RegisterGHExtensionInitGH}{Register a function which will initialise a given extension to the Cactus GH}
+\label{CCTK-RegisterGHExtensionInitGH}
+\function{int}{}{istat}
+\argument{int}{}{handle}
+\argument{void *}{}{(*func)(cGH *)}
+\showcargs
+\begin{params}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% cctk_GHExtensions.h
+\begin{CCTKFunc}{CCTK\_RegisterGHExtensionScheduleTraverseGH}{Register a GH extension schedule traversal routine}
+\label{CCTK-RegisterGHExtensionScheduleTraverseGH}
+\function{int}{}{istat}
+\argument{int}{}{handle}
+\argument{int}{}{(*func)(cGH *,const char *)}
+\showcargs
+\begin{params}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% cctk_GHExtensions.h
+\begin{CCTKFunc}{CCTK\_RegisterGHExtensionSetupGH}{Register a function which will set up a given extension to the Cactus GH}
+\label{CCTK-RegisterGHExtensionSetupGH}
+\function{int}{}{istat}
+\argument{int}{}{handle}
+\argument{void *}{}{(*func)(tFleshConfig *, int, cGH *)}
+\showcargs
+\begin{params}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_RegisterIOMethod}{Register a new I/O method}
+\label{CCTK-RegisterIOMethod}
+\function{int}{integer}{handle}
+\argument{const char *}{}{name}
+\showargs
+\begin{params}
+\parameter{handle}{handle returned by registration}
+\parameter{name}{name of the I/O method}
+\end{params}
+\begin{discussion}
+IO methods should be registered at {\t CCTK\_STARTUP}.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+% cctk_IOMethods.h
+\begin{CCTKFunc}{CCTK\_RegisterIOMethodOutputGH}{Register a routine for an I/O method which will be called from {\tt CCTK\_OutputGH}.}
+\label{CCTK-RegisterIOMethodOutputGH}
+\function{int}{integer}{istat}
+\argument{int}{}{handle}
+\argument{int}{}{(* func)(const cGH *)}
+\showcargs
+\begin{params}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+% cctk_IOMethods.h
+\begin{CCTKFunc}{CCTK\_RegisterIOMethodOutputVarAs}{Register a routine for an I/O method which will provide aliased variable output}
+\label{CCTK-RegisterIOMethodOutputVarAs}
+\function{int}{integer}{istat}
+\argument{int}{}{handle}
+\argument{int}{}{(* func)(const cGH *,const char*, const char *)}
+\showcargs
+\begin{params}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+% cctk_IOMethods.h
+\begin{CCTKFunc}{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}
+\function{int}{integer}{istat}
+\argument{int}{}{handle}
+\argument{int}{}{(* func)(const cGH *,int)}
+\showcargs
+\begin{params}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+% cctk_IOMethods.h
+\begin{CCTKFunc}{CCTK\_RegisterIOMethodTriggerOutput}{Register a routine for an I/O method which will handle trigger output}
+\label{CCTK-RegisterIOMethodTriggerOutput}
+\function{int}{integer}{istat}
+\argument{int}{}{handle}
+\argument{int}{}{(* func)(const cGH *,int)}
+\showcargs
+\begin{params}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_RegisterReductionOperator}{}
+\label{CCTK-RegisterReductionOperator}
+%\function{int}{integer}{istat}
+%\argument{int}{}{handle}
+%\argument{int}{}{(* func)(const cGH *,int)}
+\showcargs
+\begin{params}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+%%%%%
+% SSS
+%%%%%
+
+% CommOverloadables.c
+\begin{CCTKFunc}{CCTK\_SetupGH}{Setup a new GH}
+\label{CCTK-SetupGH}
+\subroutine{cGH *}{}{cctkGH}
+\argument{tFleshConfig}{}{config}
+\argument{int}{}{convlevel}
+\showcargs
+\begin{params}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+
+
+% CommOverloadables.c
+\begin{CCTKFunc}{CCTK\_SyncGroup}{Synchronise the ghostzones for a group of grid variables}
+\label{CCTK-SyncGroup}
+\subroutine{int}{integer}{istat}
+\argument{cGH *}{CCTK\_POINTER}{cctkGH}
+\argument{const char *}{character*(*)}{group}
+\showargs
+\begin{params}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\end{params}
+\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 {\tt CCTK\_DisableGroupComm}.
+
+Note that an alternative to calling {\tt CCTK\_SyncGroup} explicitly
+from within a thorn, is to use the {\tt SYNC} keyword in a thorns
+{\tt 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.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+
+%%%%%
+% TTT
+%%%%%
+
+%%%%%
+% UUU
+%%%%%
+
+%%%%%
+% VVV
+%%%%%
+
+\begin{CCTKFunc}{CCTK\_VarDataPtr}{Returns the data pointer for a grid variable}
+\label{CCTK-VarDataPtr}
+\subroutine{void *}{}{ptr}
+\argument{const cGH *}{}{cctkGH}
+\argument{int}{}{timelevel}
+\argument{char *}{}{name}
+\showcargs
+\begin{params}
+\parameter{cctkGH}{pointer to CCTK grid hierarchy}
+\parameter{timelevel}{The timelevel of the grid variable}
+\parameter{name}{The full name of the variable}
+\end{params}
+\begin{discussion}
+The variable name should be in the form {\t <implementation>::<variable>}.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t myVar = (CCTK\_REAL *)(CCTK\_VarDataPtr(GH,0,"imp::realvar"))}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_VarDataPtrB}{Returns the data pointer for a grid variable from the variable index or the variable name}
+\label{CCTK-VarDataPtrB}
+\subroutine{void *}{}{ptr}
+\argument{const cGH *}{}{cctkGH}
+\argument{int}{}{timelevel}
+\argument{int}{}{index}
+\argument{char *}{}{name}
+\showcargs
+\begin{params}
+\parameter{ptr}{a void pointer to the grid variable data}
+\parameter{cctkGH}{}
+\parameter{timelevel}{The timelevel of the grid variable}
+\parameter{index}{The index of the variable}
+\parameter{name}{The full name of the variable}
+\end{params}
+\begin{discussion}
+If the name if {\t NULL} the index will be used, if the index is negative the name will be used.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t myVar = (CCTK\_REAL *)(CCTK\_VarDataPtrB(GH,0,CCTK\_VarIndex("imp::realvar"),NULL))}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_VarDataPtrI}{Returns the data pointer for a grid variable from the variable index}
+\label{CCTK-VarDataPtrI}
+\subroutine{void *}{}{ptr}
+\argument{const cGH *}{}{cctkGH}
+\argument{int}{}{timelevel}
+\argument{int}{}{index}
+\showcargs
+\begin{params}
+\parameter{cctkGH}{}
+\parameter{timelevel}{The timelevel of the grid variable}
+\parameter{index}{The index of the variable}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t myVar = (CCTK\_REAL *)(CCTK\_VarDataPtr(GH,0,CCTK\_VarIndex("imp::realvar")))}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+% 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\\ {\t <implementation>::<variable>} for a public or protected
+variable, and\\ {\t <thornname>::<variable>} for a private variable.
+\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 \texttt{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");
+\end{verbatim}
+\end{Example}
+\begin{Example}{Fortran}
+\begin{verbatim}
+call CCTK_VarIndex(index,"evolve::phi")
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_VarName}{Given a variable index, returns the variable name}
+\label{CCTK-VarName}
+\subroutine{const char *}{integer}{name}
+\argument{int}{integer}{index}
+\showcargs
+\begin{params}
+\parameter{name}{The variable name}
+\parameter{index}{The variable index}
+\end{params}
+\begin{discussion}
+No Fortran routine exists at the moment.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t index = CCTK\_VarIndex("evolve::phi");}\\
+               && {\t name = CCTK\_VarName(index);}
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+% Groups.c
+\begin{CCTKFunc}{CCTK\_VarTypeI}{Provides variable type index from the variable index}
+\label{CCTK-VarTypeI}
+\subroutine{int}{integer}{type}
+\argument{int}{integer}{index}
+\showargs
+\begin{params}
+\parameter{type}{The variable type index}
+\parameter{group}{The variable index}
+\end{params}
+\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 {\t CCTK\_VARIABLE\_INT}, {\t CCTK\_VARIABLE\_REAL}, {\t CCTK\_VARIABLE\_COMPLEX} or {\t CCTK\_VARIABLE\_CHAR}.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t index = CCTK\_VarIndex("evolve::phi")}\\
+               &&{\t real = (CCTK\_VARIABLE\_REAL == CCTK\_VarTypeI(index)) ;}
+\\
+\hfill {\bf Fortran} && {\t call CCTK\_VARTYPEI(type,3)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\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}
+\end{SynopsisSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{vtype}
+Variable type index.
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+This function returns the size in bytes of any of the Cactus variable
+types {\t CCTK\_INT}, {\t CCTK\_REAL}, {\t CCTK\_COMPLEX}, etc.
+\end{Discussion}
+
+%\begin{SeeAlsoSection}
+%\end{SeeAlsoSection}
+
+%\begin{ExampleSection}
+%\begin{Example}{C}
+%\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"
+#include "cctk_WarnLevel.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
+{\t CCTK\_THORNSTRING} macro here (defined in {\t cctk.h}).
+\end{Parameter}
+\begin{Parameter}{format}
+The {\t fprintf(3)}-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 {\t fprintf(3)}.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{CCTK\_INFO}
+macro to print an info message with a single string argument
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "cctk.h"
+#include "cctk_WarningLevel.h"
+
+const char *outdir;
+
+CCTK_VInfo(CCTK_THORNSTRING, "Output files will go to '%s'", outdir);
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+
+\begin{FunctionDescription}{CCTK\_VWarn}
+\label{CCTK-VWarn}
+Prints a formatted string with a variable argument list as warning message and
+possibly stops the code
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "cctk.h"
+#include "cctk_WarnLevel.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 \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.
+\end{Parameter}
+\begin{Parameter}{line}
+The line number in the originating source file where the {\t CCTK\_VWarn()} call
+occured. You can use the standardized {\t \_\_LINE\_\_} preprocessor macro here.
+\end{Parameter}
+\begin{Parameter}{file}
+The file name of the originating source file where the {\t CCTK\_VWarn()} call
+occured. You can use the standardized {\t \_\_FILE\_\_} preprocessor macro here.
+\end{Parameter}
+\begin{Parameter}{thorn}
+The thorn name of the originating source file where the {\t CCTK\_VWarn()} call occured. You can use the {\t CCTK\_THORNSTRING} macro here (defined in {\t cctk.h}).
+\end{Parameter}
+\begin{Parameter}{format}
+The {\t fprintf(3)}-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 {\t stderr}.
+
+By default Cactus prints any warning with warning levels $\le 1$ to standard
+error, and would stop the code on a level 0 warning.
+This behaviour can be changed on the command line using
+the flags {\t -W} and {\t -E} (see the Users' Guide for full details).
+
+The boolean flesh parameter {\tt 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 omit the line number and name of the
+source file.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{CCTK\_WARN}
+macro to print a warning message with a single string argument
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "cctk.h"
+#include "cctk_WarningLevel.h"
+
+const char *outdir;
+
+CCTK_VWarn(1, __LINE__, __FILE__, CCTK_THORNSTRING,
+           "Output directory '%s' could not be created", outdir);
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+%%%%%
+% WWW
+%%%%%
+
+
+
+% WarnLevel.c
+\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"
+#include "cctk_WarnLevel.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
+\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 {\t stderr}.
+
+{\tt CCTK\_WARN(level, message)} expands to a call to the underlying function
+{\tt CCTK\_Warn()}:
+
+\begin{verbatim}
+CCTK_Warn(level, __LINE__, __FILE__, CCTK_THORNSTRING, message)
+\end{verbatim}
+
+So 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). It is recommended that the macro {\tt CCTK\_WARN} is used
+to print a warning message rather than calling {\tt CCTK\_Warn()} directly.
+
+To include variables in a warning message from C, you can use the routine
+{\tt CCTK\_VWarn()} which accepts a variable argument list.
+To include variables from Fortran, a string must be constructed and passed
+in a {\tt CCTK\_WARN} macro.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{CCTK\_VWarn()}
+prints a warning message with a variable argument list
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "cctk.h"
+#include "cctk_WarningLevel.h"
+
+CCTK_WARN(0, "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(1, message)
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapter{Utility Functions}
+\label{sect-FunctionReference/UtilityFunctions}
+
+In this section all \hbox{{\tt Util\_}*} Cactus utility functions are
+described.  These are low-level functions mainly for more complicated
+programming, which are used by the rest of Cactus, but don't depend
+heavily on it.  Some of them are callable from Fortran or C, but
+many are C-only.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Functions Alphabetically}
+
+Here the functions are listed alphabetically within each section.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%% comment this whole section out until it's non-empty
+%%\subsection{Miscellaneous Functions}
+%%
+%%\begin{Lentry}
+
+%%\item[Util\_asprintf]
+%%     [\pageref{Util-asprintf}]
+
+%%\item[Util\_BinTreeFindNode]
+%%     [\pageref{Util-BinTreeFindNode}]
+
+%%\item[Util\_BinTreePrintNodes]
+%%     [\pageref{Util-BinTreePrintNodes}]
+
+%%\item[Util\_BinTreeStoreData]
+%%     [\pageref{Util-BinTreeStoreData}]
+
+%%\item[Util\_BinTreeTraverseInorder]
+%%     [\pageref{Util-BinTreeTraverseInorder}]
+
+%%\item[Util\_BinTreeTraversePostorder]
+%%     [\pageref{Util-BinTreeTraversePostorder}]
+
+%%\item[Util\_BinTreeTraversePreorder]
+%%     [\pageref{Util-BinTreeTraversePreorder}]
+
+%%\item[Util\_CacheMalloc]
+%%     [\pageref{Util-CacheMalloc}]
+
+%%\item[Util\_CurrentDate]
+%%     [\pageref{Util-CurrentDate}]
+
+%%\item[Util\_CurrentTime]
+%%     [\pageref{Util-CurrentTime}]
+
+%%\item[Util\_DeleteHandle]
+%%     [\pageref{Util-DeleteHandle}]
+
+%%\item[Util\_DoubleInRange]
+%%     [\pageref{Util-DoubleInRange}]
+
+%%\item[Util\_DoubleInRangeList]
+%%     [\pageref{Util-DoubleInRangeList}]
+
+%%\item[Util\_GetHandle]
+%%     [\pageref{Util-GetHandle}]
+
+%%\item[Util\_GetHandleName]
+%%     [\pageref{Util-GetHandleName}]
+
+%%\item[Util\_GetHandledData]
+%%     [\pageref{Util-GetHandledData}]
+
+%%\item[Util\_GetHostName]
+%%     [\pageref{Util-GetHostName}]
+
+%%\item[Util\_HashAdd]
+%%     [\pageref{Util-HashAdd}]
+
+%%\item[Util\_HashCreate]
+%%     [\pageref{Util-HashCreate}]
+
+%%\item[Util\_HashData]
+%%     [\pageref{Util-HashData}]
+
+%%\item[Util\_HashDelete]
+%%     [\pageref{Util-HashDelete}]
+
+%%\item[Util\_HashDestroy]
+%%     [\pageref{Util-HashDestroy}]
+
+%%\item[Util\_HashHash]
+%%     [\pageref{Util-HashHash}]
+
+%%\item[Util\_HashStore]
+%%     [\pageref{Util-HashStore}]
+
+%%\item[Util\_InList]
+%%     [\pageref{Util-InList}]
+
+%%\item[Util\_IntInRange]
+%%     [\pageref{Util-IntInRange}]
+
+%%\item[Util\_IntInRangeList]
+%%     [\pageref{Util-IntInRangeList}]
+
+%%\item[Util\_NewHandle]
+%%     [\pageref{Util-NewHandle}]
+
+%%\item[Util\_NullTerminateString]
+%%     [\pageref{Util-NullTerminateString}]
+
+%%\item[Util\_SplitFilename]
+%%     [\pageref{Util-SplitFilename}]
+
+%%\item[Util\_SplitString]
+%%     [\pageref{Util-SplitString}]
+
+%%\item[Util\_StringListAdd]
+%%     [\pageref{Util-StringListAdd}]
+
+%%\item[Util\_StringListCreate]
+%%     [\pageref{Util-StringListCreate}]
+
+%%\item[Util\_StringListDestroy]
+%%     [\pageref{Util-StringListDestroy}]
+
+%%\item[Util\_StringListNext]
+%%     [\pageref{Util-StringListNext}]
+
+%%\end{Lentry}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection{String Functions}
+
+\begin{Lentry}
+
+\item[Util\_StrCmpi]
+     [\pageref{Util-StrCmpi}]
+Compare two strings, ignoring upper/lower case.
+
+\item[Util\_Strdup]
+     [\pageref{Util-Strdup}]
+``Duplicate'' a string,
+\ie{} copy it to a newly--\verb|malloc|ed buffer.
+
+\item[Util\_Strlcat]
+     [\pageref{Util-Strlcat}]
+Concatenate two strings safely.
+
+\item[Util\_Strlcpy]
+     [\pageref{Util-Strlcpy}]
+Copy a string safely.
+
+\end{Lentry}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection{Table Functions}
+
+\begin{Lentry}
+
+\item[Util\_TableClone]
+     [\pageref{Util-TableClone}]
+Create a new table which is a ``clone'' (exact copy) of an existing
+table
+
+\item[Util\_TableCreate]
+     [\pageref{Util-TableCreate}]
+Create a new (empty) table
+
+\item[Util\_TableCreateFromString]
+     [\pageref{Util-TableCreateFromString}]
+Create a new table (with the case-insensitive flag set) and sets
+values in it based on a string argument (interpreted with
+``parameter-file'' semantics)
+
+\item[Util\_TableDeleteKey]
+     [\pageref{Util-TableDeleteKey}]
+Delete a specified key/value entry from a table
+
+\item[Util\_TableDestroy]
+     [\pageref{Util-TableDestroy}]
+Destroy a table
+
+\item[Util\_TableGet*]
+     [\pageref{Util-TableGet*}]
+This is a family of functions, one for each Cactus data type,
+to get the single (1-element array) value, or more generally the
+first array element of the value, associated with a specified key
+in a key/value table.
+
+\item[Util\_TableGet*Array]
+     [\pageref{Util-TableGet*Array}]
+This is a family of functions, one for each Cactus data type,
+to get a copy of the value associated with a specified key, and store
+it (more accurately, as much of it as will fit) in a specified array
+
+\item[Util\_TableGetGeneric]
+     [\pageref{Util-TableGetGeneric}]
+Get the single (1-element array) value, or more generally the
+first array element of the value, associated with a specified key
+in a key/value table; the value's data type is generic
+
+\item[Util\_TableGetGenericArray]
+     [\pageref{Util-TableGetGenericArray}]
+Get a copy of the value associated with a specified key, and store
+it (more accurately, as much of it as will fit) in a specified array;
+the array's data type is generic
+
+\item[Util\_TableGetString]
+     [\pageref{Util-TableGetString}]
+Gets a copy of the character-string value associated with a specified
+key in a table, and stores it (more accurately, as much of it as will fit)
+in a specified character string
+
+\item[Util\_TableItAdvance]
+     [\pageref{Util-TableItAdvance}]
+Advance a table iterator to the next entry in the table
+
+\item[Util\_TableItClone]
+     [\pageref{Util-TableItClone}]
+Creates a new table iterator which is a ``clone'' (exact copy) of an
+existing table iterator
+
+\item[Util\_TableItCreate]
+     [\pageref{Util-TableItCreate}]
+Create a new table iterator
+
+\item[Util\_TableItDestroy]
+     [\pageref{Util-TableItDestroy}]
+Destroy a table iterator
+
+\item[Util\_TableItQueryIsNonNull]
+     [\pageref{Util-TableItQueryIsNonNull}]
+Query whether a table iterator is {\em not\/} in the ``null-pointer'' state
+
+\item[Util\_TableItQueryIsNull]
+     [\pageref{Util-TableItQueryIsNull}]
+Query whether a table iterator is in the ``null-pointer'' state
+
+\item[Util\_TableItQueryKeyValueInfo]
+     [\pageref{Util-TableItQueryKeyValueInfo}]
+Query the key and the type and number of elements of the value
+corresponding to that key, of the table entry to which an iterator points
+
+\item[Util\_TableItQueryTableHandle]
+     [\pageref{Util-TableItQueryTableHandle}]
+Query what table a table iterator iterates over
+
+\item[Util\_TableItResetToStart]
+     [\pageref{Util-TableItResetToStart}]
+Reset a table iterator to point to the starting table entry
+
+\item[Util\_TableItSetToKey]
+     [\pageref{Util-TableItSetToKey}]
+Set a key/value iterator to point to a specified entry in the table.
+
+\item[Util\_TableItSetToNull]
+     [\pageref{Util-TableItSetToNull}]
+Set a key/value iterator to the ``null-pointer'' state.
+
+\item[Util\_TableQueryFlags]
+     [\pageref{Util-TableQueryFlags}]
+Query a table's flags word
+
+\item[Util\_TableQueryValueInfo]
+     [\pageref{Util-TableQueryValueInfo}]
+Query whether or not a specified key is in the table, and optionally
+the type and/or number of elements of the value corresponding to this key
+
+\item[Util\_TableQueryMaxKeyLength]
+     [\pageref{Util-TableQueryMaxKeyLength}]
+Query the maximum key length in a table
+
+\item[Util\_TableQueryNKeys]
+     [\pageref{Util-TableQueryNKeys}]
+Query the number of key/value entries in a table
+
+\item[Util\_TableSet*]
+     [\pageref{Util-TableSet*}]
+This is a family of functions, one for each Cactus data type,
+to set the value associated with a specified key to be a specified
+single (1-element array) value
+
+\item[Util\_TableSet*Array]
+     [\pageref{Util-TableSet*Array}]
+This is a family of functions, one for each Cactus data type,
+to set the value associated with a specified key to be a copy
+of a specified array
+
+\item[Util\_TableSetFromString]
+     [\pageref{Util-TableSetFromString}]
+Sets values in a table based on a string argument (interpreted with
+``parameter-file'' semantics)
+
+\item[Util\_TableSetGeneric]
+     [\pageref{Util-TableSetGeneric}]
+Set the value associated with a specified key to be a specified
+single (1-element array) value, whose data type is generic
+
+\item[Util\_TableSetGenericArray]
+     [\pageref{Util-TableSetGenericArray}]
+Set the value associated with a specified key to be a copy of a
+specified array, whose data type is generic
+
+\item[Util\_TableSetString]
+     [\pageref{Util-TableSetString}]
+Sets the value associated with a specified key in a table, to be
+a copy of a specified C-style null-terminated character string
+
+\end{Lentry}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Full Descriptions of String Functions}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_StrCmpi}
+\label{Util-StrCmpi}
+Compare two strings, ignoring upper/lower case.
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_String.h"
+int cmp = Util_StrCmpi(const char *str1, const char *str2);
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{cmp}
+An integer which is:\\
+\begin{tabular}{@{}rl}
+$<0$	& if $\verb|str1| < \verb|str2|$ in lexicographic order
+	  ignoring upper/lower case distinctions			\\
+$0$	& if $\verb|str1| = \verb|str2|$
+	  ignoring upper/lower case distinctions			\\
+$>0$	& if $\verb|str1| > \verb|str2|$ in lexicographic order
+	  ignoring upper/lower case distinctions			%%%\\
+\end{tabular}
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{str1}
+A non-NULL pointer to a (C-style NUL-terminated) string to be compared.
+\end{Parameter}
+\begin{Parameter}{str2}
+A non-NULL pointer to a (C-style NUL-terminated) string to be compared.
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+The standard C library \verb|strcmp()| function does a {\em case-sensitive\/}
+string comparison, \ie{} \verb|strcmp("cactus", "Cactus")| will find the
+two strings not equal.  Sometimes it's useful to do {\em case-insensitive\/}
+string comparison, where upper/lower case distinctions are ignored.
+Many systems provide a \verb|strcasecmp()| or \verb|strcmpi()|
+function to do this, but some systems don't, and even on those that do,
+the name isn't standardised.  So, Cactus provides its own version,
+\verb|Util_StrCmpi()|.
+
+Notice that the return value of \verb|Util_StrCmpi()|, like that of
+\verb|strcmp()|, is zero (logical ``false'' in C) for equal strings,
+and nonzero (logcla ``true'' in C) for non-equal strings.
+Code of the form
+\begin{verbatim}
+if (Util_StrCmpi(str1, str2))
+        { /* strings differ */ }
+\end{verbatim}
+or
+\begin{verbatim}
+if (!Util_StrCmpi(str1, str2))
+        { /* strings are identical apart from case distinctions */ }
+\end{verbatim}
+may be confusing to readers, because the sense of the comparison
+isn't immediately obvious.  Writing an explicit comparison against zero
+make make things clearer:
+\begin{verbatim}
+if (Util_StrCmpi(str1, str2) != 0)
+        { /* strings differ */ }
+\end{verbatim}
+or
+\begin{verbatim}
+if (Util_StrCmpi(str1, str2) == 0)
+        { /* strings are identical apart from case distinctions */ }
+\end{verbatim}
+
+Unfortunately, the basic concept of ``case-insensitive'' string
+operations doesn't generalize well to non-English character sets,%%%
+\footnote{%%%
+	 Hawaiian and Swahili are apparently the only
+	 other living languages that use solely the
+	 26-letter ``English'' Latin alphabet.
+	 }%%%
+{} where lower-case $\leftrightarrow$ upper-case mappings may be
+context-dependent, many-to-one, and/or time-dependent.%%%
+\footnote{%%%
+	 For example, the (lower-case) German ``\ss''
+	 doesn't have a unique upper-case equivalent:
+	 ``\ss'' usually maps to ``SS''
+	 (for example ``gro\ss'' $\leftrightarrow$ ``GROSS''),
+	 {\em but\/} if that would conflict
+	 with another word, then ``\ss'' maps to ``SZ''
+	 (for example ``ma\ss{}e'' $\leftrightarrow$ ``MASZE''
+	 because there's a different word ``MASSE'').
+	 Or at least that's the way it was prior to 1998.
+	 The 1998 revisions to German orthography
+	 removed the SZ rule, so now (post-1998) the two
+	 distinct German words ``masse'' (English ``mass'')
+	 and ``ma\ss{}e'' (``measures'') have identical
+	 upper-case forms ``MASSE''.  To further complicate
+	 matters, (the German-speaking parts of) Switzerland
+	 have a slightly different orthography, which never
+	 had the SZ rule.
+
+	 French provides another tricky example:
+	 In France ``\'e'' $\leftrightarrow$ ``\'E'' and
+	 ``\`e'' $\leftrightarrow$ ``\`E'',
+	 whereas in (the French-speaking parts of) Canada
+	 there are no accents on upper-case letters, so
+	 ``\'e'' $\leftrightarrow$ ``E'' and
+	 ``\`e'' $\leftrightarrow$ ``E''.
+	 }%%%
+{}  At present Cactus basically ignores these issues. :(
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{strcmp()}
+Standard C library function (prototype in \verb|<string.h>|)
+to compare two strings.
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_String.h"
+
+/* does the Cactus parameter  driver  specify the PUGH driver? */
+/* (Cactus parameters are supposed to be case-insensitive) */
+if (Util_StrCmpi(driver, "pugh") == 0)
+        { /* PUGH code */ }
+else
+        { /* non-PUGH code */ }
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_Strdup}
+\label{Util-Strdup}
+``Duplicate'' a string, \ie{} copy it to a newly--\verb|malloc|ed buffer.
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_String.h"
+char* copy = Util_Strdup(const char *str);
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{copy}
+A pointer to a buffer obtained from \verb|malloc()|,
+which this function sets to a copy of the (C-style NUL-terminated)
+string \verb|str|.  This buffer should be freed with \verb|free()|
+when it's not needed any more.
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{str}
+A non-NULL pointer to a (C-style NUL-terminated) string.
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+Many systems have a C library function \verb|strdup|, which
+\verb|malloc|s sufficient memory for a copy of its argument string,
+does the copy, and returns a pointer to the copy.  However, some
+systems lack this function, so Cactus provides its own version,
+\verb|Util_Strdup()|.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{<stdlib.h>}
+System header file containing prototypes for
+\verb|malloc()| and \verb|free()|.
+\end{SeeAlso}
+\begin{SeeAlso}{strcpy()}
+Standard C library function (prototype in \verb|<string.h>|)
+to copy a string to a buffer.
+{\em This does not check that the buffer is big enough to hold the string,
+and is thus very dangerous.  Use \verb|Util_Strlcpy()| instead!}
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_Strlcpy()}
+Safely copy a string.
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{NULL}
+\verb|malloc()| was unable to allocate memory for the buffer.
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_String.h"
+
+/*
+ * return the (positive) answer to a question,
+ * or negative if an error occured
+ */
+int answer_question(const char* question)
+{
+/*
+ * we need to modify the question string in the process of parsing it
+ * but we must not destroy the input ==> copy it and modify the copy
+ *
+ * ... note the const qualifier on  question_copy  says that
+ *     the pointer  question_copy  won't itself change, but
+ *     we can modify the string that it points to
+ */
+char* const question_copy = Util_Strdup(question);
+if (question_copy == NULL)
+        { return -1; }     /* couldn't get memory for copy buffer */
+
+/* code that will modify  question_copy */
+
+free(question_copy);
+return 42;
+}
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_Strlcat}
+\label{Util-Strlcat}
+Concatenate strings safely.
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_String.h"
+size_t result_len = Util_Strlcat(char *dst, const char *src, size_t size);
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{result\_len}
+The size of the string the function tried to create, i.e.\
+the initial \verb|strlen(dst)| plus \verb|strlen(src)|.
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{dst}
+A non-NULL pointer to the (C-style NUL-terminated) destination string.
+\end{Parameter}
+\begin{Parameter}{src}
+A non-NULL pointer to the (C-style NUL-terminated) source string.
+\end{Parameter}
+\begin{Parameter}{size}
+The size of the destination buffer.
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+The standard \verb|strcat()| and \verb|strcpy()| functions provide
+no way to specify the size of the destination buffer, so code using
+these functions is often vulnerable to buffer overflows.  The standard
+\verb|strncat()| and \verb|strncpy()| functions can be used to write
+safe code, but their API is cumbersome, error-prone, and sometimes
+surprisingly inefficient:
+\begin{itemize}
+\item	Their \verb|size| arguments are the number of characters
+	{\em remaining\/} in the destination buffer, which must
+	often be calculated at run-time, and is prone to off-by-one
+	errors.
+\item	\verb|strncpy()| doesn't always NUL-terminate the destination string.
+\item	\verb|strncpy()| NUL-fills the remainder of the buffer not
+	used for the source string; this NUL-filling can be {\em very\/}
+	expensive.
+\end{itemize}
+
+To solve these problems, the OpenBSD project developed the
+\verb|strlcat()| and \verb|strlcpy()| functions.  See
+\verb|http://www.openbsd.org/papers/strlcpy-paper.ps|
+for a history and general discussion of these functions.
+Some other Unix systems (notably Solaris) now provide these,
+but many don't, so Cactus provides its own versions,
+\verb|Util_Strlcat()| and \verb|Util_Strlcpy()|.
+
+\verb|Util_Strlcat()| appends the NUL-terminated string \verb|src| to the
+end of the NUL-terminated string \verb|dst|.  It will append at most
+\verb|size - strlen(dst) - 1| characters (hence it never overflows the
+destination buffer), and it always leaves \verb|dst| string NUL-terminated.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{strcat()}
+Standard C library function (prototype in \verb|<string.h>|)
+to concatenate two strings.
+{\em This does not check that the buffer is big enough to hold the result,
+and is thus very dangerous.  Use \verb|Util_Strlcat()| instead!}
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_Strlcpy()}
+Safely copy a string.
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_String.h"
+
+/*
+ * safely concatenate strings s1,s2,s3 into buffer:
+ * ... this code is safe (it will never overflow the buffer), but
+ *     quick-n-dirty in that it doesn't give any error indication
+ *     if the result is truncated to fit in the buffer
+ */
+#define BUFFER_SIZE     1024
+char buffer[BUFFER_SIZE];
+
+Util_Strlcpy(buffer, s1, sizeof(buffer));
+Util_Strlcat(buffer, s2, sizeof(buffer));
+Util_Strlcat(buffer, s3, sizeof(buffer));
+\end{verbatim}
+\end{Example}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_String.h"
+
+#define OK              0
+#define ERROR_TRUNC     1
+
+/*
+ * safely concatenate strings s1,s2,s3 into buffer[N_buffer];
+ * return OK if ok, ERROR_TRUNC if result was truncated to fit in buffer
+ */
+int cat3(int N_buffer, char buffer[],
+         const char s1[], const char s2[], const char s3[])
+{
+int length;
+
+length = Util_Strlcpy(buffer, s1, N_buffer);
+if (length >= N_buffer)
+        return ERROR_TRUNC;                   /*** ERROR EXIT ***/
+
+length = Util_Strlcat(buffer, s2, N_buffer);
+if (length >= N_buffer)
+        return ERROR_TRUNC;                   /*** ERROR EXIT ***/
+
+length = Util_Strlcat(buffer, s3, N_buffer);
+if (length >= N_buffer)
+        return ERROR_TRUNC;                   /*** ERROR EXIT ***/
+
+return OK;                                    /*** NORMAL RETURN ***/
+}
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_Strlcpy}
+\label{Util-Strlcpy}
+Copies a string safely.
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_String.h"
+size_t result_len = Util_Strlcpy(char *dst, const char *src, size_t size);
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{result\_len}
+The size of the string the function tried to create, i.e.\
+\verb|strlen(src)|.
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{dst}
+A non-NULL pointer to the (C-style NUL-terminated) destination string.
+\end{Parameter}
+\begin{Parameter}{src}
+A non-NULL pointer to the (C-style NUL-terminated) source string.
+\end{Parameter}
+\begin{Parameter}{size}
+The size of the destination buffer.
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+The standard \verb|strcat()| and \verb|strcpy()| functions provide
+no way to specify the size of the destination buffer, so code using
+these functions is often vulnerable to buffer overflows.  The standard
+\verb|strncat()| and \verb|strncpy()| functions can be used to write
+safe code, but their API is cumbersome, error-prone, and sometimes
+surprisingly inefficient:
+\begin{itemize}
+\item	Their \verb|size| arguments are the number of characters
+	{\em remaining\/} in the destination buffer, which must
+	often be calculated at run-time, and is prone to off-by-one
+	errors.
+\item	\verb|strncpy()| doesn't always NUL-terminate the destination string.
+\item	\verb|strncpy()| NUL-fills the remainder of the buffer not
+	used for the source string; this NUL-filling can be {\em very\/}
+	expensive.
+\end{itemize}
+
+To solve these problems, the OpenBSD project developed the
+\verb|strlcat()| and \verb|strlcpy()| functions.  See
+\verb|http://www.openbsd.org/papers/strlcpy-paper.ps|
+for a history and general discussion of these functions.
+Some other Unix systems (notably Solaris) now provide these,
+but many don't, so Cactus provides its own versions,
+\verb|Util_Strlcat()| and \verb|Util_Strlcpy()|.
+
+\verb|Util_Strlcpy()| copies up to \verb|size-1| characters from the
+source string to the destination string, followed by a NUL character
+(so \verb|dst| is always NUL-terminated).  Unlike \verb|strncpy()|,
+\verb|Util_Strlcpy()| does {\em not\/} fill any left-over space at
+the end of the destination buffer with NUL characters.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{strcpy()}
+Standard C library function (prototype in \verb|<string.h>|)
+to copy a string to a buffer.
+{\em This does not check that the buffer is big enough to hold the string,
+and is thus very dangerous.  Use \verb|Util_Strlcpy()| instead!}
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_Strdup()}
+``Duplicate'' a string, \ie{} copy it to a newly-\verb|malloc|ed buffer.
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_Strlcat()}
+Safely concatenates two strings.
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_String.h"
+
+/*
+ * safely concatenate strings s1,s2,s3 into buffer:
+ * ... this code is safe (it will never overflow the buffer), but
+ *     quick-n-dirty in that it doesn't give any error indication
+ *     if the result is truncated to fit in the buffer
+ */
+#define BUFFER_SIZE     1024
+char buffer[BUFFER_SIZE];
+
+Util_Strlcpy(buffer, s1, sizeof(buffer));
+Util_Strlcat(buffer, s2, sizeof(buffer));
+Util_Strlcat(buffer, s3, sizeof(buffer));
+\end{verbatim}
+\end{Example}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_String.h"
+
+#define OK              0
+#define ERROR_TRUNC     1
+
+/*
+ * safely concatenate strings s1,s2,s3 into buffer[N_buffer];
+ * return OK if ok, ERROR_TRUNC if result was truncated to fit in buffer
+ */
+int cat3(int N_buffer, char buffer[],
+         const char s1[], const char s2[], const char s3[])
+{
+int length;
+
+length = Util_Strlcpy(buffer, s1, N_buffer);
+if (length >= N_buffer)
+        return ERROR_TRUNC;                   /*** ERROR EXIT ***/
+
+length = Util_Strlcat(buffer, s2, N_buffer);
+if (length >= N_buffer)
+        return ERROR_TRUNC;                   /*** ERROR EXIT ***/
+
+length = Util_Strlcat(buffer, s3, N_buffer);
+if (length >= N_buffer)
+        return ERROR_TRUNC;                   /*** ERROR EXIT ***/
+
+return OK;                                    /*** NORMAL RETURN ***/
+}
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Full Descriptions of Table Functions}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableClone}
+\label{Util-TableClone}
+Creates a new table which is a ``clone'' (exact copy) of an existing
+table
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int clone_handle = Util_TableClone(int handle);
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableClone(clone_handle, handle)
+integer clone_handle, handle
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{clone\_handle ($\ge 0$)}
+A handle to the clone table
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle}
+Handle to the table to be cloned
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+Viewing a table as a set of key/value pairs, this function creates
+a new table (with the same flags word as the original) containing
+copies of all the original table's key/value pairs.  The two tables
+are completely independent, \ie{} future changes to one won't affect
+the other.
+
+Note that if there are any \verb|CCTK_POINTER| and/or \verb|CCTK_FPOINTER|
+values in the table, they are ``shallow copied'', \ie{} the (pointer)
+values in the table are copied.  This results in the clone table's
+pointer values pointing to the same places as the original table's
+pointer values.  Be careful with this!  In particular,
+if you're using pointer values in the table to keep track of
+\verb|malloc()| memory, be careful not to \verb|free()|
+the same block of memory twice!
+
+Note that table iterators are {\em not\/} guaranteed to sequence
+through the original and clone tables in the same order.  (This
+is a special case of the more general ``non-guarantee'' in
+the Section of table iterators in the Users' Guide:
+the order of table iterators may differ even between different
+tables with identical key/value contents.)
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableCreate()}
+create a table
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableCreateFromString()}
+convenience routine to create a table and set key/value entries
+in it based on a parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableDestroy()}
+destroy a table
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_NO\_MEMORY}
+unable to allocate memory
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_FLAGS}
+flags word is negative in the to-be-cloned table
+(this indicates an internal error in the table routines,
+and should never happen)
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+
+/*
+ * This function is passed (a handle to) a table containing some entries.
+ * It needs to set some additional entries and pass the table to some
+ * other function(s), but it also needs to leave the original table
+ * intact for other use by the caller.  The solution is to clone the
+ * original table and work on the clone, leaving the original table
+ * unchanged.
+ */
+int my_function(int handle, int x, int y)
+{
+int status;
+
+/* clone the table */
+const int clone_handle = Util_TableClone(handle)
+if (clone_handle < 0)
+        return clone_handle;               /* error in cloning table */
+
+/* now set our entries in the clone table */
+status = Util_TableSetInt(clone_handle, x, "x");
+if (status < 0)
+        return status;                     /* error in setting x */
+status = Util_TableSetInt(clone_handle, y, "y");
+if (status < 0)
+        return status;                     /* error in setting y */
+
+/* ... code to use the clone table ... */
+/* ... eg pass clone_handle to other functions ... */
+
+/* we're done with the clone now */
+Util_TableDestroy(clone_handle);
+return 0;
+}
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableCreate}
+\label{Util-TableCreate}
+Creates a new (empty) table
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int handle = Util_TableCreate(int flags);
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableCreate(handle, flags)
+integer handle, flags
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{handle ($\ge 0$)}
+A handle to the newly-created table
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{flags ($\ge 0$)}
+A flags word for the table.  This should be the inclusive-or of zero
+or more of the \verb|UTIL_TABLE_FLAGS_|* bit masks (defined in
+\verb|"util_Table.h"|).  For Fortran users, note that inclusive-or
+is the same as sum here, since the bit masks are all disjoint.
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+We require the flags word to be non-negative so that other
+functions can distinguish flags from (negative) error codes.
+
+Any User-defined flag words should use only bit positions at or above\\
+\verb|UTIL_TABLE_FLAGS_USER_DEFINED_BASE|, i.e.\ all bit positions
+below this are reserved for present of future Cactus use.
+
+At present there is only a single flags-word bit mask defined
+in \verb|"util_Table.h"|:
+\begin{description}
+\item[{\t UTIL\_TABLE\_FLAGS\_CASE\_INSENSITIVE}]\mbox{}\\
+        By default keys are treated as C-style character strings,
+        and the table functions compare them with the standard C
+        \verb|strcmp()| function.
+        However, by setting the\\
+        \verb|UTIL_TABLE_FLAGS_CASE_INSENSITIVE|
+        bit in the flags word, this table's keys may be made
+        case-insensitive, \ie{} the table routines then compare
+        this table's keys with \verb|Util_StrCmpi()|.%%%
+        Note that keys are still {\em stored\/} exactly as
+        the caller specifies them (\ie{} they are {\em not\/}
+        forced into a canonical case); it's only their
+        {\em comparison\/} that's affected by this flag.
+\end{description}
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_StrCmpi()}
+compare two strings, ignoring upper/lower case
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableClone()}
+create a new table which is a ``clone'' (exact copy) of an existing
+table
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableCreateFromString()}
+convenience routine to create a table and set key/value entries
+in it based on a parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableDestroy()}
+destroy a table
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_NO\_MEMORY}
+unable to allocate memory
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_FLAGS}
+flags word is negative
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+
+/* create a table, simplest case */
+int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);
+
+/* create a table whose keys will be treated as case-insensitive */
+int handle2 = Util_TableCreate(UTIL_TABLE_FLAGS_CASE_INSENSITIVE);
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableCreateFromString}
+\label{Util-TableCreateFromString}
+Creates a new table (with the case-insensitive flag set) and sets
+values in it based on a string argument (interpreted with
+``parameter-file'' semantics)
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int handle = Util_TableCreateFromString(const char *string);
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableCreateFromString(handle, string)
+integer       handle
+character*(*) string
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{handle ($\ge 0$)}
+a handle to the newly-created table
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{string}
+a pointer to a C-style null-terminated string specifying the table
+contents; see the description for \verb|Util_TableSetFromString()|
+for a full description of the syntax and semantics of this string
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableClone()}
+Create a new table which is a ``clone'' (exact copy) of an existing
+table
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableCreate()}
+create a table
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetFromString()}
+sets values in a table based on a string argument
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetInt()}
+store a \verb|CCTK_INT| value in a table
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetReal()}
+store a \verb|CCTK_REAL| value in a table
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_NO\_MEMORY}
+unable to allocate memory
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_BAD\_KEY}
+invalid input: key contains invalid character
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_BAD\_INPUT}
+invalid input: can't parse input string
+\end{Error}
+\begin{Error}{\rm other error codes}
+this function may also return any error codes returned by
+\verb|Util_TableCreate()| or \verb|Util_TableSetFromString()|
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+
+int handle = Util_TableCreateFromString("order = 3\t"
+                                        "myreal = 42.314159\t"
+                                        "mystring = 'hello'\t"
+                                        "myarray = { 0 1 2 3 }");
+
+/* equivalent code to the above */
+int handle = Util_TableCreate(UTIL_TABLE_FLAGS_CASE_INSENSITIVE);
+Util_TableSetFromString(handle, "order = 3\t"
+                                "myreal = 42.314159\t"
+                                "mystring = 'hello'"
+                                "myarray = { 0 1 2 3 }");
+
+/* also equivalent to the above */
+int handle = Util_TableCreate(UTIL_TABLE_FLAGS_CASE_INSENSITIVE);
+CCTK_INT array[] = {0, 1, 2, 3};
+
+Util_TableSetInt(handle, 3, "order");
+Util_TableSetReal(handle, 42.314159, "myreal");
+Util_TableSetString(handle, "hello", "mystring");
+Util_TableSetIntArray(handle, 4, array, "myarray");
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableDeleteKey}
+\label{Util-TableDeleteKey}
+Deletes a specified key/value entry from a table
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int key_exists = Util_TableDeleteKey(int handle, const char *key);
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableDeleteKey(key_exists, handle, key)
+integer        key_exists, handle
+character*(*)  key
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{\rm 0}
+ok (key existed before this call, and has now been deleted)
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table
+\end{Parameter}
+\begin{Parameter}{key}
+a pointer to the key (a C-style null-terminated string)
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+This function invalidates any iterators for the table which are
+not in the ``null-pointer'' state.
+\end{Discussion}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+handle is invalid
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY}
+key contains '/' character
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_NO\_SUCH\_KEY}
+no such key in table
+\end{Error}
+\end{ErrorSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableDestroy}
+\label{Util-TableDestroy}
+Destroys a table
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int status = Util_TableDestroy(int handle);
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableDestroy(status, handle)
+integer status, handle
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{\rm 0}
+ok
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+Of course, this function invalidates any and all iterators for the table. :)
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableClone()}
+Create a new table which is a ``clone'' (exact copy) of an existing
+table
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableCreate()}
+create a table
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableCreateFromString()}
+convenience routine to create a table and set key/value entries
+in it based on a parameter-file--like character string
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+handle is invalid
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+
+/* create a table */
+int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);
+
+/* do things with the table: put values in it, */
+/* pass its handle to other functions, etc etc */
+/* ... */
+
+/* at this point we (and all other functions we */
+/* may call in the future) are done with the table */
+Util_TableDestroy(handle);
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableGet*}
+\label{Util-TableGet*}
+This is a family of functions, one for each Cactus data type,
+to get the single (1-element array) value, or more generally the
+first array element of the value, associated with a specified key
+in a key/value table.
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int N_elements = Util_TableGetXxx(int handle,
+                                  CCTK_XXX *value,
+                                  const char *key);
+\end{verbatim}
+where \verb|XXX| is one of
+   \verb|POINTER|, \verb|FPOINTER|%%%
+\footnote{%%%
+	 For backwards compatability the function
+	 {\tt Util\_TableGetFnPointer()} is also provided
+	 as an alias for {\tt Util\_TableGetFPointer()}.
+	 This is deprecated as of Cactus 4.0 beta 13.
+	 }%%%
+,
+   \verb|CHAR|,
+   \verb|INT|, \verb|INT2|, \verb|INT4|, \verb|INT8|,
+   \verb|REAL|, \verb|REAL4|, \verb|REAL8|, \verb|REAL16|,
+   \verb|COMPLEX|, \verb|COMPLEX8|, \verb|COMPLEX16|, \verb|COMPLEX32|
+(not all of these may be supported on any given system)
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableGetXxx(N_elements, handle, value, key)
+integer        N_elements, handle
+CCTK_XXX       value
+character*(*)  key
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{N\_elements}
+the number of array elements in the value
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table
+\end{Parameter}
+\begin{Parameter}{value}
+a pointer to where this function should store a copy of the value
+(or more generally the first array element of the value) associated
+with the specified key,
+or NULL pointer to skip storing this
+\end{Parameter}
+\begin{Parameter}{key}
+a pointer to the key (a C-style null-terminated string)
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+Note that it is {\em not\/} an error for the value to actually have
+$> 1$ array elements; in this case only the first element is stored.
+The rationale for this design is that the caller may know or suspect
+that the value is a large array, but may only want the first array
+element; in this case this design avoids the caller having to allocate
+a large buffer unnecessarily.
+
+In contrast, it {\em is\/} an error for the value to actually be an
+empty (0-length) array, because then there is no ``first array element''
+to get.
+
+It is also an error for the value to actually have a different type
+than \verb|CCTK_XXX|.
+
+If any error code is returned, the user's value buffer
+(pointed to by \verb|value| if this is non-NULL) is unchanged.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableCreateFromString()}
+convenience routine to create a table and set key/value entries
+in it based on a parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*Array()}
+get an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*String()}
+get a character-string value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*()}
+set a single (1-element array) value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*Array()}
+set an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGeneric()}
+set a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGenericArray()}
+set an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetFromString()}
+convenience routine to set key/value entries in a table based on a
+parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetString()}
+set a character-string value
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+handle is invalid
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY}
+key contains '/' character
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_NO\_SUCH\_KEY}
+no such key in table
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_WRONG\_DATA\_TYPE}
+value has data type other than \verb|CCTK_TYPE|
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_VALUE\_IS\_EMPTY}
+value is an empty (0-element) array
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+
+#define N_DIGITS        5
+static const CCTK_INT pi_digits[N_DIGITS] = {3, 14, 159, 2653, 58979};
+
+int N;
+CCTK_INT x;
+int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);
+
+Util_TableSetIntArray(handle, N_DIGITS, pi_digits, "digits of pi");
+Util_TableSetIntArray(handle, 0, pi_digits, "empty array");
+
+/* gets N = 5, x = 3 */
+N = Util_TableGetInt(handle, &x, "digits of pi");
+
+/* gets N = UTIL_ERROR_TABLE_VALUE_IS_EMPTY */
+N = Util_TableGetInt(handle, &x, "empty array");
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableGet*Array}
+\label{Util-TableGet*Array}
+This is a family of functions, one for each Cactus data type,
+to get a copy of the value associated with a specified key, and store
+it (more accurately, as much of it as will fit) in a specified array
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int N_elements = Util_TableGetXxxArray(int handle,
+                                       int N_array, CCTK_XXX array[],
+                                       const char *key);
+\end{verbatim}
+where \verb|XXX| is one of
+   \verb|POINTER|, \verb|FPOINTER|%%%
+\footnote{%%%
+	 For backwards compatability the function
+	 {\tt Util\_TableGetFnPointerArray()} is also provided
+	 as an alias for {\tt Util\_TableGetFPointerArray()}.
+	 This is deprecated as of Cactus 4.0 beta 13.
+	 }%%%
+,
+   \verb|CHAR|,
+   \verb|INT|, \verb|INT2|, \verb|INT4|, \verb|INT8|,
+   \verb|REAL|, \verb|REAL4|, \verb|REAL8|, \verb|REAL16|,
+   \verb|COMPLEX|, \verb|COMPLEX8|, \verb|COMPLEX16|, \verb|COMPLEX32|
+(not all of these may be supported on any given system)
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableGetXxxArray(N_elements, handle, N_array, array, key)
+integer        N_elements, handle, N_array
+CCTK_XXX(*)    array
+character*(*)  key
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{N\_elements}
+the number of array elements in the value
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table
+\end{Parameter}
+\begin{Parameter}{N\_array}
+the number of array elements in \verb|array[]|
+(must be $\ge 0$ if \verb|array != NULL|)
+\end{Parameter}
+\begin{Parameter}{array}
+a pointer to where this function should store (up to \verb|N_array|
+elements of) a copy of the value associated with the specified key,
+or NULL pointer to skip storing this
+\end{Parameter}
+\begin{Parameter}{key}
+a pointer to the key (a C-style null-terminated string)
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+Note that it is {\em not\/} an error for the value to actually have
+$> \verb|N_array|$ array elements; in this case only the first \verb|N_array|
+elements are stored.  The caller can detect this by comparing the
+return value with \verb|N_array|.
+The rationale for this design is that the caller may know or suspect
+that the value is a large array, but may only want the first few array
+elements; in this case this design avoids the caller having to allocate
+a large buffer unnecessarily.
+
+It is also {\em not\/} an error for the value to actually have
+$< \verb|N_array|$ array elements; again the caller can detect this by
+comparing the return value with \verb|N_array|.
+
+It {\em is\/} an error for the value to actually have a different type
+than \verb|CCTK_XXX|.
+
+If any error code is returned, the user's value buffer
+(pointed to by \verb|array| if this is non-NULL) is unchanged.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableCreateFromString()}
+convenience routine to create a table and set key/value entries
+in it based on a parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*()}
+get a single (1-element array) value,
+or more generally the first array element of an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGeneric()}
+get a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGenericArray()}
+get an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*String()}
+get a character-string value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*()}
+set a single (1-element array) value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*Array()}
+set an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGeneric()}
+set a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGenericArray()}
+set an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetFromString()}
+convenience routine to set key/value entries in a table based on a
+parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetString()}
+set a character-string value
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+handle is invalid
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY}
+key contains '/' character
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_BAD\_INPUT}
+\verb|array != NULL| and \verb|N_array| $< 0$
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_NO\_SUCH\_KEY}
+no such key in table
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_WRONG\_DATA\_TYPE}
+value has data type other than \verb|CCTK_TYPE|
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+
+#define N_STUFF         3
+static const CCTK_REAL stuff[N_STUFF] = {42.0, 69.0, 105.5};
+
+#define N_OUTPUT        2
+CCTK_INT output[N_OUTPUT];
+
+int N;
+int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);
+
+Util_TableSetRealArray(handle, N_STUFF, stuff, "blah blah blah");
+
+/* gets N = 3, output[0] = 42.0, output[1] = 69.0 */
+N = Util_TableGetRealArray(handle, N_OUTPUT, output, "blah blah blah");
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableGetGeneric}
+\label{Util-TableGetGeneric}
+Get the single (1-element array) value, or more generally the
+first array element of the value, associated with a specified key
+in a key/value table; the value's data type is generic.  That
+is, the value is specified by a \verb|CCTK_VARIABLE_|* type code
+and a \verb|void *| pointer.
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int N_elements = Util_TableGetGeneric(int handle,
+                                      int type_code,
+                                      void *value,
+                                      const char *key);
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableGetGeneric(N_elements, handle, type_code, value, key)
+integer        N_elements, handle, type_code
+CCTK_POINTER   value
+character*(*)  key
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{N\_elements}
+the number of array elements in the value
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table
+\end{Parameter}
+\begin{Parameter}{type\_code}
+the value's type code
+(one of the \verb|CCTK_VARIABLE_|* constants from \verb|"cctk_Constants.h"|)
+\end{Parameter}
+\begin{Parameter}{value}
+a pointer to where this function should store a copy of the value
+(or more generally the first array element of the value) associated
+with the specified key,
+or NULL pointer to skip storing this
+\end{Parameter}
+\begin{Parameter}{key}
+a pointer to the key (a C-style null-terminated string)
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+Note that it is {\em not\/} an error for the value to actually have
+$> 1$ array elements; in this case only the first element is stored.
+The rationale for this design is that the caller may know or suspect
+that the value is a large array, but may only want the first array
+element; in this case this design avoids the caller having to allocate
+a large buffer unnecessarily.
+
+In contrast, it {\em is\/} an error for the value to actually be an
+empty (0-length) array, because then there is no ``first array element''
+to get.
+
+It is also an error for the value to actually have a different type
+than that specified by \verb|type_code|.
+
+If any error code is returned, the user's value buffer
+(pointed to by \verb|value| if this is non-NULL) is unchanged.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableCreateFromString()}
+convenience routine to create a table and set key/value entries
+in it based on a parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*()}
+get a single (1-element array) value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*Array()}
+get an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*String()}
+get a character-string value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableItQueryValueInfo()}
+query key present/absent in table, and optionally type and/or number
+of elements, using an iterator
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableQueryValueInfo()}
+query key present/absent in table, and optionally type and/or number
+of elements
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*()}
+set a single (1-element array) value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*Array()}
+set an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGeneric()}
+set a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGenericArray()}
+set an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetFromString()}
+convenience routine to set key/value entries in a table based on a
+parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetString()}
+set a character-string value
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+handle is invalid
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY}
+key contains '/' character
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_NO\_SUCH\_KEY}
+no such key in table
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_WRONG\_DATA\_TYPE}
+value has data type other than \verb|CCTK_TYPE|
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_VALUE\_IS\_EMPTY}
+value is an empty (0-element) array
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+#include "cctk_Constants.h"
+
+#define N_DIGITS        5
+static const CCTK_INT pi_digits[N_DIGITS] = {3, 14, 159, 2653, 58979};
+
+int N;
+CCTK_INT x;
+void *xptr = (void *) &x;
+int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);
+
+Util_TableSetIntArray(handle, N_DIGITS, pi_digits, "digits of pi");
+Util_TableSetIntArray(handle, 0, pi_digits, "empty array");
+
+/* gets N = 5, x = 3 */
+N = Util_TableGetGeneric(handle, CCTK_VARIABLE_INT, &x, "the answer");
+
+/* gets N = UTIL_ERROR_TABLE_VALUE_IS_EMPTY, leaves x unchanged */
+N = Util_TableGetGeneric(handle, CCTK_VARIABLE_INT, &x, "empty array");
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableGetGenericArray}
+\label{Util-TableGetGenericArray}
+Get a copy of the value associated with a specified key, and store
+it (more accurately, as much of it as will fit) in a specified array;
+the array's data type is generic.  That is the array is specified by
+a \verb|CCTK_VARIABLE_|* type code, a count of the number of array
+elements, and a \verb|void *| pointer.
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int N_elements = Util_TableGetGenericArray(int handle,
+                                           int type_code,
+                                           int N_array, void *array,
+                                           const char *key);
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableGetGenericArray(N_elements,
+.                              handle,
+.                              type_code,
+.                              N_array, array,
+.                              key)
+integer        N_elements, handle, type_code, N_array
+CCTK_POINTER   array
+character*(*)  key
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{N\_elements}
+the number of array elements in the value
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table
+\end{Parameter}
+\begin{Parameter}{type\_code}
+the value's type code
+(one of the \verb|CCTK_VARIABLE_|* constants from \verb|"cctk_Constants.h"|)
+\end{Parameter}
+\begin{Parameter}{N\_array}
+the number of array elements in \verb|array[]|
+(must be $\ge 0$ if \verb|array != NULL|)
+\end{Parameter}
+\begin{Parameter}{array}
+a pointer to where this function should store (up to \verb|N_array|
+elements of) a copy of the value associated with the specified key,
+or NULL pointer to skip storing this
+\end{Parameter}
+\begin{Parameter}{key}
+a pointer to the key (a C-style null-terminated string)
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+Note that it is {\em not\/} an error for the value to actually have
+$> \verb|N_array|$ array elements; in this case only the first \verb|N_array|
+elements are stored.  The caller can detect this by comparing the
+return value with \verb|N_array|.
+The rationale for this design is that the caller may know or suspect
+that the value is a large array, but may only want the first few array
+elements; in this case this design avoids the caller having to allocate
+a large buffer unnecessarily.
+
+It is also {\em not\/} an error for the value to actually have
+$< \verb|N_array|$ array elements; again the caller can detect this by
+comparing the return value with \verb|N_array|.
+
+It {\em is\/} an error for the value to actually have a different type
+than that specified by \verb|type_code|.
+
+If any error code is returned, the user's value buffer
+(pointed to by \verb|array| if this is non-NULL) is unchanged.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableCreateFromString()}
+convenience routine to create a table and set key/value entries
+in it based on a parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*()}
+get a single (1-element array) value,
+or more generally the first array element of an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGeneric()}
+get a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGenericArray()}
+get an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*String()}
+get a character-string value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableItQueryValueInfo()}
+query key present/absent in table, and optionally type and/or number
+of elements, using an iterator
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableQueryValueInfo()}
+query key present/absent in table, and optionally type and/or number
+of elements
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*()}
+set a single (1-element array) value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*Array()}
+set an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGeneric()}
+set a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGenericArray()}
+set an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetFromString()}
+convenience routine to set key/value entries in a table based on a
+parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetString()}
+set a character-string value
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+handle is invalid
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY}
+key contains '/' character
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_BAD\_INPUT}
+\verb|array != NULL| and \verb|N_array| $< 0$
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_NO\_SUCH\_KEY}
+no such key in table
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_WRONG\_DATA\_TYPE}
+value has data type other than \verb|CCTK_TYPE|
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+
+#define N_STUFF         3
+static const CCTK_REAL stuff[N_STUFF] = {42.0, 69.0, 105.5};
+
+#define N_OUTPUT        2
+CCTK_INT output[N_OUTPUT];
+
+int N;
+int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);
+
+Util_TableSetRealArray(handle, N_STUFF, stuff, "stuff");
+
+/* gets N = UTIL_ERROR_TABLE_WRONG_DATA_TYPE, output[] unchanged */
+N = Util_TableGetGenericArray(handle,
+                              CCTK_VARIABLE_INT,
+                              N_OUTPUT, output,
+                              "stuff");
+/* gets N = 3, output[0] = 42.0, output[1] = 69.0 */
+N = Util_TableGetGenericArray(handle,
+                              CCTK_VARIABLE_REAL,
+                              N_OUTPUT, output,
+                              "stuff");
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableGetString}
+\label{Util-TableGetString}
+Gets a copy of the character-string value associated with a specified
+key in a table, and stores it (more accurately, as much of it as will fit)
+in a specified character string
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int length = Util_TableGetString(int handle,
+                                 int buffer_length, char buffer[],
+                                 const char *key);
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{ResultNote}
+Results are the same as all the other \verb|Util_TableGet|* functions:
+\end{ResultNote}
+\begin{Result}{length}
+the length of the string
+(C \verb|strlen()| semantics, \ie{} {\em not\/} including
+the terminating null character)
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table
+\end{Parameter}
+\begin{Parameter}{buffer\_length}
+the length (\verb|sizeof()|) of \verb|buffer[]|
+(must be $\ge 1$ if \verb|buffer != NULL|)
+\end{Parameter}
+\begin{Parameter}{buffer}
+a pointer to a buffer into which this function should store
+(at most \verb|buffer_length-1|  characters of) the value,
+terminated by a null character as usual for C strings,
+or NULL pointer to skip storing this
+\end{Parameter}
+\begin{Parameter}{key}
+a pointer to the key (a C-style null-terminated string)
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+This function assumes that the string is stored as an array of
+\verb|CCTK_CHAR|s, {\em not\/} including a terminating null character.
+
+This function differs from \verb|Util_TableGetCharArray()| in two ways:
+It explicitly provides a terminating null character for C-style strings,
+and it explicitly checks for the string being too long to fit in the buffer
+(in which case it returns \verb|UTIL_ERROR_TABLE_STRING_TRUNCATED|).
+
+If the error code \verb|UTIL_ERROR_TABLE_STRING_TRUNCATED| is returned,
+then the first \verb|buffer_length-1| characters of the string are
+returned in the user's buffer (assuming \verb|buffer| is non-NULL),
+followed by a null character to properly terminate the string in the
+buffer.  If any other error code is returned, the user's value buffer
+(pointed to by \verb|buffer| if this is non-NULL) is unchanged.
+
+To find out how long the string is (and thus how big of a buffer you
+need to allocate to avoid having the string truncated), you can call
+this function with $\verb|buffer_length| = 0$ and $\verb|buffer| = \verb|NULL|$
+(or actually anything you want); the return result will give the
+string length.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableCreateFromString()}
+convenience routine to create a table and set key/value entries
+in it based on a parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*()}
+get a single (1-element array) value,
+or more generally the first array element of an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*Array()}
+get an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetCharArray()}
+get an array-of-\verb|CCTK_CHAR| value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGeneric()}
+get a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGenericArray()}
+get an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*()}
+set a single (1-element array) value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*Array()}
+set an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGeneric()}
+set a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGenericArray()}
+set an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetString()}
+set a character-string value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetFromString()}
+convenience routine to set key/value entries in a table based on a
+parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetCharArray()}
+set an array-of-\verb|CCTK_CHAR| value
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+handle is invalid
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY}
+key contains '/' character
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_BAD\_INPUT}
+\verb|buffer != NULL| and \verb|buffer_length| $\le 0$
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_NO\_SUCH\_KEY}
+no such key in table
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_WRONG\_DATA\_TYPE}
+value has data type other than \verb|CCTK_CHAR|
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_STRING\_TRUNCATED}
+\quad
+\verb|buffer != NULL| and value was truncated to fit in \verb|buffer[]|
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+
+#define N_BUFFER        100
+char buffer[N_BUFFER];
+
+int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);
+Util_TableSetString(handle, "relativity", "Einstein");
+
+/* get length of string (= 10 here) */
+int length = Util_TableGetString(handle, 0, NULL, "Einstein");
+
+/* get null-terminated string into buffer, also returns 10 */
+Util_TableGetString(handle, N_BUFFER, buffer, "Einstein");
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableItAdvance}
+\label{Util-TableItAdvance}
+Advance a table iterator to the next entry in the table
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int is_nonnull = Util_TableItAdvance(int ihandle);
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{\rm 1}
+ok (iterator now points to some table entry)
+\end{Result}
+\begin{Result}{\rm 0}
+ok (iterator has just advanced past the last table entry,
+    and is now in the "null-pointer" state)
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{ihandle ($\ge 0$)}
+handle to the iterator
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+If we view an iterator as an abstraction of a pointer into the table,
+then this function is the abstraction of the C \verb|++| operation applied
+to the pointer, except that this function automagically sets the iterator
+to the "null-pointer" state when it advances past the last table entry.
+
+Note that bad things (garbage results, core dumps) may happen if
+you call this function on an iterator which has been invalidated
+by a change in the table's contents.
+\end{Discussion}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+iterator handle is invalid
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+/* walk through all entries of a table */
+int ihandle;
+
+        for ( ihandle = Util_TableItCreate(handle) ;
+              Util_TableItQueryIsNonNull(ihandle) > 0 ;
+              Util_TableItAdvance(ihandle) )
+        {
+        /* do something with the table entry */
+        }
+
+Util_TableItDestroy(ihandle);
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableItClone}
+\label{Util-TableItClone}
+Creates a new table iterator which is a ``clone'' (exact copy) of an
+existing table iterator
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int clone_ihandle = Util_TableItClone(int ihandle);
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{clone\_ihandle ($\ge 0$)}
+A handle to the clone table iterator
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{ihandle}
+Handle to the table iterator to be cloned
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+This function creates a new iterator which points to the same place
+in the same table as the original iterator.  If the original iterator
+is in the ``null-pointer'' state, then the clone is also in this state.
+
+Note that bad things (garbage results, core dumps) may happen if
+you call this function on an iterator which has been invalidated
+by a change in the table's contents.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableClone()}
+create a new table which is a ``clone'' (exact copy) of an existing
+table
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableItCreate()}
+create a table iterator
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableItDestroy()}
+destroy a table iterator
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+iterator handle to be cloned, is invalid
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_NO\_MEMORY}
+unable to allocate memory
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+
+/*
+ * Apart from efficiency and slight differences in error return codes,
+ * Util_TableItClone() could be simulated by the following code.
+ */
+int Util_TableItClone(int ihandle)
+{
+int status;
+
+/* to what table does the to-be-cloned iterator point? */
+const int handle = Util_TableQueryTableHandle(ihandle);
+if (handle < 0)
+        return handle;                /* error in querying table handle */
+
+/* create the to-be-cloned iterator */
+/* (pointing into the same table as the original iterator) */
+  {
+const int clone_ihandle = Util_TableItCreate(handle);
+if (clone_ihandle < 0)
+        return clone_ihandle;       /* error in creating clone iterator */
+
+/* how long is the key to which the to-be-cloned iterator points? */
+  {
+const int key_length = Util_TableItQueryKeyValueInfo(ihandle,
+                                                     0, NULL,
+                                                     NULL, NULL);
+if (key_length == UTIL_TABLE_ITERATOR_IS_NULL)
+        {
+        /* to-be-cloned iterator is in "null-pointer" state */
+        Util_TableItSetToNull(clone_ihandle);
+        return clone_ihandle;                          /* normal return */
+        }
+if (key_length < 0)
+        return key_length;   /* error in querying to-be-cloned iterator */
+
+/* to what key does the to-be-cloned iterator point? */
+  {
+const int key_buffer_length = key_length + 1;
+char *const key_buffer = (char *) malloc(key_buffer_length);
+if (key_buffer == NULL)
+        return UTIL_ERROR_NO_MEMORY;
+status = Util_TableItQueryKeyValueInfo(ihandle,
+                                       key_buffer_length, key_buffer);
+if (status < 0)
+        return status;       /* error in querying to-be-cloned iterator */
+
+/* set the clone iterator to point to the same key as the original */
+status = Util_TableItSetToKey(clone_ihandle, key_buffer);
+free(key_buffer);
+return clone_ihandle;                                  /* normal return */
+  }
+  }
+  }
+}
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableItCreate}
+\label{Util-TableItCreate}
+Create a new table iterator
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int ihandle = Util_TableItCreate(int handle);
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{ihandle ($\ge 0$)}
+handle to the iterator
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table over which the iterator should iterate
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+This function creates a new table iterator.  The iterator initially
+points at the starting table entry.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableItDestroy()}
+destroy a table iterator
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+table handle is invalid
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_NO\_MEMORY}
+unable to allocate memory
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+/* walk through all entries of a table */
+int ihandle;
+
+        for ( ihandle = Util_TableItCreate(handle) ;
+              Util_TableItQueryIsNonNull(ihandle) > 0 ;
+              Util_TableItAdvance(ihandle) )
+        {
+        /* do something with the table entry */
+        }
+
+Util_TableItDestroy(ihandle);
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableItDestroy}
+\label{Util-TableItDestroy}
+Destroy a table iterator
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int status = Util_TableItDestroy(int ihandle);
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{\rm 0}
+ok
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{ihandle ($\ge 0$)}
+handle to the iterator
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableItCreate()}
+create a table iterator
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+iterator handle is invalid
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_NO\_MEMORY}
+unable to allocate memory
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+/* walk through all entries of a table */
+int ihandle;
+
+        for ( ihandle = Util_TableItCreate(handle) ;
+              Util_TableItQueryIsNonNull(ihandle) > 0 ;
+              Util_TableItAdvance(ihandle) )
+        {
+        /* do something with the table entry */
+        }
+
+Util_TableItDestroy(ihandle);
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableItQueryIsNonNull}
+\label{Util-TableItQueryIsNonNull}
+Query whether a table iterator is {\em not\/} in the ``null-pointer'' state
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int status = Util_TableItQueryIsNonNull(int ihandle);
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{\rm 1}
+iterator is {\em not\/} in the ``null-pointer'' state,
+\ie{} iterator points to some table entry
+\end{Result}
+\begin{Result}{\rm 0}
+iterator is in the ``null-pointer'' state
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{ihandle ($\ge 0$)}
+handle to the iterator
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+If no errors occur,
+\verb|Util_TableItQueryIsNonNull(ihandle)|
+is the same as\\
+\verb|1 - Util_TableItQueryIsNull(ihandle)|.
+
+Note that bad things (garbage results, core dumps) may happen if
+you call this function on an iterator which has been invalidated
+by a change in the table's contents.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableItQueryIsNull()}
+query whether a table iterator is in the ``null-pointer'' state
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+iterator handle is invalid
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+/* walk through all entries of a table */
+int ihandle;
+
+        for ( ihandle = Util_TableItCreate(handle) ;
+              Util_TableItQueryIsNonNull(ihandle) > 0 ;
+              Util_TableItAdvance(ihandle) )
+        {
+        /* do something with the table entry */
+        }
+
+Util_TableItDestroy(ihandle);
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableItQueryIsNull}
+\label{Util-TableItQueryIsNull}
+Query whether a table iterator is in the ``null-pointer'' state
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int status = Util_TableItQueryIsNull(int ihandle);
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{\rm 1}
+iterator is in the ``null-pointer'' state
+\end{Result}
+\begin{Result}{\rm 0}
+iterator is {\em not\/} in the ``null-pointer'' state,
+\ie{} iterator points to some table entry
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{ihandle ($\ge 0$)}
+handle to the iterator
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+If no errors occur,
+\verb|Util_TableItQueryIsNull(ihandle)|
+is the same as
+\verb|1 - Util_TableItQueryIsNonNull(ihandle)|.
+
+Note that bad things (garbage results, core dumps) may happen if
+you call this function on an iterator which has been invalidated
+by a change in the table's contents.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableItQueryIsNonNull()}
+query whether a table iterator is {\em not\/} in the ``null-pointer'' state,
+\ie{} whether the iterator points to some table entry
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+iterator handle is invalid
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+/* variant code to walk through all entries of a table */
+int ihandle;
+
+        for ( ihandle = Util_TableItCreate(handle) ;
+              Util_TableItQueryIsNull(ihandle) == 0 ;
+              Util_TableItAdvance(ihandle) )
+        {
+        /* do something with the table entry */
+        }
+
+Util_TableItDestroy(ihandle);
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableItQueryKeyValueInfo}
+\label{Util-TableItQueryKeyValueInfo}
+Query the key and the type and number of elements of the value
+corresponding to that key, of the table entry to which an iterator points
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int key_length =
+ Util_TableItQueryKeyValueInfo(int ihandle,
+                               int key_buffer_length, char key_buffer[],
+                               CCTK_INT *type_code, CCTK_INT *N_elements)
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{key\_length}
+The string length of the key
+(this has C {\t strlen()} semantics, \ie{} it does {\em not\/}
+include a terminating null character)
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table iterator
+\end{Parameter}
+\begin{Parameter}{key\_buffer\_length}
+\quad
+the length (\verb|sizeof()|) of \verb|key_buffer[]|
+(must be $\ge 1$ if \verb|key_buffer != NULL|)
+\end{Parameter}
+\begin{Parameter}{key\_buffer}
+a pointer to a buffer into which this function should store
+(at most \verb|key_buffer_length-1| characters of) the key,
+terminated by a null character as usual for C strings,
+or NULL pointer to skip storing this
+\end{Parameter}
+\begin{Parameter}{type\_code}
+a pointer to where this function should store the value's type code
+(one of the \verb|CCTK_VARIABLE_|* constants from \verb|"cctk_Constants.h"|),
+or a NULL pointer to skip storing this.
+\end{Parameter}
+\begin{Parameter}{N\_elements}
+a pointer to where this function should store
+the number of array elements in the value,
+or a NULL pointer to skip storing this.
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+The usual use of an iterator is to iterate through all the entries
+of a table, calling this function on each entry, then taking further
+action based on the results.
+
+Note that bad things (garbage results, core dumps) may happen if
+you call this function on an iterator which has been invalidated
+by a change in the table's contents.
+
+If the error code \verb|UTIL_ERROR_TABLE_STRING_TRUNCATED| is returned,
+then the first \verb|key_buffer_length-1| characters of the key are
+returned in the user's key buffer (assuming \verb|key_buffer| is non-NULL),
+followed by a null character to properly terminate the string in the
+buffer.  If any other error code is returned, the user's key buffer
+(pointed to by \verb|key_buffer| if this is non-NULL) is unchanged.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableQueryValueInfo()}
+query key present/absent in table, and optionally type and/or number
+of elements, but using the key instead of an iterator
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+handle is invalid
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_ITERATOR\_IS\_NULL}
+\quad
+iterator is in "null-pointer" state
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_STRING\_TRUNCATED}
+\quad
+\verb|key_buffer != NULL| and key was truncated to fit in \verb|key_buffer|
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+/* print out all entries in a table */
+/* return 0 for ok, type code for any types we can't handle, */
+/*                  -ve for other errors */
+#include <stdio.h>
+#include <stdlib.h>
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+#include "cctk.h"
+
+int print_table(int handle)
+{
+int max_key_length, N_key_buffer, ihandle;
+char *key_buffer;
+
+max_key_length = Util_TableQueryMaxKeyLength(handle);
+if (max_key_length < 0)
+        return max_key_length;
+
+N_key_buffer = max_key_length + 1;
+key_buffer = (char *) malloc(N_key_buffer);
+if (key_buffer == NULL)
+        return UTIL_ERROR_NO_MEMORY;
+
+        for ( ihandle = Util_TableItCreate(handle) ;
+              Util_TableItQueryIsNonNull(ihandle) > 0 ;
+              Util_TableItAdvance(ihandle) )
+        {
+        CCTK_INT type_code, N_elements;
+        CCTK_INT value_int;
+        CCTK_REAL value_real;
+
+        Util_TableItQueryKeyValueInfo(ihandle,
+                                      N_key_buffer, key_buffer,
+                                      &type_code, &N_elements);
+        printf("key = \"%s\"\n", key_buffer);
+
+        switch  (type_code)
+                {
+        case CCTK_VARIABLE_INT:
+                Util_TableGetInt(handle, &value_int, key_buffer);
+                printf("value[int] = %d\n", (int)value_int);
+                break;
+        case CCTK_VARIABLE_REAL:
+                Util_TableGetReal(handle, &value_real, key_buffer);
+                printf("value[real] = %g\n", (double)value_real);
+                break;
+        default:
+                /* we don't know how to handle this type */
+                Util_TableItDestroy(ihandle);
+                free(key_buffer);
+                return type_code;
+                }
+        }
+
+Util_TableItDestroy(ihandle);
+free(key_buffer);
+return 0;
+}
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableItQueryTableHandle}
+\label{Util-TableItQueryTableHandle}
+Query what table a table iterator iterates over
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int handle = Util_TableItQueryTableHandle(int ihandle);
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{handle ($\ge 0$)}
+handle to the table over which the iterator iterates
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{ihandle ($\ge 0$)}
+handle to the iterator
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+Note that it is always ok to call this function, regardless of
+whether or not the iterator is in the ``null-pointer'' state.
+
+It's also ok to call this function even when the iterator has been
+invalidated by a change in the table's contents.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableItCreate()}
+create an iterator (which iterates over a specified table)
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+iterator handle is invalid
+\end{Error}
+\end{ErrorSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableItResetToStart}
+\label{Util-TableItResetToStart}
+Reset a table iterator to point to the starting table entry
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int status = Util_TableItResetToStart(int ihandle);
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{ResultNote}
+Results are the same as calling \verb|Util_TableItQueryIsNonNull()|
+on the iterator after the reset:
+\end{ResultNote}
+\begin{Result}{\rm 1}
+iterator is {\em not\/} in the ``null-pointer'' state,
+\ie{} iterator points to some table entry
+\end{Result}
+\begin{Result}{\rm 0}
+iterator is in the ``null-pointer'' state
+(this happens if and only if the table is empty)
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{ihandle ($\ge 0$)}
+handle to the iterator
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+Note that it is always ok to call this function, regardless of
+whether or not the iterator is in the ``null-pointer'' state.
+
+It's also ok to call this function even when the iterator has been
+invalidated by a change in the table's contents.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableItSetToNull()}
+set an iterator to the ``null-pointer'' state
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableItSetToKey()}
+set an iterator to point to a specified table entry
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+iterator handle is invalid
+\end{Error}
+\end{ErrorSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableItSetToKey}
+\label{Util-TableItSetToKey}
+Set a table iterator to point to a specified table entry
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int status = Util_TableItSetToKey(int ihandle, const char *key);
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{\rm 0}
+ok
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{ihandle ($\ge 0$)}
+handle to the iterator
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+This function has the same effect as calling \verb|Util_TableItResetToStart()|
+followed by calling \verb|Util_TableItAdvance()| zero or more times
+to make the iterator point to the desired table entry.  However, this
+function will typically be (much) more efficient than that sequence.
+
+Note that it is always ok to call this function, regardless of
+whether or not the iterator is in the ``null-pointer'' state.
+
+It's also ok to call this function even when the iterator has been
+invalidated by a change in the table's contents.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableItResetToStart()}
+reset an iterator to point to the starting table entry
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableItSetToNull()}
+set a table iterator to the "null-pointer" state
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+iterator handle is invalid
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY}
+key contains '/' character
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_NO\_SUCH\_KEY}
+no such key in table
+\end{Error}
+\end{ErrorSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableItSetToNull}
+\label{Util-TableItSetToNull}
+Set a table iterator to the "null-pointer" state
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int handle = Util_TableItSetToNull(int ihandle);
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{\rm 0}
+ok
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{ihandle ($\ge 0$)}
+handle to the iterator
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+Note that it is always ok to call this function, regardless of
+whether or not the iterator is already in the ``null-pointer'' state.
+
+It's also ok to call this function even when the iterator has been
+invalidated by a change in the table's contents.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableItResetToStart()}
+reset an iterator to point to the starting table entry
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableItSetToKey()}
+set an iterator to point to a specified table entry
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+iterator handle is invalid
+\end{Error}
+\end{ErrorSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableQueryFlags}
+Query a table's flags word
+\label{Util-TableQueryFlags}
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int flags = Util_TableQueryFlags(int handle);
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableQueryFlags(flags, handle)
+integer  flags, handle
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{flags ($\ge 0$)}
+the flags word
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+See \verb|Util_TableCreate()| for further discussion of the semantics
+of flag words.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableClone()}
+create a new table which is a ``clone'' (exact copy) of an existing
+table
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableCreate()}
+create a table (flags word specified explicitly)
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableCreateFromString()}
+convenience routine to create a table (with certain default flags)
+and set key/value entries in it based on a parameter-file--like
+character string
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+handle is invalid
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include <string.h>
+#include "util_ErrorCodes.h"
+#include "util_String.h"
+#include "util_Table.h"
+
+/* compare two strings, doing the comparison with the same */
+/* case-sensitive/insensitive semantics as a certain table uses */
+int compare_strings(int handle, const char *str1, const char *str2)
+{
+int flags = Util_TableQueryFlags(handle);
+return (flags & UTIL_TABLE_FLAGS_CASE_INSENSITIVE)
+       ? Util_StrCmpi(str1, str2)
+       :      strcmp (str1, str2);
+}
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableQueryValueInfo}
+\label{Util-TableQueryValueInfo}
+Query whether or not a specified key is in the table, and optionally
+the type and/or number of elements of the value corresponding to this key
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int key_exists =
+ Util_TableQueryValueInfo(int handle,
+                          CCTK_INT *type_code, CCTK_INT *N_elements,
+                          const char *key);
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableQueryValueInfo(key_exists,
+.                             handle,
+.                             type_code, N_elements,
+.                             key)
+integer        key_exists, handle
+CCTK_INT       type_code, N_elements
+character*(*)  key
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{\rm 1}
+ok (key is in table)
+\end{Result}
+\begin{Result}{\rm 0}
+ok (no such key in table)\\
+(in this case nothing is stored in \verb|*type_code| and \verb|*N_elements|)
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table
+\end{Parameter}
+\begin{Parameter}{type\_code}
+a pointer to where this function should store the value's type code
+(one of the \verb|CCTK_VARIABLE_|* constants from \verb|"cctk_Constants.h"|),
+or a NULL pointer to skip storing this.
+\end{Parameter}
+\begin{Parameter}{N\_elements}
+a pointer to where this function should store
+the number of array elements in the value,
+or a NULL pointer to skip storing this.
+\end{Parameter}
+\begin{Parameter}{key}
+a pointer to the key (a C-style null-terminated string)
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+Unlike all the other table query functions, this function returns
+0 for ``no such key in table''.  The rationale for this design is that
+by passing NULL pointers for \verb|type_code| and \verb|N_elements|, this
+function is then a Boolean ``is key in table?'' predicate.
+
+If any error code is returned, the user's buffers (pointed to by
+\verb|type_code| and \verb|N_elements| if these are non-NULL) are
+unchanged.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableItQueryKeyValueInfo()}
+query key present/absent in table, and optionally type and/or number
+of elements, but using an iterator instead of the key
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+handle is invalid
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY}
+key contains `/' character
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include <stdio.h>
+#include <assert.h>
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+
+static const int data[] = {314, 159, 265};
+#define N_DATA  (sizeof(data) / sizeof(data[0]))
+
+CCTK_INT type_code, N_elements;
+
+/* see whether or not "key" is in table */
+if (Util_TableQueryValueInfo(handle, NULL, NULL, "key"))
+        {
+        /* key is in the table */
+        }
+   else {
+        /* key is not in the table */
+        }
+
+/* put "data" in table as 3-element integer array */
+Util_TableSetIntArray(handle, N_DATA, data, "data");
+
+/* query info about "data" value */
+assert( Util_TableQueryValueInfo(handle,
+                                 &type_code, &N_elements,
+                                 "data") == 1 );
+assert( type_code == CCTK_VARIABLE_INT );
+assert( N_elements == N_DATA );
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableQueryMaxKeyLength}
+\label{Util-TableQueryMaxKeyLength}
+Query the maximum key length in a table
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int max_key_length = Util_TableQueryMaxKeyLength(int handle);
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableQueryMaxKeyLength(max_key_length, handle)
+integer  max_key_length, handle
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{max\_key\_length ($\ge 0$)}
+The string length of the longest key in the table
+(this has C {\t strlen()} semantics, \ie{} it does {\em not\/}
+include a terminating null character)
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+This function is useful if you're going to iterate through a table,
+and you want to allocate a buffer which is guaranteed to be big enough
+to hold any key in the table.
+\end{Discussion}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+handle is invalid
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include <stdlib.h>
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+#include "cctk.h"
+
+int max_key_length = Util_TableQueryMaxKeyLength(handle);
+int N_buffer = max_key_length + 1;
+char *const buffer = (char *) malloc(N_buffer);
+if (buffer == NULL)
+        {
+        CCTK_WARN(-1, "couldn't allocate memory for table key buffer!");
+        abort();        /* CCTK_Abort() would be better */
+                        /* if we have a cGH* available */
+        }
+
+/* now buffer is guaranteed to be */
+/* big enough for any key in the table */
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableQueryNKeys}
+\label{Util-TableQueryNKeys}
+Query the number of key/value entries in a table
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int N_Keys = Util_TableQueryNKeys(int handle);
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableQueryNKeys(N_Keys, handle)
+integer  N_Keys, handle
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{N\_Keys ($\ge 0$)}
+the number of key/value entries in the table
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+handle is invalid
+\end{Error}
+\end{ErrorSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableSet*}
+\label{Util-TableSet*}
+This is a family of functions, one for each Cactus data type,
+to set the value associated with a specified key to be a specified
+single (1-element array) value
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int status = Util_TableSetXxx(int handle,
+                              CCTK_XXX value,
+                              const char *key);
+\end{verbatim}
+where \verb|XXX| is one of
+   \verb|POINTER|, \verb|FPOINTER|%%%
+\footnote{%%%
+	 For backwards compatability the function
+	 {\tt Util\_TableSetFnPointer()} is also provided
+	 as an alias for {\tt Util\_TableSetFPointer()}.
+	 This is deprecated as of Cactus 4.0 beta 13.
+	 }%%%
+,
+   \verb|CHAR|,
+   \verb|INT|, \verb|INT2|, \verb|INT4|, \verb|INT8|,
+   \verb|REAL|, \verb|REAL4|, \verb|REAL8|, \verb|REAL16|,
+   \verb|COMPLEX|, \verb|COMPLEX8|, \verb|COMPLEX16|, \verb|COMPLEX32|
+(not all of these may be supported on any given system)
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableSetXxx(status, handle, value, key)
+integer        status, handle
+CCTK_XXX       value
+character*(*)  key
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{\rm 1}
+ok (key was already in table before this call, old value was replaced)\\
+   (it doesn't matter what the old value's \verb|type_code| and
+    \verb|N_elements| were, \ie{} these do {\em not\/} have to match
+    the new value)
+\end{Result}
+\begin{Result}{\rm 0}
+ok (key was not in table before this call)
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table
+\end{Parameter}
+\begin{Parameter}{value}
+the value to be associated with the key
+\end{Parameter}
+\begin{Parameter}{key}
+a pointer to the key (a C-style null-terminated string)
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+The key may be any C character string which does not contain a slash
+character (\verb|'/'|).
+
+The value is stored as a 1-element array.
+
+This function invalidates any iterators for the table which are
+not in the ``null-pointer'' state.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableCreateFromString()}
+convenience routine to create a table and set key/value entries
+in it based on a parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*()}
+get a single (1-element array) value,
+or more generally the first array element of an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*Array()}
+get an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGeneric()}
+get a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGenericArray()}
+get an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*String()}
+get a character-string value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*Array()}
+set an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGeneric()}
+set a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGenericArray()}
+set an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetFromString()}
+convenience routine to set key/value entries in a table based on a
+parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetString()}
+set a character-string value
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+handle is invalid
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY}
+key contains '/' character
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_NO\_MEMORY}
+unable to allocate memory
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include <math.h>
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+
+CCTK_COMPLEX16 z;
+int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);
+
+Util_TableSetInt(handle, 42, "the answer");
+Util_TableSetReal(handle, 299792458.0, "speed of light");
+
+z.Re = cos(0.37);       z.Im = sin(0.37);
+Util_TableSetComplex16(handle, z, "my complex number");
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableSet*Array}
+\label{Util-TableSet*Array}
+This is a family of functions, one for each Cactus data type,
+to set the value associated with a specified key to be a copy
+of a specified array
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int status = Util_TableSetXxxArray(int handle,
+                                   int N_elements,
+                                   const CCTK_XXX array[],
+                                   const char *key);
+\end{verbatim}
+where \verb|XXX| is one of
+   \verb|POINTER|, \verb|FPOINTER|%%%
+\footnote{%%%
+	 For backwards compatability the function
+	 {\tt Util\_TableSetFnPointerArray()} is also provided
+	 as an alias for {\tt Util\_TableSetFPointerArray()}.
+	 This is deprecated as of Cactus 4.0 beta 13.
+	 }%%%
+,
+   \verb|CHAR|,
+   \verb|INT|, \verb|INT2|, \verb|INT4|, \verb|INT8|,
+   \verb|REAL|, \verb|REAL4|, \verb|REAL8|, \verb|REAL16|,
+   \verb|COMPLEX|, \verb|COMPLEX8|, \verb|COMPLEX16|, \verb|COMPLEX32|
+(not all of these may be supported on any given system)
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableSetXxxArray(status, handle, N_elements, array, key)
+integer        status, handle, N_elements
+CCTK_XXX(*)    array
+character*(*)  key
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{\rm 1}
+ok (key was already in table before this call, old value was replaced)\\
+   (it doesn't matter what the old value's \verb|type_code| and
+    \verb|N_elements| were, \ie{} these do {\em not\/} have to match
+    the new value)
+\end{Result}
+\begin{Result}{\rm 0}
+ok (key was not in table before this call)
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table
+\end{Parameter}
+\begin{Parameter}{N\_elements ($\ge 0$)}
+the number of array elements in \verb|array[]|
+\end{Parameter}
+\begin{Parameter}{array}
+a pointer to the array (a copy of which) is to be associated with the key
+\end{Parameter}
+\begin{Parameter}{key}
+a pointer to the key (a C-style null-terminated string)
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+The key may be any C character string which does not contain a slash
+character (\verb|'/'|).
+
+Note that empty (0-element) arrays are ok.
+
+This function invalidates any iterators for the table which are
+not in the ``null-pointer'' state.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableCreateFromString()}
+convenience routine to create a table and set key/value entries
+in it based on a parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*()}
+get a single (1-element array) value,
+or more generally the first array element of an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*Array()}
+get an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGeneric()}
+get a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGenericArray()}
+get an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*String()}
+get a character-string value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*()}
+set a single (1-element array) value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGeneric()}
+set a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGenericArray()}
+set an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetFromString()}
+convenience routine to set key/value entries in a table based on a
+parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetString()}
+set a character-string value
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+handle is invalid
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY}
+key contains '/' character
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_BAD\_INPUT}
+\verb|N_elements| $< 0$
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_NO\_MEMORY}
+unable to allocate memory
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+
+#define N_DIGITS        5
+static const CCTK_INT pi_digits[N_DIGITS] = {3, 14, 159, 2653, 58979};
+int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);
+
+Util_TableSetIntArray(handle, N_DIGITS, pi_digits, "digits of pi");
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableSetFromString}
+\label{Util-TableSetFromString}
+Sets values in a table based on a string argument, which is interpreted
+with ``parameter-file'' semantics
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int count = Util_TableSetFromString(int handle, const char *string);
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableSetFromString(count, handle, string)
+integer        count, handle
+character*(*)  string
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{count ($\ge 0$)}
+the number of key/value entries set
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{string}
+a pointer to a C-style null-terminated string specifying the table
+entries to be set (see below for details on the string contents)
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+The string should contain a sequence of zero or more \verb|key=value|
+``assignments'', separated by whitespace.  This function processes
+these assignments in left-to-right order, setting corresponding key/value
+entries in the table.
+
+The present implementation only recognises integer, real, and character-string
+values (not complex), and integer and real arrays.
+To be precise, the string must match the following BNF:\\
+\quad
+\begin{tabular}{l@{\quad$\rightarrow$\quad}p{9cm}}
+string  & assign*                                                       \\
+assign  & whitespace*                                                   \\
+assign  & whitespace* key whitespace* = whitespace* value delimiter     \\
+key     & any string not containing \verb|'/'| or \verb|'='| or whitespace\\
+value   & array $\big|$ int\_value $\big|$ real\_value $\big|$ string\_value\\
+array   & \{ int\_value* \} $\big|$ \{ real\_value \}                   \\
+int\_value      & anything recognized as a valid integer by strdol(3)
+                  in base 10                                            \\
+real\_value     & anything not recognized as a valid integer by strtol(3)
+                  but recognized as valid by strdod(3)                  \\
+string\_value   & a C-style string enclosed in "double quotes"
+                  (C-style character escape codes are allowed
+                  ie. bell~(\verb|'\a'|), backspace~(\verb|'\b'|),
+                  form-feed~(\verb|'\f'|), newline~(\verb|'\n'|),
+                  carriage-return~(\verb|'\r'|), tab~(\verb|'\t'|),
+                  vertical-tab~(\verb|'\v'|), backslash~(\verb|'\\'|),
+                  single-quote~(\verb|'\''|), double-quote~(\verb|'\"'|),
+                  question-mark~(\verb|'\?'|))                          \\
+string\_value   & a C-style string enclosed in 'single quotes'
+                  (C-style character escape codes are {\bf not} allowed,
+                  ie. every character within the string is interpreted
+                  literally)                                            \\
+delimiter       & end-of-string $\big|$ whitespace                      \\
+whitespace      & blank~(\verb|' '|)
+                  $\big|$ tab~(\verb|'\t'|)
+                  $\big|$ newline~(\verb|'\n'|)
+                  $\big|$ carriage-return~(\verb|'\r'|)
+                  $\big|$ form-feed~(\verb|'\f'|)
+                  $\big|$ vertical-tab~(\verb|'\v'|)                    %%%\\
+\end{tabular}\\
+where * denotes 0 or more repetitions and $\big|$ denotes logical or.
+
+Notice also that the keys allowed by this function are somewhat more
+restricted than those allowed by the other \verb|Util_TableSet*()|
+functions, in that this function disallows keys containing \verb|'='|
+and/or whitespace.
+
+If any error code is returned, assignments lexicographically earlier
+in the input string than where the error was detected will already
+have been made in the table.  Unfortunately, there is no easy way to
+find out where the error was detected. :(
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableCreateFromString()}
+convenience routine to create a table and set key/value entries
+in it based on a parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*()}
+get a single (1-element array) value,
+or more generally the first array element of an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*Array()}
+get an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGeneric()}
+get a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGenericArray()}
+get an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*String()}
+get a character-string value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*()}
+set a single (1-element array) value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*Array()}
+set an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGeneric()}
+set a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGenericArray()}
+set an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetString()}
+set a character-string value
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_NO\_MEMORY}
+unable to allocate memory
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_BAD\_KEY}
+invalid input: key contains invalid character
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_BAD\_INPUT}
+invalid input: can't parse input string
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_NO\_MIXED\_TYPE\_ARRAY}
+invalid input: different array values have different datatypes
+\end{Error}
+\begin{Error}{\rm other error codes}
+this function may also return any error codes returned by
+\verb|Util_TableSetString()|, \verb|Util_TableSetInt()|,
+\verb|Util_TableSetReal()|, \verb|Util_TableSetIntArray()|,
+or \verb|Util_TableSetRealArray()|.
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+
+/* suppose we have a table referred to by  handle */
+
+/* then the call... */
+int count = Util_TableSetFromString(handle, "n = 6\t"
+                                            "dx = 4.0e-5\t"
+                                            "pi = 3.1\t"
+                                            "s = 'my string'\t"
+                                            "array = { 1 2 3 }");
+/* ... will return count=5 ... */
+
+/* ... and is otherwise equivalent to the five calls ... */
+CCTK_INT array[] = {1, 2, 3};
+
+Util_TableSetInt(handle, 6, "n");
+Util_TableSetReal(handle, 4.0e-5, "dx");
+Util_TableSetReal(handle, 3.1, "pi");
+Util_TableSetString(handle, "my string", "s");
+Util_TableSetIntArray(handle, 3, array, "array");
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableSetGeneric}
+\label{Util-TableSetGeneric}
+Set the value associated with a specified key to be a specified
+single (1-element array) value, whose data type is generic.  That
+is, the value is specified by a \verb|CCTK_VARIABLE_|* type code
+and a \verb|void *| pointer.
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int status = Util_TableSetGeneric(int handle,
+                                  int type_code, const void *value,
+                                  const char *key);
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableSetGeneric(status, handle, type_code, value, key)
+integer        status, handle, type_code
+CCTK_POINTER   value
+character*(*)  key
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{\rm 1}
+ok (key was already in table before this call, old value was replaced)\\
+   (it doesn't matter what the old value's \verb|type_code| and
+    \verb|N_elements| were, \ie{} these do {\em not\/} have to match
+    the new value)
+\end{Result}
+\begin{Result}{\rm 0}
+ok (key was not in table before this call)
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table
+\end{Parameter}
+\begin{Parameter}{type\_code}
+the array elements' type code
+(one of the \verb|CCTK_VARIABLE_|* constants from \verb|"cctk_Constants.h"|)
+\end{Parameter}
+\begin{Parameter}{value\_ptr}
+a pointer to the value to be associated with the key
+\end{Parameter}
+\begin{Parameter}{key}
+a pointer to the key (a C-style null-terminated string)
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+The key may be any C character string which does not contain a slash
+character (\verb|'/'|).
+
+The value is stored as a 1-element array.
+
+This function invalidates any iterators for the table which are
+not in the ``null-pointer'' state.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableCreateFromString()}
+convenience routine to create a table and set key/value entries
+in it based on a parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*()}
+get a single (1-element array) value,
+or more generally the first array element of an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*Array()}
+get an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGeneric()}
+get a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGenericArray()}
+get an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*String()}
+get a character-string value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*()}
+set a single (1-element array) value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*Array()}
+set an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGeneric()}
+set a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGenericArray()}
+set an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetFromString()}
+convenience routine to set key/value entries in a table based on a
+parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetString()}
+set a character-string value
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+handle is invalid
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY}
+key contains '/' character
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_NO\_MEMORY}
+unable to allocate memory
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_Table.h"
+#include "cctk_Constants.h"
+
+const CCTK_INT i = 42;
+const void *iptr = (void *) &i;
+CCTK_INT icopy;
+
+const CCTK_REAL x = 299792458.0;
+const void *xptr = (void *) &x;
+CCTK_REAL xcopy;
+
+const int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);
+
+Util_TableSetGeneric(handle, CCTK_VARIABLE_INT, iptr, "the answer");
+Util_TableSetGeneric(handle, CCTK_VARIABLE_REAL, xptr, "speed of light");
+
+/* gets icopy to 42 */
+Util_TableGetInt(handle, &icopy, "the answer");
+
+/* gets xcopy to 299792458.0 */
+Util_TableGetReal(handle, &xcopy, "speed of light");
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableSetGenericArray}
+\label{Util-TableSetGenericArray}
+Set the value associated with a specified key to be a copy of a
+specified array, whose data type is generic.  That is, the array
+is specified by a \verb|CCTK_VARIABLE_|* type code, a count of
+the number of array elements, and a \verb|void *| pointer.
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int status = Util_TableSetGenericArray(int handle,
+                                       int type_code,
+                                       int N_elements, const void *array,
+                                       const char *key);
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableSetGenericArray(status,
+.                              handle,
+.                              type_code,
+.                              N_elements, array,
+.                              key)
+integer           status, handle, type_code, N_elements
+CCTK_POINTER(*)   array
+character*(*)     key
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{\rm 1}
+ok (key was already in table before this call, old value was replaced)\\
+   (it doesn't matter what the old value's \verb|type_code| and
+    \verb|N_elements| were, \ie{} these do {\em not\/} have to match
+    the new value)
+\end{Result}
+\begin{Result}{\rm 0}
+ok (key was not in table before this call)
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table
+\end{Parameter}
+\begin{Parameter}{type\_code}
+the array elements' type code
+(one of the \verb|CCTK_VARIABLE_|* constants from \verb|"cctk_Constants.h"|)
+\end{Parameter}
+\begin{Parameter}{N\_elements ($\ge 0$)}
+the number of array elements in \verb|array[]|
+\end{Parameter}
+\begin{Parameter}{value\_ptr}
+a pointer to the value to be associated with the key
+\end{Parameter}
+\begin{Parameter}{key}
+a pointer to the key (a C-style null-terminated string)
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+The key may be any C character string which does not contain a slash
+character (\verb|'/'|).
+
+The value is stored as a 1-element array.
+
+This function invalidates any iterators for the table which are
+not in the ``null-pointer'' state.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableCreateFromString()}
+convenience routine to create a table and set key/value entries
+in it based on a parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*()}
+get a single (1-element array) value,
+or more generally the first array element of an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*Array()}
+get an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGeneric()}
+get a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGenericArray()}
+get an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*String()}
+get a character-string value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*()}
+set a single (1-element array) value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*Array()}
+set an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGeneric()}
+set a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetFromString()}
+convenience routine to set key/value entries in a table based on a
+parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetString()}
+set a character-string value
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+handle is invalid
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY}
+key contains '/' character
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_NO\_MEMORY}
+unable to allocate memory
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_Table.h"
+#include "cctk_Constants.h"
+
+#define N_IARRAY    3
+const CCTK_INT iarray[N_IARRAY] = {42, 69, 105};
+const void *iarray_ptr = (void *) iarray;
+CCTK_INT iarray2[N_IARRAY];
+
+#define N_XARRAY    2
+const CCTK_REAL xarray[N_XARRAY] = {6.67e-11, 299792458.0};
+const void *xarray_ptr = (void *) xarray;
+CCTK_REAL xarray2[N_XARRAY];
+
+const int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);
+
+Util_TableSetGenericArray(handle,
+                          CCTK_VARIABLE_INT,
+                          N_IARRAY, iarray_ptr,
+                          "my integer array");
+Util_TableSetGenericArray(handle,
+                          CCTK_VARIABLE_REAL,
+                          N_XARRAY, xarray_ptr,
+                          "my real array");
+
+/* gets iarray2[0] = 42, iarray2[1] = 69, iarray2[2] = 105 */
+Util_TableGetIntArray(handle, N_IARRAY, iarray2, "my integer array");
+
+/* gets xarray2[0] = 6.67e-11, xarray2[1] = 299792458.0 */
+Util_TableGetRealArray(handle, N_XARRAY, xarray2, "my real array");
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{FunctionDescription}{Util\_TableSetString}
+\label{Util-TableSetString}
+Sets the value associated with a specified key in a table, to be
+a copy of a specified C-style null-terminated character string
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+int status = Util_TableSetString(int handle,
+                                 const char *string,
+                                 const char *key);
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+call Util_TableSetString(status, handle, string, key)
+integer           status, handle
+character*(*)     string, key
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{ResultNote}
+Results are the same as all the other \verb|Util_TableSet|* functions:
+\end{ResultNote}
+\begin{Result}{\rm 1}
+ok (key was already in table before this call, old value was replaced)\\
+   (it doesn't matter what the old value's \verb|type_code| and
+    \verb|N_elements| were, \ie{} these do {\em not\/} have to match
+    the new value)
+\end{Result}
+\begin{Result}{\rm 0}
+ok (key was not in table before this call)
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{handle ($\ge 0$)}
+handle to the table
+\end{Parameter}
+\begin{Parameter}{string}
+a pointer to the string (a C-style null-terminated string)
+\end{Parameter}
+\begin{Parameter}{key}
+a pointer to the key (a C-style null-terminated string)
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
+The key may be any C character string which does not contain a slash
+character (\verb|'/'|).
+
+The string is stored as an array of \verb|strlen(string)|
+\verb|CCTK_CHAR|s.  It does {\em not\/} include a terminating
+null character.
+
+This function is very similar to \verb|Util_TableSetCharArray()|.
+
+This function invalidates any iterators for the table which are
+not in the ``null-pointer'' state.
+\end{Discussion}
+
+\begin{SeeAlsoSection}
+\begin{SeeAlso}{Util\_TableCreateFromString()}
+convenience routine to create a table and set key/value entries
+in it based on a parameter-file--like character string
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*()}
+get a single (1-element array) value,
+or more generally the first array element of an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*Array()}
+get an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGeneric()}
+get a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGetGenericArray()}
+get an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableGet*String()}
+get a character-string value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetCharArray()}
+get an array-of-\verb|CCTK_CHAR| value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*()}
+set a single (1-element array) value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSet*Array()}
+set an array value
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGeneric()}
+set a single (1-element array) value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetGenericArray()}
+set an array value with generic data type
+\end{SeeAlso}
+\begin{SeeAlso}{Util\_TableSetCharArray()}
+set an array-of-\verb|CCTK_CHAR| value
+\end{SeeAlso}
+\end{SeeAlsoSection}
+
+\begin{ErrorSection}
+\begin{Error}{UTIL\_ERROR\_BAD\_HANDLE}
+handle is invalid
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_TABLE\_BAD\_KEY}
+key contains '/' character
+\end{Error}
+\begin{Error}{UTIL\_ERROR\_NO\_MEMORY}
+unable to allocate memory
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "util_ErrorCodes.h"
+#include "util_Table.h"
+
+static const CCTK_CHAR array[]
+        = {'r', 'e', 'l', 'a', 't', 'i', 'v', 'i', 't', 'y'};
+#define N_ARRAY (sizeof(array) / sizeof(array[0]))
+int handle = Util_TableCreate(UTIL_TABLE_FLAGS_DEFAULT);
+
+Util_TableSetString(handle, "relativity", "Einstein");
+
+/* this produces the same table entry as the Util_TableSetString() */
+Util_TableSetCharArray(handle, N_ARRAY, array, "Einstein");
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\end{cactuspart}
diff --git a/doc/ReferenceManual/Preface.tex b/doc/ReferenceManual/Preface.tex
new file mode 100644
index 00000000..1e4b0e8a
--- /dev/null
+++ b/doc/ReferenceManual/Preface.tex
@@ -0,0 +1,111 @@
+% /*@@
+%   @file      Preface.tex
+%   @date      Sun Jul 20 11:41:11 CEST 2003
+%   @author    Jonathan Thornburg, borrowing heavily from the
+%              Preface for the Cactus User's Guide
+%   @desc 
+%   Preface for the Cactus Reference Manual
+%   @enddesc 
+%   @version $Header$
+% @@*/
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+{\large \bf Preface} 
+\label{sec:pr}
+ 
+\vskip .5cm
+
+This document will eventually be a complete reference manual for
+the Cactus Code. However, it is currently under
+development, so please be patient if you can't find what you need.
+Please report omissions, errors, or suggestions to 
+and of our contact addresses below, and we will
+try and fix them as soon as possible. 
+
+\vskip .5cm
+
+{\bf Overview of documentation}
+
+\vskip .5cm
+
+This guide covers the following topics
+
+\begin{Lentry}
+
+\item [{\bf Part~\ref{part:FunctionReference}: Function Reference.}]
+	Here all Cactus flesh functions which are available to
+	thorn writers in C and/or Fortran are described.
+
+\item [\bf Part~\ref{part:Appendices}: Appendices.]
+	These contain a description of the Cactus Configuration Language,
+	a glossary,
+	and other odds and ends, such as how to use GNATS or TAGS.
+
+\end{Lentry}
+
+Other topics to be discussed in separate documents include:
+
+\begin{Lentry}
+
+\item [{\bf Users' Guide}] This gives a general overview of the
+  Cactus Computational Tool Kit, including overall design/architecture,
+  how to get/configure/compile/run it, and general discussions of the
+  how to program in Cactus.
+
+\item [{\bf Relativity Thorn Guide}] This will contain details about the arrangements and thorns making up the Cactus Relativity Tool Kit, one of the major 
+ motivators, and still the driving force, for the Cactus Code.
+
+\item [{\bf Flesh Maintainers Guide}] 
+ This will contain all the gruesome details
+ about the inner workings of Cactus, for all those who want or need to 
+ expand or maintain the core of Cactus.
+
+\end{Lentry}
+
+\vskip .5cm
+
+{\bf Typographical Conventions}
+
+\begin{Lentry}
+
+\item[{\tt Typewriter}] Is currently used for everything you type,
+	for program names, and code extracts.
+\item[{\tt < ... >}] Indicates a compulsory argument.
+\item[{\tt [ ... ]}] Indicates an optional argument.
+\item[{\tt |}] Indicates an exclusive or.
+
+\end{Lentry}
+ 
+\vskip .5cm
+
+{\bf How to Contact Us}
+
+\vskip .5cm
+
+Please let us know of any errors or omissions in this guide, as well
+as suggestions for future editions. These can be reported via our 
+bug tracking system at {\tt www.cactuscode.org}, or via email to
+{\tt cactusmaint@cactuscode.org}. Alternatively, write to us at
+
+\vskip .5cm
+The Cactus Team\\
+Albert Einstein Institute\\
+Max Planck Institute for Gravitational Physics\\
+Am M\"{u}hlenberg 1\\
+D-14476 Golm\\
+Germany
+
+
+\vskip .5cm
+
+{\bf Acknowledgements}
+
+\vskip .5cm
+
+Hearty thanks to all those who have helped with documentation for the
+Cactus Code. Special thanks to those who struggled with the earliest
+sparse versions of this guide and sent in mistakes and suggestions,
+in particular John Baker, Carsten Gundlach, Ginny Hudak-David, 
+Sai Iyer, Paul Lamping, Nancy Tran and Ed Seidel. 
diff --git a/doc/ReferenceManual/ReferenceManual.tex b/doc/ReferenceManual/ReferenceManual.tex
new file mode 100644
index 00000000..446221f4
--- /dev/null
+++ b/doc/ReferenceManual/ReferenceManual.tex
@@ -0,0 +1,89 @@
+% /*@@
+%   @file      ReferenceManual.tex
+%   @date      Sun Jul 20 11:37:03 CEST 2003
+%   @author    Jonathan Thornburg, borrowing latex source from
+%              the Cactus Users' Guide which was contributed by
+%              many people
+%   @desc 
+%   Main file for the Cactus Reference Manual
+%   @enddesc 
+%   @version $Header$
+% @@*/
+
+\documentclass{report}
+
+\usepackage[
+pdfauthor={Gabrielle Allen, Tom Goodale, Gerd Lanfermann, Thomas Radke, David Rideout, Jonathan Thornburg},
+pdftitle={Cactus Reference Manual},
+pdfpagelabels,
+pdfstartview=FitV,
+hypertexnames=false,
+plainpages=false,
+colorlinks=true,
+linkcolor=blue,
+citecolor=blue,
+urlcolor=blue
+]{hyperref}
+
+
+
+% This must come after most of the other \usepackages, because we
+% might want to pass options to them
+\usepackage{../latex/cactus}
+
+
+
+\usepackage{tocloft}
+\addtolength{\cftchapnumwidth}{0.5em}
+\addtolength{\cftsecnumwidth}{0.5em}
+\addtolength{\cftsubsecnumwidth}{0.5em}
+\addtolength{\cftsubsubsecnumwidth}{0.5em}
+
+\makeatletter
+\@addtoreset{chapter}{part}
+\makeatother
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{document}
+
+\cactustitlepage{Reference Manual}{$ $Revision$ $}{$ $Date$ $}
+
+\setcounter{page}{1}
+
+% Table of contents
+\pagenumbering{roman}
+
+\tableofcontents
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\renewcommand{\thepart}{\BigAlph{part}}
+\renewcommand{\thechapter}{\BigAlph{part}\arabic{chapter}}
+\renewcommand{\thepage}{\BigAlph{part}\arabic{page}}
+\pagestyle{fancy}
+\parskip = 10 pt
+\parindent = 0pt
+
+\newpage
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\input Preface.tex
+
+\input FunctionReference.tex
+
+\input ../UsersGuide/Appendices.tex
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\end{document}