xx ADMMacros

ADMMacros

Original code by Gabrielle Allen, later enhancements by Denis Pollney

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 Christoffel 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 ; 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 Differencing

By default, the macros use centered 2ndxorder finite differencing, with 3-point finite difference molecules. That is, when finite differencing the the grid-point indices , , and must also be valid, and driver::ghostxsize must be set to at least .

Some of the macros also support centered 4thxorder finite differencing; This is selected with the parameter spatial_order. This may be set to eitherx orx; it defaults tox. If it’s set tox, then 5-point finite difference molecules are used, so the grid-point indices , , and must also be valid, and driver::ghostxsize must be set to at least . The only save way to be certain which macros support 4thxorder finite differencing is to check the source code; the macros which don’t support it simply hard-code 2ndxorder finite differencing and ignore the

spatialxorder parameter.

At present 4thxorder finite differencing is only supported for Fortran code. (That is, at present the Cxversions of the macros all ignore the spatialxorder parameter.)

2 Using ADM Macros

Each macro described in Sectionx4 is implemented using three include files:

<MACRONAME>xdeclare.h

sets up the declarations for the internal macro variables. All the internal (hidden) variables have names beginning with the macro name. This file should be included in the declarations section of your routine.

<MACRONAME>xguts.h

is the actual included source code which will calculate the quantities.

<MACRONAME>xundefine.h

resets the macros. This file 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,xdj2,xdk2xxxxxxxx/*xonlyxinxC,xnotxinxFortranx*/
dt,xdx,xdy,xdz
idx,xidy,xidz
i2dx,xi2dy,xi2dz
i12dx,xi12dy,xi12dz
idxx,xidxy,xidxz,xidyy,xidyz,xidzz
i12dxx,xi12dyy,xi12dzz
i36dxy,xi36dxz,xi36dyz

To use the macros, first find the name of the macro from the table in Sectionx4 and put the include files in the correct place following the instructions above. Note that all ADMMacro include files are in the directory EinsteinBase/ADMMacros/src/macro/, so you include the macros with lines such as

#includex"EinsteinBase/ADMMacros/src/macro/<MACRONAME>_<TYPE>.h"

(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 Sectionx4. 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 redefine 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 files:

ADMxSpacingxdeclare.h

This must be #included before any of the other <MACRONAME>xdeclare.h files.

ADMxSpacing.h

This must be #included after all of the other <MACRONAME>xdeclare.h and before any of the

     <MACRONAME>xguts.h files.

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 define the grid-function subscripting index ijk, which can be found from i, j and k using the macro CCTKxGFINDEX3D(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 define the grid-function strides di, dj and dk to give the grid-function subscripting index offsets of the grid points , , and (respectively) relative to . That is, you should define di = 1, dj = cctkxlsh[0], and dk = cctkxlsh[0]*cctkxlsh[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>xguts.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 macro to calculate the trace of the extrinsic curvature.

cxxxxxDeclarationsxforxmacros.
#includex"EinsteinBase/ADMMacros/src/macro/TRK_declare.h"
cxwe'rexnotxtakingxanyxderivativesxhere,xbutxifxwexwere,
cxwexwouldxalsoxneedxthexfollowingxline:
#includex"EinsteinBase/ADMMacros/src/macro/ADM_Spacing_declare.h"
cxwe'rexnotxtakingxanyxderivativesxhere,xbutxifxwexwere,
cxwexwouldxalsoxneedxthexfollowingxline:
#includex"EinsteinBase/ADMMacros/src/macro/ADM_Spacing.h"
<CUT>
cxxxxxAddxthexshiftxterm:xNx=xB^ixD_i(trK).
xxxxxxifx((maxshift).and.(shift_state.eq.1))xthen
xxxxxxxxxdoxk=1,nz
xxxxxxxxxxxxdoxj=1,ny
xxxxxxxxxxxxxxxdoxi=1,nx
#includex"EinsteinBase/ADMMacros/src/macro/TRK_guts.h"
xxxxxxxxxxxxxxxxxxK_temp(i,j,k)x=xTRK_TRK
xxxxxxxxxxxxxxxxendxdo
xxxxxxxxxxxxxendxdo
xxxxxxxxxendxdo
#includex"EinsteinBase/ADMMacros/src/macro/TRK_undefine.h"

3.2 C

This function computes the curved-space Laplacian of a scalar field , , assuming that the partial derivatives and have already been computed:

/*
x*xThisxfunctionxcomputesxthexcurved-spacexLaplacianxofxaxscalarxfield,
x*x$\del^ix\del_ix\phi
x*xxxxx=xg^{ij}x\partial_{ij}x\phix-xg^{ij}x\Gamma^k_{ij}x\partial_kx\phi$
x*xatxthexinteriorxgridxpointsxonly;xitxdoesn'txdoxanythingxatxallxonxthe
x*xboundaries.
x*
x*xThisxfunctionxusesxthexfollowingxCactusxgridxfunctions:
x*xxxxinput:xxxdx_phi,xdy_phi,xdz_phixxxxxxx#x1stxderivativesxofxphi
x*xxxxxxxxxxxxxdxx_phi,xdxy_phi,xdxz_phi,xxx#x2ndxderivativesxofxphi
x*xxxxxxxxxxxxxxxxxxxxxxdyy_phi,xdyz_phi,
x*xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxdzz_phi
x*xxxxoutput:xxLaplacian_phi
x*/
voidxcompute_Laplacian(CCTK_ARGUMENTS)
{
DECLARE_CCTK_ARGUMENTS
intxi,j,k;
/*xcontractedxChristoffelxsymbolsx$\Gamma^kx=xg^{ij}x\Gamma^k_{ij}$x*/
CCTK_REALxGamma_u_x,xGamma_u_y,xGamma_u_z;
/*xgrid-functionxstridesxforxADMMacrosx*/
constxintxdix=x1;
constxintxdjx=xcctk_ash[0];
constxintxdkx=xcctk_ash[0]*cctk_ash[1];
/*xdeclarexthexADMMacrosxvariablesxforx$g^{ij}$xandx$\Gamma^k_{ij}$x*/
#includex"EinsteinBase/ADMMacros/src/macro/UPPERMET_declare.h"
#includex"EinsteinBase/ADMMacros/src/macro/CHR2_declare.h"
xxxxforx(kx=x1x;xkx<xcctk_lsh[2]-1x;x++k)
xxxx{
xxxxforx(jx=x1x;xjx<xcctk_lsh[1]-1x;x++j)
xxxx{
xxxxforx(ix=x1x;xix<xcctk_lsh[0]-1x;x++i)
xxxx{
xxxxconstxintxijkx=xCCTK_GFINDEX3D(cctkGH,i,j,k);xxx/*xgrid-functionxsubscriptingxindexxforxADMMacrosx*/
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/*x(mustxbexassignedxinsidexthexi,j,kxloops)x*/
xxxx/*xcomputexthexADMMacrosx$g^{ij}$xandx$\Gamma^k_{ij}$xvariablesxatxthex(i,j,k)xgridxpointx*/
xxxx#includex"EinsteinBase/ADMMacros/src/macro/UPPERMET_guts.h"
xxxx#includex"EinsteinBase/ADMMacros/src/macro/CHR2_guts.h"
xxxx/*xcomputexthexcontractedxChristoffelxsymbolsx$\Gamma^kx=xg^{ij}x\Gamma^k_{ij}$x*/
xxxxGamma_u_xx=
xxxxxxUPPERMET_UXX*CHR2_XXXx+x2.0*UPPERMET_UXY*CHR2_XXYx+x2.0*UPPERMET_UXZ*CHR2_XXZ
xxxxxxxxxxxxxxxxxxxxxxxxxxxx+xxxxxUPPERMET_UYY*CHR2_XYYx+x2.0*UPPERMET_UYZ*CHR2_XYZ
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx+xxxxxUPPERMET_UZZ*CHR2_XZZ;
xxxxGamma_u_yx=
xxxxxxUPPERMET_UXX*CHR2_YXXx+x2.0*UPPERMET_UXY*CHR2_YXYx+x2.0*UPPERMET_UXZ*CHR2_YXZ
xxxxxxxxxxxxxxxxxxxxxxxxxxxx+xxxxxUPPERMET_UYY*CHR2_YYYx+x2.0*UPPERMET_UYZ*CHR2_YYZ
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx+xxxxxUPPERMET_UZZ*CHR2_YZZ;
xxxxGamma_u_zx=
xxxxxxUPPERMET_UXX*CHR2_ZXXx+x2.0*UPPERMET_UXY*CHR2_ZXYx+x2.0*UPPERMET_UXZ*CHR2_ZXZ
xxxxxxxxxxxxxxxxxxxxxxxxxxxx+xxxxxUPPERMET_UYY*CHR2_ZYYx+x2.0*UPPERMET_UYZ*CHR2_ZYZ
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx+xxxxxUPPERMET_UZZ*CHR2_ZZZ;

xxxx/*xcomputexthexLaplacianx*/
xxxxLaplacian_phi[ijk]x=
xxxxxxUPPERMET_UXX*dxx_phi[ijk]x+x2.0*UPPERMET_UXY*dxy_phi[ijk]x+x2.0*UPPERMET_UXZ*dxz_phi[ijk]
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx+xxxxxUPPERMET_UYY*dyy_phi[ijk]x+x2.0*UPPERMET_UYZ*dyz_phi[ijk]
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx+xxxxxUPPERMET_UZZ*dzz_phi[ijk]
xxxxxx-xxGamma_u_x*dx_phi[ijk]xx-xxxxxxxxGamma_u_y*dy_phi[ijk]xx-xxxxxxxxGamma_u_z*dz_phi[ijk];
xxxx}
xxxx}
xxxx}
#includex"EinsteinBase/ADMMacros/src/macro/UPPERMET_undefine.h"
#includex"EinsteinBase/ADMMacros/src/macro/CHR2_undefine.h"
}

4 Macros

Macros exist for the following quantities

11Calculates  11Macro Name  11Sets variables
11All first spatial derivatives of lapse, : 11DA  11DAxDXDA,  DAxDYDA, DAxDZDA
11All second spatial derivatives of lapse, : 11DDA  11DDAxDXXDA, DDAxDXYDA, DDAxDXZDA, DDAxDYYDA, DDAxDYZDA, DDAxDZZDA
11All second covariant spatial derivatives of lapse, : 11CDCDA  11
11All first spatial derivatives of shift, : 11DB  11
11All first covariant derivatives of the extrinsic curvature, 11CDK  11
11First covariant derivatives of the extrinsic curvature, , , 11CDXCDK,  CDYCDK, CDZCDK11
11Determinant of 3-metric:  11DETG  11
11Upper 3-metric, :  11UPPERMET  11
11Trace of extrinsic curvature : 11TRK  11
11Trace of stress energy tensor: 11TRT  11
11Hamiltonian constraint: 11HAMADM 11
11Partial derivatives of extrinsic curvature, , , : 11DXDK, DYDK, DZDK  11
11First partial derivatives of 3-metric, , , : 11DXDG, DYDG, DZDG  11
11All first partial derivatives of 3-metric, : 11DG  11
11First covariant derivatives of 3-metric, , , : 11DXDCG, DYDCG, DZDCG 11
11Second partial derivatives of 3-metric, , , : 11DXXDG, DXYDG, DXZDG, DYYDG, DYZDG, DZZDG11
11All second partial derivative of 3-metric, 11DDG  11
11Ricci tensor :  11RICCI  11
11Trace of Ricci tensor :  11TRRICCI  11
11Christoffel symbols of first kind: 11CHR1  11
11Christoffel symbols of second kind : 11CHR2  11
11Momentum constraints  11MOMX, MOMY, MOMZ  11
11Source  term  in evolution equation for conformal metric, : 11DCGDT  11

11

5 Definitions 6 Parameters

11spatialxorder 10Scope: restrictedx01  INT

11Description: Order of spatial differencing

11 Range 10 x01 Default: 2
112  102nd order finite differencing
114  104th order finite differencing

11

7 Interfaces

General Implements: admmacros

Grid Variables

7.0.1 PUBLIC GROUPS

11x Group Names x10x Variable Names xx01 Details x11x
11 localxspatialxorder 10 localxspatialxorder x01  compact110
11                 10  x01 description11Can be set pointwise to change the finite differencing order
11                 10  x01 dimensions110
11                 10  x01 distribution11CONSTANT
11                 10  x01 group type11SCALAR
11                 10  x01 timelevels111
11                 10  x01variable type11INT

11

Uses header: CalcTmunuxtemps.inc CalcTmunu.inc 8 Schedule This section lists all the variables which are assigned storage by thorn EinsteinBase/ADMMacros. 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 x

11Always:  11x
11localxspatialxorder11x

11x  11x

11

Scheduled Functions

CCTKxBASEGRID x admmacrosxsetlocalspatialorder x initialize the localxspatialxorder x

11x11Language:11c
11 x 11Type: 11function
11 x 11Writes: 11admmacros::localxspatialxorder(everywhere)