Date

Abstract

Provides macros for common relativity calculations, using the ADMBase variables.

### 1 Purpose

This thorn provides various macros which can be used to calculate quantities, such as the Christoﬀel Symbol or Riemann Tensor components, using the basic variables of thorn ADMBase. The macros can be used in both Fortran and C code. The macros work pointwise to calculate quantities at the grid point $\left(\mathtt{\text{i}},\mathtt{\text{j}},\mathtt{\text{k}}\right)$; it’s up to you to loop over all the grid points where you want computations done. The macros are written in such a way that within any single loop, quantities which have already been calculated are automagically reused as needed in later calculations.

#### 1.1 Finite Diﬀerencing

By default, the macros use centered 2nd order ﬁnite diﬀerencing, with 3-point ﬁnite diﬀerence molecules. That is, when ﬁnite diﬀerencing the the grid-point indices $\mathtt{\text{i}}±1$, $\mathtt{\text{j}}±1$, and $\mathtt{\text{k}}±1$ must also be valid, and driver::ghost_size must be set to at least $1$.

Some of the macros also support centered 4th order ﬁnite diﬀerencing; This is selected with the parameter spatial_order. This may be set to either $2$ or $4$; it defaults to $2$. If it’s set to $4$, then 5-point ﬁnite diﬀerence molecules are used, so the grid-point indices $\mathtt{\text{i}}±2$, $\mathtt{\text{j}}±2$, and $\mathtt{\text{k}}±2$ must also be valid, and driver::ghost_size must be set to at least $2$. The only save way to be certain which macros support 4th order ﬁnite diﬀerencing is to check the source code; the macros which don’t support it simply hard-code 2nd order ﬁnite diﬀerencing and ignore the spatial_order parameter.

At present 4th order ﬁnite diﬀerencing is only supported for Fortran code. (That is, at present the C versions of the macros all ignore the spatial_order parameter.)

Each macro described in Section 4 is implemented using three include ﬁles:

<MACRONAME>_declare.h
sets up the declarations for the internal macro variables. All the internal (hidden) variables have names beginning with the macro name. This ﬁle should be included in the declarations section of your routine.
<MACRONAME>_guts.h
is the actual included source code which will calculate the quantities.
<MACRONAME>_undefine.h
resets the macros. This ﬁle must be #included at the end of every loop using macros. Without this, a second loop using macros would assume that quantities have already been calculated (and thus get wrong results).

The macros which compute derivatives also use the following variables; you should avoid using these in your code, in either lower or upper case:

di2, dj2, dk2        /* only in C, not in Fortran */
dt, dx, dy, dz
idx, idy, idz
i2dx, i2dy, i2dz
i12dx, i12dy, i12dz
idxx, idxy, idxz, idyy, idyz, idzz
i12dxx, i12dyy, i12dzz
i36dxy, i36dxz, i36dyz

To use the macros, ﬁrst ﬁnd the name of the macro from the table in Section 4 and put the include ﬁles in the correct place following the instructions above. Note that all ADMMacro include ﬁles are in the directory EinsteinBase/ADMMacros/src/macro/, so you include the macros with lines such as

(Recall that Cactus uses a C-style preprocessor for Fortran as well as C/C++ code; you use the same #includes for all these languages.)

Each variable that the macro calculates is listed in the table of Section 4. Note that these variable names are themselves macros and are case sensitive. Always use the macro variables on the right hand sides of equations, never redeﬁne them yourself, since they may be used in later (hidden) calculations.

#### 2.1 Fortran

If you are using the macros inside a Fortran function then the i, j and k indices are used directly.

If you’re using (either directly or indirectly) any macro which computes derivatives, you also need to #include two additional ﬁles:

This must be #included before any of the other <MACRONAME>_declare.h ﬁles.

This must be #included after all of the other <MACRONAME>_declare.h and before any of the <MACRONAME>_guts.h ﬁles.

The Fortran example below should make this clear(er).

#### 2.2 C

If you are using the macros inside a C function then you must deﬁne the grid-function subscripting index ijk, which can be found from i, j and k using the macro CCTK_GFINDEX3D(cctkGH,i,j,k). Of course, since ijk depends on i, j and k, you have to assign ijk its value inside the loop-over-grid-points loops.

You must also deﬁne the grid-function strides di, dj and dk to give the grid-function subscripting index oﬀsets of the grid points $\left(i+1,j,k\right)$, $\left(i,j+1,k\right)$, and $\left(i,j,k+1\right)$ (respectively) relative to $\left(i,j,k\right)$. That is, you should deﬁne di = 1, dj = cctk_lsh[0], and dk = cctk_lsh[0]*cctk_lsh[1]. Since these don’t depend on i, j and k, they can be assigned values once outside the loop-over-grid-points loops.

The C example below should make this clear(er).

Note that you should assign all these variables their values before #includeing the <MACRONAME>_guts.h macro (it may do calculations which use these values).

### 3 Examples

#### 3.1 Fortran

This example comes from thorn CactusArchive/Maximal and uses the $trK$ macro to calculate the trace of the extrinsic curvature.

c     Declarations for macros.

c we’re not taking any derivatives here, but if we were,
c we would also need the following line:

c we’re not taking any derivatives here, but if we were,
c we would also need the following line:

<CUT>

c     Add the shift term: N = B^i D_i(trK).
if ((maxshift).and.(shift_state.eq.1)) then
do k=1,nz
do j=1,ny
do i=1,nx
K_temp(i,j,k) = TRK_TRK
end do
end do
end do

#### 3.2 C

This function computes the curved-space Laplacian of a scalar ﬁeld $\varphi$, ${\nabla }^{i}{\nabla }_{i}\varphi ={g}^{ij}{\partial }_{ij}\varphi -{g}^{ij}{\Gamma }_{ij}^{k}{\partial }_{k}\varphi$, assuming that the partial derivatives ${\partial }_{ij}\varphi$ and ${\partial }_{k}\varphi$ have already been computed:

/*
* This function computes the curved-space Laplacian of a scalar field,
* $\del^i \del_i \phi * = g^{ij} \partial_{ij} \phi - g^{ij} \Gamma^k_{ij} \partial_k \phi$
* at the interior grid points only; it doesn’t do anything at all on the
* boundaries.
*
* This function uses the following Cactus grid functions:
*    input:   dx_phi, dy_phi, dz_phi       # 1st derivatives of phi
*             dxx_phi, dxy_phi, dxz_phi,   # 2nd derivatives of phi
*                      dyy_phi, dyz_phi,
*                               dzz_phi
*    output:  Laplacian_phi
*/
void compute_Laplacian(CCTK_ARGUMENTS)
{
DECLARE_CCTK_ARGUMENTS
int i,j,k;

/* contracted Christoffel symbols $\Gamma^k = g^{ij} \Gamma^k_{ij}$ */
CCTK_REAL Gamma_u_x, Gamma_u_y, Gamma_u_z;

/* grid-function strides for ADMMacros */
const int di = 1;
const int dj = cctk_ash[0];
const int dk = cctk_ash[0]*cctk_ash[1];

/* declare the ADMMacros variables for $g^{ij}$ and $\Gamma^k_{ij}$ */

for (k = 1 ; k < cctk_lsh[2]-1 ; ++k)
{
for (j = 1 ; j < cctk_lsh[1]-1 ; ++j)
{
for (i = 1 ; i < cctk_lsh[0]-1 ; ++i)
{
const int ijk = CCTK_GFINDEX3D(cctkGH,i,j,k);   /* grid-function subscripting index for ADMMacros */
/* (must be assigned inside the i,j,k loops) */

/* compute the ADMMacros $g^{ij}$ and $\Gamma^k_{ij}$ variables at the (i,j,k) grid point */

/* compute the contracted Christoffel symbols $\Gamma^k = g^{ij} \Gamma^k_{ij}$ */
Gamma_u_x =
UPPERMET_UXX*CHR2_XXX + 2.0*UPPERMET_UXY*CHR2_XXY + 2.0*UPPERMET_UXZ*CHR2_XXZ
+     UPPERMET_UYY*CHR2_XYY + 2.0*UPPERMET_UYZ*CHR2_XYZ
+     UPPERMET_UZZ*CHR2_XZZ;
Gamma_u_y =
UPPERMET_UXX*CHR2_YXX + 2.0*UPPERMET_UXY*CHR2_YXY + 2.0*UPPERMET_UXZ*CHR2_YXZ
+     UPPERMET_UYY*CHR2_YYY + 2.0*UPPERMET_UYZ*CHR2_YYZ
+     UPPERMET_UZZ*CHR2_YZZ;
Gamma_u_z =
UPPERMET_UXX*CHR2_ZXX + 2.0*UPPERMET_UXY*CHR2_ZXY + 2.0*UPPERMET_UXZ*CHR2_ZXZ
+     UPPERMET_UYY*CHR2_ZYY + 2.0*UPPERMET_UYZ*CHR2_ZYZ
+     UPPERMET_UZZ*CHR2_ZZZ;

/* compute the Laplacian */
Laplacian_phi[ijk] =
UPPERMET_UXX*dxx_phi[ijk] + 2.0*UPPERMET_UXY*dxy_phi[ijk] + 2.0*UPPERMET_UXZ*dxz_phi[ijk]
+     UPPERMET_UYY*dyy_phi[ijk] + 2.0*UPPERMET_UYZ*dyz_phi[ijk]
+     UPPERMET_UZZ*dzz_phi[ijk]
-  Gamma_u_x*dx_phi[ijk]  -        Gamma_u_y*dy_phi[ijk]  -        Gamma_u_z*dz_phi[ijk];
}
}
}

 Calculates Macro Name Sets variables All ﬁrst spatial derivatives of lapse, ${\alpha }_{,i}$: DA DA_DXDA, DA_DYDA, DA_DZDA All second spatial derivatives of lapse, ${\alpha }_{,ij}$: DDA DDA_DXXDA, DDA_DXYDA, DDA_DXZDA, DDA_DYYDA, DDA_DYZDA, DDA_DZZDA All second covariant spatial derivatives of lapse, ${\alpha }_{;ij}$: CDCDA All ﬁrst spatial derivatives of shift, ${\beta }_{\phantom{\rule{2.77695pt}{0ex}}\phantom{\rule{2.77695pt}{0ex}}j}^{i}$: DB All ﬁrst covariant derivatives of the extrinsic curvature, ${K}_{ij;kl}$ CDK First covariant derivatives of the extrinsic curvature, ${K}_{ij;x}$, ${K}_{ij;y}$, ${K}_{ij;z}$ CDXCDK, CDYCDK, CDZCDK Determinant of 3-metric: DETG Upper 3-metric, $gij$: UPPERMET Trace of extrinsic curvature $trK$: TRK Trace of stress energy tensor: TRT Hamiltonian constraint: HAMADM Partial derivatives of extrinsic curvature, ${K}_{ij,x}$, ${K}_{ij,y}$, ${K}_{ij,z}$: DXDK, DYDK, DZDK First partial derivatives of 3-metric, ${g}_{ij,x}$, ${g}_{ij,y}$, ${g}_{ij,z}$: DXDG, DYDG, DZDG All ﬁrst partial derivatives of 3-metric, ${g}_{ij,k}$: DG First covariant derivatives of 3-metric, ${g}_{ij;x}$, ${g}_{ij;y}$, ${g}_{ij;z}$: DXDCG, DYDCG, DZDCG Second partial derivatives of 3-metric, ${g}_{ij,xx}$, ${g}_{ij,xy}$, ${g}_{ij,xz}$: DXXDG, DXYDG, DXZDG, DYYDG, DYZDG, DZZDG All second partial derivative of 3-metric, ${g}_{ij,lm}$ DDG Ricci tensor ${R}_{ij}$: RICCI Trace of Ricci tensor $R$: TRRICCI Christoﬀel symbols of ﬁrst kind: ${\Gamma }_{cab}$ CHR1 Christoﬀel symbols of second kind ${\Gamma }_{\phantom{\rule{2.77695pt}{0ex}}\phantom{\rule{2.77695pt}{0ex}}ab}^{c}$: CHR2 Momentum constraints MOMX, MOMY, MOMZ Source term in evolution equation for conformal metric, ${\stackrel{̃}{g}}_{ij,t}$: DCGDT