Symmetries ---------- Authors: Gabrielle Allen, Tom Goodale, David Rideout Date: April 2003 Status: Draft Version: $Header: /cactus/CactusWebSite/Development/Specs/Symmetry.txt,v 1.4 2003/05/26 09:53:08 rideout Exp $ Why? --- 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. 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. * 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 table if they want. * The GF table is set up at CCTK_PREPARAMCHECK by the symmetry thorns, so that the CoordBase can use this information to set up and check coordinates during CCTK_PARAMCHECK. (CCTK_PREPARAMCHECK 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.) * If no symmetries are registered for the GF, then an empty Symmetry Table is created. Symmetry Tables --------------- A symmetry table will have the following form: data type key name key value --------- -------- --------- STRING SYM FACE face symmetry type INT SYM_ZONES FACE number of symmetry zones Where is a string consisting of a plus or minus sign, which indicates the 'plus' or 'minus' face, followed by an integer which indicates a dimension of the grid. For example, for a 3D GF, one specifies the 'minus y face', i.e. the face identified by indices (:,1,:) in Fortran 90 syntax, with the two character string "-2". The symmetry type of a face is a string which indicates what type of symmetry condition should be applied on that face. Some examples are "REFLECTION", "ROTATION", "CARTOON", "FOLD". ("FOLD" may be used on a 2D grid which wraps around an airfoil, so that the "-2" face folds over to meet itself downstream of the airfoil.) If a particular face is not included in the table, then it is assumed to have no symmetry associated with it. The number of symmetry zones is the depth of grid points which the symmetry boundary condition should update. (i.e. this is usually the radius of the interior stencil.) All symmetry tables are case insensitive. Schedule Setup -------------- SymBase will create the following schedule groups: SCHEDULE GROUP Symmetries AT CCTK_PREPARAMCHECK SCHEDULE GROUP SetupSymmetries IN Symmetries Each thorn which wishes to register symmetry information with SymBase will schedule a registration routine during SetupSymmetries (see API below). After all symmetries have been registered, SymBase will SCHEDULE SymmetryValidate IN Symmetries AFTER SetupSymmetries which will check to ensure that all registered symmetries are compatible, and will stop the code if not. (As an alternative, one could have the registration routine check each symmetry registration in turn for conflicts, however this creates a dependence upon the order in which symmetries are registered, which seems undesirable.) API --- The SymBase implementation will provide an aliased function CCTK_INT SymmetryRegister (CCTK_STRING sym_name) which will be used to register the existence of an abstract symmetry type. It will also provide aliased functions CCTK_INT SymmetryRegisterGrid (CCTK_POINTER GH, CCTK_INT faces, CCTK_INT num_sym_zones, CCTK_STRING sym_name) CCTK_INT SymmetryRegisterGA (CCTK_POINTER GH, CCTK_INT faces, CCTK_INT num_sym_zones, CCTK_STRING group_name, CCTK_STRING sym_name) CCTK_INT SymmetryRegisterGAI (CCTK_POINTER GH, CCTK_INT faces, CCTK_INT num_sym_zones, CCTK_STRING group_index, CCTK_STRING sym_name) which are called to register a specific symmetry with the grid (function) or a grid array. Each function will check to see that an abstract symmetry of this name has been registered. The faces parameter is a specification of faces as described in src/include/cctk_Faces.h. As mentioned above, symmetry names are case insensitive. A grid array group can be specified by name or index. To get symmetry information associated with any grid variable, SymBase provides aliased functions CCTK_INT SymmetryTable (CCTK_POINTER GH, CCTK_STRING group_name) or CCTK_INT SymmetryTableI (CCTK_POINTER GH, CCTK_INT group_index) which can be called by an application thorn, which return the symmetry table handle associated with that grid variable. 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.