Added documentation on how to use the ADM macros. Started adding a

definition of each macro


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

1 files changed, 121 insertions, 2 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 5bad226..5875987 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -1,4 +1,7 @@
 \documentclass{article}
+
+\usepackage{../../../../doc/UsersGuide/CactusDoc}
+
 \begin{document}
 
 \title{ADMMacros}
@@ -10,8 +13,124 @@
 
 \section{Purpose}
 
-This thorn provides a load of macros to be used by other thorns to do
-various calculations.
+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}.
+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.
+
+\section{Using ADM Macros}
+
+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 
+        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}
+
+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. 
+
+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 file
+are in the directory {\tt CactusEinstein/ADMMacros/src/macros}, so this means adding lines such 
+as
+
+{\tt
+\begin{verbatim}
+#include "CactusEinstein/ADMacros/src/macro/<MACRONAME>_<TYPE>.h"
+\end{verbatim}
+}
+
+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 uses 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}
+
+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"
+
+<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
+#include "CactusEinstein/ADMMacros/src/macro/TRK_guts.h"
+                  K_temp(i,j,k) = TRK_TRK
+                end do
+             end do
+         end do
+#include "CactusEinstein/ADMMacros/src/macro/TRK_undefine.h"
+\end{verbatim}
+}
+
+
+\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} \\
+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 &\\
+All first spatial derivatives of shift, $\beta^{i}_{\;\;j}$: & DB &\\
+All first 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, $g{ij}$:& 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 first 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 &\\
+Christoffel symbols of first kind: $\Gamma_{cab}$ & CHR1&\\
+Christoffel symbols of second kind $\Gamma^{c}_{\;\;ab}$: & CHR2& \\
+Momentum constraints & MOMX, MOMY, MOMZ&\\
+Source term in evolution equation for conformal metric, $\tilde{g}_{ij,t}$: & DCGDT &\\
+
+\end{tabular}
+
+\section{Definitions}
+
+\begin{equation}
+\Gamma_{cab} = \frac{1}{2}\left(g_{ac,b} + g_{bc,a} + g_{ab,c}\right)
+\end{equation}
+
+\begin{equation}
+\Gamma^{c}_{\;\;ab} = g^{cd}\Gamma_{dab} = \frac{1}{2} g^{cd} \left(g_{ac,b} + g_{bc,a} + g_{ab,c}\right)
+\end{equation}
 
 \section{Comments}