xx SymBase

SymBase

Erik Schnetter <schnetter@aei.mpg.de>

Date

Abstract

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.

PIC

Figurex1: Multiple SymBase symmetry transformations across different registered symmetry faces. A point is transformed to point by transformation , and then to point by transformation . Data is only actually stored for point .

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_INTxFUNCTION
xxxxSymmetryRegisterx(CCTK_STRINGxINxsym_name)
CCTK_INTxFUNCTION
xxxxSymmetryHandleOfNamex(CCTK_STRINGxINxsym_name)
CCTK_POINTER_TO_CONSTxFUNCTION
xxxxSymmetryNameOfHandlex(CCTK_INTxINxsym_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_INTxsymmetry_handle[]
CCTK_INTxsymmetry_zone_width[]

The faces are numbered in the same way those of the cctkxbbox array. Each element of symmetryxhandle is a symmetry handle as described in sectionx2. The symmetry zone is the same as a Cactus ghost zone, just in the context of a symmetry boundary, so the symmetryxzonexwidth 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_INTxFUNCTION
xxxxSymmetryRegisterGrid
xxxxxxxxx(CCTK_POINTERxINxcctkGH,
xxxxxxxxxxCCTK_INTxINxsym_handle,
xxxxxxxxxxCCTK_INTxINxARRAYxwhich_faces,
xxxxxxxxxxCCTK_INTxINxARRAYxsymmetry_zone_width)
CCTK_INTxFUNCTION
xxxxSymmetryRegisterGI
xxxxxxxx(CCTK_POINTERxINxcctkGH,
xxxxxxxxxCCTK_INTxINxsym_handle,
xxxxxxxxxCCTK_INTxINxARRAYxwhich_faces,
xxxxxxxxxCCTK_INTxINxARRAYxsymmetry_zone_width,
xxxxxxxxxCCTK_INTxINxgroup_index)
CCTK_INTxFUNCTION
xxxxSymmetryRegisterGN
xxxxxxxx(CCTK_POINTERxINxcctkGH,
xxxxxxxxxCCTK_INTxINxsym_handle,
xxxxxxxxxCCTK_INTxINxARRAYxwhich_faces,
xxxxxxxxxCCTK_INTxINxARRAYxsymmetry_zone_width,
xxxxxxxxxCCTK_STRINGxINxgroup_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) symxhandle must be a symmetry handle obtained as described in the previous section. whichxfaces and symmetryxzonexwidth are arrays with one element per face, numbered in the same way as the cctkxbbox array. whichxfaces selects which faces to register, and symmetryxzonexwidth 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_INTxFUNCTION
xxxxSymmetryTableHandleForGridx(CCTK_POINTER_TO_CONSTxINxcctkGH)
CCTK_INTxFUNCTION
xxxxSymmetryTableHandleForGI
xxxxxxxx(CCTK_POINTER_TO_CONSTxINxcctkGH,
xxxxxxxxxCCTK_INTxINxgroup_index)
CCTK_INTxFUNCTION
xxxxSymmetryTableHandleForGN
xxxxxxxx(CCTK_POINTER_TO_CONSTxINxcctkGH,
xxxxxxxxxCCTK_STRINGxINxgroup_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 symmetryxhandle 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:

#includex"cctk.h"
#includex"util_Table.h"
CCTK_INTxsymtable;
CCTK_INTxsymbnd[6];
intxface;
intxierr;
symtablex=xSymmetryTableHandleForGridx(cctkGH);
ifx(symtable<0)
xxCCTK_VWarn(0,x__LINE__,x__FILE__,x"Thorn_Name",x"symtablexisxoutxofxbounds");
ierrx=xUtil_TableGetIntArrayx(symtable,x6,xsymbnd,x"symmetry_handle");
ifx(ierr!=6)
xxCCTK_VWarn(0,x__LINE__,x__FILE__,x"Thorn_Name",x"Util_TableGetIntArrayxreturnedxerror");
forx(face=0;xface<6;x++face)x{
xxifx(cctk_bbox[face]x&&xsymbnd[face]<0)x{
xxxx/*xApplyxphysicalxboundaryxconditionxherex*/
xx}
}

#includex"util_Table.h"
CCTK_INTxsymtable
CCTK_INTxsymbnd(6)
integerxface
integerxierr
symtablex=xSymmetryTableHandleForGridx(cctkGH)
ifx(symtable<0)xcallxCCTK_WARNx(0,x"internalxerror")
callxUtil_TableGetIntArrayx(ierr,xint(symtable),x6,xsymbnd,x"symmetry_handle")
ifx(ierr/=6)xcallxCCTK_WARNx(0,x"internalxerror")
doxface=1,6
xxifx(cctk_bbox(face)/=0x.and.xsymbnd(face)<0)xthen
xxxx!xApplyxphysicalxboundaryxconditionxhere
xxendxif
endxdo

5 Symmetry Interpolation

The mechanism by which the grid points are mapped into the domain works as follows:

The user calls CCTKxInterpGridArrays 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 CCTKxInterpGridArrays returns.

PIC

Figurex2: The recursive calls involved in symmetry interpolation. Values of grid functions at global Cartesian coordinates are calculated by nested calls to the symmetry interpolators, which first apply the symmetry transformation to the coordinates. When all the symmetries have been applied, the local interpolator is called, producing the interpolation of grid function values in the local basis. As the symmetry interpolators return, they apply the inverse basis transformation to the interpolated grid function values.

This mechanism has thus four players:

The driver forwards any CCTKxInterpGridArrays 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 CCTKxInterpGridArrays. 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_INTxsymmetry_interpolate
xxxx(CCTK_POINTER_TO_CONSTxINxcctkGH,
xxxxxCCTK_INTxINxN_dims,
xxxxxCCTK_INTxINxlocal_interp_handle,
xxxxxCCTK_INTxINxparam_table_handle,
xxxxxCCTK_INTxINxcoord_system_handle,
xxxxxCCTK_INTxINxN_interp_points,
xxxxxCCTK_INTxINxinterp_coords_type,
xxxxxCCTK_POINTER_TO_CONSTxARRAYxINxinterp_coords,
xxxxxCCTK_INTxINxN_input_arrays,
xxxxxCCTK_INTxARRAYxINxinput_array_indices,
xxxxxCCTK_INTxINxN_output_arrays,
xxxxxCCTK_INTxARRAYxINxoutput_array_types,
xxxxxCCTK_POINTERxARRAYxINxoutput_arrays,
xxxxxCCTK_INTxINxfaces)

These arguments are the same as those for CCTKxInterpGridArrays, 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_INTxFUNCTIONxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\
xxxxSymmetryRegisterGridInterpolatorxxxxxxxxxxxxxxxxxxxxxxxx\
xxxxxxxx(CCTK_POINTERxINxcctkGH,xxxxxxxxxxxxxxxxxxxxxxxxxxxx\
xxxxxxxxxCCTK_INTxINxsym_handle,xxxxxxxxxxxxxxxxxxxxxxxxxxxx\
xxxxxxxxxCCTK_INTxCCTK_FPOINTERxINxsymmetry_interpolatexxxxx\
xxxxxxxxxxxxx(CCTK_POINTER_TO_CONSTxINxcctkGH,xxxxxxxxxxxxxx\
xxxxxxxxxxxxxxCCTK_INTxINxN_dims,xxxxxxxxxxxxxxxxxxxxxxxxxxx\
xxxxxxxxxxxxxxCCTK_INTxINxlocal_interp_handle,xxxxxxxxxxxxxx\
xxxxxxxxxxxxxxCCTK_INTxINxparam_table_handle,xxxxxxxxxxxxxxx\
xxxxxxxxxxxxxxCCTK_INTxINxcoord_system_handle,xxxxxxxxxxxxxx\
xxxxxxxxxxxxxxCCTK_INTxINxN_interp_points,xxxxxxxxxxxxxxxxxx\
xxxxxxxxxxxxxxCCTK_INTxINxinterp_coords_type,xxxxxxxxxxxxxxx\
xxxxxxxxxxxxxxCCTK_POINTER_TO_CONSTxARRAYxINxinterp_coords,x\
xxxxxxxxxxxxxxCCTK_INTxINxN_input_arrays,xxxxxxxxxxxxxxxxxxx\
xxxxxxxxxxxxxxCCTK_INTxARRAYxINxinput_array_indices,xxxxxxxx\
xxxxxxxxxxxxxxCCTK_INTxINxN_output_arrays,xxxxxxxxxxxxxxxxxx\
xxxxxxxxxxxxxxCCTK_INTxARRAYxINxoutput_array_types,xxxxxxxxx\
xxxxxxxxxxxxxxCCTK_POINTERxARRAYxINxoutput_arrays,xxxxxxxxxx\
xxxxxxxxxxxxxxCCTK_INTxINxfaces))

which takes a function pointer to the aforementioned “symmetry interpolation” routine, while symxhandle 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 CCTKxALLxFACES 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_INTxFUNCTIONxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\
xxxxSymmetryInterpolateFacesxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\
xxxxxxxx(CCTK_POINTER_TO_CONSTxINxcctkGH,xxxxxxxxxxxxxxxxxxx\
xxxxxxxxxCCTK_INTxINxN_dims,xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\
xxxxxxxxxCCTK_INTxINxlocal_interp_handle,xxxxxxxxxxxxxxxxxxx\
xxxxxxxxxCCTK_INTxINxparam_table_handle,xxxxxxxxxxxxxxxxxxxx\
xxxxxxxxxCCTK_INTxINxcoord_system_handle,xxxxxxxxxxxxxxxxxxx\
xxxxxxxxxCCTK_INTxINxN_interp_points,xxxxxxxxxxxxxxxxxxxxxxx\
xxxxxxxxxCCTK_INTxINxinterp_coords_type,xxxxxxxxxxxxxxxxxxxx\
xxxxxxxxxCCTK_POINTER_TO_CONSTxARRAYxINxinterp_coords,xxxxxx\
xxxxxxxxxCCTK_INTxINxN_input_arrays,xxxxxxxxxxxxxxxxxxxxxxxx\
xxxxxxxxxCCTK_INTxARRAYxINxinput_array_indices,xxxxxxxxxxxxx\
xxxxxxxxxCCTK_INTxINxN_output_arrays,xxxxxxxxxxxxxxxxxxxxxxx\
xxxxxxxxxCCTK_INTxARRAYxINxoutput_array_types,xxxxxxxxxxxxxx\
xxxxxxxxxCCTK_POINTERxARRAYxINxoutput_arrays,xxxxxxxxxxxxxxx\
xxxxxxxxxCCTK_INTxINxfaces)

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 CCTKxInterpGridArrays:

CCTK_INTxFUNCTION
xxxxSymmetryInterpolate
xxxxxxxx(CCTK_POINTER_TO_CONSTxINxcctkGH,
xxxxxxxxxCCTK_INTxINxN_dims,
xxxxxxxxxCCTK_INTxINxlocal_interp_handle,
xxxxxxxxxCCTK_INTxINxparam_table_handle,
xxxxxxxxxCCTK_INTxINxcoord_system_handle,
xxxxxxxxxCCTK_INTxINxN_interp_points,
xxxxxxxxxCCTK_INTxINxinterp_coords_type,
xxxxxxxxxCCTK_POINTER_TO_CONSTxARRAYxINxinterp_coords,
xxxxxxxxxCCTK_INTxINxN_input_arrays,
xxxxxxxxxCCTK_INTxARRAYxINxinput_array_indices,
xxxxxxxxxCCTK_INTxINxN_output_arrays,
xxxxxxxxxCCTK_INTxARRAYxINxoutput_array_types,
xxxxxxxxxCCTK_POINTERxARRAYxINxoutput_arrays)

CCTK_INTxFUNCTION
xxxxDriverInterpolate
xxxxxxxx(CCTK_POINTER_TO_CONSTxINxcctkGH,
xxxxxxxxxCCTK_INTxINxN_dims,
xxxxxxxxxCCTK_INTxINxlocal_interp_handle,
xxxxxxxxxCCTK_INTxINxparam_table_handle,
xxxxxxxxxCCTK_INTxINxcoord_system_handle,
xxxxxxxxxCCTK_INTxINxN_interp_points,
xxxxxxxxxCCTK_INTxINxinterp_coords_type,
xxxxxxxxxCCTK_POINTER_TO_CONSTxARRAYxINxinterp_coords,
xxxxxxxxxCCTK_INTxINxN_input_arrays,
xxxxxxxxxCCTK_INTxARRAYxINxinput_array_indices,
xxxxxxxxxCCTK_INTxINxN_output_arrays,
xxxxxxxxxCCTK_INTxARRAYxINxoutput_array_types,
xxxxxxxxxCCTK_POINTERxARRAYxINxoutput_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

a covector

ddxsym:

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_REALxscalarevolvexTYPE=gfxTAGS='tensortypealias="scalar"'

From CactusEinstein/ADMBase:

CCTK_REALxmetricxTYPE=gfxTAGS='tensortypealias="dd_sym"xtensormetric="ADMBase::metric"'
CCTK_REALxcurvxTYPE=gfxTAGS='tensortypealias="dd_sym"xtensormetric="ADMBase::metric"'
CCTK_REALxlapsexTYPE=gfxTAGS='tensortypealias="scalar"xtensormetric="ADMBase::metric"'
CCTK_REALxshiftxTYPE=gfxTAGS='tensortypealias="U"xtensormetric="ADMBase::metric"'

From AEIThorns/BSSNxMoL:

CCTK_REALxADM_BSSN_BxTYPE=gfx\
xxxxTAGS='tensortypealias="u"xtensormetric="ADMBase::metric"'
CCTK_REALxADM_BSSN_dtlapsexTYPE=gfx\
xxxxTAGS='tensortypealias="scalar"xtensormetric="ADMBase::metric"'
CCTK_REALxADM_BSSN_phixTYPE=gfx\
xxxxTAGS='tensortypealias="scalar"xtensormetric="BSSN_MoL::ADM_BSSN_metric"x\
xxxxxxxxxxtensorweight=0.16666666666666667xtensorspecial="log"'
CCTK_REALxADM_BSSN_metricxTYPE=gfx\
xxxxTAGS='tensortypealias="dd_sym"xtensormetric="BSSN_MoL::ADM_BSSN_metric"x\
xxxxxxxxxxtensorweight=-0.66666666666666667'
CCTK_REALxADM_BSSN_KxTYPE=gfx\
xxxxTAGS='tensortypealias="scalar"xtensormetric="BSSN_MoL::ADM_BSSN_metric"'
CCTK_REALxADM_BSSN_curvxTYPE=gfx\
xxxxTAGS='tensortypealias="dd_sym"xtensormetric="BSSN_MoL::ADM_BSSN_metric"x\
xxxxxxxxxxtensorweight=-0.66666666666666667'
CCTK_REALxADM_BSSN_gammaxTYPE=gfx\
xxxxTAGS='tensortypealias="u"xtensormetric="BSSN_MoL::ADM_BSSN_metric"x\
xxxxxxxxxxtensorweight=0.66666666666666667xtensorspecial="Gamma"'

7 Parameters

11verbose10Scope: privatex01  BOOLEAN

11Description: Output symmetry boundary face descriptions after registration

11       10  x01  Default: yes

11

8 Interfaces General Implements: symbase

Provides: SymmetryRegister to SymmetryHandleOfName to SymmetryNameOfHandle to SymmetryRegisterGrid to SymmetryRegisterGI to SymmetryRegisterGN to SymmetryRegisterGridInterpolator to SymmetryTableHandleForGrid to SymmetryTableHandleForGI to SymmetryTableHandleForGN to GetSymmetryBoundaries to SymmetryInterpolate to SymmetryInterpolateFaces to

9 Schedule This section lists all the variables which are assigned storage by thorn CactusBase/SymBase. Storage can either last for the duration of the run (Always means that if this thorn is activated storage will be assigned, Conditional means that if this thorn is activated storage will be assigned for the duration of the run if some condition is met), or can be turned on for the duration of a schedule function.

Storage NONE

Scheduled Functions

CCTKxSTARTUP x symbasexstartup x register gh extension for symbase x

11x11Language:11c
11 x 11Type: 11function

CCTKxWRAGH x symbasexwrapper x wrapper group for symbase x

11x11Type:11group

11

SymBasexWrapper x symmetryregister x register your symmetries here x

11x11Type:11group

11

SymBasexWrapper x symbasexstatistics x print symmetry boundary face descriptions x

11x11After: 11symmetryregister
11 x 11Language:11c
11 x 11Type: 11function

11

CCTKxBASEGRID x symbasexcheck x check whether the driver set up the grid consistently x

11x11Language:11c
11 x 11Type: 11function