* document 2nd vs 4th order FD parameter

* clarify comments in example


git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinBase/ADMMacros/trunk@79 b1d164ef-f17a-46e7-89d4-021c7118ef4e

1 files changed, 72 insertions, 55 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 947e1ce..fe73a12 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -106,15 +106,32 @@ at specific grid points, which are always labelled by {\tt i}, {\tt j}
 and {\tt k}. They are written in such a way that needed quantities
 which are already calculated are reused.
 
+\subsection{Finite Differencing}
+
+By default, the macros use centered 2nd~order finite differencing,
+with 3-point finite difference molecules.
+That is, when finite differencing the the grid-point indices
+${\tt i} \pm 1$, ${\tt j} \pm 1$, and ${\tt k} \pm 1$ must also be valid.
+
+Some of the macros also support centered 4th~order finite differencing;
+This is selected with the parameter \verb|spatial_order|.  This may be
+set to either~$2$ or~$4$; it defaults to~$2$.  If it's set to~$4$, then
+5-point finite difference molecules are used, so the grid-point indices
+${\tt i} \pm 2$, ${\tt j} \pm 2$, and ${\tt k} \pm 2$ must also be valid.
+
+At present 4th~order finite differencing is only supported for Fortran code.
+(That is, at present the C~versions of the macros simply ignore the
+\verb|spatial_order| parameter.)
+
 \section{Using ADM Macros}
 
-Each macro described in Section~\ref{admmacros:macros} is implemented using three include 
-files. 
+Each macro described in Section~\ref{admmacros:macros} is implemented using three include
+files.
 
 \begin{itemize}
 
-\item {\tt <MACRONAME>\_declare.h} sets up the declarations for the internal macro 
-        variables. All the internal (hidden) variables have names beginning with 
+\item {\tt <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 file should be included in the declarations section
         of your routine.
 
@@ -170,14 +187,14 @@ The C example below should make this clearer.
 
 \subsection{Fortran}
 
-This example comes from thorn {\tt CactusEinstein/Maximal} and uses the $trK$ macro to 
-calculate the trace of the extrinsic curvature. 
+This example comes from thorn {\tt CactusEinstein/Maximal} and uses the $trK$ macro to
+calculate the trace of the extrinsic curvature.
 
 \begin{verbatim}
 c     Declarations for macros.
 #include "CactusEinstein/ADMMacros/src/macro/TRK_declare.h"
 
-<CUT> 
+<CUT>
 
 c     Add the shift term: N = B^i D_i(trK).
       if ((maxshift).and.(shift_state.eq.1)) then
@@ -197,26 +214,26 @@ c     Add the shift term: N = B^i D_i(trK).
 This function computes the curved-space Laplacian of a scalar field $\phi$,
 $\del^i \del_i \phi
 	= g^{ij} \partial_{ij} \phi - g^{ij} \Gamma^k_{ij} \partial_k \phi$
-using centered 2nd order finite differencing.
+assuming that the partial derivatives $\partial_{ij} \phi$ and $\partial_k \phi$
+have already been computed:
 
-\newpage
+\newpage	% we'd like the entire example to fit on a single page
 \begingroup
 \footnotesize
 \begin{verbatim}
 /*
  * 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
- * $$
+ * $\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
+ * 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)
 {
@@ -235,41 +252,41 @@ const int dk = cctk_lsh[0]*cctk_lsh[1];
 #include "CactusEinstein/ADMMacros/src/macro/UPPERMET_declare.h"
 #include "CactusEinstein/ADMMacros/src/macro/CHR2_declare.h"
 
-  for (k = 0 ; k < cctk_lsh[2] ; ++k)
-  {
-  for (j = 0 ; j < cctk_lsh[1] ; ++j)
-  {
-  for (i = 0 ; i < cctk_lsh[0] ; ++i)
-  {
-  const int ijk = CCTK_GFINDEX3D(cctkGH,i,j,k);   /* another magic variable for ADMMacros */
-
-  /* compute the ADMMacros $g^{ij}$ and $\Gamma^k_{ij}$ */
-  #include "CactusEinstein/ADMMacros/src/macro/UPPERMET_guts.h"
-  #include "CactusEinstein/ADMMacros/src/macro/CHR2_guts.h"
-
-  /* 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];
-  }
-  }
-  }
+    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);   /* another magic variable for ADMMacros */
+
+    /* compute the ADMMacros $g^{ij}$ and $\Gamma^k_{ij}$ variables at this grid point */
+    #include "CactusEinstein/ADMMacros/src/macro/UPPERMET_guts.h"
+    #include "CactusEinstein/ADMMacros/src/macro/CHR2_guts.h"
+
+    /* 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];
+    }
+    }
+    }
 
 #include "CactusEinstein/ADMMacros/src/macro/UPPERMET_undefine.h"
 #include "CactusEinstein/ADMMacros/src/macro/CHR2_undefine.h"