Abnormal Cactus termination.

Synopsis

Result

The function never returns, and hence never produces a result.

Parameters

GH (≠ NULL) Pointer to a valid Cactus grid hierarchy.

Discussion

This routine causes an immediate, abnormal Cactus termination. It never returns to the caller.

See Also

CCTK_Exit [A150] Exit the code cleanly
CCTK_WARN [A551] Macro to print a single string as a warning message and possibly stop the code
CCTK_Warn [A551] Prints a single string as a warning message and possibly stops the code
CCTK_VWarn [A547] Prints a formatted string with a variable argument list as a warning message to standard error and possibly stops the code

Errors

The function never returns, and hence never reports an error.

Examples

Finds the thorn which activated a particular implementation.

Synopsis

Result

thorn Name of activating thorn, or NULL if inactive

Parameters

name Implementation name

See Also

CCTK_CompiledImplementation [A90] Return the name of the compiled implementation with given index
CCTK_CompiledThorn [A92] Return the name of the compiled thorn with given index
CCTK_ImplementationRequires [A263] Return the ancestors for an implementation
CCTK_ImplementationThorn [A265] Returns the name of one thorn providing an implementation.
CCTK_ImpThornList [A267] Return the thorns for an implementation
CCTK_IsImplementationActive [A302] Reports whether an implementation was activated in a parameter file
CCTK_IsImplementationCompiled [A304] Reports whether an implementation was compiled into a configuration
CCTK_IsThornActive [A306] Reports whether a thorn was activated in a parameter file
CCTK_IsThornCompiled [A308] Reports whether a thorn was compiled into a configuration
CCTK_NumCompiledImplementations [A347] Return the number of implementations compiled in
CCTK_NumCompiledThorns [A349] Return the number of thorns compiled in
CCTK_ThornImplementation [A510] Returns the implementation provided by the thorn

Errors

NULL The implementation is inactive, or an error occurred.

Returns the number of active time levels for a group.

Synopsis

Result

timelevels The currently active number of timelevels for the group.

Parameters

GH (≠ NULL) Pointer to a valid Cactus grid hierarchy.
groupname Name of the group.
groupindex Index of the group.
varname Name of a variable in the group.
varindex Index of a variable in the group.

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 CCTK_MaxTimeLevels.

See Also

CCTK_MaxTimeLevels [A325] Return the maximum number of active timelevels.
CCTK_NumTimeLevels [A362] Deprecated; same as CCTK_ActiveTimeLevels.
CCTK_GroupStorageDecrease [A238] Base function, overloaded by the driver, which decreases the number of active timelevels, and also returns the number of active timelevels.
CCTK_GroupStorageIncrease [A241] Base function, overloaded by the driver, which increases the number of active timelevels, and also returns the number of active timelevels.

Errors

timelevels < 0 Illegal arguments given.

Returns a pointer to the processor-local size for variables in a group, specified by its name, in a given dimension.

Synopsis

Result

NULL A NULL pointer is returned if the group index or the dimension given are invalid.

Parameters

GH (≠ NULL) Pointer to a valid Cactus grid hierarchy.
dir (≥ 0) Which dimension of array to query.
groupname Name of the group.

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 CCTK_GroupgshGN instead.

See Also

CCTK_GroupgshGN [A196] Returns an array with the array size in all dimensions.
... There are many related functions which grab information from the GH, but many are not yet documented.

Returns a pointer to the processor-local size for variables in a group, specified by its index, in a given dimension.

Synopsis

Result

NULL A NULL pointer is returned if the group index or the dimension given are invalid.

Parameters

GH (≠ NULL) Pointer to a valid Cactus grid hierarchy.
dir (≥ 0) Which dimension of array to query.
groupi The group index.

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 CCTK_GroupgshGI instead.

See Also

CCTK_GroupgshGI [A196] Returns an array with the array size in all dimensions.
... There are many related functions which grab information from the GH, but many are not yet documented.

Synchronizes all processors at a given execution point 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 CCTK_Barrier. Note that this is a collective operation – it must be called by all processors otherwise the code will hang.

Synopsis

Registers a named timer clock with the Flesh.

Synopsis

Parameters

const char * name The name the clock will be given

const cClockFuncs * functions The structure holding the function pointers that define the clock

Discussion

The cClockFuncs structure contains function pointers defined by the clock module to be registered.

Errors

A negative return value indicates an error.

Turns two real numbers into a complex number

Synopsis

Parameters

cmpno The complex number
realpart The real part of the complex number
imagpart The imaginary part of the complex number

Examples

Absolute value of a complex number

Synopsis

Parameters

absval The computed absolute value
realpart The complex number who absolute value is to be returned

Examples

Sum of two complex numbers

Synopsis

Parameters

addval The computed added value
inval1 The first complex number to be summed
inval2 The second complex number to be summed

Examples

Complex conjugate of a complex number

Synopsis

Parameters

conjval The computed conjugate
inval The complex number to be conjugated

Examples

Cosine of a complex number

Synopsis

Parameters

cosval The computed cosine
inval The complex number to be cosined

Discussion

NOT YET AVAILABLE

Examples

Division of two complex numbers

Synopsis

Parameters

divval The divided value
inval1 The enumerator
inval1 The denominator

Examples

Exponent of a complex number

Synopsis

Parameters

expval The computed exponent
inval The complex number to be exponented

Discussion

NOT YET AVAILABLE

Examples

Imaginary part of a complex number

Synopsis

Parameters

imval The imaginary part
inval The complex number

Discussion

The imaginary part of a complex number z = a + bi is b.

Examples

Logarithm of a complex number

Synopsis

Parameters

logval The computed logarithm
inval The complex number

Discussion

NOT YET AVAILABLE

Examples

Multiplication of two complex numbers

Synopsis

Parameters

mulval The product
inval1 First complex number to be multiplied
inval2 Second complex number to be multiplied

Discussion

The product of two complex numbers z₁ = a₁ + b₁i and z₂ = a₂ + b₂i is z = (a₁a₂ - b₁b₂) + (a₁b₂ + a₂b₁)i.

Examples

Real part of a complex number

Synopsis

Parameters

reval The real part
inval The complex number

Discussion

The real part of a complex number z = a + bi is a.

Examples

Sine of a complex number

Synopsis

Parameters

sinval The computed sine
inval The complex number to be Sined

Discussion

NOT YET AVAILABLE

Examples

Square root of a complex number

Synopsis

Parameters

expval The computed square root
inval The complex number to be square rooted

Discussion

NOT YET AVAILABLE

Examples

Subtraction of two complex numbers

Synopsis

Parameters

addval The computed subtracted value
inval1 The complex number to be subtracted from
inval2 The complex number to subtract

Discussion

If z₁ = a₁ + b₁i and z₂ = a₂ + b₂i then

Examples

Returns a formatted string containing the date stamp when Cactus was compiled

Synopsis

Result

compile_date formatted string containing the date stamp

See Also

CCTK_CompileTime [A89] Returns a formatted string containing the time stamp when Cactus was compiled
CCTK_CompileDateTime [A88] Returns a formatted string containing the datetime stamp when Cactus was compiled

Returns a formatted string containing the datetime stamp when Cactus was compiled

Synopsis

Result

compile_datetime formatted string containing the datetime stamp

Discussion

If possible, the formatted string returned contains the datetime in a machine-processable format as defined in ISO 8601 chapter 5.4.

See Also

CCTK_CompileDate [A87] Returns a formatted string containing the date stamp when Cactus was compiled
CCTK_CompileTime [A89] Returns a formatted string containing the time stamp when Cactus was compiled

Returns a formatted string containing the time stamp when Cactus was compiled

Synopsis

Result

compile_time formatted string containing the time stamp

See Also

CCTK_CompileDate [A87] Returns a formatted string containing the date stamp when Cactus was compiled
CCTK_CompileDateTime [A88] Returns a formatted string containing the datetime stamp when Cactus was compiled

Return the name of the compiled implementation with given index.

Synopsis

Result

imp Name of the implementation

Parameters

index Implementation index, with 0 ≤ index < numimpls, where numimpls is returned by CCTK_NumCompiledImplementations.

See Also

CCTK_ActivatingThorn [A47] Finds the thorn which activated a particular implementation
CCTK_CompiledThorn [A92] Return the name of the compiled thorn with given index
CCTK_ImplementationRequires [A263] Return the ancestors for an implementation
CCTK_ImplementationThorn [A265] Returns the name of one thorn providing an implementation.
CCTK_ImpThornList [A267] Return the thorns for an implementation
CCTK_IsImplementationActive [A302] Reports whether an implementation was activated in a parameter file
CCTK_IsImplementationCompiled [A304] Reports whether an implementation was compiled into a configuration
CCTK_IsThornActive [A306] Reports whether a thorn was activated in a parameter file
CCTK_IsThornCompiled [A308] Reports whether a thorn was compiled into a configuration
CCTK_NumCompiledImplementations [A347] Return the number of implementations compiled in
CCTK_NumCompiledThorns [A349] Return the number of thorns compiled in
CCTK_ThornImplementation [A510] Returns the implementation provided by the thorn

Errors

NULL Error.

Return the name of the compiled thorn with given index.

Synopsis

Result

thorn Name of the thorn

Parameters

index Thorn index, with 0 ≤ index < numthorns, where numthorns is returned by CCTK_NumCompiledThorns.

See Also

CCTK_ActivatingThorn [A47] Finds the thorn which activated a particular implementation
CCTK_CompiledImplementation [A90] Return the name of the compiled implementation with given index
CCTK_ImplementationRequires [A263] Return the ancestors for an implementation
CCTK_ImplementationThorn [A265] Returns the name of one thorn providing an implementation.
CCTK_ImpThornList [A267] Return the thorns for an implementation
CCTK_IsImplementationActive [A302] Reports whether an implementation was activated in a parameter file
CCTK_IsImplementationCompiled [A304] Reports whether an implementation was compiled into a configuration
CCTK_IsThornActive [A306] Reports whether a thorn was activated in a parameter file
CCTK_IsThornCompiled [A308] Reports whether a thorn was compiled into a configuration
CCTK_NumCompiledImplementations [A347] Return the number of implementations compiled in
CCTK_NumCompiledThorns [A349] Return the number of thorns compiled in
CCTK_ThornImplementation [A510] Returns the implementation provided by the thorn

Errors

NULL Error.

Give the direction for a given coordinate.

All the CCTK_Coord* APIs are deprecated, and will probably be phased out fairly soon. New code should use the APIs provided by the CoordBase thorn instead (this lives in the CactusBase arrangement).

Synopsis

Parameters

dir The direction of the coordinate
coordname The name assigned to this coordinate
systemname The name of the coordinate system

Discussion

The coordinate name is independent of the grid function name.

Examples

Give the grid variable index for a given coordinate.

All the CCTK_Coord* APIs are deprecated, and will probably be phased out fairly soon. New code should use the APIs provided by the CoordBase thorn instead (this lives in the CactusBase arrangement).

Synopsis

Parameters

index The coordinates associated grid variable index
direction The direction of the coordinate in this coordinate system
coordname The name assigned to this coordinate
systemname The coordinate system for this coordinate

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.

Examples

Return the global upper and lower bounds for a given coordinate.

All the CCTK_Coord* APIs are deprecated, and will probably be phased out fairly soon. New code should use the APIs provided by the CoordBase thorn instead (this lives in the CactusBase arrangement).

Synopsis

Parameters

ierr Error code
cctkGH pointer to CCTK grid hierarchy
lower Global lower bound of the coordinate (POINTER in C)
upper Global upper bound of the coordinate (POINTER in C)
direction Direction of coordinate in coordinate system
coordname Coordinate name
systemname Coordinate system name

Discussion

The coordinate name is independent of the grid function name. The coordinate range is registered by 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.

Examples

Define a coordinate in a given coordinate system.

All the CCTK_Coord* APIs are deprecated, and will probably be phased out fairly soon. New code should use the APIs provided by the CoordBase thorn instead (this lives in the CactusBase arrangement).

Synopsis

Parameters

ierr Error code
direction Direction of coordinate in coordinate system
gvname Name of grid variable associated with coordinate
coordname Name of this coordinate
systemname Name of this coordinate system

Discussion

There must already be a coordinate system registered, using CCTK_CoordRegisterSystem.

Examples

Assign the global maximum and minimum values of a coordinate on a given grid hierachy.

All the CCTK_Coord* APIs are deprecated, and will probably be phased out fairly soon. New code should use the APIs provided by the CoordBase thorn instead (this lives in the CactusBase arrangement).

Synopsis

Parameters

ierr Error code
dimension Pointer to CCTK grid hierachy
min Global minimum of coordinate
max Global maximum of coordinate
direction Direction of coordinate in coordinate system
coordname Name of coordinate in coordinate system
systemname Name of this coordinate system

Discussion

There must already be a coordinate registered with the given name, with CCTK_CoordRegisterData. The coordinate range can be accessed by CCTK_CoordRange.

Examples

Assigns a coordinate system with a chosen name and dimension.

All the CCTK_Coord* APIs are deprecated, and will probably be phased out fairly soon. New code should use the APIs provided by the CoordBase thorn instead (this lives in the CactusBase arrangement).

Synopsis

Parameters

ierr Error code
dimension Dimension of coordinate system
systemname Unique name assigned to coordinate system

Examples

Give the dimension for a given coordinate system.

All the CCTK_Coord* APIs are deprecated, and will probably be phased out fairly soon. New code should use the APIs provided by the CoordBase thorn instead (this lives in the CactusBase arrangement).

Synopsis

Parameters

dim The dimension of the coordinate system
systemname The name of the coordinate system

Examples

Returns the handle associated with a registered coordinate system.

All the CCTK_Coord* APIs are deprecated, and will probably be phased out fairly soon. New code should use the APIs provided by the CoordBase thorn instead (this lives in the CactusBase arrangement).

Synopsis

Parameters

handle The coordinate system handle
systemname Name of the coordinate system

Examples

Errors

negative A negative return code indicates an invalid coordinate system name.

Returns the name of a registered coordinate system.

All the CCTK_Coord* APIs are deprecated, and will probably be phased out fairly soon. New code should use the APIs provided by the CoordBase thorn instead (this lives in the CactusBase arrangement).

Synopsis

Parameters

handle The coordinate system handle
systemname The coordinate system name

Discussion

No Fortran routine exists at the moment.

Examples

Errors

NULL A NULL pointer is returned if an invalid handle was given.

Create a directory with required permissions

Synopsis

Parameters

ierr Error code
mode Permission mode for new directory as an octal number
pathname Directory to create

Discussion

To create a directory readable by everyone, but writeable only by the user running the code, the permission mode would be 0755. Alternatively, a permission mode of 0777 gives everyone unlimited access; the user’s 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 mkdir(2) system call.

Examples

Errors

1 Directory already exists
0 Directory successfully created
-1 Memory allocation failed
-2 Failed to create directory
-3 Some component of pathname already exists but is not a directory

Given the full name of a variable/group, separates the name returning both the implementation and the variable/group

Synopsis

Parameters

istat Status flag returned by routine
fullname The full name of the group/variable
imp The implementation name
name The group/variable name

Discussion

The implementation name and the group/variable name must be explicitly freed after they have been used.

No Fortran routine exists at the moment.

Examples

Turn communications off for a group of grid variables

Synopsis

Parameters

cctkGH pointer to CCTK grid hierarchy

Discussion

Turning off communications means that ghost zones will not be communicated during a call to CCTK_SyncGroup. By default communications are all off.

Turn communications off for a group of grid variables.

Synopsis

Result

0 The Group has been disabled.

Parameters

cctkGH pointer to CCTK grid hierarchy
group number of group of grid variables to turn off

Discussion

Turning off communications means that ghost zones will not be communicated during a call to CCTK_SyncGroup. By default communications are all off.

See Also

CCTK_DisableGroupComm [A134] Turn communications off for a group of grid variables.
CCTK_EnableGroupCommI [A141] Turn communications on for a group of grid variables.
CCTK_EnableGroupComm [A139] Turn communications on for a group of grid variables.

Free the storage associated with a group of grid variables

Synopsis

Parameters

cctkGH pointer to CCTK grid hierarchy

Deallocates memory for a group based upon its index

Synopsis

Result

0 The group previously had storage
1 The group did not have storage to disable storage
-1 The decrease storage routine was not overloaded

Parameters

GH pointer to grid hierarchy
group index of the group to deallocate storage for

Discussion

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

Turn communications on for a group of grid variables

Synopsis

Parameters

cctkGH pointer to CCTK grid hierarchy

Discussion

Grid variables with communication enabled will have their ghost zones communicated during a call to 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 schedule.ccl file.

Turn communications on for a group of grid variables.

Synopsis

Result

0 The Group has been enabled.

Parameters

cctkGH pointer to CCTK grid hierarchy
group number of the group of grid variables to turn on

Discussion

Grid variables with communication enabled will have their ghost zones communicated during a call to 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 schedule.ccl file.

See Also

CCTK_DisableGroupComm [A134] Turn communications off for a group of grid variables.
CCTK_DisableGroupCommI [A135] Turn communications off for a group of grid variables.
CCTK_EnableGroupComm [A141] Turn communications on for a group of grid variables.

Assign the storage for a group of grid variables

Synopsis

Result

0 The Storage has been enabled.

Parameters

cctkGH pointer to CCTK grid hierarchy
group name of the group to allocate storage for

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 schedule.ccl file.

Assign the storage for a group of grid variables

Synopsis

Result

0 The Storage has been enabled.

Parameters

cctkGH pointer to CCTK grid hierarchy
group Index of the group to allocate storage for

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 schedule.ccl file.

Checks a STRING or KEYWORD parameter for equality with a given string

Synopsis

Result

1 if the parameter is (case-independently) equal to the specified value
0 if the parameter is (case-independently) not equal to the specified value

Parameters

parameter The string or keyword parameter to compare; Cactus represents this as a CCTK_POINTER pointing to the string value.
value The value against which to compare the string or keyword parameter. This is typically a string literal (see the examples below).

Discussion

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

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

See Also

Util_StrCmpi [B27] compare two C-style strings case-independently

Errors

null pointer If either argument is passed as a null pointer, CCTK_Equals() aborts the Cactus run with an error message. Otherwise, there are no error returns from this function.

Examples

Exit the code cleanly

Synopsis

Parameters

cctkGH pointer to CCTK grid hierarchy
value the return code to abort with

Discussion

This routine causes an immediate, regular termination of Cactus. It never returns to the caller.

Given a group name, returns the first variable index in the group.

Synopsis

Result

first_varindex (≥ 0) The first variable index in the group.

Parameters

group_name (≠ NULL in C) For C, this is a non-NULL pointer to the character-string name of the group. For Fortran, this is the character-string name of the group. In both cases this should be of the form "implementation::group".

Discussion

If the group contains N > 0 variables, and V is the value of first_varindex returned by this function, then the group’s variables have variable indices V , V + 1, V + 2, …, V + N - 1.

See Also

CCTK_FirstVarIndexI() Given a group index, returns the first variable index in the group.
CCTK_GroupData() Get “static” information about a group (including the number of variables in the group).
CCTK_GroupDynamicData() Get “dynamic” information about a group.

Errors

-1 Group name is invalid.
-2 Group has no members.

Given a group index, returns the first variable index in the group.

Synopsis

Result

first_varindex (≥ 0) The first variable index in the group.

Parameters

group_index (≥ 0) The group index, e.g. as returned by CCTK_GroupIndex().

Discussion

If the group contains N > 0 variables, and V is the value of first_varindex returned by this function, then the group’s variables have variable indices V , V + 1, V + 2, …, V + N - 1.

See Also

CCTK_FirstVarIndex() Given a group name, returns the first variable index in the group.
CCTK_GroupData() Get “static” information about a group (including the number of variables in the group).
CCTK_GroupDynamicData() Get “dynamic” information about a group.

Errors

-1 Group index is invalid.
-2 Group has no members.

Copy the contents of a C string into a Fortran string variable

Synopsis

Parameters

c_string This is (a pointer to) a standard C-style (NUL-terminated) string. Typically this argument is the name of a Cactus keyword or string paramameter.
fortran_string [This is an output argument] A Fortran character variable into which this function copies the C string (or as much of it as will fit).
fortran_length The length of the Fortran character variable.

Result

string_length This function sets this variable to the number of characters in the C string (not counting the terminating NUL character). If this is larger than the declared length of fortran_string then the string was truncated. If this is negative, then an error occurred.

Discussion

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

Examples

Given a variable index, returns the full name of the variable

Synopsis

Parameters

implementation The full variable name
index The variable index

Discussion

The full variable name must be explicitly freed after it has been used.

No Fortran routine exists at the moment. The full variable name is in the form <implementation>::<variable>

Examples

Given a pointer to the cTimerVal corresponding to a timer clock returns a pointer to a string that is the name of the clock

Synopsis

Parameters

const cTimerVal * val timer clock value pointer

Discussion

Do not attempt to free the returned pointer directly. You must use the string before calling CCTK_TimerDestroyData on the containing timer info.

Given a pointer to the cTimerVal corresponding to a timer clock returns the resolution of the clock in seconds.

Synopsis

Parameters

const cTimerVal * val timer clock value pointer

Discussion

Ideally, the resolution should represent a good lower bound on the smallest non-zero difference between two consecutive calls of CCTK_GetClockSeconds. In practice, it is sometimes far smaller than it should be. Often it just represents the smallest value representable due to how the information is stored internally.

Given a pointer to the cTimerVal corresponding to a timer clock returns a the elapsed time in seconds between the preceding CCTK_TimerStart and CCTK_TimerStop as recorded by the requested clock.

Synopsis

Parameters

const cTimerVal * val timer clock value pointer

Discussion

Be aware, different clocks measure different things (proper time, CPU time spent on this process, etc.), and have varying resolution and accuracy.

Given a name of a clock that is in the given cTimerData structure, returns a pointer to the cTimerVal structure holding the clock’s value.

Synopsis

Parameters

const char * name Name of clock

const cTimerData * info Timer information structure containing clock.

Discussion

Do not attempt to free the returned pointer directly.

Errors

A null return value indicates an error.

Given a index of a clock that is in the given cTimerData structure, returns a pointer to the cTimerVal structure holding the clock’s value.

Synopsis

Parameters

int index Index of clock

const cTimerData * info Timer information structure containing clock.

Discussion

Do not attempt to free the returned pointer directly.

Errors

A null return value indicates an error.

Get the pointer to a registered extension to the Cactus GH structure

Synopsis

Parameters

extension The pointer to the GH extension
cctkGH The pointer to the CCTK grid hierarchy
name The name of the GH extension

Discussion

No Fortran routine exists at the moment.

Examples

Errors

NULL A NULL pointer is returned if an invalid extension name was given.

Get the handle associated with a extension to the Cactus GH structure

Synopsis

Parameters

handle The GH extension handle
group The name of the GH extension

Examples

The name of the implementation of the registered grid array reduction operator, NULL if none is registered

Synopsis

Result

ga_reduc_imp Returns the name of the implementation of the registered grid array reduction operator or NULL if none is registered

Discussion

We only allow one grid array reduction operator currently. This function can be used to check if any grid array reduction operator has been registered.

See Also

CCTK_ReduceGridArrays() Performs reduction on a list of distributed grid arrays

CCTK_RegisterGridArrayReductionOperator() Registers a function as a grid array reduction operator of a certain name

CCTK_NumGridArrayReductionOperators() The number of grid array reduction operators registered

Given a group index or name, return an array of the bounding box of the group for each face

Synopsis

Result

0 success
-1 incorrect dimension supplied
-2 data not available from driver
-3 called on a scalar group
-4 invalid group index

Parameters

status Return value.
cctkGH (≠ NULL) Pointer to a valid Cactus grid hierarchy.
dim (≥ 1) Number of dimensions of group.
bbox (≠ NULL) Pointer to array which will hold the return values.
groupindex Group index.
groupname Group’s full name.

Discussion

The bounding box for a given group is returned in a user-supplied array buffer.

See Also

CCTK_GroupbboxVI, CCTK_GroupbboxVN Returns the lower bounds for a given variable.

Given a variable index or name, return an array of the bounding box of the variable for each face

Synopsis

Result

0 success
-1 incorrect dimension supplied
-2 data not available from driver
-3 called on a scalar group
-4 invalid variable index

Parameters

status Return value.
cctkGH (≠ NULL) Pointer to a valid Cactus grid hierarchy.
dim (≥ 1) Number of dimensions of variable.
bbox (≠ NULL) Pointer to array which will hold the return values.
varindex Group index.
varname Group’s full name.

Discussion

The bounding box for a given variable is returned in a user-supplied array buffer.

See Also

CCTK_GroupbboxGI, CCTK_GroupbboxGN Returns the upper bounds for a given group.

Given a group index, returns information about the group and its variables.

Synopsis

Result

0 success

Parameters

group_index The group index for which the information is desired.
group_data_buffer (≠ NULL) Pointer to a cGroup structure in which the information should be stored. See the ”Discussion” section below for more information about this structure.

Discussion

The cGroup structure¹ contains (at least) the following members:²

See Also

"interface.ccl" Defines variables, groups, tags tables, and lots of other things.
CCTK_GroupDynamicData [A192] Gets grid-size information for a group’s variables.
CCTK_GroupIndex [A203] Gets the group index for a given group name.
CCTK_GroupIndexFromVar [A207] Gets the group index for a given variable name.
CCTK_GroupName [A227] Gets the group name for a given group index.
CCTK_GroupNameFromVarI [A229] Gets the group name for a given variable name.
CCTK_GroupTypeI [A253] Gets a group type index for a given group index.
CCTK_GroupTypeFromVarI [A249] Gets a group type index for a given variable index.

Errors

-1 group_index is invalid.
-2 group_data_buffer is NULL.

Examples

Given a variable index, returns the dimension of all variables in the corresponding group.

Synopsis

Result

positive the dimension of the group
-1 invalid variable index

Parameters

varindex Variable index

Discussion

The dimension of all variables in a group associcated with the given variable is returned.

See Also

CCTK_GroupDimI Returns the dimension for a given group

Given a group index, returns the dimension of that group.

Synopsis

Result

positive the dimension of the group
-1 invalid group index

Parameters

groupindex Group index

Discussion

The dimension of variables in the given group is returned.

See Also

CCTK_GroupDimFromVarI Returns the dimension for a group given by a member variable index

Returns the driver’s internal data for a given group

Synopsis

Result

0 Sucess
-1 the given pointer to the data structure data is null
-3 the givenGH pointer is invalid
-77 the requested group has zero variables

Parameters

GH a valid initialized GH structure for your driver
group the index of the group you’re interested in
data a pointer to a caller-supplied data structure to store the group data

Discussion

This function returns information about the given grid hierarchy. The data structure used to store the information in is of type cGroupDynamicData. The members of this structure that are set are :

• dim: The number of dimensions in this grid hierarchy.
• lsh: The local(on this processor) size.
• gsh: The global grid size.
• lbnd: An array of integers containing the lowest index of the local grid as seen on the global grid.(These use zero based indexing)
• ubnd: An arry of integers containing the largest index of the local grid as seen on the global grid.(These use zero based indexing)
• nghostzones: An array of integers with the number of ghostzones for each dimension.
• bbox: An array of integers containing which indicate whether the boundaries are internal(e.g. artificial boundaries between processors) or actual physical boundaries. A value of 1 indicates an actual physical boundary while a 0 indicates an internal one.
• activetimelevels:An array of which time levels this grid hierarchy is active.

-

Given a group index, return a pointer to an array containing the ghost sizes of the group in each dimension.

Synopsis

Result

non-NULL a pointer to the ghost size array
NULL invalid group index

Parameters

groupindex Group index

Discussion

The ghost sizes in each dimension for a given group are returned as a pointer reference.

See Also

CCTK_GroupDimI Returns the dimension for a group.
CCTK_GroupSizesI Returns the size arrays for a group.

Given a group index or name, return an array of the global size of the group in each dimension

Synopsis

Result

0 success
-1 incorrect dimension supplied
-2 data not available from driver
-3 called on a scalar group
-4 invalid group name

Parameters

cctkGH (≠ NULL) Pointer to a valid Cactus grid hierarchy.
dim (≥ 1) Number of dimensions of group.
gsh (≠ NULL) Pointer to array which will hold the return values.
groupindex Index of the group.
groupname Name of the group.

Discussion

The global size in each dimension for a given group is returned in a user-supplied array buffer.

See Also

CCTK_GroupgshVI, CCTK_GroupgshVN Returns the global size for a given variable.
CCTK_GrouplshGI, CCTK_GrouplshGN Returns the local size for a given group.
CCTK_GrouplshVI, CCTK_GrouplshVN Returns the local size for a given variable.

Given a variable index or its full name, return an array of the global size of the variable in each dimension

Synopsis

Result

0 success
-1 incorrect dimension supplied
-2 data not available from driver
-3 called on a scalar group
-4 invalid variable index

Parameters

status Return value.
cctkGH (≠ NULL) Pointer to a valid Cactus grid hierarchy.
dim (≥ 1) Number of dimensions of variable.
gsh (≠ NULL) Pointer to array which will hold the return values.
varindex Variable index.
varname Variable’s full name.

Discussion

The global size in each dimension for a given variable is returned in a user-supplied array buffer.

See Also

CCTK_GroupgshGI, CCTK_GroupgshGN Returns the global size for a given group.
CCTK_GrouplshGI, CCTK_GrouplshGN Returns the local size for a given group.
CCTK_GrouplshVI, CCTK_GrouplshVN Returns the local size for a given variable.

Get the index number for a group name

Synopsis

Parameters

groupname The name of the group

Discussion

The group name should be the given in its fully qualified form, that is <implementation>::<group> for a public or protected group, and <thornname>::<group> for a private group.

Examples

Given a variable name, returns the index of the associated group

Synopsis

Parameters

groupindex The index of the group
name The full name of the variable

Discussion

The variable name should be in the form <implementation>::<variable>

Examples

Given a variable index, returns the index of the associated group

Synopsis

Parameters

groupindex The index of the group
varindex The index of the variable

Examples

Given a group index or name, return an array of the lower bounds of the group in each dimension

Synopsis

Result

0 success
-1 incorrect dimension supplied
-2 data not available from driver
-3 called on a scalar group
-4 invalid group index

Parameters

status Return value.
cctkGH (≠ NULL) Pointer to a valid Cactus grid hierarchy.
dim (≥ 1) Number of dimensions of group.
lbnd (≠ NULL) Pointer to array which will hold the return values.
groupindex Group index.
groupname Group’s full name.

Discussion

The lower bounds in each dimension for a given group is returned in a user-supplied array buffer.

See Also

CCTK_GrouplbndVI, CCTK_GrouplbndVN Returns the lower bounds for a given variable.
CCTK_GroupubndGI, CCTK_GroupubndGN Returns the upper bounds for a given group.
CCTK_GroupubndVI, CCTK_GroupubndVN Returns the upper bounds for a given variable.

Given a variable index or name, return an array of the lower bounds of the variable in each dimension

Synopsis

Result

0 success
-1 incorrect dimension supplied
-2 data not available from driver
-3 called on a scalar group
-4 invalid variable index

Parameters

status Return value.
cctkGH (≠ NULL) Pointer to a valid Cactus grid hierarchy.
dim (≥ 1) Number of dimensions of variable.
lbnd (≠ NULL) Pointer to array which will hold the return values.
varindex Group index.
varname Group’s full name.

Discussion

The lower bounds in each dimension for a given variable is returned in a user-supplied array buffer.

See Also

CCTK_GrouplbndGI, CCTK_GrouplbndGN Returns the lower bounds for a given group.
CCTK_GroupubndGI, CCTK_GroupubndGN Returns the upper bounds for a given group.
CCTK_GroupubndVI, CCTK_GroupubndVN Returns the upper bounds for a given variable.

Given a group index or name, return an array of the local size of the group in each dimension

Synopsis

Result

0 success
-1 incorrect dimension supplied
-2 data not available from driver
-3 called on a scalar group
-4 invalid group name

Parameters

cctkGH (≠ NULL) Pointer to a valid Cactus grid hierarchy.
dim (≥ 1) Number of dimensions of group.
lsh (≠ NULL) Pointer to array which will hold the return values.
groupindex Index of the group.
groupname Name of the group.

Discussion

The local size in each dimension for a given group is returned in a user-supplied array buffer.

See Also

CCTK_GroupgshVI, CCTK_GroupgshVN Returns the global size for a given variable.
CCTK_GrouplshGI, CCTK_GrouplshGN Returns the local size for a given group.
CCTK_GrouplshVI, CCTK_GrouplshVN Returns the local size for a given variable.

Given a variable index or its full name, return an array of the local size of the variable in each dimension

Synopsis

Result

0 success
-1 incorrect dimension supplied
-2 data not available from driver
-3 called on a scalar group
-4 invalid variable index

Parameters

status Return value.
cctkGH (≠ NULL) Pointer to a valid Cactus grid hierarchy.
dim (≥ 1) Number of dimensions of variable.
lsh (≠ NULL) Pointer to array which will hold the return values.
varindex Variable index.
varname Variable’s full name.

Discussion

The local size in each dimension for a given variable is returned in a user-supplied array buffer.

See Also

CCTK_GroupgshGI, CCTK_GroupgshGN Returns the global size for a given group.
CCTK_GroupgshVI, CCTK_GroupgshVN Returns the global size for a given variable.
CCTK_GrouplshGI, CCTK_GrouplshGN Returns the local size for a given group.

Given a group index, returns the group name

Synopsis

Parameters

name The group name
index The group index

Discussion

The group name must be explicitly freed after it has been used.

No Fortran routine exists at the moment.

Examples

Given a variable index, return the name of the associated group

Synopsis

Parameters

group The name of the group
varindex The index of the variable

Examples

Given a group index or name, return an array with the number of ghostzones in each dimension of the group

Synopsis

Result

0 success
-1 incorrect dimension supplied
-2 data not available from driver
-3 called on a scalar group

Parameters

status Return value.
cctkGH (≠ NULL) Pointer to a valid Cactus grid hierarchy.
dim (≥ 1) Number of dimensions of group.
nghostzones (≠ NULL) Pointer to array which will hold the return values.
groupindex Group index.
groupname Group name.

Discussion

The number of ghostzones in each dimension for a given group is returned in a user-supplied array buffer.

See Also

CCTK_GroupnghostzonesVI, CCTK_GroupnghostzonesVN Returns the number of ghostzones for a given variable.

Given a variable index or its full name, return an array with the number of ghostzones in each dimension of the variable

Synopsis

Result

0 success
-1 incorrect dimension supplied
-2 data not available from driver
-3 called on a scalar group

Parameters

status Return value.
cctkGH (≠ NULL) Pointer to a valid Cactus grid hierarchy.
dim (≥ 1) Number of dimensions of group.
nghostzones (≠ NULL) Pointer to array which will hold the return values.
varindex Variable index.
varname Variable’s full name.

Discussion

The number of ghostzones in each dimension for a given variable is returned in a user-supplied array buffer.

See Also

CCTK_GroupnghostzonesGI, CCTK_GroupnghostzonesGN Returns the number of ghostzones for a given group.

Given a group index, return a pointer to an array containing the sizes of the group in each dimension.

Synopsis

Result

non-NULL a pointer to the size array
NULL invalid group index

Parameters

groupindex Group index

Discussion

The sizes in each dimension for a given group are returned as a pointer reference.

See Also

CCTK_GroupDimI Returns the dimension for a group.
CCTK_GroupGhostsizesI Returns the size arrays for a group.

Decrease the number of timelevels allocated for the given variable groups.

Synopsis

Result

The new total number of timelevels with storage enabled for all groups queried or modified.

Parameters

GH pointer to grid hierarchy
n_groups Number of groups
groups list of group indices to reduce storage for
timelevels number of time levels to reduce storage for for each group
groups list of group indices to allocate storage for
status optional return array which, if not NULL, will, on return, contain the number of timelevels which were previously allocated storage for each group

Discussion

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

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

A driver should replace the appropriate GV pointers on the cGH structure when it changes the storage state of a GV.

Increases the number of timelevels allocated for the given variable groups.

Synopsis

Result

The new total number of timelevels with storage enabled for all groups queried or modified.

Parameters

GH pointer to grid hierarchy
n_groups Number of groups
groups list of group indices to allocate storage for
timelevels number of time levels to allocate storage for for each group
groups list of group indices to allocate storage for
status optional return array which, if not NULL, will, on return, contain the number of timelevels which were previously allocated storage for each group

Discussion

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

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

A driver should replace the appropriate GV pointers on the cGH structure when it changes the storage state of a GV.

Given a group name, return the table handle of the group’s tags table.

Synopsis

Result

table_handle The table handle of the group’s tags table.

Parameters

group_name The character-string name of group. This should be given in its fully qualified form, that is implementation::group_name or thorn_name::group_name.

See Also

CCTK_GroupData [A183] This function returns a variety of “static” information about a group (“static” in the sense that it doesn’t change during a Cactus run).
CCTK_GroupDynamicData [A192] This function returns a variety of “dynamic” information about a group (“dynamic” in the sense that a driver can (and often does) change this information during a Cactus run).

Errors

-1 no group exists with the specified name

Given a group name, return the table handle of the group’s tags table.

Synopsis

Result

table_handle The table handle of the group’s tags table.

Parameters

group_index The group index of the group.

See Also

CCTK_GroupData [A183] This function returns a variety of “static” information about a group (“static” in the sense that it doesn’t change during a Cactus run).
CCTK_GroupDynamicData [A192] This function returns a variety of “dynamic” information about a group (“dynamic” in the sense that a driver can (and often does) change this information during a Cactus run).
CCTK_GroupIndex [A203] Get the group index for a specified group name.
CCTK_GroupIndexFromVar [A207] Get the group index for the group containing the variable with a specified name.
CCTK_GroupIndexFromVarI [A211] Get the group index for the group containing the variable with a specified variable index.

Errors

-1 no group exists with the specified name

Provides a group’s group type index given a variable index

Synopsis

Parameters

type The group’s group type index
group The variable index

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 CCTK_SCALAR, CCTK_GF, CCTK_ARRAY.

Examples

Provides a group’s group type index given a group index

Synopsis

Result

-1 -1 is returned if the given group index is invalid.

Parameters

group Group index.

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 CCTK_SCALAR, CCTK_GF, CCTK_ARRAY.

See Also

CCTK_GroupTypeFromVarI [A249] This function takes a variable index rather than a group index as its argument.

Given a group index or name, return an array of the upper bounds of the group in each dimension

Synopsis

Result

0 success
-1 incorrect dimension supplied
-2 data not available from driver
-3 called on a scalar group
-4 invalid group index

Parameters

status Return value.
cctkGH (≠ NULL) Pointer to a valid Cactus grid hierarchy.
dim (≥ 1) Number of dimensions of group.
ubnd (≠ NULL) Pointer to array which will hold the return values.
groupindex Group index.
groupname Group’s full name.

Discussion

The upper bounds in each dimension for a given group is returned in a user-supplied array buffer.

See Also

CCTK_GrouplbndGI, CCTK_GrouplbndGN Returns the lower bounds for a given group.
CCTK_GrouplbndVI, CCTK_GrouplbndVN Returns the lower bounds for a given variable.
CCTK_GroupubndVI, CCTK_GroupubndVN Returns the upper bounds for a given variable.

Given a variable index or name, return an array of the upper bounds of the variable in each dimension

Synopsis

Result

0 success
-1 incorrect dimension supplied
-2 data not available from driver
-3 called on a scalar group
-4 invalid variable index

Parameters

status Return value.
cctkGH (≠ NULL) Pointer to a valid Cactus grid hierarchy.
dim (≥ 1) Number of dimensions of variable.
ubnd (≠ NULL) Pointer to array which will hold the return values.
varindex Group index.
varname Group’s full name.

Discussion

The upper bounds in each dimension for a given variable is returned in a user-supplied array buffer.

See Also

CCTK_GrouplbndGI, CCTK_GrouplbndGN Returns the lower bounds for a given group.
CCTK_GrouplbndVI, CCTK_GrouplbndVN Returns the lower bounds for a given variable.
CCTK_GroupubndGI, CCTK_GroupubndGN Returns the upper bounds for a given group.

Given a variable index, returns the implementation name

Synopsis

Parameters

implementation The implementation name
index The variable index

Discussion

No Fortran routine exists at the moment

Examples

Return the ancestors for an implementation.

Synopsis

Result

imps (not documented)

Parameters

imp (not documented)

See Also

CCTK_ActivatingThorn [A47] Finds the thorn which activated a particular implementation
CCTK_CompiledImplementation [A90] Return the name of the compiled implementation with given index
CCTK_CompiledThorn [A92] Return the name of the compiled thorn with given index
CCTK_ImplementationThorn [A265] Returns the name of one thorn providing an implementation.
CCTK_ImpThornList [A267] Return the thorns for an implementation
CCTK_IsImplementationActive [A302] Reports whether an implementation was activated in a parameter file
CCTK_IsImplementationCompiled [A304] Reports whether an implementation was compiled into a configuration
CCTK_IsThornActive [A306] Reports whether a thorn was activated in a parameter file
CCTK_IsThornCompiled [A308] Reports whether a thorn was compiled into a configuration
CCTK_NumCompiledImplementations [A347] Return the number of implementations compiled in
CCTK_NumCompiledThorns [A349] Return the number of thorns compiled in
CCTK_ThornImplementation [A510] Returns the implementation provided by the thorn

Errors

(not documented)

Returns the name of one thorn providing an implementation.

Synopsis

Result

thorn Name of the thorn or NULL

Parameters

name Name of the implementation

See Also

CCTK_ActivatingThorn [A47] Finds the thorn which activated a particular implementation
CCTK_CompiledImplementation [A90] Return the name of the compiled implementation with given index
CCTK_CompiledThorn [A92] Return the name of the compiled thorn with given index
CCTK_ImplementationRequires [A263] Return the ancestors for an implementation
CCTK_ImpThornList [A267] Return the thorns for an implementation
CCTK_IsImplementationActive [A302] Reports whether an implementation was activated in a parameter file
CCTK_IsImplementationCompiled [A304] Reports whether an implementation was compiled into a configuration
CCTK_IsThornActive [A306] Reports whether a thorn was activated in a parameter file
CCTK_IsThornCompiled [A308] Reports whether a thorn was compiled into a configuration
CCTK_NumCompiledImplementations [A347] Return the number of implementations compiled in
CCTK_NumCompiledThorns [A349] Return the number of thorns compiled in
CCTK_ThornImplementation [A510] Returns the implementation provided by the thorn

Errors

NULL Error.

Return the thorns for an implementation.

Synopsis

Result

thorns (not documented)

Parameters

name Name of implementation

Discussion

(not documented)

See Also

CCTK_ActivatingThorn [A47] Finds the thorn which activated a particular implementation
CCTK_CompiledImplementation [A90] Return the name of the compiled implementation with given index
CCTK_CompiledThorn [A92] Return the name of the compiled thorn with given index
CCTK_ImplementationRequires [A263] Return the ancestors for an implementation
CCTK_ImplementationThorn [A265] Returns the name of one thorn providing an implementation.
CCTK_IsImplementationActive [A302] Reports whether an implementation was activated in a parameter file
CCTK_IsImplementationCompiled [A304] Reports whether an implementation was compiled into a configuration
CCTK_IsThornActive [A306] Reports whether a thorn was activated in a parameter file
CCTK_IsThornCompiled [A308] Reports whether a thorn was compiled into a configuration
CCTK_NumCompiledImplementations [A347] Return the number of implementations compiled in
CCTK_NumCompiledThorns [A349] Return the number of thorns compiled in
CCTK_ThornImplementation [A510] Returns the implementation provided by the thorn

Errors

(not documented)

Macro to print a single string as an information message to screen

Synopsis

Parameters

message The string to print as an info message

Discussion

This macro can be used by thorns to print a single string as an info message to screen.

The macro CCTK_INFO(message) expands to a call to the underlying function CCTK_Info:

So the macro automatically includes the name of the originating thorn in the info message. It is recommended that the macro CCTK_INFO is used to print a message rather than calling CCTK_Info directly.

To include variables in an info message from C, you can use the routine CCTK_VInfo which accepts a variable argument list. To include variables from Fortran, a string must be constructed and passed in a CCTK_INFO macro.

See Also

CCTK_VInfo() prints a formatted string with a variable argument list as an info message to screen

Examples

Register one or more routines for dealing with information messages in addition to printing them to screen

Synopsis

Parameters

data The void pointer holding extra information about the registered call back routine

callback The function pointer pointing to the call back function dealing with information messages. The definition of the function pointer is:

The argument list is the same as those in CCTK_Info() (see the discussion of CCTK_INFO() page A269) except an extra void pointer to hold the information about the call back routine.

Discussion

This function can be used by thorns to register their own routines to deal with information messages. The registered function pointers will be stored in a pointer chain. When CCTK_VInfo() is called, the registered routines will be called in the same order as they get registered in addition to dumping warning messages to stderr.

The function can only be called in C.

See Also

CCTK_VInfo() prints a formatted string with a variable argument list as an info message to screen

CCTK_WarnCallbackRegister Register one or more routines for dealing with warning messages in addition to printing them to standard error

Examples

Interpolate a list of distributed grid variables

The computation is optimized for the case of interpolating a number of grid variables at a time; in this case all the interprocessor communication can be done together, and the same interpolation coefficients can be used for all the variables. A grid variable can be either a grid function or a grid array.

Synopsis

Result

0 success
< 0 indicates an error condition (see Errors)

Parameters

cctkGH (≠ NULL) Pointer to a valid Cactus grid hierarchy.
N_dims (≥ 1) Number of dimensions in which to interpolate. This must be ≤ the dimensionality of the coordinate system defined by coord_system_handle. The default case is that it’s =; see the discussion of the interpolation_hyperslab_handle parameter-table entry for the < case.
local_interp_handle (≥ 0) Handle to the local interpolation operator as returned by CCTK_InterpHandle.
param_table_handle (≥ 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).
coord_system_handle (≥ 0) Cactus coordinate system handle defining the mapping between (usually floating-point) coordinates and integer grid subscripts, as returned by CCTK_CoordSystemHandle.
N_interp_points (≥ 0) The number of interpolation points requested by this processor.
interp_coords_type_code One of the CCTK_VARIABLE_* type codes, giving the data type of the interpolation-point coordinate arrays pointed to by interp_coords[]. All interpolation-point coordinate arrays must be of the same data type. (In practice, this data type will almost always be CCTK_REAL or one of the CCTK_REAL* types.)
interp_coords (≠ NULL) (Pointer to) an array of 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 coord_system_handle.
N_input_arrays (≥ 0) The number of input variables to be interpolated. If 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 operand_indices is used to specify a nontrivial (e.g. one-to-many) mapping of input variables to output arrays, only the unique set of input variables should be given here.
input_array_variable_indices (≠ NULL) (Pointer to) an array of N_input_arrays CCTK grid variable indices (as returned by CCTK_VarIndex) specifying the input grid variables for the interpolation. For any element with an index value of -1 in the grid variable indices array, that interpolation is skipped. This may be useful if the main purpose of the call is e.g. to do some query or setup computation.
N_output_arrays (≥ 0) The number of output arrays to be returned from the interpolation. If N_output_arrays is zero then no interpolation is done; such a call may be useful for setup, interpolator querying, etc. Note that N_output_arrays may differ from N_input_arrays, e.g. if the operand_indices parameter-table entry is used to specify a nontrivial (e.g. many-to-one) mapping of input variables to output arrays. If such a mapping is specified, only the unique set of output arrays should be given in the output_arrays argument.
output_array_type_codes (≠ NULL) (Pointer to) an array of N_output_arrays CCTK_VARIABLE_* type codes giving the data types of the 1-D output arrays pointed to by output_arrays[].
output_arrays (≠ NULL) (Pointer to) an array of N_output_arrays pointers to the (user-supplied) 1-D output arrays for the interpolation. If any of the pointers in the 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.

Discussion

This function interpolates a list of CCTK grid variables (in a multiprocessor run these are generally distributed over processors) on a list of interpolation points. The grid topology and coordinates are implicitly specified via a Cactus coordinate system. The interpolation points may be anywhere in the global Cactus grid. In a multiprocessor run they may vary from processor to processor; each processor will get whatever interpolated data it asks for. The routine CCTK_InterpGridArrays does not do the actual interpolation itself but rather takes care of whatever interprocessor communication may be necessary, and – for each processor’s local patch of the domain-decomposed grid variables – calls CCTK_InterpLocalUniform to invoke an external local interpolation operator (as identified by an interpolation handle).

Additional parameters for the interpolation operation of both CCTK_InterpGridArrays and 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 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 order, a 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

Also, the global interpolator will typically need to specify some options of its own for the local interpolator.³ These will overwrite any entries with the same keys in the 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 CCTK_InterpGridArrays is a collective operation, so in the multiprocessor case you must call this function in parallel on each processor, passing identical arguments except for the number of interpolation points, the interpolation coordinates, and the output array pointers. You may (and typically will) specify a different set of interpolation points on each processor’s call – you may even specify an empty set on some processors. The interpolation points may be “owned” by any processors (this function takes care of all interprocessor-communication issues), though it may be more efficient to have most or all of the interpolation points “owned” by the current processor.

In the multiprocessor case, the result returned by CCTK_InterpGridArrays is guaranteed to be the same on all processors. (All current implementations simply take the minimum of the per-processor results over all processors; this gives a result which is 0 if all processors succeeded, or which is the most negative error code encountered by any processor otherwise.)

The semantics of 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, CCTK_InterpGridArrays is made an overloadable function. The Cactus flesh will supply only a dummy routine for it which – if called – does nothing but print a warning message saying that it wasn’t overloaded by another thorn, and stop the code. So one will always need to compile in and activate a driver-specific thorn which provides an interpolation routine for CCTK grid variables and properly overloads 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. PUGHInterp in the CactusPUGH arrangement, CarpetInterp in the Carpet arrangement, LocalInterp in the CactusBase arrangement, and/or AEILocalInterp in the AEIThorns arrangement) for details.

Note that in a multiprocessor Cactus run, it’s the user’s responsibility to choose the interprocessor ghost-zone size (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 CCTK_ERROR_INTERP_GHOST_SIZE_TOO_SMALL error code.

See Also

CCTK_InterpHandle() Get the interpolator handle for a given character-string name.
CCTK_InterpLocalUniform() Interpolate a list of processor-local arrays which define a uniformly-spaced data grid

Errors

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 cctk_Interp.h, util_ErrorCodes.h, and/or util_Table.h in the src/include/ directory in the Cactus flesh.
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)
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)
CCTK_ERROR_INTERP_GHOST_SIZE_TOO_SMALL for a multi-processor run, the size of the interprocessor boundaries (the 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.
UTIL_ERROR_BAD_INPUT one or more of the input arguments is invalid (e.g. NULL pointer)
UTIL_ERROR_NO_MEMORY unable to allocate memory
UTIL_ERROR_BAD_HANDLE parameter table handle is invalid
other error codes this function may also return any error codes returned by the Util_Table* routines used to get parameters from (and/or set results in) the parameter table

Examples

Here’s a simple example to do quartic 3-D interpolation of a real and a complex grid array, at 1000 interpolation points:

Return the handle for a given interpolation operator

Synopsis

Parameters

handle Handle for the interpolation operator
operator Name of interpolation operator

Examples

Errors

negative A negative value is returned for invalid/unregistered interpolation operator names.

Interpolate a list of processor-local arrays which define a uniformly-spaced data grid

The computation is optimized for the case of interpolating a number of arrays at a time; in this case the same interpolation coefficients can be used for all the arrays.

Synopsis

Result

0 success

Parameters

N_dims (≥ 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 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.
operator_handle (≥ 0) Handle to the interpolation operator as returned by CCTK_InterpHandle.
param_table_handle (≥ 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 order, a 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.
coord_origin (≠ NULL) (Pointer to) an array giving the coordinates of the data point with integer array subscripts 0, 0, …, 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 coord_origin[] is actually used.
coord_delta (≠ NULL) (Pointer to) an array giving the coordinate spacing of the data arrays. See the “Discussion” section below for more on how coord_delta[] is actually used.
N_interp_points (≥ 0) The number of points at which interpolation is to be done.
interp_coords_type_code One of the CCTK_VARIABLE_* type codes, giving the data type of the 1-D interpolation-point-coordinate arrays pointed to by interp_coords[]. (In practice, this data type will almost always be CCTK_REAL or one of the CCTK_REAL* types.)
interp_coords (≠ NULL) (Pointer to) an array of 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 coord_origin[] and coord_delta[].
N_input_arrays (≥ 0) The number of input arrays to be interpolated. Note that if the parameter table entry 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.
input_array_dims (≠ NULL) (Pointer to) an array of N_dims integers giving the dimensions of the N_dims-D input arrays. By default all the input arrays are taken to have these dimensions, with [0] the most contiguous axis and [N_dims-1] the least contiguous axis, and array subscripts in the range 0 <= subscript < input_array_dims[axis]. See the discussion of the input_array_strides optional parameter (passed in the parameter table) for details of how this can be overridden.
input_array_type_codes (≠ NULL) (Pointer to) an array of N_input_arrays CCTK_VARIABLE_* type codes giving the data types of the N_dims-D input arrays pointed to by input_arrays[].
input_arrays (≠ NULL) (Pointer to) an array of N_input_arrays pointers to the N_dims-D input arrays for the interpolation. If any input_arrays[in] pointer is NULL, that interpolation is skipped.
N_output_arrays (≥ 0) The number of output arrays to be returned from the interpolation.
output_array_type_codes (≠ NULL) (Pointer to) an array of N_output_arrays CCTK_VARIABLE_* type codes giving the data types of the 1-D output arrays pointed to by output_arrays[].
output_arrays (≠ NULL) (Pointer to) an array of N_output_arrays pointers to the (user-supplied) 1-D output arrays for the interpolation. If any output_arrays[out] pointer is NULL, that interpolation is skipped.

Discussion

CCTK_InterpLocalUniform is a generic API for interpolating processor-local arrays when the data points’ xyz coordinates are linear functions of the integer array subscripts ijk (we’re describing this for 3-D, but the generalization to other numbers of dimensions should be obvious). The coord_origin[] and coord_delta[] arguments specify these linear functions:

The (x,y,z) coordinates are used for the interpolation (i.e. the interpolator may internally use polynomials in these coordinates); 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.

See Also

CCTK_InterpHandle() Get the interpolator handle for a given character-string name.
CCTK_InterpGridArrays() Interpolate a list of Cactus grid arrays
CCTK_InterpRegisterOpLocalUniform() Register a CCTK_InterpLocalUniform interpolation operator
CCTK_InterpLocalNonUniform() Interpolate a list of processor-local arrays, with non-uniformly spaced data points.

Errors

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 cctk_Interp.h, util_ErrorCodes.h, and/or util_Table.h in the src/include/ directory in the Cactus flesh.
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)
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)
UTIL_ERROR_BAD_INPUT one or more of the inputs is invalid (e.g. NULL pointer)
UTIL_ERROR_NO_MEMORY unable to allocate memory
UTIL_ERROR_BAD_HANDLE parameter table handle is invalid
other error codes this function may also return any error codes returned by the Util_Table* routines used to get parameters from (and/or set results in) the parameter table

Examples

Here’s a simple example of interpolating a CCTK_REAL and a CCTK_COMPLEX 10 × 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 interp_coords[], input_arrays[], and output_arrays[] arrays as non-const, and set their values with ordinary (run-time) assignment statements. In C++, there’s no restriction on initializer values, so we could declare the arrays const and initialize them as part of their declarations.

Register a CCTK_InterpLocalUniform interpolation operator.

Synopsis

Result

handle (≥ 0) A cactus handle to refer to all interpolation operators registered under this operator name.

Parameters

operator_ptr (≠ NULL) Pointer to the CCTK_InterpLocalUniform interpolation operator. This argument must be a C function pointer of the appropriate type; the typedef can be found in src/include/cctk_Interp.h in the Cactus source code.
operator_name (≠ NULL) (Pointer to) a (C-style null-terminated) character string giving the name under which to register the operator.
thorn_name (≠ NULL) (Pointer to) a (C-style null-terminated) character string giving the name of the thorn which provides the interpolation operator.

Discussion

Only C functions (or other routines with C-compatible calling sequences) can be registered as interpolation operators.

See Also

CCTK_InterpHandle() Get the interpolator handle for a given character-string name.
CCTK_InterpLocalUniform() Interpolate a list of processor-local arrays, with uniformly spaced data points.

Errors

-1 NULL pointer was passed as interpolation operator routine
-2 interpolation handle could not be allocated
-3 Interpolation operator with this name already exists

Examples

Reports whether an aliased function has been provided

Synopsis

Parameters

istat the return status
functionname the name of the function to check

Discussion

This function returns a non-zero value if the function given by functionname is provided by any active thorn, and zero otherwise.

Reports whether an implementation was activated in a parameter file

Synopsis

Parameters

istat the return status
implementationname the name of the implementation to check

Discussion

This function returns a non-zero value if the implementation given by implementationname was activated in a parameter file, and zero otherwise. See also CCTK_ActivatingThorn [A47], CCTK_CompiledImplementation [A90], CCTK_CompiledThorn [A92], CCTK_ImplementationRequires [A263], CCTK_ImplementationThorn [A265], CCTK_ImpThornList [A267], CCTK_IsImplementationCompiled [A304], CCTK_IsThornActive [A306], CCTK_NumCompiledImplementations [A347], CCTK_NumCompiledThorns [A349], CCTK_ThornImplementation [A510].

Reports whether an implementation was compiled into the configuration

Synopsis

Parameters

istat the return status
implementationname the name of the implementation to check

Discussion

This function returns a non-zero value if the implementation given by implementationname was compiled into the configuration, and zero otherwise. See also CCTK_ActivatingThorn [A47], CCTK_CompiledImplementation [A90], CCTK_CompiledThorn [A92], CCTK_ImplementationRequires [A263], CCTK_ImplementationThorn [A265], CCTK_ImpThornList [A267], CCTK_IsImplementationActive [A302], CCTK_IsThornActive [A306], CCTK_IsThornCompiled [A308], CCTK_NumCompiledImplementations [A347], CCTK_NumCompiledThorns [A349], CCTK_ThornImplementation [A510].

Reports whether a thorn was activated in a parameter file

Synopsis

Result

status This function returns a non-zero value if thorn thorn_name was activated in a parameter file, and zero otherwise.

Parameters

thorn_name The character-string name of the thorn, for example ”SymBase”.

Discussion

This function lets you find out at run-time whether or not a given thorn is active in the current Cactus run.

Reports whether a thorn was activated in a parameter file

Synopsis

Parameters

istat the return status
thorname the name of the thorn to check

Discussion

This function returns a non-zero value if the implementation given by thornname was compiled into the configuration, and zero otherwise.

Returns the name of a registered reduction operator

Synopsis

Result

name Returns the name of a registered local reduction operator of handle
handle or NULL if the handle is invalid

Parameters

handle The handle of a registered local reduction operator

Discussion

This function returns the name of a registered reduction operator given its handle. NULL is returned if the handle is invalid

See Also

CCTK_ReduceLocalArrays() Reduces a list of local arrays (new local array reduction API)

CCTK_LocalArrayReductionHandle() Returns the handle of a given local array reduction operator

CCTK_RegisterLocalArrayReductionOperator() Registers a function as a reduction operator of a certain name

CCTK_LocalArrayReduceOperatorImplementation() Provide the implementation which provides an local array reduction operator

CCTK_NumLocalArrayReduceOperators() The number of local reduction operators registered

Provide the implementation which provides an local array reduction operator

Synopsis

Result

implementation The name of the implementation implementing the local reduction operator of handle
handle

Parameters

handle The handle of a registered local reduction operator

Discussion

This function returns the implementation name of a registered reduction operator given its handle or NULL if the handle is invalid

See Also

CCTK_ReduceLocalArrays() Reduces a list of local arrays (new local array reduction API)

CCTK_LocalArrayReductionHandle() Returns the handle of a given local array reduction operator

CCTK_RegisterLocalArrayReductionOperator() Registers a function as a reduction operator of a certain name
CCTK_LocalArrayReduceOperator() Returns the name of a registered reduction operator

CCTK_NumLocalArrayReduceOperators() The number of local reduction operators registered

Returns the handle of a given local array reduction operator

Synopsis

Result

handle The handle corresponding to the local reduction operator

Parameters

operator The reduction operation to be performed. If no matching registered operator is found, a warning is issued and an error returned.

Discussion

This function returns the handle of the local array reduction operator. The local reduction handle is also used in the grid array reduction.

See Also

CCTK_ReduceLocalArrays() Reduces a list of local arrays (new local array reduction API)

CCTK_RegisterLocalArrayReductionOperator() Registers a function as a reduction operator of a certain name

CCTK_LocalArrayReduceOperatorImplementation() Provide the implementation which provides an local array reduction operator

CCTK_LocalArrayReduceOperator() Returns the name of a registered reduction operator

CCTK_NumLocalArrayReduceOperators() The number of local reduction operators registered

Get the maximum dimension of any grid variable

Synopsis

Parameters

dim The maximum dimension

Discussion

Note that the maximum dimension will depend only on the active thorn list, and not the compiled thorn list.

Examples

Get the maximum dimension of all grid functions

Synopsis

Parameters

dim The maximum dimension of all grid functions

Discussion

Note that the maximum dimension will depend only on the active thorn list, and not the compiled thorn list.

Examples

Gives the number of timelevels for a group

Synopsis

Parameters

name The full group name
numlevels The number of timelevels

Discussion

The group name should be in the form <implementation>::<group>

Examples

Gives the number of timelevels for a group

Synopsis

Parameters

numlevels The number of timelevels
index The group index

Examples

Gives the number of timelevels for a group

Synopsis

Result

The maximum number of timelevels this group has, or -1 if the group name is incorrect.

Parameters

group The variable group’s name

Discussion

This function and its relatives return the maximum number of timelevels that the given variable group can have active. This function does not tell you anything about how many time levels are active at the time.

Gives the number of timelevels for a variable

Synopsis

Parameters

numlevels The number of timelevels
index The variable index

Examples

Gives the number of timelevels for a variable

Synopsis

Parameters

name The full variable name
numlevels The number of timelevels

Discussion

The variable name should be in the form <implementation>::<variable>

Examples

Returns the number of the local processor for a parallel run

Synopsis

Parameters

cctkGH pointer to CCTK grid hierarchy

Discussion

For a single processor run this call will return zero. For multiprocessor runs, this call will return 0 ≤ myproc < CCTK_nProcs(cctkGH).

Calling CCTK_MyProc(NULL) is safe (it will not crash). Current drivers (PUGH, Carpet) handle this case correctly (i.e. CCTK_MyProc(NULL) returns a correct result), but only a “best effort” is guaranteed for future drivers (or future revisions of current drivers).

Returns the number of processors being used for a parallel run

Synopsis

Parameters

cctkGH pointer to CCTK grid hierarchy

Discussion

For a single processor run this call will return one.

Calling CCTK_nProcs(NULL) is safe (it will not crash). Current drivers (PUGH, Carpet) handle this case correctly (i.e. CCTK_nProcs(NULL) returns a correct result), but only a “best effort” is guaranteed for future drivers (or future revisions of current drivers).

Returns a C-style NULL pointer value.

Synopsis

Result

pointer_var a CCTK_POINTER type variable which is initialized with a C-style NULL pointer

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 CCTK_NullPointer.

Note that there is only a Fortran wrapper available for CCTK_NullPointer.

See Also

CCTK_PointerTo() Returns the address of a variable passed in by reference from a Fortran routine.

Examples

Return the number of implementations compiled in.

Synopsis

Result

numimpls Number of implementations compiled in.

See Also

CCTK_ActivatingThorn [A47] Finds the thorn which activated a particular implementation
CCTK_CompiledImplementation [A90] Return the name of the compiled implementation with given index
CCTK_CompiledThorn [A92] Return the name of the compiled thorn with given index
CCTK_ImplementationRequires [A263] Return the ancestors for an implementation
CCTK_ImplementationThorn [A265] Returns the name of one thorn providing an implementation.
CCTK_ImpThornList [A267] Return the thorns for an implementation
CCTK_IsImplementationActive [A302] Reports whether an implementation was activated in a parameter file
CCTK_IsImplementationCompiled [A304] Reports whether an implementation was compiled into a configuration
CCTK_IsThornActive [A306] Reports whether a thorn was activated in a parameter file
CCTK_IsThornCompiled [A308] Reports whether a thorn was compiled into a configuration
CCTK_NumCompiledThorns [A349] Return the number of thorns compiled in
CCTK_ThornImplementation [A510] Returns the implementation provided by the thorn

Return the number of thorns compiled in.

Synopsis

Result

numthorns Number of thorns compiled in.

See Also

CCTK_ActivatingThorn [A47] Finds the thorn which activated a particular implementation
CCTK_CompiledImplementation [A90] Return the name of the compiled implementation with given index
CCTK_CompiledThorn [A92] Return the name of the compiled thorn with given index
CCTK_ImplementationRequires [A263] Return the ancestors for an implementation
CCTK_ImplementationThorn [A265] Returns the name of one thorn providing an implementation.
CCTK_ImpThornList [A267] Return the thorns for an implementation
CCTK_IsImplementationActive [A302] Reports whether an implementation was activated in a parameter file
CCTK_IsImplementationCompiled [A304] Reports whether an implementation was compiled into a configuration
CCTK_IsThornActive [A306] Reports whether a thorn was activated in a parameter file
CCTK_IsThornCompiled [A308] Reports whether a thorn was compiled into a configuration
CCTK_NumCompiledImplementations [A347] Return the number of implementations compiled in
CCTK_ThornImplementation [A510] Returns the implementation provided by the thorn

The number of grid array reduction operators registered

Synopsis

Result

num_ga_reduc The number of registered grid array reduction operators (currently either 1 or 0)

Discussion

This function returns the number of grid array reduction operators. Since we only allow one grid array reduction operator currently, this function can be used to check if a grid array reduction operator has been registered or not.

See Also

CCTK_ReduceGridArrays() Performs reduction on a list of distributed grid arrays

CCTK_RegisterGridArrayReductionOperator() Registers a function as a grid array reduction operator of a certain name

CCTK_GridArrayReductionOperator() The name of the grid reduction operator, or NULL if none is registered

Get the number of groups of variables compiled in the code

Synopsis

Parameters

number The number of groups compiled from the thorns interface.ccl files

Examples

Find the total number of I/O methods registered with the flesh

Synopsis

Parameters

num_methods number of registered IO methods

Discussion

Returns the total number of IO methods registered with the flesh.

The number of local reduction operators registered

Synopsis

Result

num_ga_reduc The number of registered local array operators

Discussion

This function returns the total number of registered local array reduction operators

See Also

CCTK_ReduceLocalArrays() Reduces a list of local arrays (new local array reduction API)

CCTK_LocalArrayReductionHandle() Returns the handle of a given local array reduction operator

CCTK_RegisterLocalArrayReductionOperator() Registers a function as a reduction operator of a certain name

CCTK_LocalArrayReduceOperatorImplementation() Provide the implementation which provides an local array reduction operator

CCTK_LocalArrayReduceOperator() Returns the name of a registered reduction operator

The number of global array reduction operators registered, either 1 or 0.

Synopsis

Result

num_reduc The number of registered global array operators

Discussion

This function returns the total number of registered global array reduction operators, it is either 1 or 0 as we do not allow multiple array reductions.

See Also

CCTK_ReduceArraysGlobally() Reduces a list of arrays globally

CCTK_LocalArrayReductionHandle() Returns the handle of a given local array reduction operator

CCTK_RegisterReduceArraysGloballyOperator() Registers a function as a reduction operator of a certain name

Returns the number of active time levels for a group (deprecated).

Synopsis

Result

timelevels The currently active number of timelevels for the group.

Parameters

GH (≠ NULL) Pointer to a valid Cactus grid hierarchy.
groupname Name of the group.
groupindex Index of the group.
varname Name of a variable in the group.
varindex Index of a variable in the group.

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 CCTK_MaxTimeLevels.

This function has been superceded by CCTK_ActiveTimeLevels and should not be used any more.

See Also

CCTK_ActiveTimeLevels [A49] Returns the number of active time levels for a group.
CCTK_MaxTimeLevels [A325] Return the maximum number of active timelevels.
CCTK_GroupStorageDecrease [A238] Base function, overloaded by the driver, which decreases the number of active timelevels, and also returns the number of active timelevels.
CCTK_GroupStorageIncrease [A241] Base function, overloaded by the driver, which increases the number of active timelevels, and also returns the number of active timelevels.

Errors

timelevels < 0 Illegal arguments given.

Given a cTimerData structure, returns its number of clocks.

Synopsis

Parameters

const cTimerData * info The timer information structure whose clocks are to be counted.

Get the number of grid variables compiled in the code

Synopsis

Parameters

number The number of grid variables compiled from the thorn’s interface.ccl files

Examples

Provides the number of variables in a group from the group name

Synopsis

Parameters

num The number of variables in the group
group The full group name

Discussion

The group name should be given in the form <implementation>::<group>

Examples