Coordinate Problems ------------------- Author: Gabrielle Allen, Tom Goodale, Thomas Radke, David Rideout Date: Sept 2002 Status: Final Draft Why? --- Need a more flexible and configurable way of specifying and using coordinates which can handle: - coordinate values specified in different ways (grid functions of any dimension, origin+spacing, etc) - can define coordinate symmetries - setting of different coordinate systems for different grid arrays - extensible coordinate properties without requiring new interfaces - easier for infrastructure thorns (eg IO) to use - works for AMR - works for multimodel/multipatch The Cactus table mechanism provides a mechanism for obsolating many of the current rigid coordinate APIs, and providing an extensible database of coordinates and their properties. We will define a standard coordinate schema, and coordinates which follow this schema will interact optimally with the Cactus Computational Toolkit thorns. It is hoped that other infrastructure thorn developers will also follow this schema, although they are then free to define their own one. Features -------- 1. Coordinate functions in the flesh will be deprecated, and a new thorn CoordBase will supply the main coordinate functions. 2. There can be a default coordinate system for each grid dimension used. This default coordinate system will then apply for all the grid functions of that dimension. 3. The default coordinate systems will be set by the thorns providing the coordinates (for example, if activated, CartGrid3D would set the default system for a 3D grid to be Cartesian. A private parameter in this thorn would allow this feature to be switched off). 4. Different coordinate systems can be set for different grid array groups. The coordinate system would be associated with the group in the interface.ccl file. Grid functions will typically use the default coordinate system, but will also be able to set particular coordinate systems in the interface.ccl file. 5. Coordinates can be defined in different ways depending on the type of system (through a grid function, origin and extent, etc). For AMR runs coordinates must be defined as grid functions. 6. Coordinate systems and coordinates can be dynamically added at any time throughout the run. 7. A new timebin CCTK_STARTUPGH (or some better name) will be scheduled after the GH has been created but before CCTK_PARAMCHECK. This time bin will be the default place for registering coordinate systems and coordinate properties. (So that they are available for checking at PARAMCHECK) New Coordinate APIs ------------------- int systemhandle = Coord_SystemRegister(const cGH *GH, int dim, const char *systemname) - adds a coordinate system with its dimension. return the handle or negative for error (errors: didn't get a handle, coordinate system already exists) int systemhandle = Coord_SystemHandle(const cGH *GH, const char *systemname) - return the handle for a given coordinate system return negative for error (errors: no system of this name) int coordhandle = Coord_CoordRegister(const cGH *GH, int systemhandle, int direction, const char *coordname) - add a coordinate with a direction to an existing coordinate system directions range from 1 to the dimension of the system return the coordinate handle or negative for an error (errors: didn't get a handle, coordinate system doesn't exist, coordinate already exists for this direction, coordinate of this name already exists in this system) int coordhandle = Coord_CoordHandle(const cGH *GH, const char *coordname, const char *systemname) - find the handle for a given coordinate in a coordinate system return negative for error (errors: no system, no coord in the system) int systemhandle = Coord_GroupSystem(const cGH *GH, const char *groupname) - return the handle for the coordinate system associated with a group of grid variables int ierr = Coord_SetDefaultSystem(const cGH *GH, const char *systemname) - set this coordinate system to be the default for grid functions of the same dimension returns zero for success (or returns the handle for the system?) returns negative for errors (errors: system doesn't exist) Question: if the system is already set does this reset it or return an error? Coordinate Schema ----------------- Coordinate System Tables NAME Cart3d|Spher3d|.... DIMENSION 1,2,3,... TYPE uniform|nonuniform|warped|mixed COORDINATES ,... (handles) Coordinate Tables SYSTEM NAME x DIRECTION 2 PHYSICALMIN 0.0 COMPMIN PHYSICALMAX COMPMAX .... TYPE uniform|non-uniform|warped TIMEDEPENDENT DATATYPE REALblahblah GAINDEX (type=uniform) DELTA Associating Coordinate Systems With Grid Variable Groups -------------------------------------------------------- We've been planning already to add a "TAG" field to the group definition in interface.ccl files. This field can hold information about groups which the flesh is not interested in. The optional coordinate system associated with a grid array can be added using this mechanism. The syntax for the interface.ccl file will look (something) like: cctk_real myarray type=array dim=2 tag="coordsystem=spher2d, tensortype=vector" { myvarx myvary myvarz } "My grid arrays" The tag field will be held as keys and tokens on a Cactus table. The handle for the table will be held on the cGH as an array[0,ngroups-1]. The handle for the table will be available from a CCTK function call int handle = CCTK_GroupTagTable(const cGH *GH, int groupindex) Implementation Details ---------------------- The handles for the system tables are stored in a hash table on a GH extension Thorn Implementation -------------------- CoordBase - holds this new API CartGrid3D - include both new and old use of coordinates (deprecate old) - register cart3d with coordinate GFs coord_x, coord_y, coord_z as names "x", "y", "z" - set cart3d to be the default coordinate system Other thorns - application thorns check at PARAMCHECK to see if the right coordinate system is being used. Until the old interface is deprecated this will be a warning. use Coord_GroupSystem to find the coordinate system for a group QUESTION: do we need an API to test/find what the default coord system is (and if so what should it return, string or table handle).