* more general explanations

* small tweaks to C example
* correct authorship based on @author comments in code
* document another 25 (Fortran) or 28 (C) hidden variables
  which users must avoid using in their own code
* reword description of C array stride variables
* correct spelling of #include paths for macros


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

1 files changed, 106 insertions, 66 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index fe73a12..343bd86 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -61,7 +61,7 @@
 % Example of including a reference
 %   \bibitem{MyArrangement_MyThorn_Author99}
 %   {J. Author, {\em The Title of the Book, Journal, or periodical}, 1 (1999),
-%   1--16. {\tt http://www.nowhere.com/}}
+%   1--16. \texttt{http://www.nowhere.com/}}
 %
 % *======================================================================*
 
@@ -79,7 +79,8 @@
 \begin{document}
 
 \title{ADMMacros}
-\author{Tom Goodale}
+\author{Original code by Gabrielle Allen,\\
+	later enhancements by Denis Pollney and Jonathan Thornburg}
 \date{$ $Date$ $}
 
 \maketitle
@@ -89,107 +90,145 @@
 
 % Add all definitions used in this documentation here
 %   \def\mydef etc
+\def\ie{i.e.\hbox{}}
 \def\del{\nabla}
 
+% get size/spacing of "++" right, cf online C++ FAQ question 35.1
+\def\Cplusplus{\hbox{C\raise.25ex\hbox{\footnotesize ++}}}
+
+
 \begin{abstract}
-Provides macros for common relativity calculations, using the {\bf ADMBase} variables.
+Provides macros for common relativity calculations, using the
+\textbf{ADMBase} variables.
 \end{abstract}
 
+
 \section{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 {\tt ADMBase} (and {\tt
-  StaticConformal} if required).  The macros can be used in both
-Fortran and C code. The macros work pointwise to calculate quantities
-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.
+components, using the basic variables of thorn \textbf{ADMBase} (and
+\textbf{StaticConformal} if required).  The macros can be used in both
+Fortran and C code.  The macros work pointwise to calculate quantities
+at the grid point $(\texttt{i},\texttt{j},\texttt{k})$; 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.
 
 \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.
+$\texttt{i} \pm 1$, $\texttt{j} \pm 1$, and $\texttt{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}
+$\texttt{i} \pm 2$, $\texttt{j} \pm 2$, and $\texttt{k} \pm 2$
+must also be valid.  The only save way to be certain which macros support
+4th~order finite differencing is to check the source code; the macros
+which don't support it simply hard-code 2nd~order finite differencing
+and ignore the \texttt{spatial\_order} parameter.
 
-Each macro described in Section~\ref{admmacros:macros} is implemented using three include
-files.
+At present 4th~order finite differencing is only supported for Fortran
+code.  (That is, at present the C~versions of the macros all ignore the
+\texttt{spatial\_order} parameter.)
 
-\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
-        the macro name. This file should be included in the declarations section
-        of your routine.
-
-\item {\tt <MACRONAME>\_guts.h} is the actual included source code which will calculate
-       the quantities.
-
-\item {\tt <MACRONAME>\_undefine.h} resets the macros. This file {\bf must be included}
-        at the end of every loop using macros. Without an undefine file, a second loop
-        using macros will assume that quantities have already been calculated.
-
-\end{itemize}
+\section{Using ADM Macros}
 
-To use the macros, first make sure that you really want to use the
-macro pointwise, and that you have already set the indices $i$, $j$,
-and $k$ to identify the correct grid point.
+Each macro described in Section~\ref{admmacros:macros} is implemented
+using three include files:
+\begin{description}
+\item[\texttt{<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.
+
+\item[\texttt{<MACRONAME>\_guts.h}]
+	is the actual included source code which will calculate the quantities.
+
+\item[\texttt{<MACRONAME>\_undefine.h}]
+	resets the macros. This file \textbf{must} be \texttt{\#include}d
+	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).
+\end{description}
+
+The macros which compute derivatives also use the following variables;
+you should avoid using these in your code:
+\begin{verbatim}
+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
+\end{verbatim}
 
-Find the name of the macro from the table in
+To use the macros, first find the name of the macro from the table in
 Section~\ref{admmacros:macros} and put the include files in the
 correct place following the instructions above. Note that all ADMMacro
-include files are in the directory {\tt
-  CactusEinstein/ADMMacros/src/macros}, so this means adding lines
-such as
-
-{\tt
+include files are in the directory \texttt{CactusEinstein/ADMMacros/src/macro/},
+so you include the macros with lines such as
 \begin{verbatim}
-#include "CactusEinstein/ADMacros/src/macro/<MACRONAME>_<TYPE>.h"
+#include "CactusEinstein/ADMMacros/src/macro/<MACRONAME>_<TYPE>.h"
 \end{verbatim}
-}
+(Recall that Cactus uses a C-style preprocessor for Fortran as well as
+C/\Cplusplus{} code; you use the same \texttt{\#include}s for all these
+languages.)
 
 Each variable that the macro calculates is listed in the table of
 Section~\ref{admmacros:macros}.  Note that these variable names are
-themselves macros and are case sensitive. {\bf Always use the macro
+themselves macros and are case sensitive. \textbf{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.}
 
 \subsection{Fortran}
 
 If you are using the macros inside a Fortran function then the
-{\tt i}, {\tt j} and {\tt k} indices are used directly.  This is
+\texttt{i}, \texttt{j} and \texttt{k} indices are used directly.  This is
 shown in the Fortran example below.
 
 \subsection{C}
 
 If you are using the macros inside a C function then you must define
-the index {\tt ijk}, which can be found from {\tt i}, {\tt j} and {\tt k}
-using the macro {\tt CCTK\_GFINDEX3D(cctkGH,i,j,k)}, and also the offsets
-{\tt di}, {\tt dj} and {\tt dk}, so that the point $(i-1,j,k)$ is the same
-as {\tt ijk - di} and so on.  That is, you must define
-{\tt di = 1}, {\tt dj = cctk\_lsh[0]} and {\tt dk = cctk\_lsh[0]*cctk\_lsh[1]}.
-The C example below should make this clearer.
+the grid-function subscripting index \texttt{ijk}, which can be found
+from \texttt{i}, \texttt{j} and \texttt{k} using the macro
+\texttt{CCTK\_GFINDEX3D(cctkGH,i,j,k)}.  Of course, since \texttt{ijk}
+depends on \texttt{i}, \texttt{j} and \texttt{k}, you have to assign
+\texttt{ijk} its value \textbf{inside} the loop-over-grid-points loops.
+
+You must also define the grid-function strides \texttt{di}, \texttt{dj}
+and \texttt{dk} to give the grid-function subscripting index offsets of
+the grid points $(i+1,j,k)$, $(i,j+1,k)$, and $(i,j,k+1)$ (respectively)
+relative to $(i,j,k)$.  That is, you should define \texttt{di = 1},
+\texttt{dj = cctk\_lsh[0]}, and \texttt{dk = cctk\_lsh[0]*cctk\_lsh[1]}.
+Since these don't depend on \texttt{i}, \texttt{j} and \texttt{k},
+they can be assigned values once outside the loop-over-grid-points loops.
+
+The C example below should make this clear.
+
+Note that you should assign all these variables their values \textbf{before}
+\texttt{\#include}ing the \texttt{<MACRONAME>\_guts.h} macro (it may do
+calculations which use these values).
+
 
 \section{Examples}
 
 \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 \texttt{CactusEinstein/Maximal} and uses
+the $trK$ macro to calculate the trace of the extrinsic curvature.
 
+\newpage	% we'd like the entire example to fit on a single page
 \begin{verbatim}
 c     Declarations for macros.
 #include "CactusEinstein/ADMMacros/src/macro/TRK_declare.h"
@@ -213,7 +252,7 @@ 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$
+	= g^{ij} \partial_{ij} \phi - g^{ij} \Gamma^k_{ij} \partial_k \phi$,
 assuming that the partial derivatives $\partial_{ij} \phi$ and $\partial_k \phi$
 have already been computed:
 
@@ -229,11 +268,11 @@ have already been computed:
  * 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)
 {
@@ -243,7 +282,7 @@ 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;
 
-/* magic variables for ADMMacros (see the ADMMacros thorn guide for details) */
+/* grid-function strides for ADMMacros */
 const int di = 1;
 const int dj = cctk_lsh[0];
 const int dk = cctk_lsh[0]*cctk_lsh[1];
@@ -258,9 +297,10 @@ const int dk = cctk_lsh[0]*cctk_lsh[1];
     {
     for (i = 1 ; i < cctk_lsh[0]-1 ; ++i)
     {
-    const int ijk = CCTK_GFINDEX3D(cctkGH,i,j,k);   /* another magic variable for ADMMacros */
+    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 this grid point */
+    /* compute the ADMMacros $g^{ij}$ and $\Gamma^k_{ij}$ variables at the (i,j,k) grid point */
     #include "CactusEinstein/ADMMacros/src/macro/UPPERMET_guts.h"
     #include "CactusEinstein/ADMMacros/src/macro/CHR2_guts.h"
 
@@ -294,12 +334,13 @@ const int dk = cctk_lsh[0]*cctk_lsh[1];
 \end{verbatim}
 \endgroup
 
+
 \section{Macros}
 \label{admmacros:macros}
 Macros exist for the following quantities
 
 \begin{tabular}{p{5cm}p{5cm}p{5cm}}
-{\bf Calculates} & {\bf Macro Name} & {\bf Sets variables} \\
+\textbf{Calculates} & \textbf{Macro Name} & \textbf{Sets variables} \\
 All first 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 &\\
@@ -326,6 +367,7 @@ Source term in evolution equation for conformal metric, $\tilde{g}_{ij,t}$: & DC
 
 \end{tabular}
 
+
 \section{Definitions}
 
 \begin{equation}
@@ -336,8 +378,6 @@ Source term in evolution equation for conformal metric, $\tilde{g}_{ij,t}$: & DC
 \Gamma^{c}_{\;\;ab} = g^{cd}\Gamma_{dab} = \frac{1}{2} g^{cd} \left(g_{ad,b} + g_{bd,a} - g_{ab,d}\right)
 \end{equation}
 
-%\section{Comments}
-
 % Do not delete next line
 % END CACTUS THORNGUIDE
 \end{document}