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

Zachariah B. Etienne <zachetie *at* gmail *dot* com >
Leonardo R. Werneck <wernecklr *at* gmail *dot* com >
Ian Ruchlin <ianruchlin *at* gmail *dot* com >

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 L2-norm

For a given field f, the L2-norm of the field, f2, is computed using the volume integral

f2 =f2dV , (1)

where dV is the volume element.

1.2 Center of the lapse

The center of the lapse, Cα, volume integral yields results which are pretty consistent with the center of mass volume integral. We compute it using

Cαi =1 α80xi dV , (2)

where α is the lapse function, xi is the position vector and dV is the volume element.

1.3 ADM mass

The ADM mass, MADM is computed using equation (A.5) in [1] (see also eq. (7.15) in [2])

MADM = 1 16πlim r S δij ihjk khij dSk , (3)

where S is the surface of integration and dSi = sidA, with si the unit outward-pointing normal vector to the surface and dA the area element. To obtain the equation above, the physical spatial metric, γij, has been decomposed using

γij = δij + hij, (4)

where δij is the Kronecker delta and represents the flat space metric in Cartesian coordinates, while hij 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

MADM = 1 16π S γij iγjk kγij dSk . (5)

where γij is the inverse spatial metric.

1.4 ADM momentum

The ADM momentum, PADMi, is obtained from equation (A.6) in [1] (see also eq. (7.56) in [2])

PADMi = 1 8πlim r S Kji δ jiKdSj , (6)

where Kij is the extrinsic curvature and K γijKij is the mean curvature. Like the ADM mass, the integration is not performed at infinity, and the implemented equation is

PADMi = 1 8π S Kij γijKdS j . (7)

1.5 ADM angular momentum

The ADM angular momentum, JADMi, follows from equation (A.7) in [1] (see also eq. (7.63) in [2])

JADMi = 1 8πlim r S 𝜖ijkx j Kkl δklKdSl , (8)

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

JADMi = 1 8π S 𝜖ijkx j Kkl γklKdSl . (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 (x,y,z) = (5.9,0,0));
  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 (x,y,z) = (+5.9,0,0));
  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;

To achieve this, add the following configuration to your parameter file:

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_outside_sphere__radius              [2] =  2.2  
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_outside_sphere__radius              [3] =  2.2  
VolumeIntegrals_vacuum::volintegral_sphere__tracks__amr_centre          [3] =  1  
VolumeIntegrals_vacuum::volintegral_usepreviousintegrands_num_integrands[3] =  4  
 
# Just an outer region  
VolumeIntegrals_vacuum::volintegral_outside_sphere__radius[4] = 8.2  
VolumeIntegrals_vacuum::volintegral_outside_sphere__radius[5] =12.0  
VolumeIntegrals_vacuum::volintegral_outside_sphere__radius[6] =16.0  
VolumeIntegrals_vacuum::volintegral_outside_sphere__radius[7] =24.0  
VolumeIntegrals_vacuum::volintegral_outside_sphere__radius[8] =48.0  
VolumeIntegrals_vacuum::volintegral_outside_sphere__radius[9] =96.0  
VolumeIntegrals_vacuum::volintegral_outside_sphere__radius[10]=192.0

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

admbase

carpetregrid2

Grid Variables

4.0.1 PRIVATE GROUPS




  Group Names     Variable Names     Details   




volintegrands   compact0
VolIntegrand1   dimensions3
VolIntegrand2   distributionDEFAULT
VolIntegrand3   group typeGF
VolIntegrand4   tagsInterpNumTimelevels=1 prolongation=”none” Checkpoint=”no”
  timelevels1
 variable typeREAL




volintegrals   compact0
VolIntegral   descriptionVolume integrals
    descriptionpost-sum. The first dimension denotes which integral(s)
VolIntegral   descriptionand the second denotes the values of the integral(s). E.g.
VolIntegral   descriptiona center of mass volume integral will have 3 outputs.
  dimensions2
  distributionCONSTANT
  group typeARRAY
  size101
    size4
  timelevels1
 variable typeREAL




movingsphregionintegrals   compact0
volintegral_inside_sphere__center_x   descriptionSpecify regions for volume integrals inside/outside spheres THAT MOVE.
volintegral_inside_sphere__center_y   dimensions1
volintegral_inside_sphere__center_z   distributionCONSTANT
volintegral_outside_sphere__center_x  group typeARRAY
volintegral_outside_sphere__center_y  size101
volintegral_outside_sphere__center_z  timelevels1
 variable typeREAL




4.0.2 PUBLIC GROUPS




  Group Names     Variable Names    Details   




integralcountervar   compact0
IntegralCounter   descriptionCounter that keeps track of which integral we are calculating.
  dimensions0
  distributionCONSTANT
  group typeSCALAR
  tagscheckpoint=”no”
  timelevels1
 variable typeINT




volintegrals_vacuum_time   compact0
physical_time   descriptionkeeps track of the physical time
    descriptionin case time coordinate is reparameterized
physical_time   descriptiona la http://arxiv.org/abs/1404.6523
  dimensions0
  distributionCONSTANT
  group typeSCALAR
  tagscheckpoint=”no”
  timelevels1
 variable typeREAL




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