Coordinate APIs

CCTK_INT systemhandle = Coord_SystemRegister(CCTK_POINTER_TO_CONST GH,
                                             CCTK_INT dim, 
                                             CCTK_STRING systemname)

registers a coordinate system, along with its dimension, with the CoordBase thorn. This will create a coordinate system table, and return the handle of the table for success, or a negative error code upon error. The possible errors are:

COORDERROR_INVALIDDIM	invalid dimension passed in
COORDERROR_INVALIDNAME	invalid name passed in
COORDERROR_TABLEERROR	error from key-value or hash tables in flesh
COORDERROR_SYSTEMEXISTS	coordinate system of this name already exists

These error codes are defined in CoordBase.h. CoordBase holds the table handles on a GH extension, under the name ``CoordBase''.

CCTK_INT systemhandle = Coord_SystemHandle(CCTK_POINTER_TO_CONST GH,
                                           CCTK_STRING systemname)

returns the handle for a given coordinate system, or negative on error:

COORDERROR_TABLEERROR	error from hash table
COORDERROR_NOSYSTEM	no coordinate system of this name is registered

CCTK_INT coordhandle = Coord_CoordRegister(CCTK_POINTER_TO_CONST GH, 
                                           CCTK_INT systemhandle, 
                                           CCTK_INT direction,
                                           CCTK_STRING coordname)

registers a coordinate within a coordinate system, in the specified `direction'. (Direction in this context means the index in the coordinate basis, which ranges from 1 to the dimension of the system.) Coord_CoordRegister() returns the coordinate handle, or negative for an error:

COORDERROR_INVALIDDIM	invalid `direction'
COORDERROR_INVALIDHANDLE	invalid handle passed in / coordinate system does not exist
COORDERROR_TABLEERROR	error from hash or key-value tables in flesh
COORDERROR_COORDINATEEXISTS	coordinate already exists for this `direction'
COORDERROR_DUPLICATENAME	coordinate of this name already exists in this system

CCTK_INT coordhandle = Coord_CoordHandle(CCTK_POINTER_TO_CONST GH,
                                         CCTK_STRING coordname,
                                         CCTK_STRING systemname)

returns the coordinate handle for a given coordinatate in a coordinate system, or negative on error:

COORDERROR_NOSYSTEM	no coordinate system of this name is registered
COORDERROR_TABLEERROR	error from hash table
COORDERROR_NOSUCHCOORD	no coordinate of the name is registered for this system

int systemhandle = Coord_GroupSystem(const cGH *GH, 
                                     const char *groupname)

returns the handle for the coordinate system associated with a group of grid variables, or negative on error. This can either be the default for coordinate systems of this dimension, or the coordinate system that is specified in the interface.ccl. Coordinate systems specified in interface.ccl will override any defaults. The possible error codes are:

COORDERROR_INVALIDGROUPNAME	no such group exists
COORDERROR_NOCOORDSYS	no coordinate system is associated with the group

CCTK_INT systemhandle = Coord_SetDefaultSystem(CCTK_POINTER_TO_CONST GH,
                                               CCTK_STRING systemname)

sets this coordinate system to be the default for grid variables of the same dimension. It returns the handle of the system, or negative for errors:

COORDERROR_INVALIDNAME	no coordinate system of this name has been registered
COORDERROR_NODIMENSION	coordinate system does not have a valid dimension
COORDERROR_DEFAULTEXISTS	grid variables of this dimension already have a
	default coordinate system registered

There can be a default coordinate system for each grid dimension. The default system will apply for each grid variable of that dimension, unless it is overridden.

CCTK_INT systemhandle = Coord_GetDefaultSystem(CCTK_POINTER_TO_CONST GH,
                                               CCTK_INT dim)

gets the default coordinate system for grid variables of dimension dim (ranging from 1 to the maximum number of dimensions registered). It returns the handle of the system, or negative for errors:

COORDERROR_INVALIDDIM	given dimension is invalid
COORDERROR_NOSYSTEM	given dimension does not have a default coordinate system associated