xx ADMBase

ADMBase

Tom Goodale

Date

Abstract

Provides the basic ADM variables used in the formalism

1 Purpose

Thorn ADMBase provides core infrastructure for thorns implementing general relativity on a 3D grid in the formalism. It provides the basic variables (3-metric, extrinsic curvature, lapse and shift vector) for the formalism, in addition to a set of parameters to regulate the methods used for their evolution. These variables are used to communicate between thorns providing initial data, evolution methods and analysis routines for the formalism. In addition, the variables can be used as a mechanism to interact with alternative formalisms, as long as routines can be written to transform alternative variables into these variables.

2 Using ADMBase

2.1 3+1 Variables

The variables provided by ADMBase are:

The 3-metric tensor,

gxx, gxy, gxz,gyy, gyz,gzz

The extrinsic curvature tensor,

kxx, kxy, kxz,kyy,kyz,kzz

The lapse function,

alp

The (optional) shift vector

betax, betay,betaz

By default the metric and extrinsic curvature tensors are assumed to be physical, however these semantics can be changed by use of the metricxtype parameter. ADMBase provides the default value of physical, however another thorn can extend this parameter, for example to specify that the variables gxx etc actually refer to the conformal 3-metric.

2.2 Initial Data

Initial data for the variables is specified by the initialxdata (3-metric and extrinsic curvature), initialxlapse (lapse), and initialxshift (shift) parameters. By default, ADMBase initialises the 3-metric and extrinsic curvature to Minkowski and the lapse to one. Initial data thorns override these defaults by extending the parameters. To see which initial data sets are available in your executable run for example

./cactus_<config>x-oxadmbase::initial_datax|xgrepxRange

The CactusEinstein arrangement includes thorns providing initial data for various black hole combinations, perturbed black holes and linear gravitational waves.

2.3 Evolution Methods

Analogous to specifying initial data, evolution methods are chosen by the evolutionxmethod (3-metric and extrinsic curvature), lapsexevolutionxmethod (lapse), and shiftxevolutionxmethod (shift) parameters. By default, ADMBase does not evolve the 3-metric or extrinsic curvature, and holds the lapse and shift static.

3 Programming With ADMBase

3.1 3+1 Variables

It is highly recommended that all thorns which inherit from ADMBase check the value of the metricxtype parameter in a routine scheduled at CCTKxPARAMCHECK and signal an error if the metric type is not recognised. (See the source file ParamCheck.c in any of the thorns in the CactusEinstein arrangement for examples of this, and note that the PARAMCHECK time bin is a good place to check for illegal/bad combinations of parameters, and also to inform the user of any relevent details of the parameters she has chosen).

ADMBase allocates one timelevel of memory for all variables, except the shift, which is only allocated if the initialxshift parameter is set to a value other than ‘none’. (‘none’ is the default.) The state of the shift storage is indicated by the shiftxstate grid scalar. This is 1 if there is storage for the shift, and 0 otherwise.

The thorn provides, on request, initial data to set the metric and extrinsic curvature to flat space in cartesian coordinates, to set the initial lapse to one and the initial shift to zero.

3.2 Initial Data

To include your initial data sets for the 3-metric, extrinsic curvature, lapse and shift in the ADMBase infrastructure, extend the keyword parameters initialxdata, initialxlapse and initialxshift. For

example, in the param.ccl file of CactusEinstein/IDAnalyticBH,

shares:xADMBase
EXTENDSxKEYWORDxinitial_data
{
xx"schwarzschild"xxxxxx::x"OnexSchwarzshildxblackxhole"
xx"bl_bh"xxxxxxxxxxxxxx::x"BrillxLindquistxblackxholes"
xx"misner_bh"xxxxxxxxxx::x"Misnerxblackxholes"
xx"multiple_misner_bh"x::x"MultiplexMisnerxblackxholes"
xx"kerr" xxxxxxx::x"OnexKerrxblackxhole"
}

ADMBase also schedules two groups ADMBasexInitialData and ADMBasexInitialGauge in this order at

CCTKxINITIAL. Initial data and initial gauge thorns should schedule their routines to run in this group, for example

ifx(CCTK_Equals(initial_data,"schwarzschild"))
{x
xxxschedulexSchwarzschildxinxADMBase_InitialData
xxx{
xxxxxLANG:xC
xxx}x"ConstructxinitialxdataxforxaxsinglexSchwarzschildxblackxhole"
}

ADMBase also schedules a group ADMBasexPostInitial at CCTKxINITIAL after both ADMBasexInitialData and

ADMBasexInitialGauge. This group is meant for thorns that modify the initial data, such as e.g.xadding noise to an exact solution.

4 Shift Vector

It is only relatively recently that numerical relativists have started to use a shift vector in 3D calculations, and previously, to save space, storage for the shift vector was not allocated. If the parameter initialxshift is set to none, ADMBase does not allocate storage for betax, betay, betaz and sets the grid scalar shiftxstate to 0. In all other cases the shiftxstate parameter is set to 1.

Thorns using the shift should always check that storage for the shift is allocated before using it.

5 Parameters

11admbasexboundaryxcondition 10Scope: restrictedx01  STRING

11Description: Boundary condition for ADMBase variables

11 Range 10 x01 Default: flat
11                       10must be a registered boundary condition

11dtlapsexevolutionxmethod 10Scope: restrictedx01  KEYWORD

11Description: The dtlapse evolution method

11 Range 10 x01 Default: static
11static  10dtlapse is not evolved
11ID-apply-regrid  10dtlapse is not evolved and initial data is used to fill in new grid points after regridding
11ID-apply-always  10dtlapse is not evolved and initial data is used to fill in new grid points before each step and after grid changes

11

11dtshiftxevolutionxmethod 10Scope: restrictedx01  KEYWORD

11Description: The dtshift evolution method

11 Range 10 x01 Default: static
11static  10dtshift is not evolved
11ID-apply-regrid  10dtshift is not evolved and initial data is used to fill in new grid points after regridding
11ID-apply-always  10dtshift is not evolved and initial data is used to fill in new grid points before each step and after grid changes

11

11evolutionxmethod  10Scope: restrictedx01  KEYWORD

11Description: The metric an extrinsic curvature evolution method

11 Range 10 x01 Default: static
11none  10The metric and extrinsic curvature are not evolved
11static  10The metric and extrinsic curvature are not evolved
11ID-apply-regrid  10The metric and extrinsic curvature are not evolved and initial data is used to fill in new grid points after regridding
11ID-apply-always  10The metric and extrinsic curvature are not evolved and initial data is used to fill in new grid points before each step and after grid changes

11

11initialxdata  10Scope: restrictedx01  KEYWORD

11Description: Initial metric and extrinsic curvature datasets

11 Range 10 x01 Default: Cartesian Minkowski
11Cartesian Minkowski  10Minkowski values in cartesian coordinates

11

11initialxdtlapse  10Scope: restrictedx01  KEYWORD

11Description: Initial dtlapse value

11 Range 10 x01 Default: none
11none  10Dtlapse is inactive
11zero  10Dtlapse is zero

11

11initialxdtshift  10Scope: restrictedx01  KEYWORD

11Description: Initial dtshift value

11 Range 10 x01 Default: none
11none  10Dtshift is inactive
11zero  10Dtshift is zero

11

11initialxlapse  10Scope: restrictedx01  KEYWORD

11Description: Initial lapse value

11 Range 10 x01 Default: one
11one  10Uniform lapse

11

11initialxshift  10Scope: restrictedx01  KEYWORD

11Description: Initial shift value

11 Range 10 x01 Default: zero
11none  10Shift is inactive
11zero  10Shift is zero

11lapsexevolutionxmethod 10Scope: restrictedx01  KEYWORD

11Description: The lapse evolution method

11 Range 10 x01 Default: static
11static  10lapse is not evolved
11ID-apply-regrid  10lapse is not evolved and initial data is used to fill in new grid points after regridding
11ID-apply-always  10lapse is not evolved and initial data is used to fill in new grid points before each step and after grid changes

11

11lapsexprolongationxtype 10Scope: restrictedx01  KEYWORD

11Description: The kind of boundary prolongation for the lapse

11 Range 10 x01 Default: Lagrange
11Lagrange  10standard prolongation (requires several time levels)
11none  10no prolongation (use this if you do not have enough time levels active)

11

11lapsextimelevels  10Scope: restrictedx01  INT

11Description: Number of time levels for the lapse

11  Range  10  x01  Default: 1

110:3  10

11

11metricxprolongationxtype 10Scope: restrictedx01  KEYWORD

11Description: The kind of boundary prolongation for the metric and extrinsic curvature

11 Range 10 x01 Default: Lagrange
11Lagrange  10standard prolongation (requires several time levels)
11none  10no prolongation (use this if you do not have enough time levels active)

11

11metricxtimelevels  10Scope: restrictedx01  INT

11Description: Number of time levels for the metric and extrinsic curvature

11  Range  10  x01  Default: 1

110:3  10

11

11metricxtype  10Scope: restrictedx01  KEYWORD

11Description: The semantics of the metric variables (physical, static conformal, etc)

11 Range 10 x01 Default: physical
11physical  10metric and extrinsic curvature are the physical ones

11

11shiftxevolutionxmethod 10Scope: restrictedx01  KEYWORD

11Description: The shift evolution method

11 Range 10 x01 Default: static
11static  10shift is not evolved
11ID-apply-regrid  10shift is not evolved and initial data is used to fill in new grid points after regridding
11ID-apply-always  10shift is not evolved and initial data is used to fill in new grid points before each step and after grid changes

11

11shiftxprolongationxtype 10Scope: restrictedx01  KEYWORD

11Description: The kind of boundary prolongation for the shift

11 Range 10 x01 Default: Lagrange
11Lagrange  10standard prolongation (requires several time levels)
11none  10no prolongation (use this if you do not have enough time levels active)

11

11shiftxtimelevels  10Scope: restrictedx01  INT

11Description: Number of time levels for the shift

11  Range  10  x01  Default: 1

110:3  10

6 Interfaces

General Implements: admbase

Inherits: grid

Grid Variables

6.0.1 PUBLIC GROUPS

11x Group Names x10x Variable Names xx01 Details x11x
11 shiftxstate 10 shiftxstate x01 compact110
11                 10  x01 description11state of storage for shift
11                 10  x01 dimensions110
11                 10  x01 distribution11CONSTANT
11                 10  x01 group type11SCALAR
11                 10  x01 timelevels111
11                 10  x01variable type11INT
11 dtlapsexstate 10 dtlapsexstate x01  compact110
11                 10  x01 description11state of storage for dtlapse
11                 10  x01 dimensions110
11                 10  x01 distribution11CONSTANT
11                 10  x01 group type11SCALAR
11                 10  x01 timelevels111
11                 10  x01variable type11INT
11 dtshiftxstate 10 dtshiftxstate x01 compact110
11                 10  x01 description11state of storage for dtshift
11                 10  x01 dimensions110
11                 10  x01 distribution11CONSTANT
11                 10  x01 group type11SCALAR
11                 10  x01 timelevels111
11                 10  x01variable type11INT
11  metric  10  x01  compact110
11                 10  gxx  x01 description11ADM 3-metric gxij
11                 10  gxy  x01 dimensions113
11                 10  gxz  x01 distribution11DEFAULT
11                 10  gyy  x01 group type11GF
11                 10  gyz  x01  tags11tensortypealias=”DDxsym” ProlongationParameter=”ADMBase::metricxprolongationxtype”
11                 10  gzz  x01 timelevels113
11                 10  x01variable type11REAL
11  curv  10  x01  compact110
11                 10  kxx  x01 description11ADM extrinsic curvature Kxij
11                 10  kxy  x01 dimensions113
11                 10  kxz  x01 distribution11DEFAULT
11                 10  kyy  x01 group type11GF
11                 10  kyz  x01  tags11tensortypealias=”DDxsym” ProlongationParameter=”ADMBase::metricxprolongationxtype”
11                 10  kzz  x01 timelevels113
11                 10  x01variable type11REAL
11  lapse  10  x01  compact110
11                 10  alp  x01 description11ADM lapse function alpha
11                 10  x01 dimensions113
11                 10  x01 distribution11DEFAULT
11                 10  x01 group type11GF
11 10 x01 tags11tensortypealias=”Scalar” ProlongationParameter=”ADMBase::lapsexprolongationxtype”
11                 10  x01 timelevels113
11                 10  x01variable type11REAL

11x Group Names x10x Variable Names xx01 Details x11x
11  shift  10  x01  compact110
11                 10  betax  x01 description11ADM shift function betax
11                 10  betay  x01 dimensions113
11                 10  betaz  x01 distribution11DEFAULT
11                 10  x01 group type11GF
11 10 x01 tags11tensortypealias=”U” ProlongationParameter=”ADMBase::shiftxprolongationxtype”
11                 10  x01 timelevels113
11                 10  x01variable type11REAL
11  dtlapse  10  x01  compact110
11                 10  dtalp  x01 description11Time derivative of ADM lapse function alpha
11                 10  x01 dimensions113
11                 10  x01 distribution11DEFAULT
11                 10  x01 group type11GF
11 10 x01 tags11tensortypealias=”Scalar” ProlongationParameter=”ADMBase::lapsexprolongationxtype”
11                 10  x01 timelevels113
11                 10  x01variable type11REAL
11  dtshift  10  x01  compact110
11                 10  dtbetax  x01 description11Time derivative of ADM shift function betax
11                 10  dtbetay  x01 dimensions113
11                 10  dtbetaz  x01 distribution11DEFAULT
11                 10  x01 group type11GF
11 10 x01 tags11tensortypealias=”U” ProlongationParameter=”ADMBase::shiftxprolongationxtype”
11                 10  x01 timelevels113
11                 10  x01variable type11REAL

11

Uses header: Symmetry.h

7 Schedule This section lists all the variables which are assigned storage by thorn EinsteinBase/ADMBase. 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:  11Conditional:
11shiftxstate dtlapsexstate dtshiftxstate  11shift[shiftxtimelevels]
11lapse[lapsextimelevels]  11dtlapse[lapsextimelevels]
11metric[metricxtimelevels] curv[metricxtimelevels]11dtshift[shiftxtimelevels]

11x  11x

11

Scheduled Functions CCTKxPARAMCHECK (conditional) x admbasexparamcheck x check consistency of parameters x

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

11

CCTKxINITIAL (conditional) x admbasexinitialdata x schedule group for calculating adm initial data x

11x11Type:11group

11

CCTKxBASEGRID (conditional) x admbasexsetdtshiftstateon x set the dtshiftxstate variable to 1 x

11x11Language:11c
11 x 11Type: 11function
11 x 11Writes: 11admbase::dtshiftxstate(everywhere)

11

CCTKxBASEGRID (conditional) x admbasexsetdtshiftstateoff x set the dtshiftxstate variable to 0 x

11x11Language:11c
11 x 11Type: 11function
11 x 11Writes: 11admbase::dtshiftxstate(everywhere)

11

ADMBasexInitialGauge (conditional) x admbasexshiftzero x set the shift to 0 at all points x

11x11Language:11c
11 x 11Type: 11function
11 x 11Writes: 11admbase::shift(everywhere)
11 x 11x  11admbase::shiftxp(everywhere)
11 x 11x  11admbase::shiftxpxp(everywhere)

11

ADMBasexInitialGauge (conditional) x admbasexdtlapsezero x set the dtlapse to 0 at all points

11x11Language:11c
11 x 11Type: 11function
11 x 11Writes: 11admbase::dtalp(everywhere)
11 x 11x  11dtalpxp(everywhere)
11 x 11x  11dtalpxpxp(everywhere)

11

ADMBasexInitialGauge (conditional) x admbasexdtshiftzero x set the dtshift to 0 at all points x

11x11Language:11c
11 x 11Type: 11function
11 x 11Writes: 11admbase::dtshift(everywhere)
11 x 11x  11admbase::dtshiftxp(everywhere)
11 x 11x  11admbase::dtshiftxpxp(everywhere)

11

CCTKxPRESTEP (conditional) x admbasexlapsestatic x copy the lapse to the current time level x

11x11Language:11c
11 x 11Reads: 11admbase::alpxp(everywhere)
11 x 11x  11admbase::dtalpxp(everywhere)
11 x 11Type: 11function
11 x 11Writes: 11admbase::alp(everywhere)
11 x 11x  11admbase::dtalp(everywhere)

11

CCTKxPRESTEP (conditional) x admbasexshiftstatic x copy the shift to the current time level x

11x11Language:11c
11 x 11Reads: 11admbase::shiftxp(everywhere)
11 x 11x  11admbase::dtshiftxp(everywhere)
11 x 11Type: 11function
11 x 11Writes: 11admbase::shift(everywhere)
11 x 11x  11admbase::dtshift(everywhere)

11

CCTKxPRESTEP (conditional) x admbasexstatic x copy the metric and extrinsic curvature to the current time level x

11x11Language:11c
11 x 11Reads: 11admbase::curvxp(everywhere)
11 x 11x  11admbase::metricxp(everywhere)
11 x 11Type: 11function
11 x 11Writes: 11admbase::curv(everywhere)
11 x 11x  11admbase::metric(everywhere)

CCTKxWRAGH (conditional) x einsteinxinitsymbound x set up gf symmetries x

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

11

MoLxPostStep (conditional) x admbasexboundaries x select admbase boundary conditions - may be required for mesh refinement x

11x11Before: 11admbasexsetadmvars
11 x 11Language:11c
11 x 11Options: 11level
11 x 11Sync:  11lapse
11 x 11x  11dtlapse
11 x 11x  11shift
11 x 11x  11dtshift
11 x 11x  11metric

11 x 11x  11curv

11 x 11Type: 11function

11

CCTKxINITIAL (conditional) x admbasexinitialgauge x schedule group for the adm initial gauge condition x

11x11After:11admbasexinitialdata
11 x 11Type:11group

11

MoLxPostStep (conditional) x applybcs x apply the boundary conditions of admbase x

11x11After: 11admbasexboundaries
11 x 11Before:11admbasexsetadmvars
11 x 11Type: 11group

11

CCTKxPOSTREGRID (conditional) x admbasexinitialdata x schedule group for calculating adm initial data x

11x11Type:11group

11

CCTKxPOSTREGRIDINITIAL (conditional) x admbasexinitialdata x schedule group for calculating adm initial data

11x11Type:11group

11

CCTKxPOSTREGRID (conditional) x admbasexinitialgauge x schedule group for the adm initial gauge condition x

11x11After: 11admbasexinitialdata
11 x 11Before:11molxpoststep
11 x 11Type: 11group

11

CCTKxPOSTREGRIDINITIAL (conditional) x admbasexinitialgauge x schedule group for the adm initial gauge condition x

11x11After: 11admbasexinitialdata
11 x 11Before:11molxpoststep
11 x 11Type: 11group

11

MoLxPostStep x admbasexsetadmvars x set the adm variables before this group, and use them afterwards x

11x11Type:11group

11

MoLxPseudoEvolution x admbasexsetadmvars x set the adm variables before this group, and use them afterwards x

11x11Type:11group

11

CCTKxINITIAL (conditional) x admbasexpostinitial x schedule group for modifying the adm initial data, such as e.g. adding noise x

11x11After:11admbasexinitialdata
11 x 11x  11admbasexinitialgauge
11 x 11Type:11group

11

ADMBasexInitialData (conditional) x admbasexcartesianminkowski x set the metric and extrinsic curvature to cartesian minkowski values

11x11Language:11c
11 x 11Type: 11function
11 x 11Writes: 11admbase::curv(everywhere)
11 x 11x  11admbase::metric(everywhere)
11 x 11x  11admbase::metricxp(everywhere)
11 x 11x  11admbase::metricxpxp(everywhere)
11 x 11x  11admbase::curvxp(everywhere)
11 x 11x  11admbase::curvxpxp(everywhere)
11 x 11x  11admbase::alp(everywhere)
11 x 11x  11admbase::shift(everywhere)
11 x 11x  11admbase::dtalp(everywhere)
11 x 11x  11admbase::dtshift(everywhere)
11 x 11x  11admbase::shiftxstate(everywhere)
11 x 11x  11admbase::dtlapsexstate(everywhere)
11 x 11x  11admbase::dtshiftxstate(everywhere)

11

ADMBasexInitialGauge (conditional) x admbasexlapseone x set the lapse to 1 at all points x

11x11Language:11c
11 x 11Type: 11function
11 x 11Writes: 11admbase::alp(everywhere)
11 x 11x  11admbase::alpxp(everywhere)
11 x 11x  11admbase::alpxpxp(everywhere)

11

CCTKxBASEGRID (conditional) x admbasexsetshiftstateon x set the shiftxstate variable to 1 x

11x11Language:11c
11 x 11Type: 11function
11 x 11Writes: 11admbase::shiftxstate(everywhere)

11

CCTKxBASEGRID (conditional) x admbasexsetshiftstateoff x set the shiftxstate variable to 0 x

11x11Language:11c
11 x 11Type: 11function
11 x 11Writes: 11admbase::shiftxstate(everywhere)

11

CCTKxBASEGRID (conditional) x admbasexsetdtlapsestateon x set the dtlapsexstate variable to 1 x

11x11Language:11c
11 x 11Type: 11function
11 x 11Writes: 11admbase::dtlapsexstate(everywhere)

CCTKxBASEGRID (conditional) x admbasexsetdtlapsestateoff x set the dtlapsexstate variable to 0 x

11x11Language:11c
11 x 11Type: 11function
11 x 11Writes: 11admbase::dtlapsexstate(everywhere)

11

Aliased Functions x

11Alias Name: xxxxxxx11Function Name:
11ApplyBCs  11ADMBasexApplyBCs