xx CartGrid3D

CartGrid3D

Gabrielle Allen Gerd Lanfermann

Joan Masso Jonathan Thornburg

Date

Abstract

CartGrid3D allows you to set up coordinates on a 3D Cartesian grid in a flexible manner. You can choose different grid domains (eg octant) to allow you to exploit any symmetry in your problem. CartGrid3D also provides routines for registering symmetries of grid functions and applying symmetry conditions across the coordinate axes.

1 Specifying the Grid Symmetry

CartGrid3D allows you to specify the grid symmetry (or lack thereof) with the grid::domain parameter:

grid::domain = "full"

There are no symmetries.

grid::domain = "bitant"

The grid includes only the half-space (plus symmetry zones); there is a reflection symmetry across the plane.

grid::domain = "quadrant"

The grid includes only the quadrant (plus symmetry zones); there is a reflection symmetry across both the plane and the plane.

grid::domain = "octant"

The grid includes only the octant (plus symmetry zones); there is a reflection symmetry across each of the plane, the plane, and the plane.

Note that the implementation of symmetries in CartGrid3D is deprecated, and the SymBase infrastructure should be used instead. The above symmetries can be implemented using SymBase and the ReflectionSymmetry thorn. Additionally, there are rotational symmetries provided by the RotatingSymmetry180 and RotatingSymmetry90 thorns.

In each case except grid::domainx=x"full", symmetry zones are introduced just on the “other side” of each symmetry grid boundary. Each symmetry zone has a width (perpendicular to the boundary) of driver::ghost_size extra grid points. For centered 2ndxorder finite differencing, a width of driver::ghost_sizex=x1 should be sufficient, but for (centered) 4thxorder finite differencing, or for upwinded 2ndxorder, a width of driver::ghost_sizex=x2 is needed. Making driver::ghost_size too large is fairly harmless (it just slightly reduces performance), but making it too small will almost certainly result in horribly wrong finite differencing near the symmetry boundaries, and may also result in core dumps from out-of-range array accessing.

Note that the symmetry zones must be explicitly included in driver::global_nx, driver::global_ny, and driver::global_nz, but should not be included in any of the grid::typex=x"byrange" parameters

grid::xmin, grid::xmax, grid::ymin, grid::ymax, grid::zmin, grid::zmax, grid::xyzmin, and/or

grid::xyzmax described in the next section.

Note also that driver::global_nx, driver::global_ny, and driver::global_nz do not include any ghost

zones introduced for multiprocessor synchronization. (For more information on ghost zones, see the section “Ghost Size” in the “Cactus Variables” chapter of the Cactus Users’ Guide.)

2 Specifying the Grid Size, Range, and Spacing

CartGrid3D provides several different methods for setting up the integer grid size (eg 128), floating-point grid spacing (eg 0.1), and floating-point grid range (eg

12.8).1 ^{1If you’re AMR-ing, this all refers to the coarsest or base grid.} You specify which method to use, with the grid::type parameter:

grid::type = "byrange"

You specify the , , and grid ranges, either with separate grid::xmin, grid::xmax,

grid::ymin, grid::ymax, grid::zmin, and grid::zmax parameters, or with the grid::xyzmin

and grid::xyzmax parameters. The grid spacings are then determined automagically from this

information and the driver::global_nx, driver::global_ny, and driver::global_nz grid-size

parameters. You should also choose the grid::domain parameter consistent with all these other parameters. (It’s not clear whether or not the code ever explicitly checks this.)

grid::type = "box"

This is a special case of grid::typex=x"byrange" with the grid ranges hard-wired to

grid::xyzminx=x-0.5 and grid::xyzmaxx=x+0.5.

grid::type = "byspacing"

You specify the , , and grid spacings, either with separate grid::dx, grid::dy, and grid::dz parameters, or with the grid::dxyz parameter. You also specify the grid symmetry with the grid::domain parameter. The , , and grid ranges are then determined automagically from this

information and the driver::global_nx, driver::global_ny, and driver::global_nz grid-size

parameters: Each coordinate’s range is chosen to be either symmetric about zero, or to extend from 0 up to a maximum value.

There are also a number of optional parameters which can be used to specify whether or not it’s ok to have a grid point with an , , and/or coordinate exactly equal to 0:

grid::noxoriginx, grid::noxoriginy, grid::noxoriginz, grid::noxorigin

These parameters are all deprecated — don’t use them!

grid::avoidxoriginx

This  is  a  Boolean

parameter; if set to true (grid::avoid_originxx=x"true" or grid::avoid_originxx=x"yes" or

grid::avoid_originxx=x1) then the grid will be “half-centered” across , ie there will be grid points at x, , , , , x, but not at .

grid::avoidxoriginy

Same thing for .

grid::avoidxoriginz

Same thing for .

grid::avoidxorigin

Same thing for all 3 axes and and , ie no grid point will have or or .

3 An Example Here is an example of setting up a grid using the PUGH unigrid driver. The relevant parts of the parameter file are as follows:

#xPUGH
driver::ghost_sizex=x2
driver::global_nxx=x61
driver::global_nyx=x61
driver::global_nzx=x33
#xCartGrid3D
grid::avoid_originx=x"no"
grid::domainx=x"bitant"
grid::typex=x"byrange"
grid::xminx=x-3.0
grid::xmaxx=x+3.0
grid::yminx=x-3.0
grid::ymaxx=x+3.0
grid::zminx=xx0.0
grid::zmaxx=x+3.0

The resulting Cactus output (describing the grid) is as follows:

INFOx(CartGrid3D):xGridxSpacings:
INFOx(CartGrid3D):xxdx=>1.0000000e-01xxdy=>1.0000000e-01xxdz=>1.0000000e-01
INFOx(CartGrid3D):xComputationalxCoordinates:
INFOx(CartGrid3D):xxx=>[-3.000,x3.000]xxy=>[-3.000,x3.000]xxz=>[-0.200,x3.000]
INFOx(CartGrid3D):xIndicesxofxPhysicalxCoordinates:
INFOx(CartGrid3D):xxx=>[0,60]xxy=>[0,60]xxz=>[2,32]
INFOx(PUGH):xSinglexprocessorxevolution
INFOx(PUGH):x3-dimensionalxgridxfunctions
INFOx(PUGH):xxxSize:x61x61x33

Since there’s no symmetry in the and directions, the grid is set up just as specified, with floating-point coordinates running from to inclusive, and 61xgrid points with integer grid indices (C) or (Fortran).

However, in the direction there’s a reflection symmetry across the plane, so the specified range of the grid, , is automagically widened to include the symmetry zone of driver::ghost_sizex=x2 grid points. The grid thus actually includes the range of floating-point coordinates . The original specification of 33xgrid points is left alone, however, so the grid points have integer array indices (C) or (Fortran). The “physical” (ie non-symmetry-zone) part of the grid is precisely the originally-specified range, , and has the integer array indices (C) or (Fortran).

4 Coordinates

CartGrid3D defines (registers) four coordinate systems: cart3d, cart2d, cart1d, and spher3d.

The Cartesian coordinates supplied by this thorn are grid functions with the standard names x, y, and z. To use these coordinates you need to inherit from grid, ie you need to have an

inherits:xgrid

line in your interface.ccl file. In addition a grid function r is provided, containing the radial coordinate from the origin where

. r = \sqrt{x^{2} + y^{2} + z^{2}}

CartGrid3D registers the lower and upper range of each coordinate with the flesh.

5 Symmetries for Grid Functions

If your problem and initial data allow it, CartGrid3D allows you to enforce even or odd parity for any grid function at (across) each coordinate axis. For a function , even parity symmetry on the -axis means

. ϕ(−x, y, z) = ϕ(x, y, z)

while odd parity symmetry means . ϕ(−x, y, z) = −ϕ(x, y, z)

Note that the symmetries will only be enforced if a symmetry domain is chosen (that is, if grid::domain is set

to something other than grid::domainx=x"full".

5.1 Registering Symmetry Behaviour

Each grid function can register how it behaves under a coordinate change using function calls in CartGrid3D. These symmetry properties can then be used by other thorns, for example CactusBase/Boundary uses them to enforce symmetry boundary conditions across coordinate axes. Symmetries should obviously be registered before they are used, but since they can be different for different grids, they must be registered after the CCTKxSTARTUP timebin. The usual place to register symmetries is in the CCTKxBASEGRID timebin.

For example, to register the symmetries of the xy component of the metric tensor from C, you first need to get access to the include file by putting the line

usesxinclude:xSymmetry.h

in your interface.ccl file. Then in your thorn you can write (C)

#includex"Symmetry.h"
staticxintxone=1;
intxsym[3];
sym[0]x=x-one;
sym[1]x=x-one;
sym[2]x=xxone;
SetCartSymVN(cctkGH,xsym,"ADMBase::gxy");

5.2 Calling Symmetry Boundary Conditions

CartGrid3D provides the following two routines to apply symmetry boundary conditions to a variable group:

CartSymGI(cGHx*GH,xintx*gi)
CartSymGN(cGHx*GH,xconstxcharx*gn)

and for a specific variable it provides:

CartSymVI(cGHx*GH,xintx*vi)
CartSymVN(cGHx*GH,xconstxcharx*gn)

A group or variable can be specified by its index value or name (use the ’I’ or ’N’ version respectively). The Fortran versions of these functions take an additional first argument, which is an integer which will hold the return value.

6 Parameters

11avoidxorigin 10Scope: privatex01 BOOLEAN

11Description: Don’t place grid points on the coordinate origin/axes

11  Range  10  x01  Default: yes

11:  10

11

11avoidxoriginx  10Scope: privatex01  BOOLEAN

11Description: Don’t place grid points on the x-coordinate origin/axes

11  Range  10  x01  Default: yes

11:  10

11

11avoidxoriginy  10Scope: privatex01  BOOLEAN

11Description: Don’t place grid points on the y-coordinate origin/axes

11  Range  10  x01  Default: yes

11:  10

11

11avoidxoriginz  10Scope: privatex01  BOOLEAN

11Description: Don’t place grid points on the z-coordinate origin/axes

11  Range  10  x01  Default: yes

11:  10

11

11noxorigin  10Scope: privatex01  BOOLEAN

11Description: DEPRECATED: Don’t place grid points on the coordinate origin/axes

11  Range  10  x01  Default: yes

11:  10

11

11noxoriginx  10Scope: privatex01  BOOLEAN

11Description: DEPRECATED: Don’t place grid points on the x-coordinate origin/axes

11  Range  10  x01  Default: yes

11:  10

11noxoriginy  10Scope: privatex01  BOOLEAN

11Description: DEPRECATED: Don’t place grid points on the y-coordinate origin/axes

11  Range  10  x01  Default: yes

11:  10

11

11noxoriginz  10Scope: privatex01  BOOLEAN

11Description: DEPRECATED: Don’t place grid points on the z-coordinate origin/axes

11  Range  10  x01  Default: yes

11:  10

11

11registerxdefaultxcoordinatexsystems 10Scope: privatex01  BOOLEAN

11Description: register cartnd as the default coordinate systems

11                            10  x01  Default: yes

11

11setxcoordinatexrangesxon  10Scope: privatex01  KEYWORD

11Description: On which grids to set the coordinate ranges

11 Range 10 x01 Default: all grids
11all grids  10set ranges in local mode, on the coarsest level
11all maps  10set ranges in singlemap mode, on the coarsest level
11first level  10set ranges in level mode, on the first level

11

11bitantxplane  10Scope: restrictedx01  KEYWORD

11Description: Plane defining bitant domain

11 Range 10 x01 Default: xy
11xy  10xy-plane
11xz  10xz-plane
11yz  10yz-plane

11

11domain  10Scope: restrictedx01  KEYWORD

11Description: Domain type

11 Range 10 x01 Default: full
11octant  10Use an octant about the origin
11quadrant  10Use a quadrant in x-y plane
11see [1] below  10Use a quadrant with rotation symmetry about an axis
11bitant  10Use a bitant about the x-y plane
11bitantxrotate  10Use a bitant with rotation symmetry about an axis
11full  10Use the full domain

11

quadrant\_reflect\_rotate

11dx  10Scope: restrictedx01  REAL

11Description: Coarse grid spacing in x-direction

11 Range 10 x01 Default: 0.3
110:*  10Positive

11

11dxyz  10Scope: restrictedx01  REAL

11Description: Coarse grid spacing in x,y,z-directions

11 Range 10 x01 Default: 0.0
110:*  10Positive

11

11dy  10Scope: restrictedx01  REAL

11Description: Coarse grid spacing in y-direction

11 Range 10 x01 Default: 0.3
110:*  10Positive

11

11dz  10Scope: restrictedx01  REAL

11Description: Coarse grid spacing in z-direction

11 Range 10 x01 Default: 0.3
110:*  10Positive

11

11quadrantxdirection  10Scope: restrictedx01  KEYWORD

11Description: Direction defining quadrant domain

11 Range 10 x01 Default: z
11x  10x-direction
11y  10y-direction
11z  10z-direction

11

11rotationxaxis  10Scope: restrictedx01  KEYWORD

11Description: Axis about which the rotation symmetry is to be applied

11 Range 10 x01 Default: z
11x  10x-axis
11y  10y-axis
11z  10z-axis

11

11symmetryxxmax  10Scope: restrictedx01  BOOLEAN

11Description: Symmetry boundary condition on upper x boundary

11 Range 10 x01 Default: no
11:  10Logical

11

11symmetryxxmin  10Scope: restrictedx01  BOOLEAN

11Description: Symmetry boundary condition on lower x boundary

11 Range 10 x01 Default: no
11:  10Logical

11

11symmetryxymax  10Scope: restrictedx01  BOOLEAN

11Description: Symmetry boundary condition on upper y boundary

11 Range 10 x01 Default: no
11:  10Logical

11symmetryxymin  10Scope: restrictedx01  BOOLEAN

11Description: Symmetry boundary condition on lower y boundary

11 Range 10 x01 Default: no
11:  10Logical

11

11symmetryxzmax  10Scope: restrictedx01  BOOLEAN

11Description: Symmetry boundary condition on upper z boundary

11 Range 10 x01 Default: no
11:  10Logical

11

11symmetryxzmin  10Scope: restrictedx01  BOOLEAN

11Description: Symmetry boundary condition on lower z boundary

11 Range 10 x01 Default: no
11:  10Logical

11

11type  10Scope: restrictedx01  KEYWORD

11Description: Grid type

11 Range 10 x01 Default: box
11box  10Box grid from -0.5 to 0.5
11byrange  10Specify min and max values
11byspacing  10Specify grid spacings
11coordbase  10Get specification from CoordBase
11multipatch  10Get specification from MultiPatch

11

11xmax  10Scope: restrictedx01  REAL

11Description: Coordinate maximum in x-direction

11 Range 10 x01 Default: 1.0
11:  10Anything

11

11xmin  10Scope: restrictedx01  REAL

11Description: Coordinate minimum in x-direction

11 Range 10 x01 Default: -1.0
11:  10Anything

11

11xyzmax  10Scope: restrictedx01  REAL

11Description: Coordinate maximum in xyz-directions

11 Range 10 x01 Default: -424242
11:  10Anything

11

11xyzmin  10Scope: restrictedx01  REAL

11Description: Coordinate minimum in x,y,z-directions

11 Range 10 x01 Default: -424242
11:  10Anything

11

11ymax  10Scope: restrictedx01  REAL

11Description: Coordinate maximum in y-direction

11 Range 10 x01 Default: 1.0
11:  10Anything

11

11ymin  10Scope: restrictedx01  REAL

11Description: Coordinate minimum in y-direction

11 Range 10 x01 Default: -1.0
11:  10Anything

11zmax  10Scope: restrictedx01  REAL

11Description: Coordinate maximum in z-direction

11 Range 10 x01 Default: 1.0
11:  10Anything

11

11zmin  10Scope: restrictedx01  REAL

11Description: Coordinate minimum in z-direction

11 Range 10 x01 Default: -1.0
11:  10Anything

11

11periodic  10Scope: shared from DRIVERx01BOOLEAN

11

11periodicxx  10Scope: shared from DRIVERx01BOOLEAN

11

11periodicxy  10Scope: shared from DRIVERx01BOOLEAN

11

11periodicxz  10Scope: shared from DRIVERx01BOOLEAN

11

7 Interfaces

General Implements: grid

Inherits: coordbase

Grid Variables

7.0.1 PUBLIC GROUPS

11x Group Names x10x Variable Names xx01 Details x11x
11 gridspacings 10  x01  compact110
11                 10  coarsexdx  x01 description113D Cartesian grid spacings
11                 10  coarsexdy  x01 dimensions110
11                 10  coarsexdz  x01 distribution11CONSTANT
11                 10  x01 group type11SCALAR
11 10 x01 tags11Checkpoint=”no”
11                 10  x01 timelevels111
11                 10  x01variable type11REAL
11  coordinates  10  x01  compact110
11                 10  x  x01 description113D Cartesian grid coordinates
11                 10  y  x01 dimensions113
11                 10  z  x01 distribution11DEFAULT
11                 10  r  x01 group type11GF
11                 10  x01  tags11Prolongation=”None” Checkpoint=”no”
11                 10  x01 timelevels111
11                 10  x01variable type11REAL

11

Adds header: Symmetry.h

Uses header: CoordBase.h

8 Schedule This section lists all the variables which are assigned storage by thorn CactusBase/CartGrid3D. 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 x

11Always:  11x
11coordinates gridspacings11x

11x  11x

11

Scheduled Functions

CCTKxSTARTUP x symmetrystartup x register gh extension for gridsymmetry

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

11

CCTKxWRAGH x registercartgrid3dcoords x register coordinates for the cartesian grid x

11x11Language:11c
11 x 11Options: 11meta
11 x 11Type: 11function

11

BoundaryConditions x cartgrid3dxapplybc x apply symmetry boundary conditions x

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

11

SymmetryRegister x cartgrid3dxregistersymmetryboundaries x register symmetry boundaries x

11x11Language:11c
11 x 11Options: 11meta
11 x 11Type: 11function

11

CCTKxPARAMCHECK x paramcheckxcartgrid3d x check coordinates for cartgrid3d x

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

11

CCTKxBASEGRID (conditional) x cartgrid3dxsetranges x set up ranges for spatial 3d cartesian coordinates (on all grids) x

11x11Before: 11spatialcoordinates
11 x 11Language:11c
11 x 11Type: 11function
11 x 11Writes: 11grid::gridspacings(everywhere)

11

CCTKxBASEGRID (conditional) x cartgrid3dxsetranges x set up ranges for spatial 3d cartesian coordinates (on all maps) x

11x11Before: 11spatialcoordinates
11 x 11Language:11c
11 x 11Options: 11singlemap
11 x 11Type: 11function
11 x 11Writes: 11grid::gridspacings(everywhere)

11

CCTKxBASEGRID (conditional) x cartgrid3dxsetranges x set up ranges for spatial 3d cartesian coordinates (on first level) x

11x11Before: 11spatialcoordinates
11 x 11Language:11c
11 x 11Options: 11level
11 x 11Reads: 11grid::gridspacings(everywhere)
11 x 11Type: 11function

11

CCTKxBASEGRID x cartgrid3dxsetcoordinates x set up spatial 3d cartesian coordinates on the gh x

11x11Language:11c
11 x 11Type: 11function
11 x 11Writes: 11grid::coordinates(everywhere)

11

CCTKxPOSTREGRIDINITIAL x cartgrid3dxsetcoordinates x set coordinates after regridding x

11x11Language:11c
11 x 11Type: 11function
11 x 11Writes: 11grid::coordinates(everywhere)

11

CCTKxPOSTREGRID x cartgrid3dxsetcoordinates x set coordinates after regridding x

11x11Language:11c
11 x 11Type: 11function
11 x 11Writes: 11grid::coordinates(everywhere)

11

Aliased Functions

11Alias Name: xxxxxxx 11Function Name:
11CartGrid3DxSetCoordinates11SpatialCoordinates
11CartGrid3DxSetRanges  11SpatialSpacings