xx Using Cartoon2D

Using Cartoon2D

Denis Pollney

Date

Abstract

The Cartoon2D thorn allows fully 3D codes to be used to model axisymmetric systems, by considering a 3D evolution which is only one plane thick and applying a rotational tensor transformation to the flat faces of the plane as a boundary condition. This allows 3D codes to be tested efficiently on 2D problems, as well as providing a means of carrying out axisymmetric evolutions in cartesian coordinates without problems at the axis.

1 Background

The Cartoon2D thorn is the implementation of an idea first presented in [1]. The principle is to use a 3-dimensional Cartesian coordinate grid which covers the plane, but is only one finite difference molecule in width in the -direction. The field variables in the plane can be updated using standard 3D coordinate finite differencing, with off-plane derivatives calculated by performing appropriate rotations of field variables using the axisymmetic assumption. This technique has the advantage of removing a number of the axis problems normally associated with axisymmetric codes.

The ‘cartoon’ method was first implemented in Cactus3 by Steve Brandt and Bernd Brxgmann, and was translated to Cactus4 by Sai Iyer. Details of the method can be found in [1]. This document provides a practical guide to using the thorn as it is currently implemented.

2 Basic usage

Only a small number of parameters need to be set to use Cartoon2D.

cartoonxactive

A flag which determines whether or not the cartoon boundary condition should be applied. This should be set to “yes” to use Cartoon2D, otherwise the evolution will be assumed to be standard 3D.

order

Determines the order of interpolations to be carried out. This will determine the number of ghost zones that you need to specify in the -direction.

allowxgridxresize

When this flag is set to “yes”, Cartoon2D is allowed to modify the grid sizes specified in the parameter file so that a cartoon-compatible grid is used. See below.

verbose

Causes Cartoon2D to print a lot of messages.

For example, the following is a section of a parameter file which sets up a cartoon-style grid in bitant mode.

activethornsxxxxxxxxxxxxxxxxxxxxxxxxxxxx=x"cartoon2dxcartgrid3dxpugh"
cartoon2d::cartoon_activexxxxxxxxxxxxxxx=x"yes"
cartoon2d::orderxxxxxxxxxxxxxxxxxxxxxxxx=x3
cartoon2d::allow_grid_resizexxxxxxxxxxxx=x"yes"
grid::typexxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=x"byspacing"
grid::domainxxxxxxxxxxxxxxxxxxxxxxxxxxxx=x"bitant"
grid::bitant_planexxxxxxxxxxxxxxxxxxxxxx=x"xy"
grid::dxyzxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=x0.2
driver::global_nxxxxxxxxxxxxxxxxxxxxxxxx=x16
driver::global_nyxxxxxxxxxxxxxxxxxxxxxxx=x3
driver::global_nzxxxxxxxxxxxxxxxxxxxxxxx=x16
driver::ghost_size_xxxxxxxxxxxxxxxxxxxxx=x2
driver::ghost_size_yxxxxxxxxxxxxxxxxxxxx=x1
driver::ghost_size_zxxxxxxxxxxxxxxxxxxxx=x2
driver::processor_topologyxxxxxxxxxxxxxx=x"manual"
driver::processor_topology_3d_xxxxxxxxxx=x1
driver::processor_topology_3d_yxxxxxxxxx=x1
driver::processor_topology_3d_zxxxxxxxxx=x2
grid::avoid_originyxxxxxxxxxxxxxxxxxxxxx=x"no"

The following features are worth noting:

The order parameter specifies that 3rd order interpolation is to be used. This requires that only one ghost zone is required in the y direction (ghostxsizexy). If 4th order interpolation was specified, then two ghost zones would be required.

The allowxgridxresize flag has been set, allowing Cartoon2D to modify the grid appropriately so that, for instance, it only extends a given number of ghost zones beyond the -axis.

The bitant plane should always be “xy”, which means that only the positive -axis is evolved and a reflection boundary is imposed along .

Though not necessary, it is often helpful to specify the processor topology explicitly to ensure that that only one processor is allocated to the direction, and that the processors in the and directions reflect the relative lengths of these axes (though in this example it doesn’t matter which of these axes gets two processors).

The avoidxoriginy parameter needs to be turned off so that the cartoon plane corresponds to .

Also, it is important to keep in mind that other thorns may also require their own parameters to be set in order to interact appropriately with Cartoon2D. For instance, see Section 4. Examples of working parameter files can be found in the Cartoon2D/test/ directory.

PIC Figurex1: The cartoon plane layout. The symmetry axis is the -axis, with grid functions defined on the plane, in this example with two ghost zones.

3 Automatic grid re-sizing

The Cartoon2D thorn has some non-standard requirements of the grid which is normally set up by the grid implementation (for instance, by CartGrid3D). In particular,

the grid in the direction should be exactly one plane in width, plus twice the number of ghost zones.

the grid in the direction only needs to extend to the -axis, plus a few extra hang-overs. The number of extra points is determined by the number of ghost zone points.

These requirements (in particular the second) can not be met if the grid is specified byspacing (ie. by giving a value), since in this case the grid is set up assuming that the axes should be centred in each grid direction.

One way to get around this is to specify the grid byrange, giving minimum and maximum coordinate values for each axis so that the values are determined by dividing the range by the number of grid points. However, using this method it can be quite complicated to ensure that the grid spacing is even in each direction and that an appropriate number of ghost points extend past the axis.

A simple hack to get around this complication is to specify the grid byspacing, but to set the allowxgridxresize parameter. In this case, the values can be set in the parameter file, and the grid ranges will be calculated based on the above criteria. Note that this involves modifying the “standard” behaviour of the CartGrid3D thorn (to place the -axis along one edge of the grid). This is accomplished by internally resetting the grid type to byrange, and then specifying ranges which are compatible with the cartoon conditions and with the appropriate number of grid points and ghost zones. Note that this involves a reset of otherwise non-steerable parameters, and so must be scheduled at CCTKxRECOVERxPARAMETERS and before the grid is set up.

4 Interaction with other thorns

Some thorns will need to know that a cartoon grid is being used in order to function properly. In principle, they should use the cartoonxactive parameter to check whether a cartoon grid is in use.

In practice, however, to avoid dependencies on Cartoon2D, it is often the case that the source code for such thorns make use of #ifdef statements to check whether Cartoon2D has been compiled in. Then, to check whether a cartoon grid is active, other thorn-specific parameters need to be set. For instance, if the ADMxBSSN thorn is being used for evolution, then the parameter

xxadm_bssn::cartoonx=x"yes"

must be set. Similarly, the ADM evolution system requires adm::cartoon to be set. The AHFinder thorn requires that the parameter

xxahfinder::ahf_cartoonx=x"yes"

be set in order to use a cartoon grid.

Note that many thorns will require cartoon-specific modifications in order to be used with the Cartoon2D thorn. It should not be assumed that a given thorn will work with Cartoon2D unless it is specifically mentioned in the documentation or source code.

5 Source code

The interface to the Cartoon2D thorn is through the routines contained in the Cartoon2DBC.c source file. These routines can be used by other thorns (eg. evolution thorns) to apply cartoon boundary conditions to grid functions whenever it is appropriate to do so. The three interface functions are:

BndCartoon2DGN(cGH *GH, int tensortype, const char* group)

This function applies the cartoon boundary condition to the grid functions in the group specified by the group parameter. The tensortype argument parameter should be one of

     TENSORTYPExSCALAR

a scalar;

     TENSORTYPExU

a vector (single, upper index);

     TENSORTYPExDDSYM

a symmetric tensor with two lower indices.

BndCartoon2DVN(cGH *GH, int tensortype, const char *impvarname)

This function is like BndCartoon2DGN(), but operates on individual grid functions rather than groups.

BndCartoon2DVI(cGH *GH, int tensortype, int vi)

This function is like BndCartoon2DGN(), but operates takes a grid function index to indicate the grid function to which the condition should be applied.

A corresponding Fortran wrapper for each of these functions is also included.

Interpolation operators are defined in the file interpolate.c.

The file SetSym.c contains routines which re-label the flat faces of the cartoon grid as CARTOONxNOSYM boundaries. This prevents any other boundary condition (eg. physical or symmetry conditions) from being applied to these faces, as they are determined by the Cartoon2D thorn. These routines need to be scheduled before the first time boundary conditions are applied to any grid function.

The file SetGrid.c contains the code to reset the grid dimensions in a cartoon-friendly way (see Section 3) if the byspacing grid type is used. In this case, appropriate coordinate grid ranges are calculated so that the values are preserved, and the parameters specifying the grid are reset. These are non-steerable, and so the routine must be run during the CCTKxRECOVERxPARAMETERS time bin in order to work. (This time bin is run even when checkpoint recovery is not being used.)

References

[1]xxxMiguel Alcubierre, Steven Brandt, Bernd Brxgmann, Daniel Holz, Edward Seidel, Ryoji Takahashi, Jonathan Thornburg (2001) Symmetry without symmetry: Numerical simulation of Axisymmetric Systems using Cartesian Grids, Int. J. Mod. Phys. D, 10, 273–289, (gr-qc/9908012).

6 Parameters

11allowxgridxresize 10Scope: privatex01  BOOLEAN

11Description: Allow grid to be resized in a cartoon-compatible way

11                 10  x01  Default: no

11

11cartoonxactive  10Scope: privatex01  BOOLEAN

11Description: Activate cartoon boundary condition

11                 10  x01  Default: no

11

11enoxorder  10Scope: privatex01  INT

11Description: The interpolation order applied to the ENO interpolator

11 Range 10 x01 Default: 4
111:5  10From linear to fifth order.

11

11newxexcision  10Scope: privatex01  BOOLEAN

11Description: Are we doing excision based on the new style mask?

11                 10  x01  Default: no

11

11newxmaskxexcisedxname 10Scope: privatex01  STRING

11Description: The name of the descriptor that says the point is excised for the new mask

11 Range 10 x01 Default: (none)
11.*  10Could be anything

11

11newxmaskxfieldxname 10Scope: privatex01  STRING

11Description: The name of the field that describes excision for the new mask

11 Range 10 x01 Default: (none)
11.*  10Could be anything

11

11newxstylexexcisionxvar 10Scope: privatex01  STRING

11Description: The variable to be checked for new style excision

11 Range 10 x01 Default: (none)
11.*  10”Expected to be \’Spacemask::spacexm ask\’”

11

11oldxexcision  10Scope: privatex01  BOOLEAN

11Description: Are we doing excision based on the old style mask?

11                 10  x01  Default: no

11

11oldxstylexexcisionxvar 10Scope: privatex01  STRING

11Description: The variable to be checked for old style excision

11 Range 10 x01 Default: (none)
11.*  10”Expected to be \’Spacemask::emask\’ ”

11

11order  10Scope: privatex01  INT

11Description: Cartoon’s interpolation order

11 Range 10 x01 Default: 4
111:5  10From linear to fifth order.

11

11stencil  10Scope: privatex01  BOOLEAN

11Description: Use custom 2D stencil if available

11                 10  x01  Default: yes

11verbose  10Scope: privatex01  BOOLEAN

11Description: Verbose information

11                 10  x01  Default: no

11

7 Interfaces

General Implements: cartoon2d

Grid Variables

7.0.1 PRIVATE GROUPS

11x Group Names x10 x Variable Names x x01 Details x11x
11 excisionxvariables 10  x01  compact110
11                 10  excisionxactive  x01 description11Internal variables to store information about excision
11                 10  oldxmaskxvi  x01 dimensions110
11                 10  newxmaskxvi  x01 distribution11CONSTANT
11                 10 newxexcisionxfield x01 group type11SCALAR
11                 10newxexcisionxdescriptorx01 timelevels111
11                 10  x01variable type11INT

11

Adds header: Cartoon2Dxtensors.h Cartoon2D.h

Uses header: SpaceMask.h 8 Schedule This section lists all the variables which are assigned storage by thorn CactusNumerical/Cartoon2D. 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

11x11Conditional:
11x 11excisionxvariables

11x 11x

11

Scheduled Functions

CCTKxPARAMCHECK (conditional) x cartoon2dxchecktensortypes x check tensor type definitions for consistency x

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

11

CCTKxBASEGRID (conditional) x cartoon2dxinitexcisionvars x initialize the excision variables x

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

11

CCTKxRECOVERxPARAMETERS (conditional) x cartoon2dxsetgrid x adjust grid sizes x

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

11

SymmetryRegister (conditional) x cartoon2dxregistersymmetries x register symmetry boundaries

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

11

CCTKxPARAMCHECK (conditional) x cartoon2dxcheckparameters x check cartoon2d parameters x

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

11

BoundaryConditions (conditional) x cartoonxapplyboundaries x apply cartoon boundary conditions x

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