Chapter P10
TmunuBase

P10.1 Abstract

Provide grid functions for the stress-energy tensor T_μν, and schedule when these grid functions are calculated. This allows different thorns to cooperate without explicitly depending on each other. This thorn is compatible with the CalcTmumu.inc interface, in the sense that thorns using this interface will work correctly with TmunuBase. Thorn TmunuBase is for the stress-energy tensor what thorn ADMBase is for the metric tensor.

P10.2 Introduction

Thorn TmunuBase provides core infrastructure for thorns implementing some kind of energy or matter in general relativity, for example general relativistic hydrodynamics formulations. It provides the basic variables, i.e., the stress-energy tensor T_μν, in addition to a set of parameters to regulate their use. These variables are used to communicate between (possibly multiple) thorns contributing to the stress-energy content of the spacetime, and thorns needing to evaluate the stress-energy tensor such as spacetime evolution methods. It also provides schedule groups to manage when T_μν is calculated and when it is ready for access.

P10.3 Using TmunuBase

P10.3.1 Variables

TmunuBase weakly assumes (but does not require) that the spacetime is described in terms of a 3 + 1 decomposition. The variables provided by TmunuBase are:

• The “scalar” part of T_μν, its time-time component: eTtt
• The “vector” part of T_μν, its time-space components: eTtx, eTty, eTtz
• The “tensor” part of T_μν, its space-space components: eTxx, eTxy, eTxz, eTyy, eTyz, eTzz

These components have the prefix e to avoid naming conflicts with existing variables. Many thorns dealing with matter already use variable names such as Ttt.

These variables have up to three time levels.

P10.3.2 Parameters

By default, the TmunuBase variables have no storage, and TmunuBase is inactive. This makes it possible to add a matter interface to existing vacuum spacetime methods without changing their behaviour.

Several parameters choose how TmunuBase behaves at run time:

• The parameter stress_energy_storage activates storage for T_μν and enables the schedule groups which calculate it.
• The parameter stress_energy_at_RHS moves calculating the T_μν from the evol bin into the MoL_PostStep group. This increases the order of accuracy of the spacetime–matter coupling, but is only possible when thorn MoL is used.¹ Generally, this parameter should be set when MoL is used.
• The parameter timelevels chooses the number of time levels for T_μν. The default is a single time level, which is sufficient for unigrid simulation. Mesh refinement simulation may require several time levels if mesh refinement boundaries require correct values.
• The parameter prolongation_type defines the prolongation operator for mesh refinement boundaries. The default is Lagrange interpolation.

The grid scalar stress_energy_state describes whether the T_μν variables have storage.

P10.4 Programming with TmunuBase

P10.4.1 Contributing to T_μν

There may be multiple thorns contributing to T_μν. Therefore, thorn TmunuBase initialises T_μν to zero, and each thorn has to add to the existing values in T_μν. The corresponding routine should be scheduled in the bin AddToTmunu. Note: Do not schedule anything in the schedule bin SetTmunu.

P10.4.2 Reading from T_μν

Since the values of T_μν change at each time step, or – if a thorn like MoL is used – at each substep, T_μν needs to be recalculated frequently. This happens either in the schedule bin evol or in the schedule group MoL_PostStep. T_μν may only be accessed after it has been calculated, e.g. IN MoL_PostStep AFTER SetTmunu. T_μν can be freely accessed at other times, e.g. in MoL_CalcRHS or at poststep or analyisis.

P10.5 Compatibility to ADMCoupling

Cactus provides another interface for contributing to the stress-energy tensor, called CalcTmunu. This alternative interface (which is described in thorn ADMCoupling) requires writing routines in fixed-format Fortran 77 and inserting lines of code into a file CalcTmunu.inc. We suggest to use exactly one of these two interface and not to mix them.

Thorn TmunuBase takes contributions from the CalcTmunu interface automatically into account as well. It also collects the values which are added to its T_μν and provides these to other thorns which use the CalcTmunu.inc interface. That is, thorn TmunuBase is fully backwards compatible.

P10.5.1 Comparison to ADMCoupling

The CalcTmunu interface and this thorn TmunuBase make different space/performance tradeoffs. CalcTmunu does not store any components of the stress-energy tensor, which saves memory and is also more efficient if its components can be quickly calculated from other variables (presumably the state vector of a hydrodynamics thorn).

TmunuBase requires explicit storage for T_μν. This is necessary if T_μν needs to be interpolated e.g. for dynamical horizon calculations. Compared to the overall number of grid function in a typical simulation the number of additional variables is tolerable (typical numbers are 10 additional variables with 200 existing variables). With the exception of the parts ensuring compatibility to CalcTmunu, TmunuBase is also a much simpler and more flexible mechanism.

P10.5.2 Acknowledgements

We thank I. Hawke for designing and implementing thorn MoL, without which a generic high-order coupling between spacetime and hydrodynamics methods would not be possible.

P10.6 Parameters

prolongation_type	Scope: private	STRING
Description: The kind of boundary prolongation for the stress-energy tensor
Range		Default: Lagrange
agrange$	standard prolongation (requires several time levels)
one$	no prolongation (use this if you do not have enough time levels active)
	any other supported prolongation type

P10.7 Interfaces

General

Implements:

tmunubase

Inherits:

admbase

staticconformal

Grid Variables

PUBLIC GROUPS

PROTECTED GROUPS

P10.8 Schedule

This section lists all the variables which are assigned storage by thorn EinsteinBase/TmunuBase. 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

Scheduled Functions

CCTK_BASEGRID

  tmunubase_setstressenergystate

  set the stress_energy_state variable

CCTK_INITIAL (conditional)

  settmunu

  calculate the stress-energy tensor

MoL_PostStep (conditional)

  settmunu

  group for calculating the stress-energy tensor

SetTmunu (conditional)

  tmunubase_settmunu

  calculate the stress-energy tensor using the old calctmunu mechanism

SetTmunu (conditional)

  tmunubase_zerotmunu

  initialise the stress-energy tensor to zero

SetTmunu (conditional)

  addtotmunu

  add to the stress-energy tensor here

SetTmunu (conditional)

  tmunubase_copytmunu

  copy the stress-energy tensor