VolumeIntegrals_GRMHD: An Einstein Toolkit thorn for GRMHD volume integrations

Zachariah B. Etienne <zachetie *at* gmail *dot* com >
Documentation by Leonardo R. Werneck <wernecklr *at* gmail *dot* com >

July 24, 2023

Abstract

VolumeIntegrals_GRMHD is a thorn for integration of spacetime quantities, accepting integration volumes consisting of spherical shells, regions with hollowed balls, and simple spheres. Results from of integrals, such as the center of mass, can be used to track e.g. neutron stars.

1 Volume integrals

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

1.1 Rest mass

We start by defining the “densitised density” (see e.g. [1]) \begin {equation} \rho _{\star } \equiv \alpha \sqrt {\gamma }\rho _{\rm b} u^{0} = W\rho _{\rm b}\sqrt {\gamma }, \end {equation} where \(\alpha \) is the lapse function, \(\gamma \) is the determinant of the physical spatial metric \(\gamma _{ij}\), \(\rho _{\rm b}\) is the baryonic density, \(u^{\mu }\) is the fluid four-velocity, and \(W\equiv \alpha u^{0}\) is the Lorentz factor. The rest mass integral is then given by \begin {equation} \boxed { M_{0} = \int \rho _{\star } dV = \int \left (W\rho _{\rm b}\sqrt {\gamma }\right )dV }\; . \end {equation} The volume \(V\) can be specified using spherical shells, regions with hollowed balls, and simple spheres. It can also be set to the entire computational domain.

1.2 Center of mass

The coordinates of center of mass \(X^{i}\) are computed from the integral \begin {equation} \boxed { X^{i} = \frac {\int \rho _{\star } x^{i}dV}{\int \rho _{\star } dV} }\; , \end {equation} where \(x^{i}\) is the position vector. The volume \(V\) can be specified using spherical shells, regions with hollowed balls, and simple spheres. It can also be set to the entire domain size.

1.3 Unit (for debugging)

This thorn also provides the functionality of performing a volume integral with a unit integrand, which should just yield the volume of the integrated region, i.e. \begin {equation} \boxed { V = \int dV }\; . \end {equation}

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:

  1. Integrate the entire volume with an integrand of 1. (used for testing/validation purposes only).

  2. Perform all four integrals required to compute the center of mass (numerator=3, denominator=1 integral), in an integration volume originally centered at \((x,y,z)=(-15.2,0,0)\) with a coordinate radius of 13.5 Also use the center of mass integral result to SET the ZEROTH AMR center. In this way, the AMR grids will track the center of mass as computed by this integration.

  3. Same as 2, except use the integrand=1 (for validation purposes, to ensure the integration volume is approximately \((4/3)\pi 13.5^3\)). Also disable tracking of this integration volume.

  4. Same as 2, except for the neutron star originally centered at \((x,y,z)=(+15.2,0,0)\).

  5. Same as 4, except use the integrand=1 (for validation purposes, to ensure the integration volume is approximately \((4/3)\pi 13.5^3\)). Also disable tracking of this integration volume.

  6. Perform rest-mass integrals over entire volume.

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

ActiveThorns = "VolumeIntegrals_GRMHD"

# Set number of integrals
VolumeIntegrals_GRMHD::NumIntegrals = 6

# Set frequency of integration. If tracking AMR centres this should
# match the regridding frequency of the thorn CactusRegrid2
VolumeIntegrals_GRMHD::VolIntegral_out_every = 32

# Enable file output
VolumeIntegrals_GRMHD::enable_file_output = 1

# Set output directory
VolumeIntegrals_GRMHD::outVolIntegral_dir = "volume_integration"

# Set verbose level. 0 disables it, 1 provides useful
# information, and 2 is very verbose.
VolumeIntegrals_GRMHD::verbose = 1

# The AMR centre will only track the first referenced
# integration quantities that track said centre.

# Integral #1: unit integrand
VolumeIntegrals_GRMHD::Integration_quantity_keyword[1] = "one"
# Integral #2: CoM
VolumeIntegrals_GRMHD::Integration_quantity_keyword[2] = "centerofmass"
# Integral #3: unit integrand
VolumeIntegrals_GRMHD::Integration_quantity_keyword[3] = "one"
# Integral #4: CoM
VolumeIntegrals_GRMHD::Integration_quantity_keyword[4] = "centerofmass"
# Integral #5: unit integrand
VolumeIntegrals_GRMHD::Integration_quantity_keyword[5] = "one"
# Integral #6: rest mass
VolumeIntegrals_GRMHD::Integration_quantity_keyword[6] = "restmass"

# Set radius of integration for integral #2
VolumeIntegrals_GRMHD::volintegral_sphere__center_x_initial         [2] = -15.2
VolumeIntegrals_GRMHD::volintegral_inside_sphere__radius            [2] =  13.5
# Let the result of integral #2 track the grid centre 0
VolumeIntegrals_GRMHD::amr_centre__tracks__volintegral_inside_sphere[2] =  0

# Set radius of integrattion for integral #3
VolumeIntegrals_GRMHD::volintegral_sphere__center_x_initial         [3] = -15.2
VolumeIntegrals_GRMHD::volintegral_inside_sphere__radius            [3] =  13.5

                                                                                       
                                                                                       
# Set radius of integration for integral #4
VolumeIntegrals_GRMHD::volintegral_sphere__center_x_initial         [4] =  15.2
VolumeIntegrals_GRMHD::volintegral_inside_sphere__radius            [4] =  13.5
# Let the result of integral #4 track the grid centre 1
VolumeIntegrals_GRMHD::amr_centre__tracks__volintegral_inside_sphere[4] =  1

# Set radius of integrattion for integral #5
VolumeIntegrals_GRMHD::volintegral_sphere__center_x_initial         [5] =  15.2
VolumeIntegrals_GRMHD::volintegral_inside_sphere__radius            [5] =  13.5

References

[1]   M.D. Duez, Y.T. Liu, S.L. Shapiro, and B.C. Stephens, Relativistic magnetohydrodynamics in dynamical spacetimes: Numerical methods and tests, Physical Review D, 72, 2, 024028 (2005).

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]






com_integrand_gamma_speed_limit
Scope: private  REAL



Description:



Range   Default: 1e4
0:*
Any positive number






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






integration_quantity_keyword
Scope: private  KEYWORD



Description: Which quantity to integrate



Range   Default: nothing
nothing
Default, null parameter
see [1] below
Use integrands from step(s) immediately preceeding. Useful for Swiss-cheese-type volume integrations.
centerofmass
Center of Mass
restmass
Rest Mass
one
Integrand = 1. Useful for debugging



[1]

usepreviousintegrands




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_grmhd

Inherits:

grid

admbase

carpetregrid2

hydrobase

admbase

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




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_GRMHD. 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)

  vi_grmhd_file_output_routine_startup

  create directory for vi grmhd file output.

 

 Language:c
 Type: function

CCTK_POST_RECOVER_VARIABLES (conditional)

  vi_grmhd_file_output_routine_startup

  create directory for vi grmhd file output.

 

 Language:c
 Type: function

CCTK_INITIAL

  vi_grmhd_initializeintegralcountertozero

  initialize integralcounter variable to zero

 

 Language:c
 Options: global
 Type: function

CCTK_POST_RECOVER_VARIABLES

  vi_grmhd_initializeintegralcountertozero

  initialize integralcounter variable to zero

 

 Language:c
 Options: global
 Type: function

CCTK_ANALYSIS

  vi_grmhd_initializeintegralcounter

  initialize integralcounter variable

 

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

CCTK_ANALYSIS

  vi_grmhd_volumeintegralgroup

  evaluate all volume integrals

 

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

VI_GRMHD_VolumeIntegralGroup

  vi_grmhd_computeintegrand

  compute integrand

 

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

VI_GRMHD_VolumeIntegralGroup

  vi_grmhd_dosum

  do sum

 

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

VI_GRMHD_VolumeIntegralGroup

  vi_grmhd_decrementintegralcounter

  decrement integralcounter variable

 

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

CCTK_ANALYSIS

  vi_grmhd_file_output

  output volumeintegral results to disk

 

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