% /*@@ % @file CCTKReference.tex % @date 27 Jan 1999 % @author Tom Goodale, Gabrielle Allen, Gerd Lanferman % @desc % Function Reference for the Cactus User's Guide % @enddesc % @version $Header$ % @history % @date Sat Nov 3 18:47:53 MET 2001 % @author Jonathan Thornburg % @desc Add new section for Utility functions, % add key/value table functions in that section % @endhistory % @history % @date Sun Jul 20 13:28:43 CEST 2003 % @author Jonathan Thornburg % @desc rename this to CCTKReference.tex, % split Util_*() functions off into a separate file % UtilReference.tex % @endhistory % @@*/ \begin{cactuspart}{\code{CCTK\_*} Functions Reference}{$RCSfile$}{$Revision$} \label{part:CCTKReference} \renewcommand{\thepage}{\Alph{part}\arabic{page}} In this chapter all \code{CCTK\_*} Cactus functions are described. These functions are callable from Fortran or C thorns. Note that whereas all functions are available from C, not all are currently available from Fortran. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Functions Alphabetically} \begin{Lentry} \item[\code{CCTK\_Abort}] [\pageref{CCTK-Abort}] Causes abnormal Cactus termination \item[\code{CCTK\_ActivatingThorn}] [\pageref{CCTK-ActivatingThorn}] Finds the thorn which activated a particular implementation \item[\code{CCTK\_ActiveTimeLevels}] [\pageref{CCTK-ActiveTimeLevels}] Returns the number of active timelevels from a group name \item[\code{CCTK\_ActiveTimeLevelsGI}] [\pageref{CCTK-ActiveTimeLevels}] Returns the number of active timelevels from a group index \item[\code{CCTK\_ActiveTimeLevelsGN}] [\pageref{CCTK-ActiveTimeLevels}] Returns the number of active timelevels from a group name \item[\code{CCTK\_ActiveTimeLevelsVI}] [\pageref{CCTK-ActiveTimeLevels}] Returns the number of active timelevels from a variable index \item[\code{CCTK\_ActiveTimeLevelsVN}] [\pageref{CCTK-ActiveTimeLevels}] Returns the number of active timelevels from a variable name \item[\code{CCTK\_ArrayGroupSize}] [\pageref{CCTK-ArrayGroupSize}] Returns a pointer to the local size for a group, given by its group name \item[\code{CCTK\_ArrayGroupSizeI}] [\pageref{CCTK-ArrayGroupSizeI}] Returns a pointer to the local size for a group, given by its group index \item[\code{CCTK\_Barrier}] [\pageref{CCTK-Barrier}] Synchronizes all processors \item[\code{CCTK\_Cmplx}] [\pageref{CCTK-Cmplx}] Turns two real numbers into a complex number (only C) \item[\code{CCTK\_CmplxAbs}] [\pageref{CCTK-CmplxAbs}] Returns the absolute value of a complex number (only C) \item[\code{CCTK\_CmplxAdd}] [\pageref{CCTK-CmplxAdd}] Returns the sum of two complex numbers (only C) \item[\code{CCTK\_CmplxConjg}] [\pageref{CCTK-CmplxConjg}] Returns the complex conjugate of a complex number (only C) \item[\code{CCTK\_CmplxCos}] [\pageref{CCTK-CmplxCos}] Returns the Cosine of a complex number (only C) [not yet available] \item[\code{CCTK\_CmplxDiv}] [\pageref{CCTK-CmplxDiv}] Returns the division of two complex numbers (only C) \item[\code{CCTK\_CmplxExp}] [\pageref{CCTK-CmplxExp}] Returns the Exponentiation of a complex number (only C) [not yet available] \item[\code{CCTK\_CmplxImag}] [\pageref{CCTK-CmplxImag}] Returns the imaginary part of a complex number (only C) \item[\code{CCTK\_CmplxLog}] [\pageref{CCTK-CmplxLog}] Returns the Logarithm of a complex number (only C) [not yet available] \item[\code{CCTK\_CmplxMul}] [\pageref{CCTK-CmplxMul}] Returns the multiplication of two complex numbers (only C) \item[\code{CCTK\_CmplxReal}] [\pageref{CCTK-CmplxReal}] Returns the real part of a complex number (only C) \item[\code{CCTK\_CmplxSin}] [\pageref{CCTK-CmplxSin}] Returns the Sine of a complex number (only C) [not yet available] \item[\code{CCTK\_CmplxSqrt}] [\pageref{CCTK-CmplxSqrt}] Returns the square root of a complex number (only C) [not yet available] \item[\code{CCTK\_CmplxSub}] [\pageref{CCTK-CmplxSub}] Returns the subtraction of two complex numbers (only C) \item[\code{CCTK\_CompiledImplementation}] [\pageref{CCTK-CompiledImplementation}] Return the name of the compiled implementation with given index \item[\code{CCTK\_CompiledThorn}] [\pageref{CCTK-CompiledThorn}] Return the name of the compiled thorn with given index \item[\code{CCTK\_CoordDir}] [\pageref{CCTK-CoordDir}] Give the direction for a given coordinate name \item[\code{CCTK\_CoordIndex}] [\pageref{CCTK-CoordIndex}] Give the grid variable index for a given coordinate \item[\code{CCTK\_CoordRange}] [\pageref{CCTK-CoordRange}] Return the global upper and lower bounds for a given coordinate name on a cctkGH \item[\code{CCTK\_CoordRegisterData}] [\pageref{CCTK-CoordRegisterData}] Register a coordinate as belonging to a coordinate system, with a given name and direction, and optionally with a grid variable \item[\code{CCTK\_CoordRegisterRange}] [\pageref{CCTK-CoordRegisterRange}] Saves the global upper and lower bounds for a given coordinate name on a cctkGH \item[\code{CCTK\_CoordRegisterSystem}] [\pageref{CCTK-CoordRegisterSystem}] Registers a coordinate system with a given dimension \item[\code{CCTK\_CoordSystemDim}] [\pageref{CCTK-CoordDim}] Provides the dimension of a given coordinate system \item[\code{CCTK\_CoordSystemHandle}] [\pageref{CCTK-CoordSystemHandle}] Get the handle associated with a registered coordinate system \item[\code{CCTK\_CoordSystemName}] [\pageref{CCTK-CoordSystemName}] Provides the name of the coordinate system identified by its handle \item[\code{CCTK\_CreateDirectory}] [\pageref{CCTK-CreateDirectory}] Creates a directory \item[\code{CCTK\_DecomposeName}] [\pageref{CCTK-DecomposeName}] Given the full name of a variable/group, separates the name returning both the implementation and the variable/group \item[\code{CCTK\_DisableGroupComm}] [\pageref{CCTK-DisableGroupComm}] Disable the communication for a group \item[\code{CCTK\_DisableGroupCommI}] [\pageref{CCTK-DisableGroupCommI}] Disable the communication for a group \item[\code{CCTK\_DisableGroupStorage}] [\pageref{CCTK-DisableGroupStorage}] Disable the storage for a group \item[\code{CCTK\_DisableGroupStorageI}] [\pageref{CCTK-DisableGroupStorageI}] Disable the storage for a group \item[\code{CCTK\_EnableGroupComm}] [\pageref{CCTK-EnableGroupComm}] Enable the communication for a group \item[\code{CCTK\_EnableGroupCommI}] [\pageref{CCTK-EnableGroupComm}] Enable the communication for a group \item[\code{CCTK\_EnableGroupStorage}] [\pageref{CCTK-EnableGroupStorage}] Enable the storage for a group \item[\code{CCTK\_EnableGroupStorageI}] [\pageref{CCTK-EnableGroupStorage}] Enable the storage for a group \item[\code{CCTK\_Equals}] [\pageref{CCTK-Equals}] Check a STRING or KEYWORD parameter for equality equality with a given string \item[\code{CCTK\_Exit}] [\pageref{CCTK-Exit}] Causes normal Cactus termination \item[\code{CCTK\_FirstVarIndex}] [\pageref{CCTK-FirstVarIndex}] Given a group name returns the first variable index in the group \item[\code{CCTK\_FirstVarIndexI}] [\pageref{CCTK-FirstVarIndexI}] Given a group index returns the first variable index in the group \item[\code{CCTK\_FortranString}] [\pageref{CCTK-FortranString}] Changes a C string into a Fortran string \item[\code{CCTK\_FullName}] [\pageref{CCTK-FullName}] Given a variable index, returns the full name of the variable \item[\code{CCTK\_GHExtension}] [\pageref{CCTK-GHExtension}] Get the pointer to a registered extension to the Cactus GH structure \item[\code{CCTK\_GHExtensionHandle}] [\pageref{CCTK-GHExtensionHandle}] Get the handle associated with a extension to the Cactus GH structure \item[\code{CCTK\_GroupbboxGI}] [\pageref{CCTK-GroupbboxGI}] Given a group index, return an array of the bounding box of the group for each face \item[\code{CCTK\_GroupbboxGN}] [\pageref{CCTK-GroupbboxGN}] Given a group name, return an array of the bounding box of the group for each face \item[\code{CCTK\_GroupbboxVI}] [\pageref{CCTK-GroupbboxVI}] Given a variable index, return an array of the bounding box of the variable for each face \item[\code{CCTK\_GroupbboxVN}] [\pageref{CCTK-GroupbboxVN}] Given a variable name, return an array of the bounding box of the variable for each face \item[\code{CCTK\_GroupData}] [\pageref{CCTK-GroupData}] Given a group index, returns information about the variables held in the group \item[\code{CCTK\_GroupDynamicData}] [\pageref{CCTK-GroupDynamicData}] Given a group index, returns information about the variables held in the group \item[\code{CCTK\_GroupgshGI}] [\pageref{CCTK-GroupgshGI}] Given a group index, return an array of the global size of the group in each dimension \item[\code{CCTK\_GroupgshGN}] [\pageref{CCTK-GroupgshGN}] Given a group name, return an array of the global size of the group in each dimension \item[\code{CCTK\_GroupgshVI}] [\pageref{CCTK-GroupgshVI}] Given a variable index, return an array of the global size of the variable in each dimension \item[\code{CCTK\_GroupgshVN}] [\pageref{CCTK-GroupgshVN}] Given a variable name, return an array of the global size of the variable in each dimension \item[\code{CCTK\_GroupIndex}] [\pageref{CCTK-GroupIndex}] Get the index number for a group name \item[\code{CCTK\_GroupIndexFromVar}] [\pageref{CCTK-GroupIndexFromVar}] Given a variable name, returns the index of the associated group \item[\code{CCTK\_GroupIndexFromVarI}] [\pageref{CCTK-GroupIndexFromVarI}] Given a variable index, returns the index of the associated group \item[\code{CCTK\_GrouplbndGI}] [\pageref{CCTK-GrouplbndGI}] Given a group index, return an array of the lower bounds of the group in each dimension \item[\code{CCTK\_GrouplbndGN}] [\pageref{CCTK-GrouplbndGN}] Given a group name, return an array of the lower bounds of the group in each dimension \item[\code{CCTK\_GrouplbndVI}] [\pageref{CCTK-GrouplbndVI}] Given a variable index, return an array of the lower bounds of the variable in each dimension \item[\code{CCTK\_GrouplbndVN}] [\pageref{CCTK-GrouplbndVN}] Given a variable name, return an array of the lower bounds of the variable in each dimension \item[\code{CCTK\_GrouplshGI}] [\pageref{CCTK-GrouplshGI}] Given a group index, return an array of the local size of the group in each dimension \item[\code{CCTK\_GrouplshGN}] [\pageref{CCTK-GrouplshGN}] Given a group name, return an array of the local size of the group in each dimension \item[\code{CCTK\_GrouplshVI}] [\pageref{CCTK-GrouplshVI}] Given a variable index, return an array of the local size of the variable in each dimension \item[\code{CCTK\_GrouplshVN}] [\pageref{CCTK-GrouplshVN}] Given a variable name, return an array of the local size of the variable in each dimension \item[\code{CCTK\_GroupName}] [\pageref{CCTK-GroupName}] Given a group index, returns the group name \item[\code{CCTK\_GroupNameFromVarI}] [\pageref{CCTK-GroupNameFromVarI}] Given a variable index, return the name of the associated group \item[\code{CCTK\_GroupnghostzonesGI}] [\pageref{CCTK-GroupnghostzonesGI}] Given a group index, return an array with the number of ghostzones in each dimension of the group \item[\code{CCTK\_GroupnghostzonesGN}] [\pageref{CCTK-GroupnghostzonesGN}] Given a group name, return an array with the number of ghostzones in each dimension of the group \item[\code{CCTK\_GroupStorageDecrease}] [\pageref{CCTK-GroupStorageDecrease}] Decrease the active number of timelevels for a list of groups \item[\code{CCTK\_GroupStorageIncrease}] [\pageref{CCTK-GroupStorageIncrease}] Increase the active number of timelevels for a list of groups \item[\code{CCTK\_GroupTypeFromVarI}] [\pageref{CCTK-GroupTypeFromVarI}] Provides a group's group type index given a variable index \item[\code{CCTK\_GroupTypeI}] [\pageref{CCTK-GroupTypeI}] Provides a group's group type index given a group index \item[\code{CCTK\_GroupubndGI}] [\pageref{CCTK-GroupubndGI}] Given a group index, return an array of the upper bounds of the group in each dimension \item[\code{CCTK\_GroupubndGN}] [\pageref{CCTK-GroupubndGN}] Given a group name, return an array of the upper bounds of the group in each dimension \item[\code{CCTK\_GroupubndVI}] [\pageref{CCTK-GroupubndVI}] Given a variable index, return an array of the upper bounds of the variable in each dimension \item[\code{CCTK\_GroupubndVN}] [\pageref{CCTK-GroupubndVN}] Given a variable name, return an array of the upper bounds of the variable in each dimension \item[\code{CCTK\_ImpFromVarI}] [\pageref{CCTK-ImpFromVarI}] Given a variable index, returns the implementation name \item[\code{CCTK\_ImplementationRequires}] [\pageref{CCTK-ImplementationRequires}] Return the ancestors for an implementation \item[\code{CCTK\_ImplementationThorn}] [\pageref{CCTK-ImplementationThorn}] Returns the name of one thorn providing an implementation \item[\code{CCTK\_ImpThornList}] [\pageref{CCTK-ImpThornList}] Return the thorns for an implementation \item[\code{CCTK\_INFO}] [\pageref{CCTK-INFO}] Macro to print a single string as an information message to screen \item[\code{CCTK\_InterpGridArrays}] [\pageref{CCTK-InterpGridArrays}] Performs an interpolation on a list of CCTK grid arrays, using a chosen external local interpolation operator \item[\code{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 \code{CCTK\_InterpGridArrays}) \item[\code{CCTK\_InterpHandle}] [\pageref{CCTK-InterpHandle}] Returns the handle for a given interpolation operator \item[\code{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 \code{CCTK\_InterpLocalUniform}, \code{CCTK\_InterpLocalNonUniform}, and \code{CCTK\_InterpLocalWarped}.) %notyet \item[\code{CCTK\_InterpLocalNonUniform}] %notyet [\pageref{CCTK-InterpLocalNonUniform}] %notyet Interpolate a list of processor-local arrays %notyet which define a nonuniformly spaced data grid (not implemented yet) \item[\code{CCTK\_InterpLocalUniform}] [\pageref{CCTK-InterpLocalUniform}] Interpolate a list of processor-local arrays which define a uniformly-spaced data grid %notyet \item[\code{CCTK\_InterpLocalWarped}] %notyet [\pageref{CCTK-InterpLocalWarped}] %notyet Interpolate a list of processor-local arrays %notyet which define a curvilinearly-warped data grid (not implemented yet) \item[\code{CCTK\_InterpRegisterOperatorGV}] [\pageref{CCTK-InterpRegisterOperatorGV}] Registers a routine as a \code{CCTK\_InterpGV} interpolation operator \item[\code{CCTK\_InterpRegisterOperatorLocal}] [\pageref{CCTK-InterpRegisterOperatorLocal}] Registers a routine as a \code{CCTK\_InterpLocal} interpolation operator %notyet \item[\code{CCTK\_InterpRegisterOpLocalNonUniform}] %notyet [\pageref{CCTK-InterpRegisterOpLocalNonUniform}] %notyet Registers a routine as a \code{CCTK\_InterpLocalNonUniform} %notyet interpolation operator \item[\code{CCTK\_InterpRegisterOpLocalUniform}] [\pageref{CCTK-InterpRegisterOpLocalUniform}] Registers a routine as a \code{CCTK\_InterpLocalUniform} interpolation operator %notyet \item[\code{CCTK\_InterpRegisterOpLocalWarped}] %notyet [\pageref{CCTK-InterpRegisterOpLocalWarped}] %notyet Registers a routine as a \code{CCTK\_InterpLocalWarped} %notyet interpolation operator \item[\code{CCTK\_IsFunctionAliased}] [\pageref{CCTK-IsFunctionAliased}] Reports whether an aliased function has been provided \item[\code{CCTK\_IsImplementationActive}] [\pageref{CCTK-IsImplementationActive}] Reports whether an implementation was activated in a parameter file \item[\code{CCTK\_IsImplementationCompiled}] [\pageref{CCTK-IsImplementationCompiled}] Reports whether an implementation was compiled into a configuration \item[\code{CCTK\_IsThornActive}] [\pageref{CCTK-IsThornActive}] Reports whether a thorn was activated in a parameter file \item[\code{CCTK\_IsThornCompiled}] [\pageref{CCTK-IsThornCompiled}] Reports whether a thorn was compiled into a configuration \item[\code{CCTK\_MaxDim}] [\pageref{CCTK-MaxDim}] Get the maximum dimension of any grid variable \item[\code{CCTK\_MaxTimeLevels}] [\pageref{CCTK-MaxTimeLevels}] Gives the maximum number of timelevels for a group \item[\code{CCTK\_MaxTimeLevelsGI}] [\pageref{CCTK-MaxTimeLevelsGI}] Gives the maximum number of timelevels for a group \item[\code{CCTK\_MaxTimeLevelsGN}] [\pageref{CCTK-MaxTimeLevelsGN}] Gives the maximum number of timelevels for a group \item[\code{CCTK\_MaxTimeLevelsVI}] [\pageref{CCTK-MaxTimeLevelsVarI}] Gives the maximum number of timelevels for a variable \item[\code{CCTK\_MaxTimeLevelsVN}] [\pageref{CCTK-MaxTimeLevelsVN}] Gives the maximum number of timelevels for a variable \item[\code{CCTK\_MyProc}] [\pageref{CCTK-MyProc}] Get the local processor number \item[\code{CCTK\_nProcs}] [\pageref{CCTK-nProcs}] Get the total number of processors used \item[\code{CCTK\_NullPointer}] [\pageref{CCTK-NullPointer}] Returns a C-style NULL pointer value \item[\code{CCTK\_NumCompiledImplementations}] [\pageref{CCTK-NumCompiledImplementations}] Return the number of implementations compiled in \item[\code{CCTK\_NumCompiledThorns}] [\pageref{CCTK-NumCompiledThorns}] Return the number of thorns compiled in \item[\code{CCTK\_NumGroups}] [\pageref{CCTK-NumGroups}] Get the number of groups of variables compiled in the code \item[\code{CCTK\_NumIOMethods}] [\pageref{CCTK-NumIOMethods}] Returns the total number of I/O methods registered with the flesh \item[\code{CCTK\_NumTimeLevels}] [\pageref{CCTK-NumTimeLevels}] Returns the number of active timelevels from a group name (deprecated) \item[\code{CCTK\_NumTimeLevelsGI}] [\pageref{CCTK-NumTimeLevels}] Returns the number of active timelevels from a group index (deprecated) \item[\code{CCTK\_NumTimeLevelsGN}] [\pageref{CCTK-NumTimeLevels}] Returns the number of active timelevels from a group name (deprecated) \item[\code{CCTK\_NumTimeLevelsVI}] [\pageref{CCTK-NumTimeLevels}] Returns the number of active timelevels from a variable index (deprecated) \item[\code{CCTK\_NumTimeLevelsVN}] [\pageref{CCTK-NumTimeLevels}] Returns the number of active timelevels from a variable name (deprecated) \item[\code{CCTK\_NumVars}] [\pageref{CCTK-NumVars}] Get the number of grid variables compiled in the code \item[\code{CCTK\_NumVarsInGroup}] [\pageref{CCTK-NumVarsInGroup}] Provides the number of variables in a group from the group name \item[\code{CCTK\_NumVarsInGroupI}] [\pageref{CCTK-NumVarsInGroupI}] Provides the number of variables in a group from the group index \item[\code{CCTK\_OutputGH}] [\pageref{CCTK-OutputGH}] Conditional output of all variables on a GH by all I/O methods \item[\code{CCTK\_OutputVar}] [\pageref{CCTK-OutputVar}] Output of a single variable by all I/O methods \item[\code{CCTK\_OutputVarAs}] [\pageref{CCTK-OutputVarAs}] Output of a single variable as an alias by all I/O methods \item[\code{CCTK\_OutputVarAsByMethod}] [\pageref{CCTK-OutputVarAsByMethod}] Output of a single variable as an alias by a single I/O method \item[\code{CCTK\_OutputVarByMethod}] [\pageref{CCTK-OutputVarByMethod}] Output of a single variable by a single I/O method \item[\code{CCTK\_ParallelInit}] [\pageref{CCTK-ParallelInit}] Initializes the parallel subsystem \item[\code{CCTK\_ParameterData}] [\pageref{CCTK-ParameterData}] Get parameter properties for given parameter/thorn pair \item[\code{CCTK\_ParameterGet}] [\pageref{CCTK-ParameterGet}] Get the data pointer to and type of a parameter's value \item[\code{CCTK\_ParameterLevel}] [\pageref{CCTK-ParameterLevel}] Return the parameter checking level \item[\code{CCTK\_ParameterQueryTimesSet}] [\pageref{CCTK-ParameterQueryTimesSet}] Return number of times a parameter has been set \item[\code{CCTK\_ParameterSet}] [\pageref{CCTK-ParameterSet}] Sets the value of a parameter \item[\code{CCTK\_ParameterValString}] [\pageref{CCTK-ParameterValString}] Get the string representation of a parameter's value \item[\code{CCTK\_ParameterWalk}] [\pageref{CCTK-ParameterWalk}] Walk through the list of parameters \item[\code{CCTK\_PARAMWARN}] [\pageref{CCTK-PARAMWARN}] Prints a warning from parameter checking, and possibly stops the code \item[\code{CCTK\_PointerTo}] [\pageref{CCTK-PointerTo}] Returns the address of a variable passed in by reference from a Fortran routine \item[\code{CCTK\_PrintGroup}] [\pageref{CCTK-PrintGroup}] Prints a group name from its index \item[\code{CCTK\_PrintString}] [\pageref{CCTK-PrintString}] Prints a Cactus string to screen (from Fortran) \item[\code{CCTK\_PrintVar}] [\pageref{CCTK-PrintVar}] Prints a variable name from its index \item[\code{CCTK\_QueryGroupStorage}] [\pageref{CCTK-QueryGroupStorage}] Queries storage for a group given by its group name \item[\code{CCTK\_QueryGroupStorageB}] [\pageref{CCTK-QueryGroupStorageB}] Queries storage for a group given by its group name or index \item[\code{CCTK\_QueryGroupStorageI}] [\pageref{CCTK-QueryGroupStorageI}] Queries storage for a group given by its group index %\item[\code{CCTK\_Reduce}] % [\pageref{CCTK-Reduce}] % Perform a reduction operation using a registered operator \item[\code{CCTK\_ReductionHandle}] [\pageref{CCTK-ReductionHandle}] Get the handle for a registered reduction operator \item[\code{CCTK\_RegisterBanner}] [\pageref{CCTK-RegisterBanner}] Register a banner for a thorn \item[\code{CCTK\_RegisterGHExtension}] [\pageref{CCTK-RegisterGHExtension}] Register the name of an extension to the Cactus GH \item[\code{CCTK\_RegisterGHExtensionInitGH}] [\pageref{CCTK-RegisterGHExtensionInitGH}] Register a routine for providing initialisation for an extension to the Cactus GH \item[\code{CCTK\_RegisterGHExtensionScheduleTraverseGH}] [\pageref{CCTK-RegisterGHExtensionScheduleTraverseGH}] Register a GH extension schedule traversal routine \item[\code{CCTK\_RegisterGHExtensionSetupGH}] [\pageref{CCTK-RegisterGHExtensionSetupGH}] Register a routine for setting up an extension to the Cactus GH \item[\code{CCTK\_RegisterIOMethod}] [\pageref{CCTK-RegisterIOMethod}] Registers a new I/O method \item[\code{CCTK\_RegisterIOMethodOutputGH}] [\pageref{CCTK-RegisterIOMethodOutputGH}] Registers an I/O method's routine for conditional output \item[\code{CCTK\_RegisterIOMethodOutputVarAs}] [\pageref{CCTK-RegisterIOMethodOutputVarAs}] Registers an I/O method's routine for unconditional output \item[\code{CCTK\_RegisterIOMethodTimeToOutput}] [\pageref{CCTK-RegisterIOMethodTimeToOutput}] Register a routine for deciding if it is time to output for an IO method \item[\code{CCTK\_RegisterIOMethodTriggerOutput}] [\pageref{CCTK-RegisterIOMethodTriggerOutput}] Register a routine for dealing with trigger output for an IO method \item[\code{CCTK\_RegisterReductionOperator}] [\pageref{CCTK-RegisterReductionOperator}] Register a function as providing a reduction operation \item[\code{CCTK\_SetupGH}] [\pageref{CCTK-SetupGH}] Sets up a CCTK grid hierarchy \item[\code{CCTK\_SyncGroup}] [\pageref{CCTK-SyncGroup}] Synchronize the ghost zones for a group of variables \item[\code{CCTK\_ThornImplementation}] [\pageref{CCTK-ThornImplementation}] Returns the implementation provided by the thorn \item[\code{CCTK\_VarDataPtr}] [\pageref{CCTK-VarDataPtr}] Returns the data pointer for a grid variable \item[\code{CCTK\_VarDataPtrB}] [\pageref{CCTK-VarDataPtrB}] Returns the data pointer for a grid variable from the variable index or name \item[\code{CCTK\_VarDataPtrI}] [\pageref{CCTK-VarDataPtrI}] Returns the data pointer for a grid variable from the variable index \item[\code{CCTK\_VarIndex}] [\pageref{CCTK-VarIndex}] Get the index for a variable \item[\code{CCTK\_VarName}] [\pageref{CCTK-VarName}] Given a variable index, returns the variable name \item[\code{CCTK\_VarTypeI}] [\pageref{CCTK-VarTypeI}] Provides variable type index from the variable index \item[\code{CCTK\_VarTypeSize}] [\pageref{CCTK-VarTypeSize}] Provides variable type size in bytes from the variable type index \item[\code{CCTK\_VInfo}] [\pageref{CCTK-VInfo}] Prints a formatted string with a variable argument list as an information message to screen \item[\code{CCTK\_VWarn}] [\pageref{CCTK-VWarn}] Prints a formatted string with a variable argument list as a warning message to standard error and possibly stops the code \item[\code{CCTK\_WARN}] [\pageref{CCTK-WARN}] Macro to print a single string as a warning message to standard error and possibly stop the code \end{Lentry} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Full Description of Functions} %%%%% % AAA %%%%% % CommOverloadables.c \begin{FunctionDescription}{CCTK\_Abort} \label{CCTK-Abort} Abnormal Cactus termination. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" int dummy = CCTK_Abort(const cGH *cctkGH); \end{verbatim} \end{Synopsis} \begin{Synopsis}{Fortran} \begin{verbatim} #include "cctk.h" subroutine CCTK_Abort (dummy, cctkGH) integer dummy CCTK_POINTER cctkGH end subroutine CCTK_Abort \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{} The function never returns, and hence never produces a result. \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{GH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter} \end{ParameterSection} \begin{Discussion} This routine causes an immediate, abnormal Cactus termination. It never returns to the caller. \end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_Exit}{CCTK-Exit} Exit the code cleanly \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_WARN}{CCTK-WARN} Macro to print a single string as a warning message and possibly stop the code \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_Warn}{CCTK-Warn} Prints a single string as a warning message and possibly stops the code \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_VWarn}{CCTK-VWarn} Prints a formatted string with a variable argument list as a warning message to standard error and possibly stops the code \end{SeeAlso2} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{} The function never returns, and hence never reports an error. \end{Error} \end{ErrorSection} \begin{ExampleSection} \begin{Example}{C} \begin{verbatim} #include "cctk.h" CCTK_Abort (cctkGH); \end{verbatim} \end{Example} \begin{Example}{Fortran} \begin{verbatim} #include "cctk.h" integer dummy call CCTK_Abort (dummy, cctkGH) \end{verbatim} \end{Example} \end{ExampleSection} \end{FunctionDescription} % ActiveThorns.c \begin{FunctionDescription}{CCTK\_ActivatingThorn} \label{CCTK-ActivatingThorn} Finds the thorn which activated a particular implementation. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" const char *thorn = CCTK_ActivatingThorn(const char *name); \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{thorn} Name of activating thorn, or \code{NULL} if inactive \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{name} Implementation name \end{Parameter} \end{ParameterSection} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_CompiledImplementation}{CCTK-CompiledImplementation} Return the name of the compiled implementation with given index \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_CompiledThorn}{CCTK-CompiledThorn} Return the name of the compiled thorn with given index \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImplementationRequires}{CCTK-ImplementationRequires} Return the ancestors for an implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImplementationThorn}{CCTK-ImplementationThorn} Returns the name of one thorn providing an implementation. \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImpThornList}{CCTK-ImpThornList} Return the thorns for an implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive} Reports whether an implementation was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled} Reports whether an implementation was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive} Reports whether a thorn was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled} Reports whether a thorn was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_NumCompiledImplementations}{CCTK-NumCompiledImplementations} Return the number of implementations compiled in \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_NumCompiledThorns}{CCTK-NumCompiledThorns} Return the number of thorns compiled in \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ThornImplementation}{CCTK-ThornImplementation} Returns the implementation provided by the thorn \end{SeeAlso2} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{NULL} The implementation is inactive, or an error occurred. \end{Error} \end{ErrorSection} \end{FunctionDescription} % cctk_GroupsOnGH.h \begin{FunctionDescription}{CCTK\_ActiveTimeLevels} \label{CCTK-ActiveTimeLevels} Returns the number of active time levels for a group. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" int timelevels = CCTK_ActiveTimeLevels(const cGH *cctkGH, const char *groupname); int timelevels = CCTK_ActiveTimeLevelsGI(const cGH *cctkGH, int groupindex); int timelevels = CCTK_ActiveTimeLevelsGN(const cGH *cctkGH, const char *groupname); int timelevels = CCTK_ActiveTimeLevelsVI(const cGH *cctkGH, int varindex); int timelevels = CCTK_ActiveTimeLevelsVN(const cGH *cctkGH, const char *varname); \end{verbatim} \end{Synopsis} \begin{Synopsis}{Fortran} \begin{verbatim} #include "cctk.h" subroutine CCTK_ActiveTimeLevels(timelevels, cctkGH, groupname) integer timelevels CCTK_POINTER cctkGH character*(*) groupname end subroutine CCTK_ActiveTimeLevels subroutine CCTK_ActiveTimeLevelsGI(timelevels, cctkGH, groupindex) integer timelevels CCTK_POINTER cctkGH integer groupindex end subroutine CCTK_ActiveTimeLevelsGI subroutine CCTK_ActiveTimeLevelsGN(timelevels, cctkGH, groupname) integer timelevels CCTK_POINTER cctkGH character*(*) groupname end subroutine CCTK_ActiveTimeLevelsGN subroutine CCTK_ActiveTimeLevelsVI(timelevels, cctkGH, varindex) integer timelevels CCTK_POINTER cctkGH integer varindex end subroutine CCTK_ActiveTimeLevelsVI subroutine CCTK_ActiveTimeLevelsVN(timelevels, cctkGH, varname) integer timelevels CCTK_POINTER cctkGH character*(*) varname end subroutine CCTK_ActiveTimeLevelsVN \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{timelevels} The currently active number of timelevels for the group. \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{GH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter} \begin{Parameter}{groupname} Name of the group. \end{Parameter} \begin{Parameter}{groupindex} Index of the group. \end{Parameter} \begin{Parameter}{varname} Name of a variable in the group. \end{Parameter} \begin{Parameter}{varindex} Index of a variable in the group. \end{Parameter} \end{ParameterSection} \begin{Discussion} This function returns the number of timelevels for which storage has been activated, which is always equal to or less than the maximum number of timelevels which may have storage provided by \code{CCTK\_MaxTimeLevels}. \end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_MaxTimeLevels}{CCTK-MaxTimeLevels} Return the maximum number of active timelevels. \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_NumTimeLevels}{CCTK-NumTimeLevels} Deprecated; same as \code{CCTK\_ActiveTimeLevels}. \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_GroupStorageDecrease}{CCTK-GroupStorageDecrease} Base function, overloaded by the driver, which decreases the number of active timelevels, and also returns the number of active timelevels. \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_GroupStorageIncrease}{CCTK-GroupStorageIncrease} Base function, overloaded by the driver, which increases the number of active timelevels, and also returns the number of active timelevels. \end{SeeAlso2} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{timelevels $<$ 0} Illegal arguments given. \end{Error} \end{ErrorSection} %\begin{ExampleSection} %\end{ExampleSection} \end{FunctionDescription} % cctk_Comm.h \begin{FunctionDescription}{CCTK\_ArrayGroupSize}{} \label{CCTK-ArrayGroupSize} Returns a pointer to the processor-local size for variables in a group, specified by its name, in a given dimension. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" int *size = CCTK_ArrayGroupSize(const cGH *cctkGH, int dir, const char *groupname); \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{NULL} A \code{NULL} pointer is returned if the group index or the dimension given are invalid. \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{GH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter} \begin{Parameter}{dir ($\ge$ 0)} Which dimension of array to query. \end{Parameter} \begin{Parameter}{groupname} Name of the group. \end{Parameter} \end{ParameterSection} \begin{Discussion} For a CCTK\_ARRAY or CCTK\_GF group, this routine returns a pointer to the processor-local size for variables in that group in a given direction. The direction is counted in C order (zero being the lowest dimension). This function returns a pointer to the result for technical reasons; so that it will efficiently interface with Fortran. This may change in the future. Consider using \code{CCTK\_GroupgshGN} instead. \end{Discussion} \begin{SeeAlsoSection} \begin{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 \code{NULL} pointer is returned if the group index or the dimension given are invalid. \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{GH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter} \begin{Parameter}{dir ($\ge$ 0)} Which dimension of array to query. \end{Parameter} \begin{Parameter}{groupi} The group index. \end{Parameter} \end{ParameterSection} \begin{Discussion} For a CCTK\_ARRAY or CCTK\_GF group, this routine returns a pointer to the processor-local size for variables in that group in a given direction. The direction is counted in C order (zero being the lowest dimension). This function returns a pointer to the result for technical reasons; so that it will efficiently interface with Fortran. This may change in the future. Consider using \code{CCTK\_GroupgshGI} instead. \end{Discussion} \begin{SeeAlsoSection} \begin{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 \code{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} % cctk_ActiveThorns.c \begin{FunctionDescription}{CCTK\_CompiledImplementation} \label{CCTK-CompiledImplementation} Return the name of the compiled implementation with given index. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" const char *imp = CCTK_CompiledImplementation(int index); \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{imp} Name of the implementation \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{index} Implementation index, with $0 \le \code{index} < \code{numimpls}$, where \code{numimpls} is returned by \code{CCTK\_NumCompiledImplementations}. \end{Parameter} \end{ParameterSection} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_ActivatingThorn}{CCTK-ActivatingThorn} Finds the thorn which activated a particular implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_CompiledThorn}{CCTK-CompiledThorn} Return the name of the compiled thorn with given index \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImplementationRequires}{CCTK-ImplementationRequires} Return the ancestors for an implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImplementationThorn}{CCTK-ImplementationThorn} Returns the name of one thorn providing an implementation. \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImpThornList}{CCTK-ImpThornList} Return the thorns for an implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive} Reports whether an implementation was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled} Reports whether an implementation was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive} Reports whether a thorn was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled} Reports whether a thorn was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_NumCompiledImplementations}{CCTK-NumCompiledImplementations} Return the number of implementations compiled in \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_NumCompiledThorns}{CCTK-NumCompiledThorns} Return the number of thorns compiled in \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ThornImplementation}{CCTK-ThornImplementation} Returns the implementation provided by the thorn \end{SeeAlso2} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{NULL} Error. \end{Error} \end{ErrorSection} \end{FunctionDescription} % cctk_ActiveThorns.c \begin{FunctionDescription}{CCTK\_CompiledThorn} \label{CCTK-CompiledThorn} Return the name of the compiled thorn with given index. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" const char *thorn = CCTK_CompiledThorn(int index); \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{thorn} Name of the thorn \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{index} Thorn index, with $0 \le \code{index} < \code{numthorns}$, where \code{numthorns} is returned by \code{CCTK\_NumCompiledThorns}. \end{Parameter} \end{ParameterSection} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_ActivatingThorn}{CCTK-ActivatingThorn} Finds the thorn which activated a particular implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_CompiledImplementation}{CCTK-CompiledImplementation} Return the name of the compiled implementation with given index \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImplementationRequires}{CCTK-ImplementationRequires} Return the ancestors for an implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImplementationThorn}{CCTK-ImplementationThorn} Returns the name of one thorn providing an implementation. \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImpThornList}{CCTK-ImpThornList} Return the thorns for an implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive} Reports whether an implementation was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled} Reports whether an implementation was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive} Reports whether a thorn was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled} Reports whether a thorn was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_NumCompiledImplementations}{CCTK-NumCompiledImplementations} Return the number of implementations compiled in \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_NumCompiledThorns}{CCTK-NumCompiledThorns} Return the number of thorns compiled in \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ThornImplementation}{CCTK-ThornImplementation} Returns the implementation provided by the thorn \end{SeeAlso2} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{NULL} Error. \end{Error} \end{ErrorSection} \end{FunctionDescription} \begin{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 \code{CCTK\_CoordRegisterRange}. To find the range, the coordinate system name must be given, and either the coordinate direction or the coordinate name. The coordinate direction will be used if is given as a positive value, otherwise the coordinate name will be used. \end{discussion} \begin{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 \code{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 \code{CCTK\_CoordRegisterData}. The coordinate range can be accessed by \code{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{int}{integer}{mode} \argument{const char *}{character*(*)}{pathname} \showargs \begin{params} \parameter{ierr}{Error code} \parameter{mode}{Permission mode for new directory as an octal number} \parameter{pathname}{Directory to create} \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. Alternatively, a permission mode of 0777 gives everyone unlimited access; the user's \code{umask} setting should cut this down to whatever the user's normal default permissions are anyway. Note that (partly for historical reasons and partly for Fortran~77 compatability) the order of the arguments is the opposite of that of the usual Unix \code{mkdir(2)} system call. \end{discussion} \begin{examples} \begin{tabular}{@{}p{3cm}cp{11cm}} \hfill {\bf C} && {\t ierr = CCTK\_CreateDirectory(0755, "Results/New") }; \\ \hfill {\bf Fortran} && {\t call CCTK\_CREATEDIRECTORY(ierr,0755, "Results/New")} \\ \end{tabular} \end{examples} \begin{errorcodes} \begin{tabular}{ll} 1 & Directory already exists\\ 0 & Directory successfully created\\ -1 & Memory allocation failed\\ -2 & Failed to create directory\\ -3 & Some component of \code{pathname} already 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 \code{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 \code{CCTK\_SyncGroup}. In general, this function does not need to be used, since communication is automatically enabled for grid variables who have assigned storage via the \code{schedule.ccl} file. \end{discussion} \begin{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 \code{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 \code{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 \code{::} \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 \code{::} for a public or protected group, and \code{::} 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 \code{::} \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 \code{CCTK\_SCALAR}, \code{CCTK\_GF}, \code{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 \code{CCTK\_SCALAR}, \code{CCTK\_GF}, \code{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} % cctk_ActiveThorns.c \begin{FunctionDescription}{CCTK\_ImplementationRequires} \label{CCTK-ImplementationRequires} Return the ancestors for an implementation. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" uStringList *imps = CCTK_ImplementationRequires(const char *imp); \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{imps} (not documented) \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{imp} (not documented) \end{Parameter} \end{ParameterSection} %\begin{Discussion} %\end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_ActivatingThorn}{CCTK-ActivatingThorn} Finds the thorn which activated a particular implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_CompiledImplementation}{CCTK-CompiledImplementation} Return the name of the compiled implementation with given index \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_CompiledThorn}{CCTK-CompiledThorn} Return the name of the compiled thorn with given index \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImplementationThorn}{CCTK-ImplementationThorn} Returns the name of one thorn providing an implementation. \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImpThornList}{CCTK-ImpThornList} Return the thorns for an implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive} Reports whether an implementation was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled} Reports whether an implementation was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive} Reports whether a thorn was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled} Reports whether a thorn was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_NumCompiledImplementations}{CCTK-NumCompiledImplementations} Return the number of implementations compiled in \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_NumCompiledThorns}{CCTK-NumCompiledThorns} Return the number of thorns compiled in \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ThornImplementation}{CCTK-ThornImplementation} Returns the implementation provided by the thorn \end{SeeAlso2} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{} (not documented) \end{Error} \end{ErrorSection} %\begin{ExampleSection} %\end{ExampleSection} \end{FunctionDescription} % cctk_ActiveThorns.c \begin{FunctionDescription}{CCTK\_ImplementationThorn} \label{CCTK-ImplementationThorn} Returns the name of one thorn providing an implementation. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" const char *thorn = CCTK_ImplementationThorn(const char *name); \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{thorn} Name of the thorn or \code{NULL} \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{name} Name of the implementation \end{Parameter} \end{ParameterSection} %\begin{Discussion} %\end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_ActivatingThorn}{CCTK-ActivatingThorn} Finds the thorn which activated a particular implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_CompiledImplementation}{CCTK-CompiledImplementation} Return the name of the compiled implementation with given index \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_CompiledThorn}{CCTK-CompiledThorn} Return the name of the compiled thorn with given index \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImplementationRequires}{CCTK-ImplementationRequires} Return the ancestors for an implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImpThornList}{CCTK-ImpThornList} Return the thorns for an implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive} Reports whether an implementation was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled} Reports whether an implementation was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive} Reports whether a thorn was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled} Reports whether a thorn was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_NumCompiledImplementations}{CCTK-NumCompiledImplementations} Return the number of implementations compiled in \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_NumCompiledThorns}{CCTK-NumCompiledThorns} Return the number of thorns compiled in \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ThornImplementation}{CCTK-ThornImplementation} Returns the implementation provided by the thorn \end{SeeAlso2} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{NULL} Error. \end{Error} \end{ErrorSection} %\begin{ExampleSection} %\end{ExampleSection} \end{FunctionDescription} % cctk_ActiveThorns.c \begin{FunctionDescription}{CCTK\_ImpThornList} \label{CCTK-ImpThornList} Return the thorns for an implementation. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" t_sktree *thorns = CCTK_ImpThornList(const char *name); \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{thorns} (not documented) \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{name} Name of implementation \end{Parameter} \end{ParameterSection} \begin{Discussion} (not documented) \end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_ActivatingThorn}{CCTK-ActivatingThorn} Finds the thorn which activated a particular implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_CompiledImplementation}{CCTK-CompiledImplementation} Return the name of the compiled implementation with given index \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_CompiledThorn}{CCTK-CompiledThorn} Return the name of the compiled thorn with given index \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImplementationRequires}{CCTK-ImplementationRequires} Return the ancestors for an implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImplementationThorn}{CCTK-ImplementationThorn} Returns the name of one thorn providing an implementation. \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive} Reports whether an implementation was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled} Reports whether an implementation was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive} Reports whether a thorn was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled} Reports whether a thorn was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_NumCompiledImplementations}{CCTK-NumCompiledImplementations} Return the number of implementations compiled in \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_NumCompiledThorns}{CCTK-NumCompiledThorns} Return the number of thorns compiled in \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ThornImplementation}{CCTK-ThornImplementation} Returns the implementation provided by the thorn \end{SeeAlso2} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{} (not documented) \end{Error} \end{ErrorSection} %\begin{ExampleSection} %\end{ExampleSection} \end{FunctionDescription} % WarnLevel.c \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. The macro \code{CCTK\_INFO(message)} expands to a call to the underlying function \code{CCTK\_Info}: \begin{verbatim} CCTK_Info(CCTK_THORNSTRING, message) \end{verbatim} So the macro automatically includes the name of the originating thorn in the info message. It is recommended that the macro \code{CCTK\_INFO} is used to print a message rather than calling \code{CCTK\_Info} directly. To include variables in an info message from C, you can use the routine \code{CCTK\_VInfo} which accepts a variable argument list. To include variables from Fortran, a string must be constructed and passed in a \code{CCTK\_INFO} macro. \end{Discussion} \begin{SeeAlsoSection} \begin{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 \code{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 \code{coord\_system\_handle}. The default case is that it's $=$; see the discussion of the \code{interpolation\_hyperslab\_handle} parameter-table entry for the $<$ case. \end{Parameter} \begin{Parameter}{local\_interp\_handle ($\ge 0$)} Handle to the local interpolation operator as returned by \code{CCTK\_InterpHandle}. \end{Parameter} \begin{Parameter}{param\_table\_handle ($\ge 0$)} Handle to a key-value table containing zero or more additional parameters for the interpolation operation. The table is allowed to be modified by the local and/or global interpolation routine(s). \end{Parameter} \begin{Parameter}{coord\_system\_handle ($\ge 0$)} Cactus coordinate system handle defining the mapping between (usually floating-point) coordinates and integer grid subscripts, as returned by \code{CCTK\_CoordSystemHandle}. \end{Parameter} \begin{Parameter}{N\_interp\_points ($\ge 0$)} The number of interpolation points requested by this processor. \end{Parameter} \begin{Parameter}{interp\_coords\_type\_code} One of the \code{CCTK\_VARIABLE\_*} type codes, giving the data type of the interpolation-point coordinate arrays pointed to by \code{interp\_coords[]}. All interpolation-point coordinate arrays must be of the same data type. \end{Parameter} \begin{Parameter}{interp\_coords ($\ne$ NULL)} (Pointer to) an array of \code{N\_dims} pointers to 1-D arrays giving the coordinates of the interpolation points requested by this processor. These coordinates are with respect to the coordinate system defined by \code{coord\_system\_handle}. \end{Parameter} \begin{Parameter}{N\_input\_arrays ($\ge 0$)} The number of input arrays to be interpolated. If \code{N\_input\_arrays} is zero then no interpolation is done; such a call may be useful for setup, interpolator querying, etc. Note that if the parameter table entry \code{operand\_indices} is used to specify a nontrivial (e.g.\ one-to-many) mapping of input 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 \code{N\_input\_arrays} CCTK grid array indices (as returned by \code{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 e.g.\ to do some query or setup computation. \end{Parameter} \begin{Parameter}{N\_output\_arrays ($\ge 0$)} The number of output arrays to be returned from the interpolation. If \code{N\_output\_arrays} is zero then no interpolation is done; such a call may be useful for setup, interpolator querying, etc. Note that \code{N\_output\_arrays} may differ from \code{N\_input\_arrays}, e.g.\ if the \code{operand\_indices} parameter-table entry is used to specify a nontrivial (e.g.\ many-to-one) mapping of input arrays to output arrays. If such a mapping is specified, only the unique set of output arrays should be given in the \code{output\_arrays} argument. \end{Parameter} \begin{Parameter}{output\_array\_type\_codes ($\ne$ NULL)} (Pointer to) an array of \code{N\_output\_arrays} \code{CCTK\_VARIABLE\_*} type codes giving the data types of the 1-D output arrays pointed to by \code{output\_arrays[]}. \end{Parameter} \begin{Parameter}{output\_arrays ($\ne$ NULL)} (Pointer to) an array of \code{N\_output\_arrays} pointers to the (user-supplied) 1-D output arrays for the interpolation. If any of the pointers in the \code{output\_arrays} array is NULL, then that interpolation is skipped. This may be useful if the main purpose of the call is e.g.\ to do some query or setup computation. \end{Parameter} \end{ParameterSection} \begin{Discussion} This function interpolates a list of CCTK grid 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 \code{CCTK\_InterpGridArrays} does not do the actual interpolation itself but rather takes care of whatever interprocessor communication may be necessary, and -- for each processor's local patch of the domain-decomposed grid arrays -- calls \code{CCTK\_InterpLocalUniform} to invoke an external local interpolation operator (as identified by an interpolation handle). Additional parameters for the interpolation operation of both \code{CCTK\_InterpGridArrays} and \code{CCTK\_InterpLocalUniform} can be passed in via a handle to a key/value options table. All interpolation operators should check for a parameter table entry with the key \code{suppress\_warnings} which -- if present -- indicates that the caller wants the interpolator to be silent in case of an error condition and only return an appropriate error code. One common parameter-table option, which a number of interpolation operators are likely to support, is \code{order}, a \code{CCTK\_INT} specifying the order of the (presumably polynomial) interpolation (1=linear, 2=quadratic, 3=cubic, etc). As another example, a table might be used to specify that the local interpolator should take derivatives, by specifying \begin{verbatim} const CCTK_INT operand_indices[N_output_arrays]; const CCTK_INT operation_codes[N_output_arrays]; \end{verbatim} Also, the global interpolator will typically need to specify some options of its own for the local interpolator.\footnote{ It is the caller's responsibility to ensure that the specified local interpolator supports any optional parameter-table entries that \code{CCTK\_InterpGridArrays} passes to it. Each thorn providing a \code{CCTK\_InterpLocalUniform} interpolator should document what options it requires from the global interpolator. } These will overwrite any entries with the same keys in the \code{param\_table\_handle} table. Finally, the parameter table can be used to pass back arbitrary information by the local and/or global interpolation routine(s) by adding/modifying appropriate key/value pairs. Note that \code{CCTK\_InterpGridArrays} is a collective operation, so in the multiprocessor case you {\em must\/} call this function in parallel on {\em each\/} processor, passing identical arguments except for the number of interpolation points, the interpolation coordinates, and the output array pointers. You may (and typically will) specify a different set of interpolation points on each processor's call -- you may even specify an empty set on some processors. The interpolation points may be ``owned'' by any processors (this function takes care of all interprocessor-communication issues), though it may be more efficient to have most or all of the interpolation points ``owned'' by the current processor. The semantics of \code{CCTK\_InterpGridArrays} are mostly independent of which Cactus driver is being used, but an implementation will most likely depend on, and make use of, driver-specific internals. For that reason, \code{CCTK\_InterpGridArrays} is made an overloadable function. The Cactus flesh will supply only a dummy routine for it which -- if called -- does nothing but print a warning message saying that it wasn't overloaded by another thorn, and stop the code. So one will always need to compile in and activate a driver-specific thorn which provides an interpolation routine for CCTK grid arrays and properly overloads \code{CCTK\_InterpGridArrays} with it at startup. Details of the operation performed, and what (if any) inputs and/or outputs are specified in the parameter table, depend on which driver-specific interpolation thorn and interpolation operator (provided by a local interpolation thorn) you use. See the documentation on individual interpolator thorns (e.g.\ \code{PUGHInterp} in the \code{CactusPUGH} arrangement, \code{LocalInterp} in the \code{CactusBase} arrangement, and/or \code{AEILocalInterp} in the \code{AEIThorns} arrangement) for details. Note that in a multiprocessor Cactus run, it's the user's responsibility to choose the interprocessor ghost-zone size (\code{driver::ghost\_size}) large enough so that the local interpolator never has to off-center its molecules near interprocessor boundaries. (This ensures that the interpolation results are independent of the interprocessor decomposition, at least up to floating-point roundoff errors.) If the ghost-zone size is too small, the interpolator should return the \code{CCTK\_ERROR\_INTERP\_GHOST\_SIZE\_TOO\_SMALL} error code. \end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso}{CCTK\_InterpHandle()} Get the interpolator handle for a given character-string name. \end{SeeAlso} %notyet \begin{SeeAlso}{CCTK\_InterpLocalNonUniform()} %notyet Interpolate a list of processor-local arrays %notyet which define a nonuniformly spaced data grid (not implemented yet) %notyet \end{SeeAlso} \begin{SeeAlso}{CCTK\_InterpLocalUniform()} Interpolate a list of processor-local arrays which define a uniformly-spaced data grid \end{SeeAlso} %notyet \begin{SeeAlso}{CCTK\_InterpLocalWarped()} %notyet Interpolate a list of processor-local arrays %notyet which define a curvilinearly-warped data grid (not implemented yet) %notyet \end{SeeAlso} \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 \code{cctk\_Interp.h}, \code{util\_ErrorCodes.h}, and/or \code{util\_Table.h} in the \code{src/include/} directory in the Cactus flesh. \end{Error} \begin{Error}{CCTK\_ERROR\_INTERP\_POINT\_OUTSIDE} one or more of the interpolation points is out of range (in this case additional information about the out-of-range point may be reported through the parameter table; see the Thorn Guide for whatever thorn provides the local interpolation operator for further details) \end{Error} \begin{Error}{CCTK\_ERROR\_INTERP\_GRID\_TOO\_SMALL} one or more of the dimensions of the input arrays is/are smaller than the molecule size chosen by the interpolator (based on the parameter-table options, e.g.\ the interpolation order) \end{Error} \begin{Error}{CCTK\_ERROR\_INTERP\_GHOST\_SIZE\_TOO\_SMALL} for a multi-processor run, the size of the interprocessor boundaries (the {\em ghostzone} size) is smaller than the molecule size chosen by the interpolator (based on the parameter-table options, e.g.\ the interpolation order).\\ This error code is also returned if a processor's chunk of the global grid is smaller than the actual molecule size. \end{Error} \begin{Error}{UTIL\_ERROR\_BAD\_INPUT} one or more of the input arguments is invalid (e.g.~\code{NULL} pointer) \end{Error} \begin{Error}{UTIL\_ERROR\_NO\_MEMORY} unable to allocate memory \end{Error} \begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} parameter table handle is invalid \end{Error} \begin{Error}{other error codes} this function may also return any error codes returned by the \code{Util\_Table*} routines used to get parameters from (and/or set results in) the parameter table \end{Error} \end{ErrorSection} \begin{ExampleSection} \begin{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 \code{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 \code{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} any negative number & the total number of out-of-bounds interpolation points\\ -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 (\code{CCTK\_InterpLocalNonUniform}, \code{CCTK\_InterpLocalUniform}, %notyet and \code{CCTK\_InterpLocalWarped} will eventually replace %notyet \code{CCTK\_InterpLocal}.) %notyet %notyet The computation is optimized for the case of interpolating a %notyet number of arrays at a time; in this case the same interpolation %notyet coefficients can be used for all the arrays. %notyet %notyet \begin{SynopsisSection} %notyet \begin{Synopsis}{C} %notyet \begin{verbatim} %notyet #include "util_ErrorCodes.h" %notyet #include "cctk.h" %notyet int status %notyet = CCTK_InterpLocalNonUniform(int N_dims, %notyet int operator_handle, %notyet int param_table_handle, %notyet int coord_arrays_type_code, %notyet const CCTK_INT coord_array_dims[], %notyet const void *const coord_arrays[], %notyet int N_interp_points, %notyet int interp_coords_type_code, %notyet const void *const interp_coords[], %notyet int N_input_arrays, %notyet const CCTK_INT input_array_dims[], %notyet const CCTK_INT input_array_type_codes[], %notyet const void *const input_arrays[], %notyet int N_output_arrays, %notyet const CCTK_INT output_array_type_codes[], %notyet void *const output_arrays[]); %notyet \end{verbatim} %notyet \end{Synopsis} %notyet \end{SynopsisSection} %notyet %notyet \begin{ResultSection} %notyet \begin{Result}{\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 \code{N\_dims} would be 1 or 2 respectively. %notyet For details, see the section on ``Non-Contiguous Input Arrays'' %notyet in the Thorn Guide for thorn AEILocalInterp. %notyet \end{Parameter} %notyet \begin{Parameter}{operator\_handle ($\ge 0$)} %notyet \hbox{} %notyet Handle to the interpolation operator as returned by %notyet \code{CCTK\_InterpHandle}. %notyet \end{Parameter} %notyet \begin{Parameter}{param\_table\_handle ($\ge 0$)} %notyet %notyet Handle to a key-value table containing additional parameters for %notyet the interpolator. %notyet %notyet One common parameter-table option, which a number of interpolation %notyet operators are likely to support, is \code{order}, a \code{CCTK\_INT} %notyet specifying the order of the (presumably polynomial) interpolation %notyet (1=linear, 2=quadratic, 3=cubic, etc). %notyet %notyet See the Thorn Guide for the AEILocalInterp thorn for other parameters. %notyet \end{Parameter} %notyet \begin{Parameter}{coord\_arrays\_type\_code} %notyet \hbox{} %notyet One of the \code{CCTK\_VARIABLE\_*} type codes, giving the data type of the %notyet 1-D coordinate arrays pointed to by \code{coord\_arrays[]}. %notyet \end{Parameter} %notyet \begin{Parameter}{coord\_array\_dims ($\ne$ NULL)} %notyet \hbox{} %notyet (Pointer to) an array of \code{N\_dims} integers giving the dimensions %notyet of the corresponding 1-D coordinate arrays. %notyet \end{Parameter} %notyet \begin{Parameter}{coord\_arrays ($\ne$ NULL)} %notyet \hbox{} %notyet (Pointer to) an array of \code{N\_dims} pointers to 1-D arrays giving the %notyet coordinates of the interpolation points. See the ``Discussion'' section %notyet below for more on the semantics of this. %notyet \end{Parameter} %notyet \begin{Parameter}{N\_interp\_points ($\ge 0$)} %notyet \hbox{} %notyet The number of points at which interpolation is to be done. %notyet \end{Parameter} %notyet \begin{Parameter}{interp\_coords\_type\_code} %notyet \hbox{} %notyet One of the \code{CCTK\_VARIABLE\_*} type codes, giving the data type %notyet of the 1-D interpolation-point-coordinate arrays pointed to by %notyet \code{interp\_coords[]}. %notyet \end{Parameter} %notyet \begin{Parameter}{interp\_coords ($\ne$ NULL)} %notyet \hbox{} %notyet (Pointer to) an array of \code{N\_dims} pointers to 1-D arrays giving the %notyet coordinates of the interpolation points. These coordinates are with %notyet respect to the coordinate system defined by \code{coord\_arrays[]}. %notyet \end{Parameter} %notyet \begin{Parameter}{N\_input\_arrays ($\ge 0$)} %notyet \hbox{} %notyet The number of input arrays to be interpolated. %notyet Note that if the parameter table entry \code{operand\_indices} %notyet is used to specify a 1-to-many mapping of input arrays to output arrays, %notyet only the unique set of input arrays should be given here. %notyet \end{Parameter} %notyet \begin{Parameter}{input\_array\_dims ($\ne$ NULL)} %notyet \hbox{} %notyet (Pointer to) an array of \code{N\_dims} integers giving the dimensions %notyet of the \code{N\_dims}-D input arrays. By default all the input arrays %notyet are taken to have these dimensions, with \code{[0]} the most contiguous %notyet axis and \code{[N\_dims-1]} the least contiguous axis, and array subscripts %notyet in the range \code{0 <= subscript < input\_array\_dims[axis]}. See the %notyet discussion of the \code{input\_array\_strides} optional parameter (passed %notyet in the parameter table) for details of how this can be overridden. %notyet \end{Parameter} %notyet \begin{Parameter}{input\_array\_type\_codes ($\ne$ NULL)} %notyet \hbox{} %notyet (Pointer to) an array of \code{N\_input\_arrays} \code{CCTK\_VARIABLE\_*} %notyet type codes giving the data types of the \code{N\_dims}-D input arrays %notyet pointed to by \code{input\_arrays[]}. %notyet \end{Parameter} %notyet \begin{Parameter}{input\_arrays ($\ne$ NULL)} %notyet \hbox{} %notyet (Pointer to) an array of \code{N\_input\_arrays} pointers to the %notyet \code{N\_dims}-D input arrays for the interpolation. %notyet \end{Parameter} %notyet \begin{Parameter}{N\_output\_arrays ($\ge 0$)} %notyet \hbox{} %notyet The number of output arrays to be returned from the interpolation. %notyet \end{Parameter} %notyet \begin{Parameter}{output\_array\_type\_codes ($\ne$ NULL)} %notyet \hbox{} %notyet (Pointer to) an array of \code{N\_output\_arrays} \code{CCTK\_VARIABLE\_*} %notyet type codes giving the data types of the 1-D output arrays pointed to by %notyet \code{output\_arrays[]}. %notyet \end{Parameter} %notyet \begin{Parameter}{output\_arrays ($\ne$ NULL)} %notyet \hbox{} %notyet (Pointer to) an array of \code{N\_output\_arrays} pointers to the %notyet (user-supplied) 1-D output arrays for the interpolation. %notyet \end{Parameter} %notyet \end{ParameterSection} %notyet %notyet \begin{Discussion} %notyet \code{CCTK\_InterpLocalNonUniform} is a generic API for interpolating %notyet processor-local arrays when the data points' coordinates~$xyz$ are %notyet {\em nonlinear\/} (but still single-variable) functions of the integer %notyet array subscripts~\code{ijk} (we're describing this for 3-D, but the %notyet generalization to other numbers of dimensions should be obvious), %notyet \begin{flushleft} %notyet $x = x(\code{i})$ \\ %notyet $y = y(\code{j})$ \\ %notyet $z = z(\code{k})$ %%%\\ %notyet \end{flushleft} %notyet These nonlinear functions are specified by setting up 1-D arrays %notyet giving their (the coordinates) values at the grid points, then passing %notyet pointers to these 1-D arrays in the \code{coord\_arrays[]} argument: %notyet \begin{flushleft} %notyet $x = \code{coord\_arrays[0][i]}$ \\ %notyet $y = \code{coord\_arrays[1][j]}$ \\ %notyet $z = \code{coord\_arrays[2][k]}$ \\ %notyet \end{flushleft} %notyet %notyet [If these nonlinear functions are known analytically, then it's %notyet probably more efficient to analytically transform to coordinates %notyet which are linear functions of the subscripts, then use %notyet \code{CCTK\_InterpLocalUniform}.] %notyet %notyet The $(x,y,z)$ coordinates are used for the interpolation %notyet (\ie{}~the interpolator may internally use polynomials in these %notyet coordinates); \code{interp\_coords[]} specifies coordinates in this %notyet same coordinate system. %notyet %notyet Details of the operation performed, and what (if any) inputs and/or %notyet outputs are specified in the parameter table, depend on which interpolation %notyet operator you use. See the Thorn Guide for the AEILocalInterp thorn for %notyet further discussion. %notyet \end{Discussion} %notyet %notyet \begin{SeeAlsoSection} %notyet \begin{SeeAlso}{CCTK\_InterpHandle()} %notyet Get the interpolator handle for a given character-string name. %notyet \end{SeeAlso} %notyet \begin{SeeAlso}{CCTK\_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 \code{CCTK\_InterpLocalNonUniform} interpolation operator. %notyet \end{SeeAlso} %notyet \end{SeeAlsoSection} %notyet %notyet \begin{ErrorSection} %notyet \begin{Error}{} %notyet To find the numerical %notyet values of the error codes (or more commonly, to find which error code %notyet corresponds to a given numerical value), look in the files %notyet \code{cctk\_Interp.h}, \code{util\_ErrorCodes.h}, and/or \code{util\_Table.h} in the \code{src/include/} directory in the Cactus flesh. %notyet \end{Error} %notyet \begin{Error}{CCTK\_ERROR\_INTERP\_POINT\_OUTSIDE} %notyet one or more of the interpolation points is out of range %notyet (in this case additional information about the out-of-range point %notyet may be reported through the parameter table; see the Thorn Guide for %notyet the AEILocalInterp thorn for further details) %notyet \end{Error} %notyet \begin{Error}{UTIL\_ERROR\_BAD\_INPUT} %notyet one or more of the inputs is invalid (e.g.~\code{NULL} pointer) %notyet \end{Error} %notyet \begin{Error}{UTIL\_ERROR\_NO\_MEMORY} %notyet unable to allocate memory %notyet \end{Error} %notyet \begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} %notyet parameter table handle is invalid %notyet \end{Error} %notyet \begin{Error}{other error codes} %notyet this function may also return any error codes returned by the %notyet \code{Util\_Table*} routines used to get parameters from %notyet (and/or set results in) the parameter table %notyet \end{Error} %notyet \end{ErrorSection} %notyet %notyet \begin{ExampleSection} %notyet \begin{Example}{C} %notyet Here's a simple example of interpolating a \code{CCTK\_REAL} and a %notyet \code{CCTK\_COMPLEX} $10 \times 20$ 2-D array, at 5 interpolation points, %notyet using cubic interpolation. %notyet %notyet \begin{verbatim} %notyet #define N_DIMS 2 %notyet #define N_INTERP_POINTS 5 %notyet #define N_INPUT_ARRAYS 2 %notyet #define N_OUTPUT_ARRAYS 2 %notyet %notyet /* (x,y) coordinates of data grid points */ %notyet #define NX 10 %notyet #define NY 20 %notyet const CCTK_REAL x_coords[NX]; %notyet const CCTK_REAL y_coords[NY]; %notyet const void *const coord_arrays[N_DIMS] %notyet = { (const void *) x_coords, (const void *) y_coords }; %notyet %notyet /* (x,y) coordinates of interpolation points */ %notyet const CCTK_REAL interp_x[N_INTERP_POINTS]; %notyet const CCTK_REAL interp_y[N_INTERP_POINTS]; %notyet const void *const interp_coords[N_DIMS] %notyet = { (const void *) interp_x, (const void *) interp_y }; %notyet %notyet /* input arrays */ %notyet /* ... note Cactus uses Fortran storage ordering, i.e.\ X is contiguous */ %notyet const CCTK_REAL input_real [NY][NX]; %notyet const CCTK_COMPLEX input_complex[NY][NX]; %notyet const CCTK_INT input_array_dims[N_DIMS] = { NX, NY }; %notyet const CCTK_INT input_array_type_codes[N_INPUT_ARRAYS] %notyet = { CCTK_VARIABLE_REAL, CCTK_VARIABLE_COMPLEX }; %notyet const void *const input_arrays[N_INPUT_ARRAYS] %notyet = { (const void *) input_real, (const void *) input_complex }; %notyet %notyet /* output arrays */ %notyet CCTK_REAL output_real [N_INTERP_POINTS]; %notyet CCTK_COMPLEX output_complex[N_INTERP_POINTS]; %notyet const CCTK_INT output_array_type_codes[N_OUTPUT_ARRAYS] %notyet = { CCTK_VARIABLE_REAL, CCTK_VARIABLE_COMPLEX }; %notyet void *const output_arrays[N_OUTPUT_ARRAYS] %notyet = { (void *) output_real, (void *) output_complex }; %notyet %notyet int operator_handle, param_table_handle; %notyet operator_handle = CCTK_InterpHandle("my interpolation operator"); %notyet if (operator_handle < 0) %notyet CCTK_WARN(-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 (\code{CCTK\_InterpLocalNonUniform}, \code{CCTK\_InterpLocalUniform}, and \code{CCTK\_InterpLocalWarped} will eventually replace \code{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 \code{N\_dims} would be 1 or 2 respectively. For details, see the section on ``Non-Contiguous Input Arrays'' in the Thorn Guide for thorn AEILocalInterp. \end{Parameter} \begin{Parameter}{operator\_handle ($\ge 0$)} \hbox{} Handle to the interpolation operator as returned by \code{CCTK\_InterpHandle}. \end{Parameter} \begin{Parameter}{param\_table\_handle ($\ge 0$)} Handle to a key-value table containing additional parameters for the interpolator. One common parameter-table option, which a number of interpolation operators are likely to support, is \code{order}, a \code{CCTK\_INT} specifying the order of the (presumably polynomial) interpolation (1=linear, 2=quadratic, 3=cubic, etc). See the Thorn Guide for the AEILocalInterp thorn for other parameters. \end{Parameter} \begin{Parameter}{coord\_origin ($\ne$ NULL)} \hbox{} (Pointer to) an array giving the coordinates of the data point with integer array subscripts 0, 0, \dots, 0, or more generally (if the actual array bounds don't include the all-zeros-subscript point) the coordinates which this data point would have if it existed. See the ``Discussion'' section below for more on how \code{coord\_origin[]} is actually used. \end{Parameter} \begin{Parameter}{coord\_delta ($\ne$ NULL)} \hbox{} (Pointer to) an array giving the coordinate spacing of the data arrays. See the ``Discussion'' section below for more on how \code{coord\_delta[]} is actually used. \end{Parameter} \begin{Parameter}{N\_interp\_points ($\ge 0$)} \hbox{} The number of points at which interpolation is to be done. \end{Parameter} \begin{Parameter}{interp\_coords\_type\_code} \hbox{} One of the \code{CCTK\_VARIABLE\_*} type codes, giving the data type of the 1-D interpolation-point-coordinate arrays pointed to by \code{interp\_coords[]}. \end{Parameter} \begin{Parameter}{interp\_coords ($\ne$ NULL)} \hbox{} (Pointer to) an array of \code{N\_dims} pointers to 1-D arrays giving the coordinates of the interpolation points. These coordinates are with respect to the coordinate system defined by \code{coord\_origin[]} and \code{coord\_delta[]}. \end{Parameter} \begin{Parameter}{N\_input\_arrays ($\ge 0$)} \hbox{} The number of input arrays to be interpolated. Note that if the parameter table entry \code{operand\_indices} is used to specify a 1-to-many mapping of input arrays to output arrays, only the unique set of input arrays should be given here. \end{Parameter} \begin{Parameter}{input\_array\_dims ($\ne$ NULL)} \hbox{} (Pointer to) an array of \code{N\_dims} integers giving the dimensions of the \code{N\_dims}-D input arrays. By default all the input arrays are taken to have these dimensions, with \code{[0]} the most contiguous axis and \code{[N\_dims-1]} the least contiguous axis, and array subscripts in the range \code{0 <= subscript < input\_array\_dims[axis]}. See the discussion of the \code{input\_array\_strides} optional parameter (passed in the parameter table) for details of how this can be overridden. \end{Parameter} \begin{Parameter}{input\_array\_type\_codes ($\ne$ NULL)} \hbox{} (Pointer to) an array of \code{N\_input\_arrays} \code{CCTK\_VARIABLE\_*} type codes giving the data types of the \code{N\_dims}-D input arrays pointed to by \code{input\_arrays[]}. \end{Parameter} \begin{Parameter}{input\_arrays ($\ne$ NULL)} \hbox{} (Pointer to) an array of \code{N\_input\_arrays} pointers to the \code{N\_dims}-D input arrays for the interpolation. If any \code{input\_arrays[in]} pointer is NULL, that interpolation is skipped. \end{Parameter} \begin{Parameter}{N\_output\_arrays ($\ge 0$)} \hbox{} The number of output arrays to be returned from the interpolation. \end{Parameter} \begin{Parameter}{output\_array\_type\_codes ($\ne$ NULL)} \hbox{} (Pointer to) an array of \code{N\_output\_arrays} \code{CCTK\_VARIABLE\_*} type codes giving the data types of the 1-D output arrays pointed to by \code{output\_arrays[]}. \end{Parameter} \begin{Parameter}{output\_arrays ($\ne$ NULL)} \hbox{} (Pointer to) an array of \code{N\_output\_arrays} pointers to the (user-supplied) 1-D output arrays for the interpolation. If any \code{output\_arrays[out]} pointer is NULL, that interpolation is skipped. \end{Parameter} \end{ParameterSection} \begin{Discussion} \code{CCTK\_InterpLocalUniform} is a generic API for interpolating processor-local arrays when the data points'~$xyz$ coordinates are {\em linear\/} functions of the integer array subscripts~\code{ijk} (we're describing this for 3-D, but the generalization to other numbers of dimensions should be obvious). The \code{coord\_origin[]} and \code{coord\_delta[]} arguments specify these linear functions: \begin{flushleft} $x = \code{coord\_origin[0] + i*coord\_delta[0]}$ \\ $y = \code{coord\_origin[1] + j*coord\_delta[1]}$ \\ $z = \code{coord\_origin[2] + k*coord\_delta[2]}$ %%%\\ \end{flushleft} The $(x,y,z)$ coordinates are used for the interpolation (\ie{}~the interpolator may internally use polynomials in these coordinates); \code{interp\_coords[]} specifies coordinates in this same coordinate system. Details of the operation performed, and what (if any) inputs and/or outputs are specified in the parameter table, depend on which interpolation operator you use. See the Thorn Guide for the AEILocalInterp thorn for further discussion. \end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso}{CCTK\_InterpHandle()} Get the interpolator handle for a given character-string name. \end{SeeAlso} \begin{SeeAlso}{CCTK\_InterpGridArrays()} Interpolate a list of Cactus grid arrays \end{SeeAlso} \begin{SeeAlso}{CCTK\_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 \code{CCTK\_InterpLocalUniform} interpolation operator \end{SeeAlso} \begin{SeeAlso}{CCTK\_InterpLocalNonUniform()} Interpolate a list of processor-local arrays, with non-uniformly spaced data points. \end{SeeAlso} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{} To find the numerical values of the error codes (or more commonly, to find which error code corresponds to a given numerical value), look in the files \code{cctk\_Interp.h}, \code{util\_ErrorCodes.h}, and/or \code{util\_Table.h} in the \code{src/include/} directory in the Cactus flesh. \end{Error} \begin{Error}{CCTK\_ERROR\_INTERP\_POINT\_OUTSIDE} one or more of the interpolation points is out of range (in this case additional information about the out-of-range point may be reported through the parameter table; see the Thorn Guide for the AEILocalInterp thorn for further details) \end{Error} \begin{Error}{CCTK\_ERROR\_INTERP\_GRID\_TOO\_SMALL} one or more of the dimensions of the input arrays is/are smaller than the molecule size chosen by the interpolator (based on the parameter-table options, e.g.\ the interpolation order) \end{Error} \begin{Error}{UTIL\_ERROR\_BAD\_INPUT} one or more of the inputs is invalid (e.g.~\code{NULL} pointer) \end{Error} \begin{Error}{UTIL\_ERROR\_NO\_MEMORY} unable to allocate memory \end{Error} \begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} parameter table handle is invalid \end{Error} \begin{Error}{other error codes} this function may also return any error codes returned by the \code{Util\_Table*} routines used to get parameters from (and/or set results in) the parameter table \end{Error} \end{ErrorSection} \begin{ExampleSection} \begin{Example}{C} Here's a simple example of interpolating a \code{CCTK\_REAL} and a \code{CCTK\_COMPLEX} $10 \times 20$ 2-D array, at 5 interpolation points, using cubic interpolation. Note that since C allows arrays to be initialized only if the initializer values are compile-time constants, we have to declare the \code{interp\_coords[]}, \code{input\_arrays[]}, and \code{output\_arrays[]} arrays as non-\code{const}, and set their values with ordinary (run-time) assignment statements. In \Cplusplus, there's no restriction on initializer values, so we could declare the arrays \code{const} and initialize them as part of their declarations. \begin{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 (\code{CCTK\_InterpLocalWarped}, \code{CCTK\_InterpLocalUniform}, %notyet and \code{CCTK\_InterpLocalWarped} will eventually replace %notyet \code{CCTK\_InterpLocal}.) %notyet %notyet The computation is optimized for the case of interpolating a %notyet number of arrays at a time; in this case the same interpolation %notyet coefficients can be used for all the arrays. %notyet %notyet \begin{SynopsisSection} %notyet \begin{Synopsis}{C} %notyet \begin{verbatim} %notyet #include "util_ErrorCodes.h" %notyet #include "cctk.h" %notyet int status = 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 \code{N\_dims} would be 1 or 2 respectively. %notyet For details, see the section on ``Non-Contiguous Input Arrays'' %notyet in the Thorn Guide for thorn AEILocalInterp. %notyet \end{Parameter} %notyet \begin{Parameter}{operator\_handle ($\ge 0$)} %notyet \hbox{} %notyet Handle to the interpolation operator as returned by %notyet \code{CCTK\_InterpHandle}. %notyet \end{Parameter} %notyet \begin{Parameter}{param\_table\_handle ($\ge 0$)} %notyet %notyet Handle to a key-value table containing additional parameters for %notyet the interpolator. %notyet %notyet One common parameter-table option, which a number of interpolation %notyet operators are likely to support, is \code{order}, a \code{CCTK\_INT} %notyet specifying the order of the (presumably polynomial) interpolation %notyet (1=linear, 2=quadratic, 3=cubic, etc). %notyet %notyet See the Thorn Guide for the AEILocalInterp thorn for other parameters. %notyet \end{Parameter} %notyet \begin{Parameter}{coord\_arrays\_type\_code} %notyet \hbox{} %notyet One of the \code{CCTK\_VARIABLE\_*} type codes, giving the data type of the %notyet \code{N\_dims}-D coordinate arrays pointed to by \code{coord\_arrays[]}. %notyet \end{Parameter} %notyet \begin{Parameter}{coord\_array\_dims ($\ne$ NULL)} %notyet \hbox{} %notyet (Pointer to) an array of \code{N\_dims} integers giving the dimensions %notyet of the coordinate arrays. All the coordinate arrays are taken to have %notyet these dimensions, with (by default) \code{[0]} the most contiguous axis %notyet and \code{[N\_dims-1]} the least contiguous axis, and array subscripts %notyet in the range \code{0 <= subscript < coord\_array\_dims[axis]}. See the %notyet discussion of the \code{coord\_array\_strides} optional parameter (passed %notyet in the parameter table) for details of how this can be overridden. %notyet \end{Parameter} %notyet \begin{Parameter}{coord\_arrays ($\ne$ NULL)} %notyet \hbox{} %notyet (Pointer to) an array of \code{N\_dims} pointers to \code{N\_dims}-D arrays %notyet giving the coordinates of the interpolation points. See the ``Discussion'' %notyet section below for more on the semantics of this. %notyet \end{Parameter} %notyet \begin{Parameter}{N\_interp\_points ($\ge 0$)} %notyet \hbox{} %notyet The number of points at which interpolation is to be done. %notyet \end{Parameter} %notyet \begin{Parameter}{interp\_coords\_type\_code} %notyet \hbox{} %notyet One of the \code{CCTK\_VARIABLE\_*} type codes, giving the data type %notyet of the 1-D interpolation-point-coordinate arrays pointed to by %notyet \code{interp\_coords[]}. %notyet \end{Parameter} %notyet \begin{Parameter}{interp\_coords ($\ne$ NULL)} %notyet \hbox{} %notyet (Pointer to) an array of \code{N\_dims} pointers to \code{N\_dims}-D arrays %notyet giving the coordinates of the interpolation points. These coordinates are %notyet with respect to the coordinate system defined by \code{coord\_arrays[]}. %notyet \end{Parameter} %notyet \begin{Parameter}{N\_input\_arrays ($\ge 0$)} %notyet \hbox{} %notyet The number of input arrays to be interpolated. %notyet Note that if the parameter table entry \code{operand\_indices} %notyet is used to specify a 1-to-many mapping of input arrays to output arrays, %notyet only the unique set of input arrays should be given here. %notyet \end{Parameter} %notyet \begin{Parameter}{input\_array\_dims ($\ne$ NULL)} %notyet \hbox{} %notyet (Pointer to) an array of \code{N\_dims} integers giving the dimensions %notyet of the input arrays. By default all the input arrays are taken to have %notyet these dimensions, with \code{[0]} the most contiguous axis and %notyet \code{[N\_dims-1]} the least contiguous axis, and array subscripts in the %notyet range \code{0 <= subscript < input\_array\_dims[axis]}. See the discussion %notyet of the \code{input\_array\_strides} optional parameter (passed in the %notyet parameter table) for details of how this can be overridden. %notyet \end{Parameter} %notyet \begin{Parameter}{input\_array\_type\_codes ($\ne$ NULL)} %notyet \hbox{} %notyet (Pointer to) an array of \code{N\_input\_arrays} \code{CCTK\_VARIABLE\_*} %notyet type codes giving the data types of the \code{N\_dims}-D input arrays %notyet pointed to by \code{input\_arrays[]}. %notyet \end{Parameter} %notyet \begin{Parameter}{input\_arrays ($\ne$ NULL)} %notyet \hbox{} %notyet (Pointer to) an array of \code{N\_input\_arrays} pointers to the %notyet \code{N\_dims}-D input arrays for the interpolation. %notyet \end{Parameter} %notyet \begin{Parameter}{N\_output\_arrays ($\ge 0$)} %notyet \hbox{} %notyet The number of output arrays to be returned from the interpolation. %notyet \end{Parameter} %notyet \begin{Parameter}{output\_array\_type\_codes ($\ne$ NULL)} %notyet \hbox{} %notyet (Pointer to) an array of \code{N\_output\_arrays} \code{CCTK\_VARIABLE\_*} %notyet type codes giving the data types of the 1-D output arrays pointed to by %notyet \code{output\_arrays[]}. %notyet \end{Parameter} %notyet \begin{Parameter}{output\_arrays ($\ne$ NULL)} %notyet \hbox{} %notyet (Pointer to) an array of \code{N\_output\_arrays} pointers to the %notyet (user-supplied) 1-D output arrays for the interpolation. %notyet \end{Parameter} %notyet \end{ParameterSection} %notyet %notyet \begin{Discussion} %notyet This function is a generic API for interpolating processor-local arrays %notyet when the data points' coordinates~$xyz$ are generic {\em multivariable %notyet nonlinear\/} functions of the integer array subscripts~\code{ijk} %notyet (we're describing this for 3-D, but the generalization to other %notyet numbers of dimensions should be obvious), %notyet \begin{flushleft} %notyet $x = x(\code{i}, \code{j}, \code{k})$ \\ %notyet $y = y(\code{i}, \code{j}, \code{k})$ \\ %notyet $z = z(\code{i}, \code{j}, \code{k})$ %%%\\ %notyet \end{flushleft} %notyet These nonlinear functions are specified by setting up 3-D arrays %notyet giving their (the coordinates) values at the grid points, then passing %notyet pointers to these 3-D arrays in the \code{coord\_arrays} argument: %notyet \begin{flushleft} %notyet $x = \code{coord\_arrays[0][i,j,k]}$ \\ %notyet $y = \code{coord\_arrays[1][i,j,k]}$ \\ %notyet $z = \code{coord\_arrays[2][i,j,k]}$ \\ %notyet \end{flushleft} %notyet where \code{[i,j,k]} refers to \code{N\_dims}-D array subscripting. %notyet %notyet [If these nonlinear functions are known analytically, then it's %notyet probably more efficient to analytically transform to coordinates %notyet which are linear functions of the subscripts, then use %notyet \code{CCTK\_InterpLocalUniform}.] %notyet %notyet The $(x,y,z)$ coordinates are used for the interpolation %notyet (\ie{}~the interpolator may internally use polynomials in these %notyet coordinates); \code{interp\_coords} specifies coordinates in this %notyet same coordinate system. %notyet %notyet Details of the operation performed, and what (if any) inputs and/or %notyet outputs are specified in the parameter table, depend on which interpolation %notyet operator you use. See the Thorn Guide for the AEILocalInterp thorn for %notyet further discussion. %notyet \end{Discussion} %notyet %notyet \begin{SeeAlsoSection} %notyet \begin{SeeAlso}{CCTK\_InterpHandle()} %notyet Get the interpolator handle for a given character-string name. %notyet \end{SeeAlso} %notyet \begin{SeeAlso}{CCTK\_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 \code{CCTK\_InterpLocalWarped} interpolation operator. %notyet \end{SeeAlso} %notyet \end{SeeAlsoSection} %notyet %notyet \begin{ErrorSection} %notyet \begin{Error}{} %notyet To find the numerical %notyet values of the error codes (or more commonly, to find which error code %notyet corresponds to a given numerical value), look in the files %notyet \code{cctk\_Interp.h}, \code{util\_ErrorCodes.h}, and/or \code{util\_Table.h} in the \code{src/include/} directory in the Cactus flesh. %notyet \end{Error} %notyet \begin{Error}{CCTK\_ERROR\_INTERP\_POINT\_OUTSIDE} %notyet one or more of the interpolation points is out of range %notyet (in this case additional information about the out-of-range point %notyet may be reported through the parameter table; see the Thorn Guide for %notyet the AEILocalInterp thorn for further details) %notyet \end{Error} %notyet \begin{Error}{UTIL\_ERROR\_BAD\_INPUT} %notyet one or more of the inputs is invalid (e.g.~\code{NULL} pointer) %notyet \end{Error} %notyet \begin{Error}{UTIL\_ERROR\_NO\_MEMORY} %notyet unable to allocate memory %notyet \end{Error} %notyet \begin{Error}{UTIL\_ERROR\_BAD\_HANDLE} %notyet parameter table handle is invalid %notyet \end{Error} %notyet \begin{Error}{other error codes} %notyet this function may also return any error codes returned by the %notyet \code{Util\_Table*} routines used to get parameters from %notyet (and/or set results in) the parameter table %notyet \end{Error} %notyet \end{ErrorSection} %notyet %notyet \begin{ExampleSection} %notyet \begin{Example}{C} %notyet Here's a simple example of interpolating a \code{CCTK\_REAL} and a %notyet \code{CCTK\_COMPLEX} $10 \times 20$ 2-D array, at 5 interpolation points, %notyet using cubic interpolation. %notyet %notyet \begin{verbatim} %notyet #define N_DIMS 2 %notyet #define N_INTERP_POINTS 5 %notyet #define N_INPUT_ARRAYS 2 %notyet #define N_OUTPUT_ARRAYS 2 %notyet %notyet /* (x,y) coordinates of data grid points */ %notyet /* ... note Cactus uses Fortran storage ordering, i.e.\ X is contiguous */ %notyet #define NX 10 %notyet #define NY 20 %notyet const CCTK_INT coord_array_dims[N_DIMS] = { NX, NY }; %notyet const CCTK_REAL x_coords[NY][NX]; %notyet const CCTK_REAL y_coords[NY][NX]; %notyet const void *const coord_arrays[N_DIMS] %notyet = { (const void *) x_coords, (const void *) y_coords }; %notyet %notyet /* (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 \code{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 \code{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 \code{CCTK\_InterpLocalUniform} interpolation operator. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" int CCTK_InterpRegisterOpLocalUniform(cInterpOpLocalUniform operator_ptr, const char *operator_name, const char *thorn_name); \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{handle ($\ge 0$)} A cactus handle to refer to all interpolation operators registered under this operator name. \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{operator\_ptr ($\ne$ NULL)} \hbox{} Pointer to the \code{CCTK\_InterpLocalUniform} interpolation operator. This argument must be a C function pointer of the appropriate type; the typedef can be found in \code{src/include/cctk\_Interp.h} in the Cactus source code. \end{Parameter} \begin{Parameter}{operator\_name ($\ne$ NULL)} \hbox{} (Pointer to) a (C-style null-terminated) character string giving the name under which to register the operator. \end{Parameter} \begin{Parameter}{thorn\_name ($\ne$ NULL)} \hbox{} (Pointer to) a (C-style null-terminated) character string giving the name of the thorn which provides the interpolation operator. \end{Parameter} \end{ParameterSection} \begin{Discussion} Only C functions (or other routines with C-compatible calling sequences) can be registered as interpolation operators. \end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso}{CCTK\_InterpHandle()} Get the interpolator handle for a given character-string name. \end{SeeAlso} \begin{SeeAlso}{CCTK\_InterpLocalUniform()} Interpolate a list of processor-local arrays, with uniformly spaced data points. \end{SeeAlso} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{-1} NULL pointer was passed as interpolation operator routine \end{Error} \begin{Error}{-2} interpolation handle could not be allocated \end{Error} \begin{Error}{-3} Interpolation operator with this name already exists \end{Error} \end{ErrorSection} \begin{ExampleSection} \begin{Example}{C} \begin{verbatim} /* prototype for function we want to register */ int AEILocalInterp_InterpLocalUniform(int N_dims, int param_table_handle, /***** coordinate system *****/ const CCTK_REAL coord_origin[], const CCTK_REAL coord_delta[], /***** interpolation points *****/ int N_interp_points, int interp_coords_type_code, const void *const interp_coords[], /***** input arrays *****/ int N_input_arrays, const CCTK_INT input_array_dims[], const CCTK_INT input_array_type_codes[], const void *const input_arrays[], /***** output arrays *****/ int N_output_arrays, const CCTK_INT output_array_type_codes[], void *const output_arrays[]); /* register it! */ CCTK_InterpRegisterOpLocalUniform(AEILocalInterp_InterpLocalUniform, "generalized polynomial interpolation", CCTK_THORNSTRING); \end{verbatim} \end{Example} \end{ExampleSection} \end{FunctionDescription} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % CCTK\_InterpRegisterOpLocalWarped here % lib/sbin/CreateFunctionBindings.pl \begin{CCTKFunc}{CCTK\_IsFunctionAliased}{Reports whether an aliased function has been provided} \label{CCTK-IsFunctionAliased} \subroutine{int}{integer}{istat} \argument{const char *}{character*(*)}{functionname} \showargs \begin{params} \parameter{istat}{the return status} \parameter{functionname}{the name of the function to check} \end{params} \begin{discussion} This function returns a non-zero value if the function given by \code{functionname} is provided by any active thorn, and zero otherwise. \end{discussion} \end{CCTKFunc} % 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 \code{implementationname} was activated in a parameter file, and zero otherwise. See also \code{CCTK\_ActivatingThorn} [\pageref{CCTK-ActivatingThorn}], \code{CCTK\_CompiledImplementation} [\pageref{CCTK-CompiledImplementation}], \code{CCTK\_CompiledThorn} [\pageref{CCTK-CompiledThorn}], \code{CCTK\_ImplementationRequires} [\pageref{CCTK-ImplementationRequires}], \code{CCTK\_ImplementationThorn} [\pageref{CCTK-ImplementationThorn}], \code{CCTK\_ImpThornList} [\pageref{CCTK-ImpThornList}], \code{CCTK\_IsImplementationCompiled} [\pageref{CCTK-IsImplementationCompiled}], \code{CCTK\_IsThornActive} [\pageref{CCTK-IsThornActive}], \code{CCTK\_NumCompiledImplementations} [\pageref{CCTK-NumCompiledImplementations}], \code{CCTK\_NumCompiledThorns} [\pageref{CCTK-NumCompiledThorns}], \code{CCTK\_ThornImplementation} [\pageref{CCTK-ThornImplementation}]. \end{discussion} \end{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 \code{implementationname} was compiled into the configuration, and zero otherwise. See also \code{CCTK\_ActivatingThorn} [\pageref{CCTK-ActivatingThorn}], \code{CCTK\_CompiledImplementation} [\pageref{CCTK-CompiledImplementation}], \code{CCTK\_CompiledThorn} [\pageref{CCTK-CompiledThorn}], \code{CCTK\_ImplementationRequires} [\pageref{CCTK-ImplementationRequires}], \code{CCTK\_ImplementationThorn} [\pageref{CCTK-ImplementationThorn}], \code{CCTK\_ImpThornList} [\pageref{CCTK-ImpThornList}], \code{CCTK\_IsImplementationActive} [\pageref{CCTK-IsImplementationActive}], \code{CCTK\_IsThornActive} [\pageref{CCTK-IsThornActive}], \code{CCTK\_IsThornCompiled} [\pageref{CCTK-IsThornCompiled}], \code{CCTK\_NumCompiledImplementations} [\pageref{CCTK-NumCompiledImplementations}], \code{CCTK\_NumCompiledThorns} [\pageref{CCTK-NumCompiledThorns}], \code{CCTK\_ThornImplementation} [\pageref{CCTK-ThornImplementation}]. \end{discussion} \end{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 \code{thornname} was activated in a parameter file, and zero otherwise. See also \code{CCTK\_ActivatingThorn} [\pageref{CCTK-ActivatingThorn}], \code{CCTK\_CompiledImplementation} [\pageref{CCTK-CompiledImplementation}], \code{CCTK\_CompiledThorn} [\pageref{CCTK-CompiledThorn}], \code{CCTK\_ImplementationRequires} [\pageref{CCTK-ImplementationRequires}], \code{CCTK\_ImplementationThorn} [\pageref{CCTK-ImplementationThorn}], \code{CCTK\_ImpThornList} [\pageref{CCTK-ImpThornList}], \code{CCTK\_IsImplementationActive} [\pageref{CCTK-IsImplementationActive}], \code{CCTK\_IsImplementationCompiled} [\pageref{CCTK-IsImplementationCompiled}], \code{CCTK\_IsThornActive} [\pageref{CCTK-IsThornActive}], \code{CCTK\_NumCompiledImplementations} [\pageref{CCTK-NumCompiledImplementations}], \code{CCTK\_NumCompiledThorns} [\pageref{CCTK-NumCompiledThorns}], \code{CCTK\_ThornImplementation} [\pageref{CCTK-ThornImplementation}]. \end{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 \code{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 $<$ \code{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 \code{::} \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 \code{::} \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 \code{CCTK\_NullPointer}. Note that there is only a Fortran wrapper available for \code{CCTK\_NullPointer}. \end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso}{CCTK\_PointerTo()} Returns the address of a variable passed in by reference from a Fortran routine. \end{SeeAlso} \end{SeeAlsoSection} \begin{ExampleSection} \begin{Example}{Fortran} \begin{verbatim} #include "cctk.h" integer ierror, table_handle CCTK_POINTER pointer_var pointer_var = CCTK_NullPointer() call Util_TableCreate(table_handle, 0) call Util_TableSetPointer(ierror, table_handle, pointer_var, "NULL pointer") \end{verbatim} \end{Example} \end{ExampleSection} \end{FunctionDescription} % cctk_ActiveThorns.c \begin{FunctionDescription}{CCTK\_NumCompiledImplementations} \label{CCTK-NumCompiledImplementations} Return the number of implementations compiled in. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" int numimpls = CCTK_NumCompiledImplementations(); \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{numimpls} Number of implementations compiled in. \end{Result} \end{ResultSection} %\begin{ParameterSection} %\end{ParameterSection} %\begin{Discussion} %\end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_ActivatingThorn}{CCTK-ActivatingThorn} Finds the thorn which activated a particular implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_CompiledImplementation}{CCTK-CompiledImplementation} Return the name of the compiled implementation with given index \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_CompiledThorn}{CCTK-CompiledThorn} Return the name of the compiled thorn with given index \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImplementationRequires}{CCTK-ImplementationRequires} Return the ancestors for an implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImplementationThorn}{CCTK-ImplementationThorn} Returns the name of one thorn providing an implementation. \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImpThornList}{CCTK-ImpThornList} Return the thorns for an implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive} Reports whether an implementation was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled} Reports whether an implementation was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive} Reports whether a thorn was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled} Reports whether a thorn was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_NumCompiledThorns}{CCTK-NumCompiledThorns} Return the number of thorns compiled in \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ThornImplementation}{CCTK-ThornImplementation} Returns the implementation provided by the thorn \end{SeeAlso2} \end{SeeAlsoSection} %\begin{ErrorSection} %\end{ErrorSection} %\begin{ExampleSection} %\end{ExampleSection} \end{FunctionDescription} % cctk_ActiveThorns.c \begin{FunctionDescription}{CCTK\_NumCompiledThorns} \label{CCTK-NumCompiledThorns} Return the number of thorns compiled in. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" int numthorns = CCTK_NumCompiledThornss(); \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{numthorns} Number of thorns compiled in. \end{Result} \end{ResultSection} %\begin{ParameterSection} %\end{ParameterSection} %\begin{Discussion} %\end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_ActivatingThorn}{CCTK-ActivatingThorn} Finds the thorn which activated a particular implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_CompiledImplementation}{CCTK-CompiledImplementation} Return the name of the compiled implementation with given index \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_CompiledThorn}{CCTK-CompiledThorn} Return the name of the compiled thorn with given index \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImplementationRequires}{CCTK-ImplementationRequires} Return the ancestors for an implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImplementationThorn}{CCTK-ImplementationThorn} Returns the name of one thorn providing an implementation. \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImpThornList}{CCTK-ImpThornList} Return the thorns for an implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive} Reports whether an implementation was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled} Reports whether an implementation was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive} Reports whether a thorn was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled} Reports whether a thorn was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_NumCompiledImplementations}{CCTK-NumCompiledImplementations} Return the number of implementations compiled in \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ThornImplementation}{CCTK-ThornImplementation} Returns the implementation provided by the thorn \end{SeeAlso2} \end{SeeAlsoSection} %\begin{ErrorSection} %\end{ErrorSection} %\begin{ExampleSection} %\end{ExampleSection} \end{FunctionDescription} % 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 \code{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} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % cctk_GroupsOnGH.h \begin{FunctionDescription}{CCTK\_NumTimeLevels} \label{CCTK-NumTimeLevels} Returns the number of active time levels for a group (deprecated). \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" int timelevels = CCTK_NumTimeLevels(const cGH *cctkGH, const char *groupname); int timelevels = CCTK_NumTimeLevelsGI(const cGH *cctkGH, int groupindex); int timelevels = CCTK_NumTimeLevelsGN(const cGH *cctkGH, const char *groupname); int timelevels = CCTK_NumTimeLevelsVI(const cGH *cctkGH, int varindex); int timelevels = CCTK_NumTimeLevelsVN(const cGH *cctkGH, const char *varname); \end{verbatim} \end{Synopsis} \begin{Synopsis}{Fortran} \begin{verbatim} #include "cctk.h" subroutine CCTK_NumTimeLevels(timelevels, cctkGH, groupname) integer timelevels CCTK_POINTER cctkGH character*(*) groupname end subroutine CCTK_NumTimeLevels subroutine CCTK_NumTimeLevelsGI(timelevels, cctkGH, groupindex) integer timelevels CCTK_POINTER cctkGH integer groupindex end subroutine CCTK_NumTimeLevelsGI subroutine CCTK_NumTimeLevelsGN(timelevels, cctkGH, groupname) integer timelevels CCTK_POINTER cctkGH character*(*) groupname end subroutine CCTK_NumTimeLevelsGN subroutine CCTK_NumTimeLevelsVI(timelevels, cctkGH, varindex) integer timelevels CCTK_POINTER cctkGH integer varindex end subroutine CCTK_NumTimeLevelsVI subroutine CCTK_NumTimeLevelsVN(timelevels, cctkGH, varname) integer timelevels CCTK_POINTER cctkGH character*(*) varname end subroutine CCTK_NumTimeLevelsVN \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{timelevels} The currently active number of timelevels for the group. \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{GH ($\ne$ NULL)} Pointer to a valid Cactus grid hierarchy. \end{Parameter} \begin{Parameter}{groupname} Name of the group. \end{Parameter} \begin{Parameter}{groupindex} Index of the group. \end{Parameter} \begin{Parameter}{varname} Name of a variable in the group. \end{Parameter} \begin{Parameter}{varindex} Index of a variable in the group. \end{Parameter} \end{ParameterSection} \begin{Discussion} This function returns the number of timelevels for which storage has been activated, which is always equal to or less than the maximum number of timelevels which may have storage provided by \code{CCTK\_MaxTimeLevels}. This function has been superceded by \code{CCTK\_ActiveTimeLevels} and should not be used any more. \end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_ActiveTimeLevels}{CCTK-ActiveTimeLevels} Returns the number of active time levels for a group. \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_MaxTimeLevels}{CCTK-MaxTimeLevels} Return the maximum number of active timelevels. \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_GroupStorageDecrease}{CCTK-GroupStoragDecrease} Base function, overloaded by the driver, which decreases the number of active timelevels, and also returns the number of active timelevels. \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_GroupStorageIncrease}{CCTK-GroupStorageIncrease} Base function, overloaded by the driver, which increases the number of active timelevels, and also returns the number of active timelevels. \end{SeeAlso2} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{timelevels $<$ 0} Illegal arguments given. \end{Error} \end{ErrorSection} %\begin{ExampleSection} %\end{ExampleSection} \end{FunctionDescription} % 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 \code{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 \code{::} \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 (e.g.\ IO method is not registered) \end{Error} \end{ErrorSection} \end{FunctionDescription} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % IOOverloadables.h \begin{FunctionDescription}{CCTK\_OutputVarAs} Output a single variable as an alias by all I/O methods \label{CCTK-OutputVarAs} \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} int istat = CCTK_OutputVarAs (const cGH *cctkGH, const char *variable, const char *alias); \end{verbatim} \end{Synopsis} \begin{Synopsis}{Fortran} \begin{verbatim} call CCTK_OutputVarAsByMethod (istat, cctkGH, variable, alias) integer istat CCTK_POINTER cctkGH character*(*) variable character*(*) alias \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ParameterSection} \begin{Parameter}{istat}return status\end{Parameter} \begin{Parameter}{cctkGH}pointer to CCTK grid hierarchy\end{Parameter} \begin{Parameter}{variable}full name of variable to output\end{Parameter} \begin{Parameter}{alias}alias name to base the output filename on\end{Parameter} \end{ParameterSection} \begin{Discussion} The output should take place if at all possible. If the appropriate file exists the data is appended, otherwise a new file is created. Uses \code{alias} as the name of the variable for the purpose of constructing a filename. \end{Discussion} \begin{ErrorSection} \begin{Error}{positive}the number of IO methods which did output of \code{variable}\end{Error} \begin{Error}{\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 \code{variable} using the method \code{method} if it is registered. Uses \code{alias} as the name of the variable for the purpose of constructing a filename. The output should take place if at all possible. If the appropriate file exists the data is appended, otherwise a new file is created. \end{Discussion} \begin{ErrorSection} \begin{Error}{\rm 0}for success\end{Error} \begin{Error}{negative}indicating some error (e.g.\ IO method is not registered)\end{Error} \end{ErrorSection} \end{FunctionDescription} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % IOOverloadables.h \begin{FunctionDescription}{CCTK\_OutputVarByMethod} \label{CCTK-OutputVarByMethod} \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} int istat = CCTK_OutputVarByMethod (const cGH *cctkGH, const char *variable, const char *method); \end{verbatim} \end{Synopsis} \begin{Synopsis}{Fortran} \begin{verbatim} call CCTK_OutputVarByMethod (istat, cctkGH, variable, method) integer istat CCTK_POINTER cctkGH character*(*) variable character*(*) method \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ParameterSection} \begin{Parameter}{istat}return status\end{Parameter} \begin{Parameter}{cctkGH}pointer to CCTK grid hierarchy\end{Parameter} \begin{Parameter}{variable}full name of variable to output\end{Parameter} \begin{Parameter}{method}method to use for output\end{Parameter} \end{ParameterSection} \begin{Discussion} Output a variable \code{variable} using the IO method \code{method} if it is registered. The output should take place if at all possible. if the appropriate file exists the data is appended, otherwise a new file is created. \end{Discussion} \begin{ErrorSection} \begin{Error}{\rm 0}for success\end{Error} \begin{Error}{negative}indicating some error (e.g.\ IO method is not registered)\end{Error} \end{ErrorSection} \end{FunctionDescription} %%%%% % PPP %%%%% % CommOverloadables.c \begin{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} % Parameters.c \begin{FunctionDescription}{CCTK\_ParameterData} \label{CCTK-ParameterData} Get parameter properties for given parameter/thorn pair. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" const cParamData *paramdata = CCTK_ParameterData (const char *name, const char *thorn); \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{paramdata} Pointer to parameter data structure \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{name} Parameter name \end{Parameter} \begin{Parameter}{thorn} Thorn name (for private parameters) or implementation name (for restricted parameters) \end{Parameter} \end{ParameterSection} \begin{Discussion} The thorn or implementation name must be the name of the place where the parameter is originally defined. It is not possible to pass the thorn or implementation name of a thorn that merely declares the parameter as used. \end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_ParameterGet}{CCTK-ParameterGet} Get the data pointer to and type of a parameter's value \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterLevel}{CCTK-ParameterLevel} Return the parameter checking level \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterQueryTimesSet}{CCTK-ParameterQueryTimesSet} Return number of times a parameter has been set \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterSet}{CCTK-ParameterSet} Sets the value of a parameter \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterValString}{CCTK-ParameterValString} Get the string representation of a parameter's value \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterWalk}{CCTK-ParameterWalk} Walk through list of parameters \end{SeeAlso2} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{NULL} No parameter with that name was found. \end{Error} \end{ErrorSection} \end{FunctionDescription} % Parameters.c \begin{FunctionDescription}{CCTK\_ParameterGet} \label{CCTK-ParameterGet} Get the data pointer to and type of a parameter's value. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" const void *paramval = CCTK_ParameterGet (const char *name, const char *thorn, int *type); \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{paramval} Pointer to the parameter value \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{name} Parameter name \end{Parameter} \begin{Parameter}{thorn} Thorn name (for private parameters) or implementation name (for restricted parameters) \end{Parameter} \begin{Parameter}{type} If not NULL, a pointer to an integer which will hold the type of the parameter \end{Parameter} \end{ParameterSection} \begin{Discussion} The thorn or implementation name must be the name of the place where the parameter is originally defined. It is not possible to pass the thorn or implementation name of a thorn that merely declares the parameter as used. \end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_ParameterData}{CCTK-ParameterData} Get parameter properties for given parameter/thorn pair \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterLevel}{CCTK-ParameterLevel} Return the parameter checking level \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterQueryTimesSet}{CCTK-ParameterQueryTimesSet} Return number of times a parameter has been set \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterSet}{CCTK-ParameterSet} Sets the value of a parameter \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterValString}{CCTK-ParameterValString} Get the string representation of a parameter's value \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterWalk}{CCTK-ParameterWalk} Walk through list of parameters \end{SeeAlso2} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{NULL} No parameter with that name was found. \end{Error} \end{ErrorSection} \end{FunctionDescription} % WaveLevel.c \begin{FunctionDescription}{CCTK\_ParameterLevel} \label{CCTK-ParameterLevel} Return the parameter checking level. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" int level = CCTK_ParameterLevel (void); \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{level} Parameter checking level now being used. \end{Result} \end{ResultSection} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_ParameterData}{CCTK-ParameterData} Get parameter properties for given parameter/thorn pair \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterGet}{CCTK-ParameterGet} Get the data pointer to and type of a parameter's value \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterQueryTimesSet}{CCTK-ParameterQueryTimesSet} Return number of times a parameter has been set \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterSet}{CCTK-ParameterSet} Sets the value of a parameter \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterValString}{CCTK-ParameterValString} Get the string representation of a parameter's value \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterWalk}{CCTK-ParameterWalk} Walk through list of parameters \end{SeeAlso2} \end{SeeAlsoSection} \end{FunctionDescription} % Parameters.c \begin{FunctionDescription}{CCTK\_ParameterQueryTimesSet} \label{CCTK-ParameterQueryTimesSet} Return number of times a parameter has been set. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" int nset = CCTK_ParameterQueryTimesSet (const char *name, const char *thorn); \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{nset} Number of times the parameter has been set. \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{name} Parameter name \end{Parameter} \begin{Parameter}{thorn} Thorn name (for private parameters) or implementation name (for restricted parameters) \end{Parameter} \end{ParameterSection} \begin{Discussion} The number of times that a parameter has been set is 0 if the parameter was not set in a parameter file. The number increases when \code{CCTK\_ParameterSet} is called. The thorn or implementation name must be the name of the place where the parameter is originally defined. It is not possible to pass the thorn or implementation name of a thorn that merely declares the parameter as used. \end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_ParameterData}{CCTK-ParameterData} Get parameter properties for given parameter/thorn pair \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterGet}{CCTK-ParameterGet} Get the data pointer to and type of a parameter's value \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterLevel}{CCTK-ParameterLevel} Return the parameter checking level \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterSet}{CCTK-ParameterSet} Sets the value of a parameter \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterValString}{CCTK-ParameterValString} Get the string representation of a parameter's value \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterWalk}{CCTK-ParameterWalk} Walk through list of parameters \end{SeeAlso2} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{$-1$} No parameter with that name exists. \end{Error} \end{ErrorSection} \end{FunctionDescription} % Parameters.c \begin{FunctionDescription}{CCTK\_ParameterSet} \label{CCTK-ParameterSet} Sets the value of a parameter. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" int ierr = CCTK_ParameterSet (const char *name, const char *thorn, const char *value); \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{ierr} Error code \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{name} Parameter name \end{Parameter} \begin{Parameter}{thorn} Thorn name (for private parameters) or implementation name (for restricted parameters) \end{Parameter} \begin{Parameter}{type} If not NULL, a pointer to an integer which will hold the type of the parameter \end{Parameter} \end{ParameterSection} \begin{Discussion} The thorn or implementation name must be the name of the place where the parameter is originally defined. It is not possible to pass the thorn or implementation name of a thorn that merely declares the parameter as used. \end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_ParameterData}{CCTK-ParameterData} Get parameter properties for given parameter/thorn pair \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterLevel}{CCTK-ParameterLevel} Return the parameter checking level \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterQueryTimesSet}{CCTK-ParameterQueryTimesSet} Return number of times a parameter has been set \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterValString}{CCTK-ParameterValString} Get the string representation of a parameter's value \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterWalk}{CCTK-ParameterWalk} Walk through list of parameters \end{SeeAlso2} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{ierr} \begin{description} \item[$0$] success \item[$-1$] parameter is out of range \item[$-2$] parameter was not found \item[$-3$] trying to steer a non-steerable parameter \item[$-6$] not a valid integer or float \item[$-7$] tried to set an accumulator parameter directly \item[$-8$] tried to set an accumulator parameter directly \item[$-9$] final value of accumulator out of range \end{description} \end{Error} \end{ErrorSection} \end{FunctionDescription} % Parameters.c \begin{FunctionDescription}{CCTK\_ParameterValString} \label{CCTK-ParameterValString} Get the string representation of a parameter's value. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" char *valstring = CCTK_ParameterValString (const char *name, const char *thorn); \end{verbatim} \end{Synopsis} \begin{Synopsis}{Fortran} \begin{verbatim} subroutine CCTK_ParameterValString (nchars, name, thorn, value) integer nchars character*(*) name character*(*) thorn character*(*) value end subroutine \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{valstring} Pointer to parameter value as string. This string must be freed after it has been used. \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{name} Parameter name \end{Parameter} \begin{Parameter}{thorn} Thorn name (for private parameters) or implementation name (for restricted parameters) \end{Parameter} \begin{Parameter}{nchars} On exit, the number of characters in the stringified parameter value, or $-1$ if the parameter doesn't exist \end{Parameter} \begin{Parameter}{value} As many characters as fit into the Fortran string. You should check for truncation by comparing \code{nchars} against the length of your Fortran string. \end{Parameter} \end{ParameterSection} \begin{Discussion} \fbox{The string \code{valstring} must be freed afterwards.} The thorn or implementation name must be the name of the place where the parameter is originally defined. It is not possible to pass the thorn or implementation name of a thorn that merely declares the parameter as used. \end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_ParameterData}{CCTK-ParameterData} Get parameter properties for given parameter/thorn pair \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterGet}{CCTK-ParameterGet} Get the data pointer to and type of a parameter's value \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterLevel}{CCTK-ParameterLevel} Return the parameter checking level \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterQueryTimesSet}{CCTK-ParameterQueryTimesSet} Return number of times a parameter has been set \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterSet}{CCTK-ParameterSet} Sets the value of a parameter \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterWalk}{CCTK-ParameterWalk} Walk through list of parameters \end{SeeAlso2} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{NULL} No parameter with that name was found. \end{Error} \end{ErrorSection} \end{FunctionDescription} % Parameters.c \begin{FunctionDescription}{CCTK\_ParameterWalk} \label{CCTK-ParameterWalk} Walk through the list of parameters. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" int istat = CCTK_ParameterWalk (int first, const char *origin, char **fullname, const cParamData **paramdata); \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{istat} Zero for success, positive if parameter was not found, negative if initial startpoint was not set. \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{origin} Thorn name, or \code{NULL} for all thorns. \end{Parameter} \begin{Parameter}{fullname} Address of a pointer that will point to the full parameter name. This name must be freed after use. \end{Parameter} \begin{Parameter}{paramdata} Address of a pointer that will point to the parameter data structure. \end{Parameter} \end{ParameterSection} \begin{Discussion} Gets parameters in order, restricted to ones from \code{origin}, or all if \code{origin} is \code{NULL}. Starts with the first parameter if \code{first} is true, otherwise gets the next one. Can be used for generating full help file, or for walking the list and checkpointing. \end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_ParameterData}{CCTK-ParameterData} Get parameter properties for given parameter/thorn pair \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterGet}{CCTK-ParameterGet} Get the data pointer to and type of a parameter's value \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterLevel}{CCTK-ParameterLevel} Return the parameter checking level \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterQueryTimesSet}{CCTK-ParameterQueryTimesSet} Return number of times a parameter has been set \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterSet}{CCTK-ParameterSet} Sets the value of a parameter \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ParameterValString}{CCTK-ParameterValString} Get the string representation of a parameter's value \end{SeeAlso2} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{negative} The initial startpoint was not set. \end{Error} \end{ErrorSection} \end{FunctionDescription} % WarnLevel.c \begin{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 \code{CCTK\_PARAMCHECK} to indicate that there is parameter error or conflict and the code should terminate. The code will terminate only after all the parameters have been checked. \end{discussion} \begin{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 \code{CCTK\_PointerTo()} which takes the variable itself as a single argument and returns the pointer to it. Note that there is only a Fortran wrapper available for \code{CCTK\_PointerTo}. \end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso}{CCTK\_NullPointer()} Returns a C-style NULL pointer value. \end{SeeAlso} \end{SeeAlsoSection} \begin{ExampleSection} \begin{Example}{Fortran} \begin{verbatim} #include "cctk.h" integer ierror, table_handle CCTK_POINTER addr, var addr = CCTK_PointerTo(var) call Util_TableCreate(table_handle, 0) call Util_TableSetPointer(ierror, table_handle, addr, "variable") \end{verbatim} \end{Example} \end{ExampleSection} \end{FunctionDescription} % Groups.c \begin{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 positive 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} \parameter{groupindex}{the group to query, given by its index} \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 positive value), otherwise false (zero). The group can be specified either through the group index \code{groupindex}, or through the group name \code{groupname}. The groupname takes precedence; only if it is passed as \code{NULL}, the group index is used. \end{discussion} \begin{errorcodes} \begin{tabular}{l} A negative error code is returned for an invalid group name. \end{tabular} \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 positive 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 \code{CCTK\_STARTUP}. Note that integer reduction handles are used to call \code{CCTK\_Reduce} to avoid problems with passing Fortran strings. Note that the name of the reduction operator is case dependent. \end{discussion} \begin{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 \code{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 \code{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 \code{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 \code{CCTK\_DisableGroupComm}. Note that an alternative to calling \code{CCTK\_SyncGroup} explicitly from within a thorn, is to use the \code{SYNC} keyword in a thorns \code{schedule.ccl} file to indicate which groups of variables need to be synchronised on exit from the routine. This latter method is the preferred method from synchronising variables. \end{discussion} \begin{examples} \begin{tabular}{@{}p{3cm}cp{11cm}} \end{tabular} \end{examples} \begin{errorcodes} \end{errorcodes} \end{CCTKFunc} %%%%% % TTT %%%%% % cctk_ActiveThorns.c \begin{FunctionDescription}{CCTK\_ThornImplementation} \label{CCTK-ThornImplementation} Returns the implementation provided by the thorn. \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" const char *imp = CCTK_ThornImplementationThorn(const char *name); \end{verbatim} \end{Synopsis} \end{SynopsisSection} \begin{ResultSection} \begin{Result}{imp} Name of the implementation or \code{NULL} \end{Result} \end{ResultSection} \begin{ParameterSection} \begin{Parameter}{name} Name of the thorn \end{Parameter} \end{ParameterSection} %\begin{Discussion} %\end{Discussion} \begin{SeeAlsoSection} \begin{SeeAlso2}{CCTK\_ActivatingThorn}{CCTK-ActivatingThorn} Finds the thorn which activated a particular implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_CompiledImplementation}{CCTK-CompiledImplementation} Return the name of the compiled implementation with given index \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_CompiledThorn}{CCTK-CompiledThorn} Return the name of the compiled thorn with given index \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImplementationRequires}{CCTK-ImplementationRequires} Return the ancestors for an implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImplementationThorn}{CCTK-ImplementationThorn} Returns the name of one thorn providing an implementation. \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_ImpThornList}{CCTK-ImpThornList} Return the thorns for an implementation \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationActive}{CCTK-IsImplementationActive} Reports whether an implementation was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsImplementationCompiled}{CCTK-IsImplementationCompiled} Reports whether an implementation was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornActive}{CCTK-IsThornActive} Reports whether a thorn was activated in a parameter file \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_IsThornCompiled}{CCTK-IsThornCompiled} Reports whether a thorn was compiled into a configuration \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_NumCompiledImplementations}{CCTK-NumCompiledImplementations} Return the number of implementations compiled in \end{SeeAlso2} \begin{SeeAlso2}{CCTK\_NumCompiledThorns}{CCTK-NumCompiledThorns} Return the number of thorns compiled in \end{SeeAlso2} \end{SeeAlsoSection} \begin{ErrorSection} \begin{Error}{NULL} Error. \end{Error} \end{ErrorSection} %\begin{ExampleSection} %\end{ExampleSection} \end{FunctionDescription} %%%%% % 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 \code{::}. \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 \code{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 \code{::} for a public or protected variable, and \code{::} 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 \code{Util\_SplitString} \end{Error} \begin{Error}{-3} given full name is in wrong format \end{Error} \begin{Error}{-4} memory allocation failed \end{Error} \end{ErrorSection} \begin{ExampleSection} \begin{Example}{C} \begin{verbatim} index = CCTK_VarIndex("evolve::phi"); \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 \code{CCTK\_VARIABLE\_INT}, \code{CCTK\_VARIABLE\_REAL}, \code{CCTK\_VARIABLE\_COMPLEX} or \code{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 \code{CCTK\_INT}, \code{CCTK\_REAL}, \code{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 \code{CCTK\_THORNSTRING} macro here (defined in \code{cctk.h}). \end{Parameter} \begin{Parameter}{format} The \code{printf}-like format string to use for printing the info message. \end{Parameter} \begin{Parameter}{...} The variable argument list. \end{Parameter} \end{ParameterSection} \begin{Discussion} This routine can be used by thorns to print a formatted string with a variable argument list as an info message to screen. The message will include the name of the originating thorn, otherwise its semantics is equivalent to \code{printf}. \end{Discussion} \begin{SeeAlsoSection} \begin{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} Possibly prints a formatted string with a variable argument list as warning message and/or stops the code \begin{SynopsisSection} \begin{Synopsis}{C} \begin{verbatim} #include "cctk.h" #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 and greater levels being less severe. \end{Parameter} \begin{Parameter}{line} The line number in the originating source file where the \code{CCTK\_VWarn} call occured. You can use the standardized \code{\_\_LINE\_\_} preprocessor macro here. \end{Parameter} \begin{Parameter}{file} The file name of the originating source file where the \code{CCTK\_VWarn} call occured. You can use the standardized \code{\_\_FILE\_\_} preprocessor macro here. \end{Parameter} \begin{Parameter}{thorn} The thorn name of the originating source file where the \code{CCTK\_VWarn} call occured. You can use the \code{CCTK\_THORNSTRING} macro here (defined in \code{cctk.h}). \end{Parameter} \begin{Parameter}{format} The \code{printf}-like format string to use for printing the warning message. \end{Parameter} \begin{Parameter}{...} The variable argument list. \end{Parameter} \end{ParameterSection} \begin{Discussion} This routine can be used by thorns to print a formatted string followed by a variable argument list as a warning message to \code{stderr}. If the message's ``warning level'' is severe enough, then after printing the message Cactus aborts the run (and \code{CCTK\_VWarn} does {\em not\/} return to the caller). Cactus's behavior when \code{CCTK\_VWarn} is called depends on the \code{-W} and \code{-E} command-line options: \begin{itemize} \item Cactus prints any warning with a warning level $\le$ the \code{-W} level to standard error (any warnings with warning levels $>$ the \code{-W} level are silently discarded). The default \code{-W} level is~1, \ie{} only level~0 and level~1 warnings will be printed. \item Cactus stops (aborts) the current run for any warning with a warning level $\le$ the \code{-E} level. The default \code{-W} level is~0, \ie{} only level~0 warnings will abort the run. \end{itemize} Cactus guarantees that $\hbox{the \code{-W}~level} \ge \hbox{the \code{-E}~level} \ge 0$. This implies that a message will always be printed for any warning that's severe enough to halt the Cactus run. It also implies that a level~0 warning is guaranteed (to be printed and) to halt the Cactus run. In any case, the Boolean flesh parameter \code{cctk\_full\_warnings} determines whether all the details about the warning origin (processor~ID, line number, source file, source thorn) are shown. The default is to 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 \code{stderr}. \code{CCTK\_WARN(level, message)} expands to a call to the underlying function \code{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 \code{CCTK\_WARN} is used to print a warning message rather than calling \code{CCTK\_Warn} directly. To include variables in a warning message from C, you can use the routine \code{CCTK\_VWarn} which accepts a variable argument list. To include variables from Fortran, a string must be constructed and passed in a \code{CCTK\_WARN} macro. \end{Discussion} \begin{SeeAlsoSection} \begin{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} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \end{cactuspart}