From f706f7b7d180d5f20e4220932dfd83c102738e2b Mon Sep 17 00:00:00 2001 From: jthorn Date: Sat, 16 Jun 2001 14:28:02 +0000 Subject: describe some of the C++ classes git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinAnalysis/AHFinderDirect/trunk@39 f88db872-0e4f-0410-b76b-b9085cfa78c5 --- doc/documentation.tex | 117 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file 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 }} +\author{Jonathan Thornburg\quad{}\code{}} % % 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}] + 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}] + 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}] + 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::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}] +\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} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -- cgit v1.2.3