describe some of the C++ classes

git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinAnalysis/AHFinderDirect/trunk@39 f88db872-0e4f-0410-b76b-b9085cfa78c5

1 files changed, 114 insertions, 3 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index e60d593..6afae74 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -7,13 +7,16 @@
 %
 \bibliographystyle{alpha}
 
-% our own name
-\def\ahf{{\tt AHFinderDirect}}
+% misc text stuff
+\def\code#1{{\tt #1}}			% for formatting code
+\def\ie{\hbox{i.e.}}
+\def\ahf{\code{AHFinderDirect}}		% our own name
 
 % get size/spacing of "++" right, cf online C++ FAQ question 35.1
 \def\Cplusplus{\hbox{C\raise.25ex\hbox{\footnotesize ++}}}
 
 % misc math mode stuff
+\def\const{{\rm const}}
 \def\ij{_{ij}}
 \def\upij{^{ij}}
 
@@ -25,7 +28,7 @@
 
 \begin{document}
 \title{The \ahf{} Thorn}
-\author{Jonathan Thornburg\quad{}{\tt <jthorn@aei.mpg.de>}}
+\author{Jonathan Thornburg\quad{}\code{<jthorn@aei.mpg.de>}}
 %
 % We want CVS to expand the Id keyword on the next line, but we don't
 % want TeX to go into math mode to typeset the expansion (because that
@@ -49,6 +52,114 @@ on angular-coordinate space.  This is very fast, but requires a
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
+\section{Implementation Notes}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection{Overview}
+
+The \ahf{} thorn is written primarily in \Cplusplus{}, calling
+C and Fortran~77 numerical libraries.  \Cplusplus{} has proven to be
+a powerful and flexible language for this type of programming, and
+I think this thorn (particularly the interpatch interpolation) would
+have been significantly harder to write in a lower-level language
+like C or Fortran~77.
+
+The implementation is only loosely coupled to Cactus -- in general
+the code uses its own types and classes, which are implemented on
+top of the Cactus ones.  Notably, all floating point arithmetic is
+done using the type \code{fp}, a typedef for \code{CCTK\_REAL}.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection{Portability}
+
+The code should be fairly portable to modern \Cplusplus{} compilers.
+Templates are used, but only template classes templated on floating-point
+or integer types, and these templates are always instantiated explicitly.
+\code{bool}, \code{mutable}, and \code{typename} are used, as are the
+new \code{for}-loop scope rules.  The code has been compiled and run
+successfully using gcc~2.95.2 on x86 GNU/Linux systems and using
+Digital C~V5.6 on Digital Unix~V4.0.  The code won't compile using
+badly broken compilers like the current (mid-2001) version of Microsoft
+Visual \Cplusplus.)
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection{\Cplusplus{} Code}
+
+The main high-level \Cplusplus{} classes in the implementation are
+as follows:
+\begin{description}
+\item[\code{patch\_system}]
+	is the top-level class representing a multipatch system.
+\item[\code{x\_patch}, \code{y\_patch}, \code{z\_patch}]
+	represent individual patches near the $x-$, $y-$, and $z-$axes
+	respectively.
+\item[\code{patch}]
+	is an virtual base class representing a grid patch.
+\item[\code{patch\_edge}]
+	represents the geometry of a single edge of a patch,
+	\ie{} it represents the conversions between (perpendicular,parallel)
+	and (rho,sigma) coordinates.
+\item[\code{ghost\_data}]
+\item[\code{patch\_interp}]
+\item[\code{interpatch\_ghost\_data}]
+\item[\code{symmetry\_ghost\_data}]
+\end{description}
+
+Class \code{patch} is in term implemented using the following
+helper classes:
+\begin{description}
+\item[\code{fd\_grid}]
+\item[\code{grid}]
+\item[\code{grid\_arrays}]
+\end{description}
+
+The implementation also uses the following low-level generic helper
+classes:
+\begin{description}
+\item[\code{array<fp>}]
+	is a template class (templated on the integer or floating-point
+	type of the array elements) providing multidimensional arrays.
+	At present these are stored directly in C++ \code{new[]}-allocated
+	storage, but sometime soon I'll add an option to use Cactus
+	grid functions or local arrays.
+\item[\code{linear\_map<fp>}]
+	is a template class (templated on the floating-point type)
+	representing a linear map between a contiguous interval of
+	integers, and floating-point numbers.
+\item[\code{cpm\_map}]
+	represents a mapping from the integers to the integers,
+	of the form $i \rightarrow \const \pm i$; the name
+	abbreviates ``\underline{c}onstant \underline{p}lus or
+	\underline{m}inus'' map.
+\item[\code{fuzzy<fp>}]
+	is a template class (templated on the floating-point type)
+	providing fuzzy arithmetic, to try to paper over some of the
+	effects of floating-point rounding errors.  For example,
+	one can write
+	\begin{verbatim}
+		for (fp x = 0.0 ; fuzzy<fp>::LE(x,1.0) ; x += 0.1)
+		{
+		// ...
+		}
+	\end{verbatim}
+	and have the loop execute as one would naievly expect,
+	even if rounding errors cause the final value of \code{x}
+	to be 0.9999999999999999 or 1.000000000000001 or suchlike.
+\item[\code{round<fp>}]
+\end{description}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection{Maple Code}
+
+The relativity code is all machine-generated from Maple code, which
+also uses a Maple preprocessor I wrote in Perl.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
 \bibliography{jt}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%