## VolumeIntegrals_vacuum: An Einstein Toolkit thorn for volume integrations in vacuum spacetimes

May 20, 2021

### Abstract

VolumeIntegrals_vacuum is a thorn for integration of spacetime quantities, accepting integration volumes consisting of spherical shells, regions with hollowed balls, and simple spheres.

### 1 Volume integrals

We now briefly describe the volume integrals that can be performed using the VolumeIntegrals_vacuum thorn.

#### 1.1 ${L}^{2}$-norm

For a given field $f$, the ${L}^{2}$-norm of the field, ${‖f‖}_{2}$, is computed using the volume integral

 ${‖f‖}_{2}= \int {f}^{2}dV\phantom{\rule{0.28em}{0ex}},$ (1)

where $dV$ is the volume element.

#### 1.2 Center of the lapse

The center of the lapse, ${C}_{\alpha }$, volume integral yields results which are pretty consistent with the center of mass volume integral. We compute it using

 ${C}_{\alpha }^{i}= \int \left[{\left(1 - \alpha \right)}^{80}{x}^{i}\right]dV\phantom{\rule{0.28em}{0ex}},$ (2)

where $\alpha$ is the lapse function, ${x}^{i}$ is the position vector and $dV$ is the volume element.

The ADM mass, ${M}_{ADM}$ is computed using equation (A.5) in [1] (see also eq. (7.15) in [2])

 ${M}_{ADM}=\frac{1}{16\pi }\underset{r\to \infty }{\mathrm{lim}}{\oint }_{S}\left[{\delta }^{ij}\left({\partial }_{i}{h}_{jk}-{\partial }_{k}{h}_{ij}\right)d{S}^{k}\right],$ (3)

where $S$ is the surface of integration and $d{S}^{i}={s}^{i}dA$, with ${s}^{i}$ the unit outward-pointing normal vector to the surface and $dA$ the area element. To obtain the equation above, the physical spatial metric, ${\gamma }_{ij}$, has been decomposed using

 ${\gamma }_{ij}={\delta }_{ij}+{h}_{ij},$ (4)

where ${\delta }_{ij}$ is the Kronecker delta and represents the flat space metric in Cartesian coordinates, while ${h}_{ij}$ is a small perturbation around flat space physical spatial metric. In practice, we do not take the integration surface to be at infinity, and therefore we implement the expression

 ${M}_{ADM}=\frac{1}{16\pi }{\oint }_{S}\left[{\gamma }^{ij}\left({\partial }_{i}{\gamma }_{jk}-{\partial }_{k}{\gamma }_{ij}\right)d{S}^{k}\right]\phantom{\rule{0.28em}{0ex}}.$ (5)

where ${\gamma }^{ij}$ is the inverse spatial metric.

The ADM momentum, ${P}_{ADM}^{i}$, is obtained from equation (A.6) in [1] (see also eq. (7.56) in [2])

 ${P}_{ADM}^{i}=\frac{1}{8\pi }\underset{r\to \infty }{\mathrm{lim}}{\oint }_{S}\left[\left({K}_{\phantom{\rule{0.33em}{0ex}}j}^{i}-{\delta }_{\phantom{\rule{0.33em}{0ex}}j}^{i}K\right)d{S}^{j}\right],$ (6)

where ${K}_{ij}$ is the extrinsic curvature and $K\equiv {\gamma }^{ij}{K}_{ij}$ is the mean curvature. Like the ADM mass, the integration is not performed at infinity, and the implemented equation is

 ${P}_{ADM}^{i}=\frac{1}{8\pi }{\oint }_{S}\left[\left({K}^{ij}-{\gamma }^{ij}K\right)d{S}_{j}\right]\phantom{\rule{0.28em}{0ex}}.$ (7)

The ADM angular momentum, ${J}_{ADM}^{i}$, follows from equation (A.7) in [1] (see also eq. (7.63) in [2])

 ${J}_{ADM}^{i}=\frac{1}{8\pi }\underset{r\to \infty }{\mathrm{lim}}{\oint }_{S}\left[{𝜖}^{ijk}{x}_{j}\left({K}_{kl}-{\delta }_{kl}K\right)d{S}^{l}\right],$ (8)

where ${𝜖}^{ijk}$ is the three-dimensional Levi-Civita tensor and ${x}^{i}$ are the components of the position vector in Cartesian coordinates. At a finite distance from the origin this equation is written as

 ${J}_{ADM}^{i}=\frac{1}{8\pi }{\oint }_{S}\left[{𝜖}^{ijk}{x}_{j}\left({K}_{kl}-{\gamma }_{kl}K\right)d{S}^{l}\right]\phantom{\rule{0.28em}{0ex}}.$ (9)

### 2 Basic usage

Except for the definition of the integrands, the behavior of this thorn is almost completely driver by the configuration of the parameter file. We present here an example of such a parameter file, which performs the following tasks:

#### 2.1 Specifying the BSSN evolution thorn

The VolumeIntegrals_vacuum thorn requires information about the Hamiltonian and momentum constraint variables in order to perform certain volume integrals. For maximum flexibility, one can specify which variables to use, making VolumeIntegrals_vacuum compatible with any BSSN evolution thorn. This is achieved by setting the following variables:

1. VolumeIntegrals_vacuum::HamiltonianVarString;

2. VolumeIntegrals_vacuum::Momentum0VarString;

3. VolumeIntegrals_vacuum::Momentum1VarString;

4. VolumeIntegrals_vacuum::Momentum2VarString;

The default values for these variables are the variables from the ML_BSSN thorn, but you can use any thorn you want. For example, to use the variables Ham, MU0, MU1, and MU2 from an evolution thorn called MyBSSNthorn, one would add the following lines to the parameter file:

VolumeIntegrals_vacuum::HamiltonianVarString = "MyBSSNthorn::Ham"
VolumeIntegrals_vacuum::Momentum0VarString   = "MyBSSNthorn::MU0"
VolumeIntegrals_vacuum::Momentum1VarString   = "MyBSSNthorn::MU1"
VolumeIntegrals_vacuum::Momentum2VarString   = "MyBSSNthorn::MU2"


#### 2.2 Full parameter file configuration example

We now provide an example of a parameter file configuration which uses the Hamiltonian and momentum constraint variables of the Baikal thorn and performs the following tasks:

1. Integral of Hamiltonian & momentum constraints, over the entire grid volume.

2. Exactly the same as 1, but excising the region inside a sphere of radius 2.2 tracking the zeroth AMR grid (initially at $\left(x,y,z\right)=\left(-5.9,0,0\right)$);

3. Exactly the same as 2, but additionally excising the region inside a sphere of radius 2.2 tracking the center of the first AMR grid (initially at $\left(x,y,z\right)=\left(+5.9,0,0\right)$);

4. Integral of Hamiltonian & momentum constraints, over the entire grid volume, minus the spherical region inside coordinate radius 8.2;

5. Integral of Hamiltonian & momentum constraints, over the entire grid volume, minus the spherical region inside coordinate radius 12.0;

6. Integral of Hamiltonian & momentum constraints, over the entire grid volume, minus the spherical region inside coordinate radius 16.0;

7. Integral of Hamiltonian & momentum constraints, over the entire grid volume, minus the spherical region inside coordinate radius 24.0;

8. Integral of Hamiltonian & momentum constraints, over the entire grid volume, minus the spherical region inside coordinate radius 48.0;

9. Integral of Hamiltonian & momentum constraints, over the entire grid volume, minus the spherical region inside coordinate radius 96.0;

10. Integral of Hamiltonian & momentum constraints, over the entire grid volume, minus the spherical region inside coordinate radius 192.0;

ActiveThorns = "VolumeIntegrals_vacuum"
# Set the Hamiltonian and momentum constraint variables to Baikal’s
VolumeIntegrals_vacuum::HamiltonianVarString = "Baikal::HGF"
VolumeIntegrals_vacuum::Momentum0VarString   = "Baikal::MU0GF"
VolumeIntegrals_vacuum::Momentum1VarString   = "Baikal::MU1GF"
VolumeIntegrals_vacuum::Momentum2VarString   = "Baikal::MU2GF"

# Now setup basic information about the integrals
VolumeIntegrals_vacuum::NumIntegrals = 10
VolumeIntegrals_vacuum::VolIntegral_out_every = 64
VolumeIntegrals_vacuum::enable_file_output = 1
VolumeIntegrals_vacuum::outVolIntegral_dir = "volume_integration"
VolumeIntegrals_vacuum::verbose = 1
# The AMR centre will only track the first referenced integration
# quantities that track said centre. Thus, centeroflapse output will
# not feed back into the AMR centre positions.
VolumeIntegrals_vacuum::Integration_quantity_keyword[1] = "H_M_CnstraintsL2"
VolumeIntegrals_vacuum::Integration_quantity_keyword[2] = "usepreviousintegrands"
VolumeIntegrals_vacuum::Integration_quantity_keyword[3] = "usepreviousintegrands"
VolumeIntegrals_vacuum::Integration_quantity_keyword[4] = "H_M_CnstraintsL2"
VolumeIntegrals_vacuum::Integration_quantity_keyword[5] = "H_M_CnstraintsL2"
VolumeIntegrals_vacuum::Integration_quantity_keyword[6] = "H_M_CnstraintsL2"
VolumeIntegrals_vacuum::Integration_quantity_keyword[7] = "H_M_CnstraintsL2"
VolumeIntegrals_vacuum::Integration_quantity_keyword[8] = "H_M_CnstraintsL2"
VolumeIntegrals_vacuum::Integration_quantity_keyword[9] = "H_M_CnstraintsL2"
VolumeIntegrals_vacuum::Integration_quantity_keyword[10]= "H_M_CnstraintsL2"

# Second integral takes the first integral integrand,
# then excises the region around the first BH
VolumeIntegrals_vacuum::volintegral_sphere__center_x_initial            [2] = -5.9
VolumeIntegrals_vacuum::volintegral_sphere__tracks__amr_centre          [2] =  0
VolumeIntegrals_vacuum::volintegral_usepreviousintegrands_num_integrands[2] =  4

# Third integral takes the second integral integrand,
# then excises the region around the first BH
VolumeIntegrals_vacuum::volintegral_sphere__center_x_initial            [3] =  5.9
VolumeIntegrals_vacuum::volintegral_sphere__tracks__amr_centre          [3] =  1
VolumeIntegrals_vacuum::volintegral_usepreviousintegrands_num_integrands[3] =  4

# Just an outer region



### References

[1]   Alcubierre, M. Introduction to 3+ 1 numerical relativity, Vol 140. Oxford University Press (2008).

[2]   Gourgoulhon, E. 3+ 1 formalism and bases of numerical relativity, arXiv preprint gr-qc/0703035 (2007).

### 3 Parameters

 amr_centre__tracks__volintegral_inside_sphere Scope: private INT Description: Use output from volume integral to move AMR box centre N. Range Default: -1 -1:100 -1 = do not track an AMR box centre. Otherwise track AMR box centre number N = [0,100]

 enable_file_output Scope: private INT Description: Enable output file Range Default: 1 0:1 0 = no output; 1 = yes, output to file

 enable_time_reparameterization Scope: private BOOLEAN Description: Enable time reparameterization a la http://arxiv.org/abs/1404.6523 Default: no

 hamiltonianvarstring Scope: private STRING Description: Hamiltonian constraint variable name Range Default: ML_BSSN::H ML_BSSN::H ML_BSSN thorn Hamiltonian constraint gridfunction name Baikal::HGF Baikal thorn Hamiltonian constraint gridfunction name BaikalVacuum::HGF BaikalVacuum thorn Hamiltonian constraint gridfunction name LeanBSSNMoL::hc LeanBSSNMoL thorn Hamiltonian constraint gridfunction name .+ Or use you can use your own thorn’s Hamiltonian constraint gridfunction name

 integration_quantity_keyword Scope: private KEYWORD Description: Which quantity to integrate Range Default: nothing nothing Default, null parameter H_M_CnstraintsL2 Hamiltonian2^, Momentum2^ see [1] below Use integrands from step(s) immediately preceeding. Useful for Swiss-cheese-type volume integrations. centeroflapse Center of Lapse one Integrand = 1. Useful for debugging ADM_Mass ADM Mass ADM_Momentum ADM Momentum see [1] below ADM Angular Momentum

[1]

usepreviousintegrands


[1]

ADM\_Angular\_Momentum


 momentum0varstring Scope: private STRING Description: Momentum constraint variable name (x-direction) Range Default: ML_BSSN::M1 ML_BSSN::M1 ML_BSSN thorn momentum constraint gridfunction name Baikal::MU0GF Baikal thorn momentum constraint gridfunction name BaikalVacuum::MU0GF BaikalVacuum thorn momentum constraint gridfunction name LeanBSSNMoL::mcx LeanBSSNMoL thorn momentum constraint gridfunction name .+ Or use you can use your own thorn’s momentum constraint gridfunction name

 momentum1varstring Scope: private STRING Description: Momentum constraint variable name (y-direction) Range Default: ML_BSSN::M2 ML_BSSN::M2 ML_BSSN thorn momentum constraint gridfunction name Baikal::MU1GF Baikal thorn momentum constraint gridfunction name BaikalVacuum::MU1GF BaikalVacuum thorn momentum constraint gridfunction name LeanBSSNMoL::mcy LeanBSSNMoL thorn momentum constraint gridfunction name .+ Or use you can use your own thorn’s momentum constraint gridfunction name

 momentum2varstring Scope: private STRING Description: Momentum constraint variable name (z-direction) Range Default: ML_BSSN::M3 ML_BSSN::M3 ML_BSSN thorn momentum constraint gridfunction name Baikal::MU2GF Baikal thorn momentum constraint gridfunction name BaikalVacuum::MU2GF BaikalVacuum thorn momentum constraint gridfunction name LeanBSSNMoL::mcz LeanBSSNMoL thorn momentum constraint gridfunction name .+ Or use you can use your own thorn’s momentum constraint gridfunction name

 numintegrals Scope: private INT Description: Number of volume integrals to perform Range Default: (none) 0:1000 zero (disable integration) or some other number

 outvolintegral_dir Scope: private STRING Description: Output directory for volume integration output files, overrides IO::out_dir Range Default: (none) .+ A valid directory name \$^ An empty string to choose the default from IO::out_dir

 verbose Scope: private INT Description: Set verbosity level: 1=useful info; 2=moderately annoying (though useful for debugging) Range Default: 1 0:2 0 = no output; 1=useful info; 2=moderately annoying (though useful for debugging)

 viv_time_reparam_t0 Scope: private REAL Description: Time reparameterization parameter t_0: Center of time reparameterization curve. SET TO BE SAME AS IN ImprovedPunctureGauge thorn Range Default: 10.0 0:* Probably don’t want to set this <0, so >=0 enforced

 viv_time_reparam_w Scope: private REAL Description: Time reparameterization parameter w: Width of time reparameterization curve. SET TO BE SAME AS IN ImprovedPunctureGauge thorn Range Default: 5.0 0:* Probably don’t want to set this <0, so >=0 enforced

 volintegral_inside_sphere__radius Scope: private REAL Description: Volume integral in a spherical region: radius of spherical region Range Default: (none) *:* Any number

 volintegral_out_every Scope: private INT Description: How often to compute volume integrals? Range Default: (none) 0:1000 zero (disable integration) or some other number

 volintegral_outside_sphere__radius Scope: private REAL Description: Volume integral outside a spherical region: radius of spherical region Range Default: (none) *:* Any number

 volintegral_sphere__center_x_initial Scope: private REAL Description: Volume integral in a spherical region: x-coord of center(s) Range Default: (none) *:* Any number

 volintegral_sphere__center_y_initial Scope: private REAL Description: Volume integral in a spherical region: y-coord of center(s) Range Default: (none) *:* Any number

 volintegral_sphere__center_z_initial Scope: private REAL Description: Volume integral in a spherical region: z-coord of center(s) Range Default: (none) *:* Any number

 volintegral_sphere__tracks__amr_centre Scope: private INT Description: Volume integral tracks AMR box centre N. Range Default: -1 -1:100 -1 = do not track an AMR box centre. Otherwise track AMR box centre number N = [0,100]

 volintegral_usepreviousintegrands_num_integrands Scope: private INT Description: Number of integrands for usepreviousintegrands, must be specified explicitly as information from previous integrand is not passed. Range Default: 4 0:100 Default is set to the maximum, 4.

 out_dir Scope: shared from IO STRING

### 4 Interfaces

#### General

Implements:

volumeintegrals_vacuum

Inherits:

grid

carpetregrid2

#### Grid Variables

##### 4.0.1 PRIVATE GROUPS
 Group Names Variable Names Details volintegrands compact 0 VolIntegrand1 dimensions 3 VolIntegrand2 distribution DEFAULT VolIntegrand3 group type GF VolIntegrand4 tags InterpNumTimelevels=1 prolongation=”none” Checkpoint=”no” timelevels 1 variable type REAL volintegrals compact 0 VolIntegral description Volume integrals description post-sum. The first dimension denotes which integral(s) VolIntegral description and the second denotes the values of the integral(s). E.g. VolIntegral description a center of mass volume integral will have 3 outputs. dimensions 2 distribution CONSTANT group type ARRAY size 101 size 4 timelevels 1 variable type REAL movingsphregionintegrals compact 0 volintegral_inside_sphere__center_x description Specify regions for volume integrals inside/outside spheres THAT MOVE. volintegral_inside_sphere__center_y dimensions 1 volintegral_inside_sphere__center_z distribution CONSTANT volintegral_outside_sphere__center_x group type ARRAY volintegral_outside_sphere__center_y size 101 volintegral_outside_sphere__center_z timelevels 1 variable type REAL

##### 4.0.2 PUBLIC GROUPS
 Group Names Variable Names Details integralcountervar compact 0 IntegralCounter description Counter that keeps track of which integral we are calculating. dimensions 0 distribution CONSTANT group type SCALAR tags checkpoint=”no” timelevels 1 variable type INT volintegrals_vacuum_time compact 0 physical_time description keeps track of the physical time description in case time coordinate is reparameterized physical_time description a la http://arxiv.org/abs/1404.6523 dimensions 0 distribution CONSTANT group type SCALAR tags checkpoint=”no” timelevels 1 variable type REAL

### 5 Schedule

This section lists all the variables which are assigned storage by thorn WVUThorns_Diagnostics/VolumeIntegrals_vacuum. 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: VolIntegrands VolIntegrals MovingSphRegionIntegrals IntegralCounterVar VolIntegrals_vacuum_time

#### Scheduled Functions

CCTK_INITIAL (conditional)

file_output_routine_startup

create directory for file output.

 Language: c Type: function

CCTK_POST_RECOVER_VARIABLES (conditional)

file_output_routine_startup

create directory for file output.

 Language: c Type: function

CCTK_INITIAL

initializeintegralcountertozero

initialize integralcounter variable to zero

 Language: c Options: global Type: function

CCTK_POST_RECOVER_VARIABLES

initializeintegralcountertozero

initialize integralcounter variable to zero

 Language: c Options: global Type: function

CCTK_ANALYSIS

initializeintegralcounter

initialize integralcounter variable

 Before: volumeintegralgroup Language: c Options: global Type: function

CCTK_ANALYSIS

volumeintegralgroup

evaluate all volume integrals

 Before: carpetlib_printtimestats carpetlib_printmemstats Type: group While: volumeintegrals_vacuum::integralcounter

VolumeIntegralGroup

volumeintegrals_vacuum_computeintegrand

compute integrand

 Before: dosum Language: c Options: global loop-local Storage: volintegrands volintegrals movingsphregionintegrals Type: function

VolumeIntegralGroup

dosum

do sum

 After: volumeintegrals_vacuum_computeintegrand Language: c Options: global Type: function

VolumeIntegralGroup

decrementintegralcounter

decrement integralcounter variable

 After: dosum Language: c Options: global Type: function

CCTK_ANALYSIS

vi_vacuum_file_output

output volumeintegral results to disk

 After: volumeintegralgroup Language: c Options: global Type: function