From 46b6ad1631071a135784d73b90f9862183ba33b2 Mon Sep 17 00:00:00 2001 From: jthorn Date: Fri, 19 Nov 2004 12:13:37 +0000 Subject: * 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 --- doc/documentation.tex | 197 ++++++++++++++++++++++++++++++++++++++++++++++---- 1 file 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} -- cgit v1.2.3