* correct a horrible mistake, where anyone following the instructions

  for how to use the ADMMacros in C code would get garbage values for
  *all* derivatives!  (the thorn guide gave values for the magic variables
  di, dj, dk which were for C storage order, but Cactus gridfns use
  Fortran storage order)
* add a C example (with correct settings of di, dj, dk, too!)


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

1 files changed, 181 insertions, 16 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index dc022a6..2b6eff7 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -1,10 +1,80 @@
+% *======================================================================*
+%  Cactus Thorn template for ThornGuide documentation
+%  Author: Ian Kelley
+%  Date: Sun Jun 02, 2002
+%  $Header$
+%
+%  Thorn documentation in the latex file doc/documentation.tex
+%  will be included in ThornGuides built with the Cactus make system.
+%  The scripts employed by the make system automatically include
+%  pages about variables, parameters and scheduling parsed from the
+%  relevant thorn CCL files.
+%
+%  This template contains guidelines which help to assure that your
+%  documentation will be correctly added to ThornGuides. More
+%  information is available in the Cactus UsersGuide.
+%
+%  Guidelines:
+%   - Do not change anything before the line
+%       % START CACTUS THORNGUIDE",
+%     except for filling in the title, author, date, etc. fields.
+%        - Each of these fields should only be on ONE line.
+%        - Author names should be separated with a \\ or a comma.
+%   - You can define your own macros, but they must appear after
+%     the START CACTUS THORNGUIDE line, and must not redefine standard
+%     latex commands.
+%   - To avoid name clashes with other thorns, 'labels', 'citations',
+%     'references', and 'image' names should conform to the following
+%     convention:
+%       ARRANGEMENT_THORN_LABEL
+%     For example, an image wave.eps in the arrangement CactusWave and
+%     thorn WaveToyC should be renamed to CactusWave_WaveToyC_wave.eps
+%   - Graphics should only be included using the graphicx package.
+%     More specifically, with the "\includegraphics" command.  Do
+%     not specify any graphic file extensions in your .tex file. This
+%     will allow us to create a PDF version of the ThornGuide
+%     via pdflatex.
+%   - References should be included with the latex "\bibitem" command.
+%   - Use \begin{abstract}...\end{abstract} instead of \abstract{...}
+%   - Do not use \appendix, instead include any appendices you need as
+%     standard sections.
+%   - For the benefit of our Perl scripts, and for future extensions,
+%     please use simple latex.
+%
+% *======================================================================*
+%
+% Example of including a graphic image:
+%    \begin{figure}[ht]
+% 	\begin{center}
+%    	   \includegraphics[width=6cm]{MyArrangement_MyThorn_MyFigure}
+% 	\end{center}
+% 	\caption{Illustration of this and that}
+% 	\label{MyArrangement_MyThorn_MyLabel}
+%    \end{figure}
+%
+% Example of using a label:
+%   \label{MyArrangement_MyThorn_MyLabel}
+%
+% Example of a citation:
+%    \cite{MyArrangement_MyThorn_Author99}
+%
+% 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/}}
+%
+% *======================================================================*
+
+% If you are using CVS use this line to give version information
+% $Header$
+
 \documentclass{article}
 
 % Use the Cactus ThornGuide style file
-% (Automatically used from Cactus distribution, if you have a 
+% (Automatically used from Cactus distribution, if you have a
 %  thorn without the Cactus Flesh download this from the Cactus
 %  homepage at www.cactuscode.org)
-\usepackage{../../../../doc/ThornGuide/cactus}
+\usepackage{../../../../doc/latex/cactus}
 
 \begin{document}
 
@@ -17,8 +87,12 @@
 % Do not delete next line
 % START CACTUS THORNGUIDE
 
+% Add all definitions used in this documentation here
+%   \def\mydef etc
+\def\del{\nabla}
+
 \begin{abstract}
-Provides macros for other ADM based thorns to use
+Provides macros for common relativity calculations, using the {\bf ADMBase} variables.
 \end{abstract}
 
 \section{Purpose}
@@ -55,16 +129,7 @@ files.
 
 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. If you are using the
-macros inside a Fortran function then the {\tt i}, {\tt j} and {\tt k}
-indices are used directly. If you are using the macros inside a C
-function then you should 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. Typically this would mean that {\tt dk = 1},
-{\tt dj = cctk\_lsh[2]} and {\tt di = cctk\_lsh[1]*cctk\_lsh[2]}, where
-C-style numbering is used.
+and $k$ to identify the correct grid point.
 
 Find the name of the macro from the table in
 Section~\ref{admmacros:macros} and put the include files in the
@@ -85,12 +150,29 @@ themselves macros and are case sensitive. {\bf 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.}
 
-\section{Example}
+\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
+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.
+
+\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. 
 
-{\tt
 \begin{verbatim}
 c     Declarations for macros.
 #include "CactusEinstein/ADMMacros/src/macro/TRK_declare.h"
@@ -109,8 +191,91 @@ c     Add the shift term: N = B^i D_i(trK).
          end do
 #include "CactusEinstein/ADMMacros/src/macro/TRK_undefine.h"
 \end{verbatim}
-}
 
+\subsection{C}
+
+This program 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.
+
+\newpage
+\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
+ * $$
+ * 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;
+
+/* magic variables for ADMMacros (see the ADMMacros thorn guide for details) */
+const int di = 1;
+const int dj = cctk_lsh[0];
+const int dk = cctk_lsh[0]*cctk_lsh[1];
+
+/* declare the ADMMacros variables for $g^{ij}$ and $\Gamma^k_{ij}$ */
+#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];
+  }
+  }
+  }
+
+#include "CactusEinstein/ADMMacros/src/macro/UPPERMET_undefine.h"
+#include "CactusEinstein/ADMMacros/src/macro/CHR2_undefine.h"
+}
+\end{verbatim}
+\endgroup
 
 \section{Macros}
 \label{admmacros:macros}