Cactus API¶

There are many function in Cactus. I only pick up the most important one and list in here.

Include¶

cctk.h¶

Any source file using Cactus infrastructure should include the header file cctk.h using the line

#include "cctk.h"

cctk_Arguments.h¶

Any routine using Cactus argument lists should include at the top of the file the header

#include "cctk_Arguments.h"

A Cactus macro CCTK_ARGUMENTS is defined for each thorn to contain:

General information about the grid hierarchy.
All the grid variables defined in the thorn’s interface.ccl.

These variables must be declared at the start of the routine using the macro DECLARE_CCTK_ARGUMENTS.

cGH¶

Parameters:

cctkGH – A C pointer identifying the grid hierarchy.
cctk_dim – An integer with the number of dimensions used for this grid hierarchy.
cctk_lsh – An array of cctk_dim integers with the local grid size on this processor.
cctk_ash – An array of cctk_dim integers with the allocated size of the array.
cctk_gsh – An array of cctk_dim integers with the global grid size.
cctk_iteration – The current iteration number.
cctk_delta_time – A CCTK_REAL with the timestep.
cctk_time – A CCTK_REAL with the current time.
cctk_delta_space – An array of cctk_dim CCTK_REALs with the grid spacing in each direction.
cctk_nghostzones – An array of cctk_dim integers with the number of ghostzones used in each direction.
cctk_origin_space – An array of cctk_dim CCTK_REALs with the spatial coordinates of the global origin of the grid.
cctk_lbnd – An array of cctk_dim integers containing the lowest index (in each direction) of the local grid, as seen on the global grid.
cctk_ubnd – An array of cctk_dim integers containing the largest index (in each direction) of the local grid, as seen on the global grid.
cctk_bbox – An array of 2*cctk_dim integers which indicate whether the boundaries are internal boundaries (e.g. between processors), or physical boundaries. A value of 1 indicates a physical (outer) boundary at the edge of the computational grid, and 0 indicates an internal boundary.
cctk_levfac – An array of cctk_dim integer factors by which the local grid is refined in the corresponding direction with respect to the base grid.
cctk_levoff – Two arrays of cctk dim integers describing the distance by which the local grid is offset with respect to the base grid, measured in local grid spacings.
cctk_timefac – The integer factor by which the time step size is reduced with respect to the base grid.
cctk_convlevel – The convergence level of this grid hierarchy. The base level is 0, and every level above that is coarsened by a factor of cctk_convfac.
cctk_convfac – The factor between convergence levels. The relation between the resolutions of different convergence levels is \(\Delta x_{L}=\Delta x_{0} \cdot F^{L}\), where L is the convergence level and F is the convergence factor. The convergence factor defaults to 2.

cctk_Parameters.h¶

Any routine using Cactus parameters should include at the top of the file the header

#include "cctk_Parameters.h"

The parameters should be declared at the start of the routine using them with the macro DECLARE_CCTK_PARAMETERS.

Cactus.Flesh¶

CCTK Function¶

int CCTK_ActiveTimeLevels(const cGH *cctkGH, const char *groupname| int groupindex| const char *varname| int varindex)¶

Returns the number of active time levels for a group.

Discussion:	This function returns the number of timelevels for which storage has been activated.
Parameters:	cGH – Pointer to a valid Cactus grid hierarchy. groupname (char) – Name of the group. groupindex (int) – Index of the group. varname (char) – Name of a variable in the group. varindex (int) – Index of a variable in the group.
Error:	Negative value: Illegal arguments given.

int CCTK_ERROR(const char *message)¶

Macro to print a single string as error message and stop the code.

Discussion:	To include variables in the error message from C, you can use the routine `CCTK_VError()` which accepts a variable argument list.
Parameters:	message (char) – The error message to print

CCTK_FirstVarIndex(const char* group_name)¶

Given a group name, returns the first variable index in the 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, \dots , V+N-1\).
Parameters:	group_name (char) – The character-string name of the group.
Returns:	The first variable index in the group.
Error:	-1 Group name is invalid. -2 Group has no members.

int CCTK_GFINDEX3D(cctkGH, i, j, k)¶

Find the 1-dimensional index which is needed from the multidimensional indices

Parameters:	cGH – Pointer to a valid Cactus grid hierarchy. ijk (int) – multidimensional indices
Returns:	(i + cctkGH->cctk_ash[0] * (j + cctkGH->cctk_ash[1] * k))

void CCTK_Info(*thorn, *message)¶

Print an information message to stdout.

Discussion:	For a multiprocessor run, only runtime information from processor zero will be printed to screen by default.
Parameters:	thorn (char) – Name of originating thorn message (char) – the warning message to output

CCTK_Reduce(const cGH *GH, int proc, int operation_handle, int num_out_vals, int type_out_vals, void *out_vals, int num_in_fields, ...)¶

Generic routine for doing a reduction operation on a set of Cactus variables.

Parameters:

GH – pointer to the grid hierarchy
proc (int) – processor that receives the result of the reduction operation (a negative value means that all processors get the result)
operation_handle (int) – the handle specifying the reduction operator
num_out_vals (int) – number of elements in the reduction output
type_out_vals (int) – datatype of the output values
out_vals – pointer to buffer holding the output values
num_in_fields (int) – number of input fields passed in the variable argument list
<...> – list of variables indices of input fields

CCTK_ReductionHandle(const char * reduction)¶

Handle for given reduction method

Discussion:	Reduction methods should be registered at CCTK_STARTUP.
Parameters:	name (char) – name of the reduction method required
Returns:	handle returned for this method

int CCTK_VarIndex(const char *varname)¶

Get the index for a variable.

Discussion:	The variable name should be the given in its fully qualified form, that is <implementation>::<variable> for a public or protected variable, and <thornname>::<variable> for a private variable. For vector variables, the zero-based component index should be included in square brackets after the variable name.
Parameters:	varname (char) – The name of the variable.
Error:	-1 no variable of this name exists -2 failed to catch error code from Util_SplitString -3 given full name is in wrong format -4 memory allocation failed

>>> index = CCTK_VarIndex("evolve::phi");
>>> index = CCTK_VarIndex("evolve::vect[0]")

CCTK_VarDataPtrI(const cGH * cctkGH, int timelevel, int index)¶

Returns the data pointer for a grid variable from the variable index.

Parameters:	cctkGH – pointer to CCTK grid hierarchy timelevel (int) – The timelevel of the grid variable index (int) – The index of the variable

void CCTK_VInfo(*thorn, *format, ...)¶

Info output routine with variable argument list

Discussion:	only be called from C, because Fortran doesn’t know about variable argument lists.
Parameters:	thorn (char) – Name of originating thorn format (char) – format string for message

int CCTK_VWarn(level, line, *file, *thorn, *format, ...)¶

If the given warning level is less or equal to the current one, it will print the given warning message to stderr.

Parameters:	level (int) – Warn Level

int CCTK_WARN(int level, const char *message)¶

Macro to print a single string as a warning message and possibly stop the code

Parameters:	level (int) – The warning level to use message (char) – The warning message to print.

Util Function¶

Util_GetHandledData(cHandledData *storage, int handle)¶

Gets a pointer to the data corresponding to the given handle.

Parameters:	level (int) – Warn Level

Coordinate¶

CartGrid3D¶

Variable¶

Parameters:	coarse_dx (scalar) – 3D Cartesian grid spacings in x direction coarse_dy (scalar) – 3D Cartesian grid spacings in y direction coarse_dz (scalar) – 3D Cartesian grid spacings in z direction x (gf) – 3D Cartesian grid coordinates x y (gf) – 3D Cartesian grid coordinates y z (gf) – 3D Cartesian grid coordinates z r (gf) – 3D Cartesian grid coordinates r

Numerical¶

Interp¶

int 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[])¶

Interpolate a list of distributed grid variables. A grid variable can be either a grid function or a grid array.

Parameters:

cGH – Pointer to a valid Cactus grid hierarchy.
N_dims (int) – Number of dimensions in which to interpolate.
local_interp_handle (int) – Handle to the local interpolation operator as returned by CCTK_InterpHandle.
param_table_handle (int) – 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 (int) – Cactus coordinate system handle defining the mapping between (usually floating-point) coordinates and integer grid subscripts, as returned by CCTK_CoordSystemHandle.
N_interp_points (int) – The number of interpolation points requested by this processor.
interp_coords_type_code (int) – 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.
interp_coords[] – (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 (int) – 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[] – (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 – 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.

Returns:

0 success
<0 indicates an error condition

InterpGridArrays()

Reduce Operators¶

CCTK_ReduceGridArrays()¶: Reduces Cactus grid arrays. This API doesn’t provide a reduction functionality itself, it only takes care of the interprocessor communication necessary when reducing distributed grid arrays.

CCTK_ReduceLocalArrays()¶: Reduces processor-local arrays with various options.

CCTK_ReductionHandle(const char *reduction_name)

Parameters:	reduction_name (char) – the name under which the operator has been registered by the providing thorn.

CCTK_ReductionArrayHandle(const char *reduction_name)¶

Parameters:	reduction_name (char) – the name under which the operator has been registered by the providing thorn.

int CCTK_Reduce(const cGH *GH, int proc, int operation_handle, int num_out_vals, int type_out_vals, void *out_vals, int num_in_fields, ...)¶

Parameters:

cGH – it is the pointer to the grid hierarchy.
proc (int) – the processor which collects the information, a negative value (−1) will distribute the data to all processors.
operation_handle (int) – the number of the reduction operation handle, needs to be found by calling CCTK_ReductionHandle or CCTK_ReductionArrayHandle.
num_out_vals (int) – integer defining the number of output values.
type_out_vals (int) – specifies the type of the gridfunction you are communicating.
out_vals – an array that will contain the output values.
num_in_fields (int) – specifies the number of input fields.
<...> – indicates a variable argument list, specify the arrays which will be reduced, the number of specified arrays must be the same as the value of the num_in_fields variable.

Error: