From f91c30b3a7c3c01a8cc0da228ba7fbf25650e196 Mon Sep 17 00:00:00 2001 From: jthorn Date: Sat, 20 Nov 2004 20:24:07 +0000 Subject: * 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 --- doc/documentation.tex | 172 +++++++++++++++++++++++++++++++------------------- 1 file 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 \_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} +\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{\_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{\_guts.h}] + is the actual included source code which will calculate the quantities. + +\item[\texttt{\_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/_.h" +#include "CactusEinstein/ADMMacros/src/macro/_.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{\_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} -- cgit v1.2.3