Symmetries ========== Authors: [version 2.1pre1] TG + Mailing list discussion [version 2.0] Jonathan Thornburg, based on many ideas/comments from Erik Schnetter [version 1.4] Gabrielle Allen, Tom Goodale, David Rideout Date: 3.Mar.2004 Status: Draft, hopefully to be implemented by mid-March 2004 Version: 2.1pre1 $Header: /cactus/CactusWebSite/Development/Specs/Symmetry_v2.0.txt,v 1.2 2004/03/26 20:14:15 goodale Exp $ Motivation ========== Application thorns often need to know about symmetries of the grid, but they have no clean way to determine this information other than attempting to read and interpret the appropriate parameters of whatever thorns implement grid symmetries. This is difficult because the complex manner in which symmetry parameters are interpreted may change, new symmetry parameters may be added or old ones may change their names or ranges, the interaction among multiple symmetry thorns is not clearly specified, etc. We need a well defined specification for how symmetry information is registered, stored, computed, and accessed. In the future it might also be nice to have a "generic symmetry boundary condition" thorn, which would handle a variety of different symmetry boundary conditions with common code, parameterized by the information described here (and probably other information as well). Features ======== * This symmetry infrastructure will be provided by a thorn CactusBase/SymBase. * Symmetries are a property of a grid ('the GF' or a GA), and will be described in a Symmetry Table (a Cactus key/value table). * Any thorn can get the Symmetry Table handle for a grid variable via an aliased call to the SymBase thorn. * All GFs use the same table of course, GAs can have their own tables if they want. * The GF table is set up at CCTK_WRAGH by the symmetry thorns, so that the CoordBase can use this information to set up and check coordinates during CCTK_PARAMCHECK. (CCTK_WRAGH is a new schedule bin which will be placed after CCTK_RECOVER_PARAMETERS and before CCTK_PARAMCHECK, for routines which need parameters and a GH, but must be run before checking of parameters takes place.) Grid Faces ========== I define N_FACES = 2*N_DIMS to be the number of faces of the grid (GH) or of a grid array. Faces are numbered in the usual Cactus order, 0 = xmin 1 = xmax 2 = ymin 3 = ymax 4 = zmin 5 = zmax ... This should be defined in src/include/cctk_Faces.h Symmetry Tables =============== For "cultural compatability" with boundary tables, all symmetry tables are case insensitive (UTIL_TABLE_FLAGS_CASE_INSENSITIVE bit is set in the table flags word, as defined in src/include/util_Table.h ). A symmetry table must contain (at least) the following entries: CCTK_INT symmetry_handle[N_FACES]; CCTK_INT symmetry_zone_width[N_FACES]; Code outside SymBase should not modify these table entries. If there is a symmetry boundary condition on a face, symmetry_handle[face] is a "symmetry handle", an integer (>= 0) returned by Symmetry_Register() (see the API section below) which identifies the particular symmetry condition. (That symmetry condition may use additional information, for example other entries in the symmetry table, to help it figure out just what to do.) Otherwise (if there is no symmetry boundary condition on this face) symmetry_handle[face] is negative. [To allow future expansion, any negative value is allowed here. The initial implementation will use -1.] If symmetry_handle[face] >= 0, symmetry_zone_width[face] is the symmetry-zone width on this face, i.e. the number of grid points in the perpendicular-to-the-face direction which the symmetry BC should update. (The symmetry-zone width must be greater than or equal to, and is usually equal to, the interior molecule radius.) Otherwise (if there is no symmetry boundary condition on this face), symmetry_zone_width[face] = 0 [The choice of 0, rather than a negative value, is to give a "safe no-op" for code which loops over *all* faces and does something for symmetry_zone_width[face] points.] Schedule Setup ============== SymBase will create the following schedule groups: SCHEDULE GROUP SymmetrySetup AT CCTK_WRAGH SCHEDULE GROUP SymmetryRegister IN SymmetrySetup Each thorn which wishes to register symmetry information with SymBase will schedule a registration routine during SymmetryRegister (see the API section below). SymBase itself may also schedule a routine SCHEDULE SymmetrySetupValidate IN SymmetrySetup AFTER SymmetryRegister to do final consistency checks after all symmetries have been registered. API === The SymBase implementation will provide the following aliased functions: Functions to register symmetries and query the symmetry handle <--> symmetry name mapping: CCTK_INT FUNCTION SymmetryRegister(CCTK_STRING IN sym_name) This function registers a symmetry and allocates a handle (>= 0) for it. It returns the handle, or a (< 0) error code if something goes wrong. CCTK_INT FUNCTION SymmetryHandleOfName(CCTK_STRING IN sym_name) This function returns the symmetry handle allocated for a given symmetry name, or -1 if no symmetry of that name has been registered. CCTK_INT FUNCTION SymmetryNameOfHandle(CCTK_INT IN sym_handle, CCTK_INT IN sym_name_buffer_length, CCTK_STRING OUT sym_name_buffer) This function allows the user to find out the symmetry name for a given symmetry handle. The user passes in the handle and a buffer in which the name should be stored (with a length so we can't overrun the buffer). The function stores the name in the buffer, followed by a '\0' character to terminate it. The function returns the string length of the name (not counting the terminating '\0'), or < 0 for error. Functions to register a specific symmetry for the grid or GA group: CCTK_INT FUNCTION SymmetryRegisterGrid (CCTK_POINTER IN GH, CCTK_INT IN sym_handle, CCTK_INT IN ARRAY which_faces, # array [N_FACES] CCTK_INT IN ARRAY symmetry_zone_width) # array [N_FACES] CCTK_INT FUNCTION SymmetryRegisterGAI (CCTK_POINTER IN GH, CCTK_INT IN sym_handle, CCTK_INT IN ARRAY which_faces, # array [N_FACES] CCTK_INT IN ARRAY symmetry_zone_width, # array [N_FACES] CCTK_INT IN group_index) CCTK_INT FUNCTION SymmetryRegisterGA (CCTK_POINTER IN GH, CCTK_INT IN sym_handle, CCTK_INT IN ARRAY which_faces, # array [N_FACES] CCTK_INT IN ARRAY symmetry_zone_width, # array [N_FACES] CCTK_STRING IN group_name) These functions return a status code (>= 0 for ok, < 0 for error). sym_handle is the symmetry handle as returned by SymmetryRegister() . GH and/or group_index or group_name identifies the grid or GA group respectively. [Note that GH is *not* a CCTK_POINTER_TO_CONST, since SymmetryRegisterGrid() might (at some time in the future) want to store some information in a GH extension.] which_faces[face] is a Boolean (0=false, 1=true) flag saying whether or not this symmetry "claims" this face of the grid, i.e. whether or not it will update this face's ghost zone. If which_faces[face] is true, symmetry_zone_width[face] is the symmetry zone width for this symmetry on this face. Otherwise (if this symmetry isn't claiming this face) symmetry_zone_width[face] is unused and is ignored. Each of these registration functions checks that sym_handle is valid, checks to make sure that the requested grid faces haven't been claimed by any previous-registered symmetry (if so, that's an error), creates the appropriate symmetry table if it doesn't already exist, then sets the appropriate entries in the symmetry table. Functions to get the symmetry table's table handle for a given grid or GA: CCTK_INT FUNCTION SymmetryTableHandleForGrid(CCTK_POINTER_TO_CONST GH) CCTK_INT FUNCTION SymmetryTableHandleForGA(CCTK_POINTER_TO_CONST GH, CCTK_INT group_index) Each of these returns the symmetry table handle registered for the specified GH/GA, or -1 if no symmetry has been registered for the GH/GA. Transformation of Tensor Components under various Symmetries ============================================================ Currently CartGrid3D creates a GH extension to hold symmetry information. The extension holds the parity transformation properties of each grid function (i.e. each component of each tensor), across each face of the grid. CartGrid3D obtains this information via calls to SetSymmetry* functions by application thorns. This information will now be deduced via the tensortype information which is stored on the tag table for each variable group. This tensortype specification is yet to be written. For the moment there is a tensortypealias tag, used by Cartoon, which allows for scalars, vectors, and 2nd rank symmetric tensors.