ADMBase

Tom Goodale

\( \)Date\( \)

Abstract

Provides the basic ADM variables used in the \(3+1\) formalism

1 Purpose

Thorn ADMBase provides core infrastructure for thorns implementing general relativity on a 3D grid in the \(3+1\) formalism. It provides the basic variables (3-metric, extrinsic curvature, lapse and shift vector) for the \(3+1\) 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 \(3+1\) 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 \(3+1\) variables.

2 Using ADMBase

2.1 3+1 Variables

The variables provided by ADMBase are:

By default the metric and extrinsic curvature tensors are assumed to be physical, however these semantics can be changed by use of the metric_type 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 \(3+1\) variables is specified by the initial_data (3-metric and extrinsic curvature), initial_lapse (lapse), and initial_shift (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> -o admbase::initial_data | grep Range

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 evolution_method (3-metric and extrinsic curvature), lapse_evolution_method (lapse), and shift_evolution_method (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 metric_type parameter in a routine scheduled at CCTK_PARAMCHECK 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 initial_shift parameter is set to a value other than ‘none’. (‘none’ is the default.) The state of the shift storage is indicated by the shift_state 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 initial_data, initial_lapse and initial_shift. For example, in the param.ccl file of CactusEinstein/IDAnalyticBH,

shares: ADMBase

EXTENDS KEYWORD initial_data
{
  "schwarzschild"      :: "One Schwarzshild black hole"
  "bl_bh"              :: "Brill Lindquist black holes"
  "misner_bh"          :: "Misner black holes"
  "multiple_misner_bh" :: "Multiple Misner black holes"
  "kerr"        :: "One Kerr black hole"
}

ADMBase also schedules two groups ADMBase_InitialData and ADMBase_InitialGauge in this order at CCTK_INITIAL. Initial data and initial gauge thorns should schedule their routines to run in this group, for example

if (CCTK_Equals(initial_data,"schwarzschild"))
{ 
   schedule Schwarzschild in ADMBase_InitialData
   {
     LANG: C
   } "Construct initial data for a single Schwarzschild black hole"
}

ADMBase also schedules a group ADMBase_PostInitial at CCTK_INITIAL after both ADMBase_InitialData and ADMBase_InitialGauge. This group is meant for thorns that modify the initial data, such as e.g. adding 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 initial_shift is set to none, ADMBase does not allocate storage for betax, betay, betaz and sets the grid scalar shift_state to 0. In all other cases the shift_state parameter is set to 1.

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

5 Parameters




admbase_boundary_condition
Scope: restricted  STRING



Description: Boundary condition for ADMBase variables



Range   Default: flat
must be a registered boundary condition






dtlapse_evolution_method
Scope: restricted  KEYWORD



Description: The dtlapse evolution method



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






dtshift_evolution_method
Scope: restricted  KEYWORD



Description: The dtshift evolution method



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






evolution_method
Scope: restricted  KEYWORD



Description: The metric an extrinsic curvature evolution method



Range   Default: static
none
The metric and extrinsic curvature are not evolved
static
The metric and extrinsic curvature are not evolved
ID-apply-regrid
The metric and extrinsic curvature are not evolved and initial data is used to fill in new grid points after regridding
ID-apply-always
The 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






initial_data
Scope: restricted  KEYWORD



Description: Initial metric and extrinsic curvature datasets



Range   Default: Cartesian Minkowski
Cartesian Minkowski
Minkowski values in cartesian coordinates






initial_dtlapse
Scope: restricted  KEYWORD



Description: Initial dtlapse value



Range   Default: none
none
Dtlapse is inactive
zero
Dtlapse is zero






initial_dtshift
Scope: restricted  KEYWORD



Description: Initial dtshift value



Range   Default: none
none
Dtshift is inactive
zero
Dtshift is zero






initial_lapse
Scope: restricted  KEYWORD



Description: Initial lapse value



Range   Default: one
one
Uniform lapse






initial_shift
Scope: restricted  KEYWORD



Description: Initial shift value



Range   Default: zero
none
Shift is inactive
zero
Shift is zero






lapse_evolution_method
Scope: restricted  KEYWORD



Description: The lapse evolution method



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






lapse_prolongation_type
Scope: restricted  KEYWORD



Description: The kind of boundary prolongation for the lapse



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






lapse_timelevels
Scope: restricted  INT



Description: Number of time levels for the lapse



Range   Default: 1
0:3






metric_prolongation_type
Scope: restricted  KEYWORD



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



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






metric_timelevels
Scope: restricted  INT



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



Range   Default: 1
0:3






metric_type
Scope: restricted  KEYWORD



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



Range   Default: physical
physical
metric and extrinsic curvature are the physical ones






shift_evolution_method
Scope: restricted  KEYWORD



Description: The shift evolution method



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






shift_prolongation_type
Scope: restricted  KEYWORD



Description: The kind of boundary prolongation for the shift



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






shift_timelevels
Scope: restricted  INT



Description: Number of time levels for the shift



Range   Default: 1
0:3



6 Interfaces

General

Implements:

admbase

Inherits:

grid

Grid Variables

6.0.1 PUBLIC GROUPS




  Group Names    Variable Names    Details   




shift_state shift_state   compact0
  descriptionstate of storage for shift
  dimensions0
  distributionCONSTANT
  group typeSCALAR
  timelevels1
 variable typeINT




dtlapse_state dtlapse_state   compact0
  descriptionstate of storage for dtlapse
  dimensions0
  distributionCONSTANT
  group typeSCALAR
  timelevels1
 variable typeINT




dtshift_state dtshift_state   compact0
  descriptionstate of storage for dtshift
  dimensions0
  distributionCONSTANT
  group typeSCALAR
  timelevels1
 variable typeINT




metric   compact0
gxx   descriptionADM 3-metric g_ij
gxy   dimensions3
gxz   distributionDEFAULT
gyy   group typeGF
gyz   tagstensortypealias=”DD_sym” ProlongationParameter=”ADMBase::metric_prolongation_type”
gzz   timelevels3
 variable typeREAL




curv   compact0
kxx   descriptionADM extrinsic curvature K_ij
kxy   dimensions3
kxz   distributionDEFAULT
kyy   group typeGF
kyz   tagstensortypealias=”DD_sym” ProlongationParameter=”ADMBase::metric_prolongation_type”
kzz   timelevels3
 variable typeREAL




lapse   compact0
alp   descriptionADM lapse function alpha
  dimensions3
  distributionDEFAULT
  group typeGF
  tagstensortypealias=”Scalar” ProlongationParameter=”ADMBase::lapse_prolongation_type”
  timelevels3
 variable typeREAL








  Group Names    Variable Names    Details   




shift   compact0
betax   descriptionADM shift function betaî
betay   dimensions3
betaz   distributionDEFAULT
  group typeGF
  tagstensortypealias=”U” ProlongationParameter=”ADMBase::shift_prolongation_type”
  timelevels3
 variable typeREAL




dtlapse   compact0
dtalp   descriptionTime derivative of ADM lapse function alpha
  dimensions3
  distributionDEFAULT
  group typeGF
  tagstensortypealias=”Scalar” ProlongationParameter=”ADMBase::lapse_prolongation_type”
  timelevels3
 variable typeREAL




dtshift   compact0
dtbetax   descriptionTime derivative of ADM shift function betaî
dtbetay   dimensions3
dtbetaz   distributionDEFAULT
  group typeGF
  tagstensortypealias=”U” ProlongationParameter=”ADMBase::shift_prolongation_type”
  timelevels3
 variable typeREAL




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

 

Always: Conditional:
shift_state dtlapse_state dtshift_state shift[shift_timelevels]
lapse[lapse_timelevels] dtlapse[lapse_timelevels]
metric[metric_timelevels] curv[metric_timelevels]dtshift[shift_timelevels]
   

Scheduled Functions

CCTK_PARAMCHECK (conditional)

  admbase_paramcheck

  check consistency of parameters

 

 Language:c
 Options: global
 Type: function

CCTK_INITIAL (conditional)

  admbase_initialdata

  schedule group for calculating adm initial data

 

 Type:group

CCTK_BASEGRID (conditional)

  admbase_setdtshiftstateon

  set the dtshift_state variable to 1

 

 Language:c
 Type: function
 Writes: admbase::dtshift_state(everywhere)

CCTK_BASEGRID (conditional)

  admbase_setdtshiftstateoff

  set the dtshift_state variable to 0

 

 Language:c
 Type: function
 Writes: admbase::dtshift_state(everywhere)

ADMBase_InitialGauge (conditional)

  admbase_shiftzero

  set the shift to 0 at all points

 

 Language:c
 Type: function
 Writes: admbase::shift(everywhere)
   admbase::shift_p(everywhere)
   admbase::shift_p_p(everywhere)

ADMBase_InitialGauge (conditional)

  admbase_dtlapsezero

  set the dtlapse to 0 at all points

 

 Language:c
 Type: function
 Writes: admbase::dtalp(everywhere)
   dtalp_p(everywhere)
   dtalp_p_p(everywhere)

ADMBase_InitialGauge (conditional)

  admbase_dtshiftzero

  set the dtshift to 0 at all points

 

 Language:c
 Type: function
 Writes: admbase::dtshift(everywhere)
   admbase::dtshift_p(everywhere)
   admbase::dtshift_p_p(everywhere)

CCTK_PRESTEP (conditional)

  admbase_lapsestatic

  copy the lapse to the current time level

 

 Language:c
 Reads: admbase::alp_p(everywhere)
   admbase::dtalp_p(everywhere)
 Type: function
 Writes: admbase::alp(everywhere)
   admbase::dtalp(everywhere)

CCTK_PRESTEP (conditional)

  admbase_shiftstatic

  copy the shift to the current time level

 

 Language:c
 Reads: admbase::shift_p(everywhere)
   admbase::dtshift_p(everywhere)
 Type: function
 Writes: admbase::shift(everywhere)
   admbase::dtshift(everywhere)

CCTK_PRESTEP (conditional)

  admbase_static

  copy the metric and extrinsic curvature to the current time level

 

 Language:c
 Reads: admbase::curv_p(everywhere)
   admbase::metric_p(everywhere)
 Type: function
 Writes: admbase::curv(everywhere)
   admbase::metric(everywhere)

CCTK_WRAGH (conditional)

  einstein_initsymbound

  set up gf symmetries

 

 Language:c
 Options: global
 Type: function

MoL_PostStep (conditional)

  admbase_boundaries

  select admbase boundary conditions - may be required for mesh refinement

 

 Before: admbase_setadmvars
  Language:c
 Options: level
 Sync: lapse
   dtlapse
   shift
   dtshift
   metric
   curv
 Type: function

CCTK_INITIAL (conditional)

  admbase_initialgauge

  schedule group for the adm initial gauge condition

 

 After:admbase_initialdata
 Type:group

MoL_PostStep (conditional)

  applybcs

  apply the boundary conditions of admbase

 

 After: admbase_boundaries
  Before:admbase_setadmvars
 Type: group

CCTK_POSTREGRID (conditional)

  admbase_initialdata

  schedule group for calculating adm initial data

 

 Type:group

CCTK_POSTREGRIDINITIAL (conditional)

  admbase_initialdata

  schedule group for calculating adm initial data

 

 Type:group

CCTK_POSTREGRID (conditional)

  admbase_initialgauge

  schedule group for the adm initial gauge condition

 

 After: admbase_initialdata
  Before:mol_poststep
 Type: group

CCTK_POSTREGRIDINITIAL (conditional)

  admbase_initialgauge

  schedule group for the adm initial gauge condition

 

 After: admbase_initialdata
  Before:mol_poststep
 Type: group

MoL_PostStep

  admbase_setadmvars

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

 

 Type:group

MoL_PseudoEvolution

  admbase_setadmvars

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

 

 Type:group

CCTK_INITIAL (conditional)

  admbase_postinitial

  schedule group for modifying the adm initial data, such as e.g. adding noise

 

 After:admbase_initialdata
    admbase_initialgauge
 Type:group

ADMBase_InitialData (conditional)

  admbase_cartesianminkowski

  set the metric and extrinsic curvature to cartesian minkowski values

 

 Language:c
 Type: function
 Writes: admbase::curv(everywhere)
   admbase::metric(everywhere)
   admbase::metric_p(everywhere)
   admbase::metric_p_p(everywhere)
   admbase::curv_p(everywhere)
   admbase::curv_p_p(everywhere)
   admbase::alp(everywhere)
   admbase::shift(everywhere)
   admbase::dtalp(everywhere)
   admbase::dtshift(everywhere)
   admbase::shift_state(everywhere)
   admbase::dtlapse_state(everywhere)
   admbase::dtshift_state(everywhere)

ADMBase_InitialGauge (conditional)

  admbase_lapseone

  set the lapse to 1 at all points

 

 Language:c
 Type: function
 Writes: admbase::alp(everywhere)
   admbase::alp_p(everywhere)
   admbase::alp_p_p(everywhere)

CCTK_BASEGRID (conditional)

  admbase_setshiftstateon

  set the shift_state variable to 1

 

 Language:c
 Type: function
 Writes: admbase::shift_state(everywhere)

CCTK_BASEGRID (conditional)

  admbase_setshiftstateoff

  set the shift_state variable to 0

 

 Language:c
 Type: function
 Writes: admbase::shift_state(everywhere)

CCTK_BASEGRID (conditional)

  admbase_setdtlapsestateon

  set the dtlapse_state variable to 1

 

 Language:c
 Type: function
 Writes: admbase::dtlapse_state(everywhere)

CCTK_BASEGRID (conditional)

  admbase_setdtlapsestateoff

  set the dtlapse_state variable to 0

 

 Language:c
 Type: function
 Writes: admbase::dtlapse_state(everywhere)

Aliased Functions

 

Alias Name:        Function Name:
ApplyBCs ADMBase_ApplyBCs