From 2e052e76dd54bff35cb0d6853689d0153337c5b6 Mon Sep 17 00:00:00 2001 From: allen Date: Wed, 1 May 2002 17:54:45 +0000 Subject: 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 --- doc/documentation.tex | 123 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 121 insertions(+), 2 deletions(-) (limited to 'doc') 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 \_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 \_guts.h} is the actual included source code which will calculate + the quantities. + +\item {\tt \_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/_.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" + + + +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} -- cgit v1.2.3