SymBase
Erik Schnetter <schnetter@aei.mpg.de>
Date
When the computational domain has symmetries, then it is often very convenient to be able to
interpolate at points that are not present on the actual computational grid, but can be mapped
into the grid through the symmetries. Thorn SymBase provides a mechanism by which symmetry
conditions can register routines that handle this mapping when a global interpolator is called.
1 Introduction
Thorn SymBase contains a registry for symmetry conditions and for symmetry faces. Other thorns that
implement symmetry boundary conditions register themselves with SymBase and reserve certain faces of the
grid, so that no other boundary condition is applied there. Thorns that implement physical boundary conditions
should query SymBase about the set of faces that have symmetry boundary conditions and should not apply the
physical boundary condition there.
The driver has to be aware that it calls thorn SymBase’s mapping routine before it actually interpolates. The
whole mechanism is transparent for the user.
2 Registering Symmetry Conditions
Each thorn that implements a symmetry boundary condition should register itself with thorn SymBase. This has
no consequences per se, but it reserves a symmetry handle for later reference. The API for registering and
querying symmetry names and handles is
CCTK_INT FUNCTION
SymmetryRegister (CCTK_STRING IN sym_name)
CCTK_INT FUNCTION
SymmetryHandleOfName (CCTK_STRING IN sym_name)
CCTK_POINTER_TO_CONST FUNCTION
SymmetryNameOfHandle (CCTK_INT IN sym_handle)
The routine SymmetryRegister should be called in a routine that has been scheduled in the schedule group
SymmetryRegister.
Note: We have the API in the specification, we have it in the interface file, in the source code,
and in a header file, and I duplicated it into grdoc headers. I refuse to write and describe and
cross-check the API a sixth time in latex. At some point, we have to start using tools for that.
Please read the grdoc headers or the grdoc-produced HTML files for a detailed description.
3 Registering Symmetries for Faces
Thorn SymBase keeps two registries. The first, mentioned in the previous section, is the set of symmetry
boundary conditions. The second, the symmetry table, prescribes to which faces of the grids which
symmetry boundary condition is to be applied. Each entry of this table constitutes a mapping from grid
faces to symmetry boundary conditions, described by arrays whose elements correspond to grid
faces:
CCTK_INT symmetry_handle[]
CCTK_INT symmetry_zone_width[]
The faces are numbered in the same way those of the cctk_bbox array. Each element of symmetry_handle is a
symmetry handle as described in section 2. The symmetry zone is the same as a Cactus ghost zone, just in the
context of a symmetry boundary, so the symmetry_zone_width will be typically be the same as the ghost zone
width.
There is one such table for the grid hierarchy, which is valid for all grid functions. There is additionally one such
table for each grid array group.
The API for registering symmetries for faces is
CCTK_INT FUNCTION
SymmetryRegisterGrid
(CCTK_POINTER IN cctkGH,
CCTK_INT IN sym_handle,
CCTK_INT IN ARRAY which_faces,
CCTK_INT IN ARRAY symmetry_zone_width)
CCTK_INT FUNCTION
SymmetryRegisterGI
(CCTK_POINTER IN cctkGH,
CCTK_INT IN sym_handle,
CCTK_INT IN ARRAY which_faces,
CCTK_INT IN ARRAY symmetry_zone_width,
CCTK_INT IN group_index)
CCTK_INT FUNCTION
SymmetryRegisterGN
(CCTK_POINTER IN cctkGH,
CCTK_INT IN sym_handle,
CCTK_INT IN ARRAY which_faces,
CCTK_INT IN ARRAY symmetry_zone_width,
CCTK_STRING IN group_name)
The first routine registers a symmetry condition for the grid hierarchy; the other two routines register
for grid array groups (by index or name, respectively) sym_handle must be a symmetry handle
obtained as described in the previous section. which_faces and symmetry_zone_width are arrays with
one element per face, numbered in the same way as the cctk_bbox array. which_faces selects
which faces to register, and symmetry_zone_width sets the number of symmetry zones for these
faces.
These routines may be called at anytime after SymmetryRegister.
It is not possible to register multiple symmetry boundary conditions for the same face.
4 Querying Symmetries of Faces
Physical boundary conditions need to know to which faces they should apply the boundary condition. They need
to query SymBase for the set of faces that have a symmetry boundary condition, and they must not apply their
physical boundary condition there. The API is
CCTK_INT FUNCTION
SymmetryTableHandleForGrid (CCTK_POINTER_TO_CONST IN cctkGH)
CCTK_INT FUNCTION
SymmetryTableHandleForGI
(CCTK_POINTER_TO_CONST IN cctkGH,
CCTK_INT IN group_index)
CCTK_INT FUNCTION
SymmetryTableHandleForGN
(CCTK_POINTER_TO_CONST IN cctkGH,
CCTK_STRING IN group_name)
The first of these functions returns the symmetry table handle for the grid hierarchy; the second and third
return the that for the grid array group (by index or name, respectively).
The table entry with key symmetry_handle contains the symmetry handle for the symmetry boundary
condition, or a negative number if the face has no symmetry boundary condition associated with
it.
The code to find out which boundaries should have a physical boundary condition applied might look as
follows:
#include "cctk.h"
#include "util_Table.h"
CCTK_INT symtable;
CCTK_INT symbnd[6];
int face;
int ierr;
symtable = SymmetryTableHandleForGrid (cctkGH);
if (symtable<0)
CCTK_VWarn(0, __LINE__, __FILE__, "Thorn_Name", "symtable is out of bounds");
ierr = Util_TableGetIntArray (symtable, 6, symbnd, "symmetry_handle");
if (ierr!=6)
CCTK_VWarn(0, __LINE__, __FILE__, "Thorn_Name", "Util_TableGetIntArray returned error");
for (face=0; face<6; ++face) {
if (cctk_bbox[face] && symbnd[face]<0) {
/* Apply physical boundary condition here */
}
}
_______________________________________________________________________________________
#include "util_Table.h"
CCTK_INT symtable
CCTK_INT symbnd(6)
integer face
integer ierr
symtable = SymmetryTableHandleForGrid (cctkGH)
if (symtable<0) call CCTK_WARN (0, "internal error")
call Util_TableGetIntArray (ierr, int(symtable), 6, symbnd, "symmetry_handle")
if (ierr/=6) call CCTK_WARN (0, "internal error")
do face=1,6
if (cctk_bbox(face)/=0 .and. symbnd(face)<0) then
! Apply physical boundary condition here
end if
end do
5 Symmetry Interpolation
The mechanism by which the grid points are mapped into the domain works as follows:
- The user calls CCTK_InterpGridArrays with a list of coordinates.
- The Flesh forwards this call to the driver.
- The driver calls SymBase’s aliased function, SymmetryInterpolate, passing along all arguments.
- SymBase sets a flag for each face for which a symmetry condition has been registered, and then
calls SymmetryInterpolateFaces, passing along all arguments. This is the beginning of a chain of
recursive calls.
- SymmetryInterpolateFaces checks whether any faces are flagged.
- If no faces are flagged, SymBase calls the driver’s aliased function DriverInterpolate, which
performs the actual interpolation. This ends the chain of recursive calls.
- If there are faces with symmetry conditions flagged, SymBase chooses one such face, and then calls
the “symmetry interpolation” routine of the symmetry condition registered for this face, passing
along all arguments.
- The “symmetry interpolation” routine maps the coordinates into the domain by applying the
symmetry condition for this face. It then removes the flag for the corresponding face, and calls
SymmetryInterpolateFaces, passing along the arguments with the changed interpolation locations.
- After the actual interpolation has happened in the driver, the recursive call will return. The
“symmetry interpolation” routine then examines the tensor types of the interpolated quantities and
un-maps the values back onto their original locations. That is, e.g., after a reflection on the lower
-boundary,
-components
of vectors need their sign changed.
- The chain of recursive calls unravels until the call to CCTK_InterpGridArrays returns.
This mechanism has thus four players:
- The driver forwards any CCTK_InterpGridArrays call to SymBase SymmetryInterpolate so that
the list of interpolation points can be mapped into the domain. (See section 5.2.)
- Thorn SymBase controls which symmetry conditions perform this mapping on which faces.
- Each symmetry boundary condition has to register a “symmetry interpolation” routine that first
maps the points into the domain, then calls SymBase SymmetryInterpolateFaces recursively.
Before returning, it performs the inverse coordinate transformation on the interpolated quantities.
- The user calls CCTK_InterpGridArrays. For them the rest of the mechanism is transparent.
5.1 Interaction With Symmetry Conditions
The symmetry conditions have to register their “symmetry interpolation” routines by calling SymBase’s aliased
function SymmetryRegisterGridInterpolator. The “symmetry interpolation” routine must use C linkage and
must have the prototype
CCTK_INT symmetry_interpolate
(CCTK_POINTER_TO_CONST IN cctkGH,
CCTK_INT IN N_dims,
CCTK_INT IN local_interp_handle,
CCTK_INT IN param_table_handle,
CCTK_INT IN coord_system_handle,
CCTK_INT IN N_interp_points,
CCTK_INT IN interp_coords_type,
CCTK_POINTER_TO_CONST ARRAY IN interp_coords,
CCTK_INT IN N_input_arrays,
CCTK_INT ARRAY IN input_array_indices,
CCTK_INT IN N_output_arrays,
CCTK_INT ARRAY IN output_array_types,
CCTK_POINTER ARRAY IN output_arrays,
CCTK_INT IN faces)
These arguments are the same as those for CCTK_InterpGridArrays, except that here the bit field faces is used
to flag those faces that remain to have their symmetry boundary condition applied to the interpolation
points.
The aliased function SymmetryRegisterGridInterpolator has the prototype
CCTK_INT FUNCTION \
SymmetryRegisterGridInterpolator \
(CCTK_POINTER IN cctkGH, \
CCTK_INT IN sym_handle, \
CCTK_INT CCTK_FPOINTER IN symmetry_interpolate \
(CCTK_POINTER_TO_CONST IN cctkGH, \
CCTK_INT IN N_dims, \
CCTK_INT IN local_interp_handle, \
CCTK_INT IN param_table_handle, \
CCTK_INT IN coord_system_handle, \
CCTK_INT IN N_interp_points, \
CCTK_INT IN interp_coords_type, \
CCTK_POINTER_TO_CONST ARRAY IN interp_coords, \
CCTK_INT IN N_input_arrays, \
CCTK_INT ARRAY IN input_array_indices, \
CCTK_INT IN N_output_arrays, \
CCTK_INT ARRAY IN output_array_types, \
CCTK_POINTER ARRAY IN output_arrays, \
CCTK_INT IN faces))
which takes a function pointer to the aforementioned “symmetry interpolation” routine, while sym_handle
specifies which symmetry condition this routine is for. This handle must have been obtained from
SymmetryRegister.
The routine SymmetryRegisterGridInterpolator must be called after the symmetry faces
have been selected by the call to SymmetryRegisterGrid.
For convenience, the macro CCTK_ALL_FACES is provided. It may be used to initialize the faces bit field in cases
where the interpolation is to occur on all grid faces.
After it has removed from the faces variable the faces whose symmetry condition it has applied, the symmetry
interpolator routine must call the SymBase function SymmetryInterpolateFaces, which has the
prototype
CCTK_INT FUNCTION \
SymmetryInterpolateFaces \
(CCTK_POINTER_TO_CONST IN cctkGH, \
CCTK_INT IN N_dims, \
CCTK_INT IN local_interp_handle, \
CCTK_INT IN param_table_handle, \
CCTK_INT IN coord_system_handle, \
CCTK_INT IN N_interp_points, \
CCTK_INT IN interp_coords_type, \
CCTK_POINTER_TO_CONST ARRAY IN interp_coords, \
CCTK_INT IN N_input_arrays, \
CCTK_INT ARRAY IN input_array_indices, \
CCTK_INT IN N_output_arrays, \
CCTK_INT ARRAY IN output_array_types, \
CCTK_POINTER ARRAY IN output_arrays, \
CCTK_INT IN faces)
5.2 Driver Interaction
The driver has to call SymBase’s aliased function SymmetryInterpolate, and has to provide an aliased function
DriverInterpolate. Both functions have prototypes similar to CCTK_InterpGridArrays:
CCTK_INT FUNCTION
SymmetryInterpolate
(CCTK_POINTER_TO_CONST IN cctkGH,
CCTK_INT IN N_dims,
CCTK_INT IN local_interp_handle,
CCTK_INT IN param_table_handle,
CCTK_INT IN coord_system_handle,
CCTK_INT IN N_interp_points,
CCTK_INT IN interp_coords_type,
CCTK_POINTER_TO_CONST ARRAY IN interp_coords,
CCTK_INT IN N_input_arrays,
CCTK_INT ARRAY IN input_array_indices,
CCTK_INT IN N_output_arrays,
CCTK_INT ARRAY IN output_array_types,
CCTK_POINTER ARRAY IN output_arrays)
CCTK_INT FUNCTION
DriverInterpolate
(CCTK_POINTER_TO_CONST IN cctkGH,
CCTK_INT IN N_dims,
CCTK_INT IN local_interp_handle,
CCTK_INT IN param_table_handle,
CCTK_INT IN coord_system_handle,
CCTK_INT IN N_interp_points,
CCTK_INT IN interp_coords_type,
CCTK_POINTER_TO_CONST ARRAY IN interp_coords,
CCTK_INT IN N_input_arrays,
CCTK_INT ARRAY IN input_array_indices,
CCTK_INT IN N_output_arrays,
CCTK_INT ARRAY IN output_array_types,
CCTK_POINTER ARRAY IN output_arrays)
6 Tensor Types
Cactus supports declaring the tensor type of grid function groups. These tensor types define how the grid
functions, which are supposed to be tensor components, transform under various transformations, such as
reflections and rotations.
The tensor types are not declared directly; instead, a tensor type alias is declared. The following tensor type
aliases are currently known and supported:
-
scalar:
- a scalar
-
u:
- a vector
-
d:
- a covector
-
dd_sym:
- a symmetric rank two tensor
(More tensor type aliases are likely to be defined in the future.)
In addition to the tensor type, one can also declare the tensor parity, tensor weight, and a tensor metric. The
tensor parity (an integer) specifies the behaviour under reflections. Scalars and polar vectors have a parity
, pseudo scalars and axial
vectors have a parity .
The tensor weight (a real number) specifies the behaviour under transformations that change the volume
element. The tensor metric (a string) specifies what metric has to be used to raise or lower indices for that
quantity.
Last but not least, a tensor special can be defined for quantities that do not transform as tensor. The currently
supported tensor specials are
-
Gamma:
- for the transformation behaviour of the
variables of the BSSN formalism; it is
with
-
log:
- for the transformation behaviour of the variable
of the BSSN formalism; it is
with .
By default, the basis with respect to which the tensor components are given is supposed to be the (local)
coordinate system given by the grid, i.e., the coordinate directions are the “natural” directions of the grid. It is
possible to specify a different basis by declaring a tensor basis, which is the name of a grid function group
containing the coordinate system.
6.1 Example Tensor Type Declarations
From CactusWave/WaveToy:
CCTK_REAL scalarevolve TYPE=gf TAGS=’tensortypealias="scalar"’
From CactusEinstein/ADMBase:
CCTK_REAL metric TYPE=gf TAGS=’tensortypealias="dd_sym" tensormetric="ADMBase::metric"’
CCTK_REAL curv TYPE=gf TAGS=’tensortypealias="dd_sym" tensormetric="ADMBase::metric"’
CCTK_REAL lapse TYPE=gf TAGS=’tensortypealias="scalar" tensormetric="ADMBase::metric"’
CCTK_REAL shift TYPE=gf TAGS=’tensortypealias="U" tensormetric="ADMBase::metric"’
From AEIThorns/BSSN_MoL: