xx Boundary Conditions

Boundary Conditions

Miguel Alcubierre Gabrielle Allen Gerd Lanfermann David Rideout

Date

Abstract

Provides a generic interface to boundary conditions, and provides a set of standard boundary conditions for one, two, and three dimensional grid variables.

1 Introduction

This thorn provides a generic method for registering routines to perform boundary conditions, and selecting variables to have these boundary conditions applied to them. In addition, it provides abstraction which allows all considerations of symmetry to be separated from those of physical boundary conditions. The general idea is that codes which use boundary conditions, be they physical or symmetry conditions, need not know anything about the thorns which provide them.

This thorn also contains some standard boundary conditions, most of which can be used with any spatial dimension and data type.

1.1 Local and non-local boundary conditions

Boundary conditions can be local, meaning that the boundary point can be updated based on data in its immediate vicinity, or non-local, meaning that the new value on the boundary depends on data from a remote region of the computational domain (for a parallel simulation this data could for example be physically located on several different processors). An example of the latter is a “rotating” symmetry condition, which arises e.g.xwhen one uses a quadrant to simulate a physical domain which possesses a rotational symmetry.

1.2 Symmetry and physical boundary conditions

Symmetry boundary conditions are those that arise by viewing the computational domain as a subregion of some larger domain which possesses symmetries. These symmetries allow a simulation of the subregion to act as an effective simulation of the larger encompassing domain, because the latter can be inferred from the former via the symmetry. For example, one can often simulate a rotating star by ‘slicing’ the space in half through the equatorial plane, simulating only one half, and placing a reflection boundary condition at this plane. The symmetry can be regarded as a property of the underlying computational grid upon which the simulation takes place.

It is often possible to describe the symmetry of a physical problem in terms of multiple ‘simpler’ symmetries. Going back to the rotating star example, we can note that there is also a rotational symmetry about the axis of the star. Thus it is sufficient to simulate only the upper half of a plane of the star, since rotational symmetry will recover half of the star from the single plane, and the reflection symmetry can recover the other half of the star. To do this we use two symmetry boundary conditions, one for the rotational symmetry and one for the reflection symmetry. At the edges and corner grid points there will be two symmetry boundary conditions active, which illustrates a general point about symmetry boundary conditions, namely that there can be any number of them active at any given grid point. In addition symmetry boundary conditions are often non-local, for example a periodic boundary condition which applies in simulating plasma in a tokamak.

Physical boundary conditions are motivated by the physics of the quantity that the grid variable represents, such as one which allows outgoing waves of a scalar field to propagate off the grid, but does not allow ingoing waves or reflections. Usually the same physical boundary condition is applied to all external boundaries of the computational domain, however this is not always the case. Currently thorn Boundary allows a separate boundary condition to be applied to each face of the domain, however this is only implemented at the moment using the older deprecated interface. Face specific calls will be available using the current interface shortly. It is also possible that one will want to use different physical boundary conditions at different regions of a face, and support for this can be added if necessary. Usually physical boundary conditions are local. A non-local physical boundary condition may arise e.g.xfrom a need to solve an elliptic equation at the boundary. As opposed to symmetry boundary conditions, it only makes sense to have a single physical boundary condition active at a given grid

point.1 1It is possible that one may wish to modify the value of the field at the boundary, after a physical boundary condition has already been applied. For example, one may wish to add a small amount of noise at the boundary to test code stability. This added ‘term’ is not a physical boundary condition in itself, however, and this cannot be registered as such. To implement such a scheme one would treat the noise in a manner similar to symmetry boundary conditions, scheduling a routine during BoundaryConditions (see below), after BoundaryxApplyPhysicalBCs, which gets the list of selected variables and adds noise to their boundaries as desired.

To summarize, a ‘physics’ thorn, such as a spacetime evolution thorn, knows only about physical boundary conditions. Symmetry boundary conditions are aspects of the grid and are managed by other thorns.

2 The generic boundary interface

The implementation Boundary provides a number of aliased functions, which allow application thorns to register routines which provide a particular physical boundary condition, and also to select variables or groups of variables to have boundary conditions applied to whenever the ApplyBCs schedule group is scheduled (see section 2.3). In addition, an aliased function is provided which returns a list of grid variables selected for a boundary condition (see appendix 11).

2.1 Boundary condition registration

To register a routine to provide some physical boundary condition, use

Boundary_RegisterPhysicalBC(CCTK_POINTERxcctkGH,
xxxxxxxxxxxxxxxxxxxxxxxxxxxxphys_bc_fn_ptrxfunction_pointer,
xxxxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_STRINGxbc_name)

where

11cctkGH         11pointer to the grid hierarchy
11functionxpointer11pointer to the function providing the boundary condition
11bcxname         11name of boundary condition

The function pointer takes arguments

(CCTK_POINTERxcctkGH,xCCTK_INTxnum_vars,xCCTK_INTx*var_indices,
xCCTK_INTx*faces,xCCTK_INTx*widths,xCCTK_INTx*table_handles)

(this defines the type physxbcxfnxptr, above) where

11cctkGH      11pointer to the grid hierarchy
11numxvars     11number of entries passed in the following three arrays
11varxindices  11array of numxvars variable indices selected for this boundary condition
11faces        11array of numxvars faces specifications (see section 2.4)
11widths       11array of numxvars boundary widths (see below)

11tablexhandles11array of numxvars table handles

The table handles hold extra arguments for each application of the boundary condition. The four arrays are sorted first on table handle, and then on variable index. This way variables which have precisely the same boundary condition are grouped together, and within this grouping variables are sorted by index, so that variable groups are stored together. In many cases this sorting will allow a more efficient implementation of the boundary condition. (At the moment it is not clear how face information should be considered in the sorting, so it is not.) A null pointer can be passed for functionxpointer, in which case no routine is executed when BoundaryxApplyPhysicalBCs is called (see section 2.3).

2.2 Boundary condition selection

To select a grid variable to have a boundary condition applied to it, use one of the following aliased functions:

Boundary_SelectVarForBC(CCTK_POINTERxcctkGH,
xxxxxxxxxxxxxxxxxxxxxxxxCCTK_INTxfaces,
xxxxxxxxxxxxxxxxxxxxxxxxCCTK_INTxboundary_width,
xxxxxxxxxxxxxxxxxxxxxxxxCCTK_INTxtable_handle,
xxxxxxxxxxxxxxxxxxxxxxxxCCTK_STRINGxvar_name,
xxxxxxxxxxxxxxxxxxxxxxxxCCTK_STRINGxbc_name)
Boundary_SelectVarForBCI(CCTK_POINTERxcctkGH,
xxxxxxxxxxxxxxxxxxxxxxxxCCTK_INTxfaces,
xxxxxxxxxxxxxxxxxxxxxxxxCCTK_INTxboundary_width,
xxxxxxxxxxxxxxxxxxxxxxxxCCTK_INTxtable_handle,
xxxxxxxxxxxxxxxxxxxxxxxxCCTK_INTxvar_index,
xxxxxxxxxxxxxxxxxxxxxxxxCCTK_STRINGxbc_name)
Boundary_SelectGroupForBC(CCTK_POINTERxcctkGH,
xxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_INTxfaces,
xxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_INTxboundary_width,
xxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_INTxtable_handle,
xxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_STRINGxgroup_name,
xxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_STRINGxbc_name)
Boundary_SelectGroupForBCI(CCTK_POINTERxcctkGH,
xxxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_INTxfaces,
xxxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_INTxboundary_width,
xxxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_INTxtable_handle,
xxxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_INTxgroup_index,
xxxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_STRINGxbc_name)

where

11cctkGH       11pointer to the grid hierarchy
11faces         11set of faces to which to apply the boundary condition
11boundaryxwidth11width (in grid points) of the boundaries
11tablexhandle  11handle for table which holds extra arguments for the boundary condition
11varxname      11name of the grid variable
11bcxname       11name of the boundary condition
11varxindex     11index of grid variable
11groupxname    11name of group of grid variables
11groupxindex   11index of group of grid variables

Each of these functions returns 0 for success, or one of the negative error codes below something went wrong.

11error code11description
11         -211no such physical boundary condition registered
11         -311faces already selected for bc
11         -511new value for GH passed in
11         -611invalid group name or index
11         -711invalid variable index
11         -811group has zero vars
11        -1111invalid variable name

11

Boundary_SelectVarForBC() and Boundary_SelectVarForBCI() select a single grid variable for a boundary

condition, using either the variable name or index respectively. Boundary_SelectGroupForBC() and Boundary_SelectGroupForBCI() select an entire variable group, using either its name or index.

Each of these functions takes a faces specification, a boundary width, and a table handle as additional arguments. The faces specification is a single integer which identifies a set of faces to which to apply the boundary condition. See section 2.4 for details. The boundary width is the thickness, in grid points, of the boundaries.

The table handle identifies a table which holds extra arguments for the particular boundary condition that is requested. For example, if a negative value is passed for the boundary width, then the boundary condition will look in this table for a -element integer array, which holds the width of each face of the boundary (for a dimensional grid variable). (The first element of the array holds the width of the ‘-x’ face, the second the ‘+x’ face, the third the ‘-y’ face, etc.)

In some cases the table handle is required, so the boundary condition, when it is called within the BoundaryConditions schedule group (see section 2.3), will return an error code. However, in most cases it is optional. If one uses an invalid table handle here (such as -1), commonly used default values will be assumed for all arguments (besides the explicit faces specification and boundary widths). Note that you, the user, will be creating the table, so you may choose whatever options (such as case sensitivity) you like. The case of the keys for which the boundary conditions implemented in this thorn search are as given in the documentation, which is currently all capitals. To be safe you may choose to create case-insensitive tables, however case sensitive tables are slightly faster.

The name of the boundary condition must match that with which the boundary condition providing function was registered. These names are case insensitive. See section 3 for a list of boundary conditions provided by

thorn Boundary.

2.3 Schedule groups

Implementation Boundary creates two schedule groups

ApplyBCs

and

BoundaryConditionsxinxApplyBCsxBEFORExBoundary_ClearSelection
 and schedules two functions BoundaryxApplyPhysicalBCs in BoundaryConditions and BoundaryxClearSelection

in ApplyBCs. BoundaryxApplyPhysicalBCs goes through the list of all selected grid variables, and calls the registered function corresponding to the requested boundary condition on each. BoundaryxClearSelection clears the list of selected grid variables. A thorn which wishes to have boundary conditions applied simply schedules ApplyBCs at the appropriate point. Please schedule it as e.g.x<MyThorn>_ApplyBCs, to make each instance of it unique. BoundaryxClearSelection ensures that each boundary condition gets executed exactly once for each selected grid variable.

2.4 Faces

The computational domain is assumed to be in the shape of a -dimensional ‘rectangle’, which has dimensional faces. (Usually is three.) Each of these faces is assigned a specific bit in a word, so that arbitrary subsets can be compactly expressed as a bitwise-or of these individual bits. Macros defining this mapping of subsets to bits will be provided. For the moment there is only CCTKxALLxFACES, which corresponds to the set of all faces of the domain. If you need face specific calls immediately, please use the old interface for now.

The mapping of bits to faces will likely be the same as that used for the (optional) BOUNDARYxWIDTH array. Precisely, the rule is as follows. For a dimensional grid variable, label the elements or bits by integers from to . Element or bit gets mapped to face , where designates the ‘floor’ function (greatest integer less than its argument), and represents the ‘-direction’ on the grid.

3 Provided boundary conditions

Thorn Boundary also provides seven standard boundary conditions, which can be applied to one, two, or three dimensional grid variables. The boundary conditions available are

Scalar Flat Radiation Copy Robin Static None

Registration for each of these can be switched off by setting any of the following parameters to “no” (each defaults to “yes”)

registerxscalar
registerxflat
registerxradiation
registerxcopy
registerxrobin
registerxstatic

     registerxnone

This is useful if you have your own implementation of one of these boundary conditions, which you would like to use instead.

3.1 General Comments

Note that the number of boundary zones, as expressed in the boundaryxwidth argument or the BOUNDARYxWIDTH array, is taken from the total number of grid points presented by Cactus through cctkxlsh, etc.

For the moment, these boundary routines may not work properly on grid arrays. Please contact

cactusmaint@cactuscode.org if you run into trouble.

3.1.1 Old interface

The old, direct function call interface to these boundary conditions is still available, and is documented here, though it is deprecated and will be removed at some point in the future. It is provided for a number of reasons, the most significant of which is to provide compatibility with existing codes. Another reason why you might choose to use the old interface is if you have difficulty doing your iterations with the Cactus scheduler, and thus have trouble scheduling the ApplyBCs schedule group everywhere you need boundary conditions applied. A third reason may be that you need face specific calls immediately.

You should not run into any special difficulty mixing the old and new interface, just be aware of the order in which boundary conditions, and code that depends upon them, are executed.

Note that if you choose to use the old interface for some boundary conditions, then the symmetry conditions will not know to apply themselves to those grid variables for which you use the old interface. To get around this difficulty, simply select these grid variables for the “None” boundary condition, and be sure that ApplyBCs is scheduled in an appropriate place.

All routines can be called by

variable name: (<implementation>:<varxname> ) Suffix: VN; apply the boundary condition to the variable with the specified name. group name: (<implementation>:<groupxname>) Suffix: GN; apply the boundary condition to all variables in the group.

variable index: Suffix: VI; apply the boundary condition to the variable with the specified variable index.

group index: Suffix: GI apply the boundary condition to all variables in the group with the specified group index.

For the boundary conditions in individual coordinate directions, use

 11dir=-111to apply at
11dir= 1 11to apply at
11dir=-2 11to apply at
11dir= 2 11to apply at
11dir=-3 11to apply at
11dir= 3 11to apply at

11

Prototypes for each of the functions described for the old interface are included in the header file Boundary.h. Please add

usesxincludexheader:xBoundary.h

to your thorn’s interface.ccl to use this header file in your C/C++ source files.

4 Scalar Boundary Condition A scalar boundary condition means that the value of the given field or fields at the boundary is set to a given scalar value, for example zero. The scalar boundary condition is registered under the name “Scalar”.

4.1 Additional arguments A table passed to the scalar boundary condition may contain the following additional arguments:

11key  11variable type 11description  11default value
11SCALAR  11CCTKxREAL 11the scalar value  110.0
11BOUNDARYxWIDTH11CCTKxINT array11stencil width for each face11n/a

 11

4.2 Old interface

Calling from C:

All Coordinate Directions:

intxierrx=xBndScalarVN(cGHx*cctkGH,xintx*stencil_size,
xxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxvar0,xcharx*variable_name)
intxierrx=xBndScalarGN(cGHx*cctkGH,xintx*stencil_size,
xxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxvar0,xcharx*group_name)
intxierrx=xBndScalarVI(cGHx*cctkGH,xintx*stencil_size,
xxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxvar0,xintxgroup_index)
intxierrx=xBndScalarGI(cGHx*cctkGH,xintx*stencil_size,
xxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxvar0,xintxvariable_index)

intxierrx=xBndScalarDirVN(cGHx*cctkGH,xintxstencil,xintxdir,
xxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxvar0,xcharx*variable_name)
intxierrx=xBndScalarDirGN(cGHx*cctkGH,xintxstencil,xintxdir,
xxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxvar0,xcharx*group_name)
intxierrx=xBndScalarDirVI(cGHx*cctkGH,xintxstencil,xintxdir,
xxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxvar0,xintxgroup_index)
intxierrx=xBndScalarDirGI(cGHx*cctkGH,xintxstencil,xintxdir,
xxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxvar0,xintxvariable_index)

Calling from Fortran:

callxBndScalarVN(ierr,xcctkGH,xstencil_size,xvar0,xvariable_name)
callxBndScalarGN(ierr,xcctkGH,xstencil_size,xvar0,xgroup_name)
callxBndScalarVI(ierr,xcctkGH,xstencil_size,xvar0,xvariable_index)
callxBndScalarGI(ierr,xcctkGH,xstencil_size,xvar0,xgroup_index)

callxBndScalarDirVN(ierr,xcctkGH,xstencil,xdir,xvar0,xvariable_name)
callxBndScalarDirGN(ierr,xcctkGH,xstencil,xdir,xvar0,xgroup_name)
callxBndScalarDirVI(ierr,xcctkGH,xstencil,xdir,xvar0,xvariable_index)
callxBndScalarDirGI(ierr,xcctkGH,xstencil,xdir,xvar0,xgroup_index)

where

 11integer     11ierr
11CCTKxPOINTER 11cctkGH
11integer      11dir
11integer      11stencil
11integer      11stencilxsize(dim)
11CCTKxREAL    11var0
11character*(*)11variablexname
11character*(*)11groupxname
11integer      11variablexindex
11integer      11groupxindex

Arguments

11ierr         11Return value, negative value indicates the boundary condition was not successfully applied
11cctkGH        11Grid hierarchy pointer
11var0          11Scalar value to apply (For a complex grid function, this is the real part,
11              11the imaginary part is set to zero.)
11dir           11Coordinate direction in which to apply boundary condition
11stencilxsize  11Array with dimension of the grid function, containing the stencil width

11variablexname 11Name of the variable
11groupxname    11Name of the group
11variablexindex11Variable index
11groupxindex   11Group index

5 Flat Boundary Condition

A flat boundary condition means that the value of the given field or fields at the boundary is copied from the value one grid point in, in any direction. For example, for a stencil width of one, the boundary value of phi phi(nx,j,k), on the positive x-boundary will be copied from phi(nx-1,j,k). The flat boundary condition is registered under the name “Flat”.

5.1 Additional arguments A table passed to the flat boundary condition may contain the following additional arguments:

11key 11variable type 11description 11default value
11BOUNDARYxWIDTH11CCTKxINT array11stencil width for each face11n/a

 11

5.2 Old interface

intxierrx=xBndFlatVN(cGHx*cctkGH,xintx*stencil_size,xcharx*variable_name)
intxierrx=xBndFlatGN(cGHx*cctkGH,xintx*stencil_size,xcharx*group_name)
intxierrx=xBndFlatVI(cGHx*cctkGH,xintx*stencil_size,xintxvariable_index)
intxierrx=xBndFlatGI(cGHx*cctkGH,xintx*stencil_size,xintxgroup_index)

intxierrx=xBndFlatDirVN(cGHx*cctkGH,xintxstencil,xintxdir,xcharx*variable_name)
intxierrx=xBndFlatDirGN(cGHx*cctkGH,xintxstencil,xintxdir,xcharx*group_name)
intxierrx=xBndFlatDirVI(cGHx*cctkGH,xintxstencil,xintxdir,xintxvariable_index)
intxierrx=xBndFlatDirGI(cGHx*cctkGH,xintxstencil,xintxdir,xintxgroup_index)

Calling from Fortran:

callxBndFlatVN(ierr,xcctkGH,xstencil_array,xvariable_name)
callxBndFlatGN(ierr,xcctkGH,xstencil_array,xgroup_name)
callxBndFlatVI(ierr,xcctkGH,xstencil_array,xvariable_index)
callxBndFlatGI(ierr,xcctkGH,xstencil_array,xgroup_index)

callxBndFlatDirVN(ierr,xcctkGH,xstencil,xdir,xvariable_name)
callxBndFlatDirGN(ierr,xcctkGH,xstencil,xdir,xgroup_name)
callxBndFlatDirVI(ierr,xcctkGH,xstencil,xdir,xvariable_index)
callxBndFlatDirGI(ierr,xcctkGH,xstencil,xdir,xgroup_index)

where

 11integer     11ierr
11CCTKxPOINTER 11cctkGH
11integer      11dir
11integer      11stencil
11integer      11stencilxarray(dim)
11character*(*)11variablexname
11character*(*)11groupxname
11integer      11variablexindex
11integer      11groupxindex

Arguments

11ierr         11Return value, negative value indicates the boundary condition was not successfully applied
11cctkGH        11Grid hierarchy pointer
11dir           11Coordinate direction in which to apply boundary condition
11stencilxsize  11Array with dimension of the grid function, containing the stencil width

11variablexname 11Name of the variable
11groupxname    11Name of the group
11variablexindex11Variable index
11groupxindex   11Group index

11

6 Radiation Boundary Condition

This is a two level scheme. Grid functions are given for the current time level (to which the BC is applied) as well as grid functions from a past timelevel which are needed for constructing the boundary condition. The grid function of the past time level needs to have the same geometry. Currently radiative boundary conditions can only be applied with a stencil width of one in each direction.

The radiative boundary condition that is implemented is That is, outgoing radial waves with a fall off, and the correct asymptotic value are assumed, including the possibility of incoming waves (these incoming waves should be modeled somehow).

Conditionx?? above leads to the differential equation: where is the normal direction to the given boundaries, and .

At a given boundary only the derivatives in the normal direction are considered. Notice that has disappeared, but we still do not know the value of .

To get we do the following: The expression is evaluated one point in from the boundary and solved for there. Now we need a way of extrapolating to the boundary. For this, assume that falls off as a power law:

The value of is defined by the parameter radpower. If this parameter is negative, is forced to be zero (this corresponds to pure outgoing waves and is the default).

The observed behavior is the following: Using is very stable, but has a very bad initial transient. Taking to be 0 or positive improves the initial behavior considerably, but introduces a drift that can kill an evolution at very late times. Empirically, the best value found so far is , for which the initial behavior is very nice, and the late time drift is quite small.

Another problem with this condition is that it does not use the physical characteristic speed, but rather it assumes a wave speed of , so the boundaries should be out in the region where the characteristic speed is constant. Notice that this speed does not have to be 1.

The radiation boundary condition is registered under the name “Radiation”.

6.1 Additional arguments

A table passed to the radiative boundary condition may contain the following additional arguments:

11key  11variable type  11description  11default value
11LIMIT  11CCTKxREAL  11                      110.0
11PREVIOUSxTIMExLEVEL11CCTKxINT or CCTKxSTRING11GV which holds the  11Cactus previous time level
11                        11                           11previous time level  11
11SPEED  11CCTKxREAL  11wave speed  111.0
11BOUNDARYxWIDTH  11CCTKxINT array  11stencil width for each face11n/a

 11

The default behavior is to use the Cactus previous time level, as defined in the interface.ccl file, for the grid variable requested for the radiative boundary condition. The “PREVIOUSxTIMExLEVEL” key is provided for backward compatibility only, and will be deprecated in the future. The corresponding value may be either a CCTKxINT, which will be interpreted as the index of a grid variable holding the previous time level, or a CCTKxSTRING, interpreted as holding the name. Note that this will not work when selecting an entire variable group (with more than one member) with one call to BoundaryxSelectGroupForBC*, as each member will have a separate previous time level, and thus require a separate table. Please make your life easier by using Cactus time levelsx 6.2 Old interface Calling from C: All Coordinate Directions:

intxierrx=xBndRadiativeVN(cGHx*cctkGH,xintx*stencil_size,
xxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxlimit,xCCTK_REALxspeed,
xxxxxxxxxxxxxxxxxxxxxxxxxxcharx*variable_name,xcharx*variable_name_past)
intxierrx=xBndRadiativeGN(cGHx*cctkGH,xintx*stencil_size,
xxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxlimit,xCCTK_REALxspeed,
xxxxxxxxxxxxxxxxxxxxxxxxxxcharx*group_name,xcharx*group_name_past)
intxierrx=xBndRadiativeVI(cGHx*cctkGH,xintx*stencil_size,
xxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxlimit,xCCTK_REALxspeed,
xxxxxxxxxxxxxxxxxxxxxxxxxxintxvariable_index,xintxvariable_index_past)
intxierrx=xBndRadiativeGI(cGHx*cctkGH,xintx*stencil_size,
xxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxlimit,xCCTK_REALxspeed,
xxxxxxxxxxxxxxxxxxxxxxxxxxintxgroup_index,xintxgroup_index_past)

intxierrx=xBndRadiativeDirVN(cGHx*cctkGH,xintxstencil,xintxdir,
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxlimit,xCCTK_REALxspeed,
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxcharx*variable_name,xcharx*variable_name_past)
intxierrx=xBndRadiativeDirGN(cGHx*cctkGH,xintx*stencil,xintxdir,
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxlimit,xCCTK_REALxspeed,
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxcharx*group_name,xcharx*group_name_past)
intxierrx=xBndRadiativeDirVI(cGHx*cctkGH,xintx*stencil,xintxdir,
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxlimit,xCCTK_REALxspeed,
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxintxvariable_index,xintxvariable_index_past)
intxierrx=xBndRadiativeDirGI(cGHx*cctkGH,xintx*stencil,xintxdir,
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxlimit,xCCTK_REALxspeed,
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxintxgroup_index,xintxgroup_index_past)

Calling from Fortran:

callxBndRadiativeVN(ierr,xcctkGH,xstencil_size,xspeed,xlimit,
xxxxxxxxxxxxxxxxxxxxvariable_name,xvariable_name_past)
callxBndRadiativeGN(ierr,xcctkGH,xstencil_size,xspeed,xlimit,
xxxxxxxxxxxxxxxxxxxxgroup_name,xgroup_name_past)
callxBndRadiativeVI(ierr,xcctkGH,xstencil_size,xspeed,xlimit,
xxxxxxxxxxxxxxxxxxxxvariable_index,xvariable_index_past)
callxBndRadiativeGI(ierr,xcctkGH,xstencil_size,xspeed,xlimit,
xxxxxxxxxxxxxxxxxxxxgroup_index,xgroup_index_past)

callxBndRadiativeDirVN(ierr,xcctkGH,xstencil,xdir,xspeed,xlimit,
xxxxxxxxxxxxxxxxxxxxxxxvariable_name,xvariable_name_past)
callxBndRadiativeDirGN(ierr,xcctkGH,xstencil,xdir,xspeed,xlimit,
xxxxxxxxxxxxxxxxxxxxxxxgroup_name,xgroup_name_past)
callxBndRadiativeDirVI(ierr,xcctkGH,xstencil,xdir,xspeed,xlimit,
xxxxxxxxxxxxxxxxxxxxxxxvariable_index,xvariable_index_past)
callxBndRadiativeDirGI(ierr,xcctkGH,xstencil,xdir,xspeed,xlimit,
xxxxxxxxxxxxxxxxxxxxxxxgroup_index,xgroup_index_past)

where

 11integer     11ierr
11CCTKxPOINTER 11cctkGH
11integer      11dir
11integer      11stencil
11integer      11stencilxarray(dim)
11character*(*)11variablexname
11character*(*)11groupxname
11integer      11variablexindex
11integer      11groupxindex
11CCTKxREAL    11speed
11CCTKxREAL    11limit

11

Arguments

11ierr              11return value, operation failed when return value negative
11cctkGH             11grid hierarchy pointer
11stencilxsize(dim)  11array of size dim (dimension of the grid function).
11                   11To how many points from the outer boundary to apply the boundary condition.
11speed              11wave speed used for boundary condition ()
11limit              11asymptotic value of function at infinity ()
11variablexname      11the name of the grid function to which the boundary condition will be applied
11variablexnamexpast 11The name of the grid function containing the values on the past time level,
11                   11needed to calculate the boundary condition.
11groupxname         11the name of the group to which the boundary condition will be applied
11groupxnamexpast    11is the name of the group containing the grid functions on the past time level,
11                   11needed to calculate the boundary condition.
11variablexindex     11the index of the grid function to which the boundary condition will be applied
11variablexindexxpast11the index of the grid function containing the values on the past time level,
11                   11needed to calculate the boundary condition.
11groupxindex        11the index of the group to which the boundary condition will be applied
11groupxindexxpast   11the index of the group containing the values on the past time level,
11                   11needed to calculate the boundary condition.

7 Copy Boundary Condition

This is a two level scheme. Copy the boundary values from a different grid function, for example the previous timelevel. The two grid functions (or groups of grid functions) must have the same geometry. The copy boundary condition is registered under the name “Copy”.

7.1 Additional arguments

The “COPYxFROM” argument for the copy boundary condition is required, so a valid table handle is required as well. The keys read are

11key  11variable type  11description  11default value
11COPYxFROM  11CCTKxINT or CCTKxSTRING11GV to copy from  11no default
11BOUNDARYxWIDTH11CCTKxINT array  11stencil width for each face11n/a

 11

(The BOUNDARYxWIDTH table entry is only necessary if the boundaryxwidth parameter is negative.)

7.2 Old interface

Calling from C:

intxierrx=xBndCopyVN(cGHx*cctkGH,xintx*stencil_size,
xxxxxxxxxxxxxxxxxxxxxcharx*variable_name_to,xcharx*variable_name_from)
intxierrx=xBndCopyGN(cGHx*cctkGH,xintx*stencil_size,
xxxxxxxxxxxxxxxxxxxxxcharx*group_name_to,xcharx*group_name_from)
intxierrx=xBndCopyVI(cGHx*cctkGH,xintx*stencil_size,
xxxxxxxxxxxxxxxxxxxxxintxvariable_index_to,xintxvariable_index_from)
intxierrx=xBndCopyGI(cGHx*cctkGH,xintx*stencil_size,
xxxxxxxxxxxxxxxxxxxxxintxgroup_index_to,xintxgroup_index_from)

Calling from Fortran:

callxBndCopyVN(ierr,xcctkGH,xstencil_size,xvariable_name_to,
xxxxxxxxxxxxxxxvariable_name_from)
callxBndCopyVN(ierr,xcctkGH,xstencil_size,xgroup_name_to,
xxxxxxxxxxxxxxxgroup_name_from)
callxBndCopyVN(ierr,xcctkGH,xstencil_size,xvariable_index_to,
xxxxxxxxxxxxxxxvariable_index_from)
callxBndCopyVN(ierr,xcctkGH,xstencil_size,xgroup_index_to,
xxxxxxxxxxxxxxxgroup_index_from)

where

11integer ierr                   11return value, operation failed when return value negative

11CCTKxPOINTER cctkGH             11grid hierarchy pointer

11integer stencilxsize(dim)       11array of size dim (dimension of the grid function). To how many points
11                                11from the outer boundary to apply the boundary condition.
11character*(*) variablexnamexto  11the name of the grid function to which the boundary condition
11                                11will be applied by copying to.
11character*(*) variablexnamexfrom11the name of the grid function containing the values to copy from.
11character*(*) groupxnamexto     11the name of the group to which the boundary condition
11                                11will be applied by copying to.
11character*(*) groupxnamexfrom   11the name of the group containing the the values to copy from.
11integer variablexindexxto       11the index of the grid function to which the boundary condition
11                                11will be applied by copying to.
11integer variablexindexxfrom     11the index of the grid function containing the the values to copy from.
11integer groupxindexxto          11the index of the group to which the boundary condition
11                                11will be applied by copying to.
11integer groupxindexxfrom        11the index of the group containing the the values to copy from.

8 Robin Boundary Condition

This boundary condition has not yet been implemented in individual coordinate directions. The Robin boundary condition is: with a constant, the decay rate and the value at infinity. This implies: or Considering now a given Cartesian direction we get: which implies The equations are then finite differenced around the grid point : or And this is then solved either for or depending on which side are we looking at.

The Robin boundary condition is registered under the name “Robin”.

8.1 Additional arguments A table passed to the Robin boundary condition may contain the following additional arguments:

11key 11variable type 11description 11default value
11FINF  11CCTKxREAL 11                      110
11DECAYxPOWER 11CCTKxINT 11 111
11BOUNDARYxWIDTH11CCTKxINT array11stencil width for each face11n/a

 11

8.2 Old interface

intxierrx=xBndRobinVN(cGHx*cctkGH,xintx*stencil_size,
xxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxfinf,xintxnpow,xcharx*variable_name)
intxierrx=xBndScalarGN(cGHx*cctkGH,xintx*stencil_size,
xxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxfinf,xintxnpow,xcharx*group_name)
intxierrx=xBndScalarVI(cGHx*cctkGH,xintx*stencil_size,
xxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxfinf,xintxnpow,xintxgroup_index)
intxierrx=xBndScalarGI(cGHx*cctkGH,xintx*stencil_size,
xxxxxxxxxxxxxxxxxxxxxxxCCTK_REALxfinf,xintxnpow,xintxvariable_index)

Calling from Fortran:

callxBndRobinVN(ierr,xcctkGH,xstencil_size,xfinf,xnpow,xvariable_name)
callxBndRobinGN(ierr,xcctkGH,xstencil_size,xfinf,xnpow,xgroup_name)
callxBndRobinVI(ierr,xcctkGH,xstencil_size,xfinf,xnpow,xvariable_index)
callxBndRobinGI(ierr,xcctkGH,xstencil_size,xfinf,xnpow,xgroup_index)

where

 11integer     11ierr
11CCTKxPOINTER 11cctkGH
11integer      11stencilxsize(dim)
11CCTKxREAL    11finf
11integer      11npow
11character*(*)11variablexname
11character*(*)11groupxname
11integer      11variablexindex
11integer      11groupxindex

11

Arguments

11ierr         11Return value, negative value indicates the boundary condition was not successfully applied
11cctkGH        11Grid hierarchy pointer
11finf          11Scalar value at infinity
11npow          11Decay rate ( in discussion above)
11stencilxsize  11Array with dimension of the grid function, containing the stencil width to apply the boundary at

11variablexname 11Name of the variable
11groupxname    11Name of the group
11variablexindex11Variable index
11groupxindex   11Group index

9 Static Boundary Condition

The static boundary condition ensures that the boundary values do not evolve in time, by copying their values from previous timelevels. The static boundary condition is registered under the name “Static”.

9.1 Additional arguments A table passed to the static boundary condition may contain the following additional arguments:

11key 11variable type 11description 11default value
11BOUNDARYxWIDTH11CCTKxINT array11stencil width for each face11n/a

 11

9.2 Old interface

intxierrx=xBndStaticVN(cGHx*cctkGH,xintx*stencil_size,xcharx*variable_name)
intxierrx=xBndStaticGN(cGHx*cctkGH,xintx*stencil_size,xcharx*group_name)
intxierrx=xBndStaticVI(cGHx*cctkGH,xintx*stencil_size,xintxvariable_index)
intxierrx=xBndStaticGI(cGHx*cctkGH,xintx*stencil_size,xintxgroup_index)

intxierrx=xBndStaticDirVN(cGHx*cctkGH,xintxstencil,xintxdir,xcharx*variable_name)
intxierrx=xBndStaticDirGN(cGHx*cctkGH,xintxstencil,xintxdir,xcharx*group_name)
intxierrx=xBndStaticDirVI(cGHx*cctkGH,xintxstencil,xintxdir,xintxvariable_index)
intxierrx=xBndStaticDirGI(cGHx*cctkGH,xintxstencil,xintxdir,xintxgroup_index)

Calling from Fortran:

callxBndStaticVN(ierr,xcctkGH,xstencil_array,xvariable_name)
callxBndStaticGN(ierr,xcctkGH,xstencil_array,xgroup_name)
callxBndStaticVI(ierr,xcctkGH,xstencil_array,xvariable_index)
callxBndStaticGI(ierr,xcctkGH,xstencil_array,xgroup_index)

callxBndStaticDirVN(ierr,xcctkGH,xstencil,xdir,xvariable_name)
callxBndStaticDirGN(ierr,xcctkGH,xstencil,xdir,xgroup_name)
callxBndStaticDirVI(ierr,xcctkGH,xstencil,xdir,xvariable_index)
callxBndStaticDirGI(ierr,xcctkGH,xstencil,xdir,xgroup_index)

where

 11integer     11ierr
11CCTKxPOINTER 11cctkGH
11integer      11dir
11integer      11stencil
11integer      11stencilxarray(dim)
11character*(*)11variablexname
11character*(*)11groupxname
11integer      11variablexindex
11integer      11groupxindex

11

Arguments

11ierr         11Return value, negative value indicates the boundary condition was not successfully applied
11cctkGH        11Grid hierarchy pointer
11dir           11Coordinate direction in which to apply boundary condition
11stencilxsize  11Array with dimension of the grid function, containing the stencil width to apply the boundary at

11variablexname 11Name of the variable
11groupxname    11Name of the group
11variablexindex11Variable index
11groupxindex   11Group index

11

10 None Boundary Condition

The “None” boundary condition does just that, nothing. It is provided to inform the boundary implementation of grid variables which should have symmetry boundary conditions applied to them, but do not have their physical boundary conditions applied using a properly registered function.

10.1 Additional arguments

The none boundary condition will ignore all arguments passed to it. (Notably, when registering variables/groups for this boundary condition, the boundary_width and table_handle arguments are unused, and may be passed as dummy values.)

10.2 Old interface

There is no old interface to this boundary condition.

11 Appendix: Symmetry and non-local boundary conditions

An additional aliased function is provided to allow one to retrieve a list of grid variables which are selected for any particular boundary condition, or the entire list of selected grid variables (regardless of selected boundary condition). This is needed to write a thorn which provides a symmetry boundary condition, or a non-local boundary condition, as either of these need to schedule a routine in the BoundaryConditions schedule group to execute their condition on the list of selected

variables2 2The consistency of the symmetry conditions scheduled in BoundaryConditions will be treated in an upcoming “Symmetry” implementation . (A symmetry boundary condition will need the entire list of selected variables, while the non-local physical condition will only need the list of variables which request that particular boundary condition.)

intxBoundary_SelectedGVs(CCTK_POINTERxcctkGH,
xxxxxxxxxxxxxxxxxxxxxxxxxCCTK_INTxarray_size,
xxxxxxxxxxxxxxxxxxxxxxxxxCCTK_POINTERxvar_indices,
xxxxxxxxxxxxxxxxxxxxxxxxxCCTK_POINTERxfaces,
xxxxxxxxxxxxxxxxxxxxxxxxxCCTK_POINTERxboundary_widths,
xxxxxxxxxxxxxxxxxxxxxxxxxCCTK_POINTERxtable_handles,
xxxxxxxxxxxxxxxxxxxxxxxxxCCTK_STRINGxbc_name)

11cctkGH        11pointer to the grid hierarchy
11arrayxsize     11size of arrays pointed to by the next three arguments
11varxindices    11array of integers into which the selected variables’ grid variable indices will be placed
11faces          11array of integers into which the faces specification for each selected grid variable will be placed
11boundaryxwidths11array of integers which holds the boundaryxwidth parameter for each selected GV
11tablexhandles  11array of integers into which the table handle for each selected grid variable will be placed
11bcxname        11name of boundary condition

This function places a list of up to arrayxsize grid variable indices, sorted as described in section 2.1, into the array varxindices. The corresponding (up to arrayxsize) faces specifications, boundary widths, and table handles are placed into the arrays faces, boundaryxwidths, and tablexhandles, respectively. (If the list contains arrayxsize elements, then only elements are placed into the arrays varxindices, faces, boundaryxwidths, and tablexhandles.) To retrieve a list of all selected grid variables (for all boundary conditions), pass a null pointer for bcxname. The return value is the number elements of the requested list, so BoundaryxSelectedGVs can be called first with varxindices equal to zero to determine how much memory to allocate for the arrays varxindices, faces, boundaryxwidths, and

tablexhandles.

A non-local boundary condition must register a null pointer as its providing function in BoundaryxRegisterPhysicalBC, so that its name exists in the database of available boundary conditions, yet no extra routine is called when BoundaryxApplyPhysicalBCs is executed.

12 Parameters

11radpower 10Scope: restrictedx01 INT

11Description: Power of decay rate in extrapolation used in radiative boundaries

11 Range 10 x01 Default: -1
11:  10A negative value switches off this feature

11

11registerxcopy 10Scope: restrictedx01  BOOLEAN

11Description: Register routine to handle the ’Copy’ boundary condition

11              10  x01  Default: yes

11registerxflat 10Scope: restrictedx01  BOOLEAN

11Description: Register routine to handle the ’Flat’ boundary condition

11              10  x01  Default: yes

11

11registerxnone 10Scope: restrictedx01  BOOLEAN

11Description: Register routine to handle the ’None’ boundary condition

11              10  x01  Default: yes

11

11registerxradiation 10Scope: restrictedx01  BOOLEAN

11Description: Register routine to handle the ’Radiation’ boundary condition

11              10  x01  Default: yes

11

11registerxrobin 10Scope: restrictedx01  BOOLEAN

11Description: Register routine to handle the ’Robin’ boundary condition

11              10  x01  Default: yes

11

11registerxscalar 10Scope: restrictedx01  BOOLEAN

11Description: Register routine to handle the ’Scalar’ boundary condition

11              10  x01  Default: yes

11

11registerxstatic 10Scope: restrictedx01  BOOLEAN

11Description: Register routine to handle the ’Static’ boundary condition

11              10  x01  Default: yes

11

11presyncxmode 10Scope: shared from CACTUSx01KEYWORD

11

13 Interfaces

General Implements: boundary

Adds header: Boundary.h

Provides: BoundaryxRegisterPhysicalBC to BoundaryxQueryRegisteredPhysicalBC to BoundaryxSelectVarForBC to BoundaryxSelectVarForBCI to BoundaryxSelectGroupForBC to BoundaryxSelectGroupForBCI to BoundaryxSelectedGVs to

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

CCTKxPARAMCHECK x boundaryxcheck x check dimension of grid variables x

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

11

CCTKxWRAGH x boundaryxregisterbcs x register boundary conditions that this thorn provides x

11x11Before: 11driverxboundaryselect
11 x 11Language:11c
11 x 11Options: 11global
11 x 11Type: 11function

11

x applybcs x apply boundary conditions

11x11Type:11group

11

ApplyBCs x boundaryconditions x execute all boundary conditions x

11x11Before:11boundaryxclearselection
11 x 11Type: 11group

11

BoundaryConditions x boundaryxapplyphysicalbcs x apply all requested local physical boundary conditions x

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

11

ApplyBCs x boundaryxclearselection x unselect all grid variables for boundary conditions x

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