convert to use the new thornguide template (looks great!)

git-svn-id: http://svn.cactuscode.org/arrangements/CactusBase/LocalInterp/trunk@65 df1f8a13-aa1d-4dd4-9681-27ded5b42416

1 files changed, 153 insertions, 78 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index f0fd626..d915427 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -1,43 +1,123 @@
-%version   $Header$
+% *======================================================================*
+%  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 
+%  relevent 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
+%       % BEGIN CACTUS THORNGUIDE",
+%     except for filling in the title, author, date etc. fields.
+%   - You can define your own macros are OK, but they must appear after
+%     the BEGIN CACTUS THORNGUIDE line, and do 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 graphix package. 
+%     More specifically, with the "includegraphics" command. Do
+%     not specify any graphic file extensions in your .tex file. This 
+%     will allow us (later) to create a PDF version of the ThornGuide
+%     via pdflatex. |
+%   - References should be included with the latex "bibitem" command.  
+%   - 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 
+%  thorn without the Cactus Flesh download this from the Cactus
+%  homepage at www.cactuscode.org)
+\usepackage{../../../../doc/ThornGuide/cactus}
 
 \begin{document}
-\title{LocalInterp}
-\author{Jonathan Thornburg, incorporating code from Thomas Radke}
-%
-% 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
-% wouldn't look as nice in the output), so we use the "$ $" construct
-% to get TeX out of math mode again when typesetting the expansion.
-%
-\date{$ $Id$ $}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% The author of the documentation
+\author{Jonathan Thornburg, incorporating code from Thomas Radke} 
+
+% The title of the document (not necessarily the name of the Thorn)
+\title{Thorn Guide for the {\bf LocalInterp} Thorn}
+
+% the date your document was last changed, if your document is in CVS, 
+% please us:
+%    \date{$ $Date$ $}
+\date{$ $Date$ $}
+
 \maketitle
 
-\abstract{
-	 This thorn provides processor-local interpolation of
-	 1-D, 2-D, and 3-D data arrays.  It provides interpolators
-	 for both the older \verb|CCTK_InterpLocal()| API, and the
-	 newer and more generic \verb|CCTK_InterpLocalUniform()| APIs.
-	 }  
+% Do not delete next line
+% START CACTUS THORNGUIDE
+
+% Add all definitions used in this documentation here 
+%   \def\mydef etc
+\def\Cplusplus{\hbox{C\hspace{-.05em}\raisebox{.4ex}{\tiny\bf ++}}}
+\def\ie{i.e.\ }
+\def\eg{e.g.\ }
+
+% Add an abstract for this thorn's documentation
+\begin{abstract}
+This thorn provides processor-local interpolation of 1-D, 2-D, and 3-D
+data arrays.  It provides interpolators for both the older
+\verb|CCTK_InterpLocal()| API, and the newer and more generic
+\verb|CCTK_InterpLocalUniform()| APIs.
+\end{abstract}
+
+% The following sections are suggestive only.
+% Remove them or add your own.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Introduction}
 
-% replicate abstract since it disappears from Thorn Guide
-This thorn provides processor-local interpolation of
-1-D, 2-D, and 3-D data arrays.  It provides interpolators
-for both the older \verb|CCTK_InterpLocal()| API, and the
-newer and more generic \verb|CCTK_InterpLocalUniform()| APIs.
-
-At present there are 2~interpolators provided (we hope to add other
+At present this thorn provides 2~interpolators (we hope to add other
 interpolators in the future):
 \begin{description}
 \item[Uniform Cartesian]
 	This is the local interpolator which used to live
-	in the PUGHInterp thorn.  It was written in C by
+	in the {\bf PUGHInterp} thorn.  It was written in C by
 	Thomas Radke in early 2001, drawing on earlier Fortran code
 	by Paul Walker.  It supports the \verb|CCTK_InterpLocal()| API.
 	It provides Lagrange polynomial interpolation for all
@@ -64,7 +144,7 @@ this is mapped to a Cactus {\bf interpolator handle} by
 there may be a separate interpolator defined for each of the
 interpolation APIs (both the processor-local ones provided by this
 thorn, and the global ones provided by driver-specific interpolator
-thorns such as PUGHInterp).
+thorns such as {\bf PUGHInterp}).
 
 Terminology for interpolation seems to differ a bit from one author
 to another.  Here we refer to the {\bf point-centered} interpolation
@@ -106,12 +186,12 @@ interpolator thus has $O(\Delta x^{n+1})$ errors for smooth input data.
 However, because the interpolating polynomial generally changes if
 the interpolation point moves from one grid cell to another, unless
 something special is done the interpolating function isn't smooth,
-i.e.\ its 1st~derivative is generically {\em discontinuous\/},
+\ie{} its 1st~derivative is generically {\em discontinuous\/},
 with $O(\Delta x^n)$ jump discontinuities each time the interpolating
 polynomial changes.  Correspondingly, the interpolation error is
 generically a ``bump function'' which is zero at each grid point
 and rises to a local maximum in each grid cell.  There are interpolation
-algorithms (e.g.\ Hermite polynomial and spline interpolation) which
+algorithms (\eg{} Hermite polynomial and spline interpolation) which
 give better smoothness, but none of the present interpolators implement
 them. :(
 
@@ -122,7 +202,7 @@ support a number of different Cactus data types.  Internally, the
 interpolator casts these \verb|void *| pointers to \verb|CCTK_REAL *|
 or whatever the correct Cactus data types are.  But when describing
 how the interpolator accesses the various arrays, for simplicity we
-usually gloss over this casting, i.e.\ we pretend that \verb|interp_coords|,
+usually gloss over this casting, \ie{} we pretend that \verb|interp_coords|,
 \verb|input_arrays|, and \verb|output_arrays| are pointers to arrays
 of \verb|CCTK_REAL *| pointers.  (This may become clearer once you
 read the next example.)
@@ -149,7 +229,7 @@ z = interp_coords[2][pt]
 from its actual C~type of \verb|const void* interp_coords[]|.)
 
 We take \verb|axis| to be an integer specifying a dimension,
-i.e.\ 0~for~$x$, 1~for~$y$, 2~for~$z$, \dots.
+\ie{} 0~for~$x$, 1~for~$y$, 2~for~$z$, \dots.
 
 When describing Jacobians and domains of dependence, it's useful to
 introduce the notion of {\bf molecule position}, a nominal reference
@@ -174,7 +254,7 @@ However, by convention we do assume that $\verb|m|=0$ is always a valid
 When describing various entries in the parameter table in
 section~\ref{sect-generic-options}, we use \verb|const| qualifiers
 on table entries to indicate that the interpolator treats them as
-\verb|const| variables/arrays, i.e.\ it promises not to change them.
+\verb|const| variables/arrays, \ie{} it promises not to change them.
 In contrast, table entries which are not shown as \verb|const| are
 considered read-write by the interpolator; it typically uses them
 to return outputs back to the caller.
@@ -213,7 +293,7 @@ const CCTK_INT order;
 \subsection{Handling of Out-of-Range Interpolation Points}
 
 By default, interpolators should consider it an error if any interpolation
-point lies outside the grid, i.e.\ if the ``interpolation'' is actually
+point lies outside the grid, \ie{} if the ``interpolation'' is actually
 an extrapolation.  (Some interpolators may apply a small ``fuzz'' to
 this test to help avoid floating-point rounding problems.)
 
@@ -365,11 +445,11 @@ offset = input_array_offsets[in]
 \end{verbatim}
 and where \verb|(i,j,k)| run from \verb|input_array_min_subscripts[]|
 to \verb|input_array_max_subscripts[]| inclusive
-(n.b.~this is an {\em inclusive\/} range, i.e.\ 
+(n.b.~this is an {\em inclusive\/} range, \ie{} 
 $\verb|min| \le \verb|(i,j,k)| \le \verb|max|$).
 
 The defaults are that each input array is contiguous in memory,
-i.e.\ \verb|input_array_offsets[]| = 0,
+\ie{} \verb|input_array_offsets[]| = 0,
 \verb|stride| determined from \verb|input_array_dims[]|
               in the usual Fortran manner,
 \verb|input_array_min_subscripts[]| = all 0s, and
@@ -387,7 +467,7 @@ contiguous 1-D arrays.
 \label{sect-generic-options/derivatives}
 
 Some interpolators can optionally take derivatives as part of the
-interpolation, i.e.\ if we view the input data as being samples of
+interpolation, \ie{} if we view the input data as being samples of
 a smooth function, then instead of estimating values of that function
 at the interpolation points, the interpolator can instead or additionally
 estimate values of various derivatives of that function at the
@@ -457,7 +537,7 @@ Sometimes we want to know the Jacobian of the interpolator,
 							\label{eqn-Jacobian}
 \end{equation}
 and/or ``just'' the set of \verb|(i,j,k)| for which this is nonzero
-(i.e.\ the sparsity structure of the Jacobian, equivalently the domain
+(\ie{} the sparsity structure of the Jacobian, equivalently the domain
 of dependence of the output result, or equivalently the interpolation
 molecule size and shape) for a given \verb|out|, \verb|in|, and \verb|pt|.%%%
 \footnote{%%%
@@ -519,7 +599,7 @@ interpolation coordinates, the interpolator should set the parameter
 \begin{verbatim}
 CCTK_INT MSS_is_fn_of_interp_coords;
 \end{verbatim}
-to 1.  Otherwise (i.e.\ if the interpolation molecule size and shape
+to 1.  Otherwise (\ie{} if the interpolation molecule size and shape
 are independent of the interpolation coordinates) it should set this
 parameter to 0.
 
@@ -531,7 +611,7 @@ parameter
 \begin{verbatim}
 CCTK_INT MSS_is_fn_of_which_operation;
 \end{verbatim}
-to 1.  Otherwise (i.e.\ if the interpolator doesn't support computing
+to 1.  Otherwise (\ie{} if the interpolator doesn't support computing
 derivatives, or if the interpolator does support computing derivatives
 but the interpolation molecule size and shape are independent of the
 \verb|operation_code[]| values), it should set this parameter to 0.
@@ -548,19 +628,19 @@ should set the parameter
 \begin{verbatim}
 CCTK_INT MSS_is_fn_of_input_array_values;
 \end{verbatim}
-to 1.  Otherwise (i.e.\ if the interpolation molecule size and shape
+to 1.  Otherwise (\ie{} if the interpolation molecule size and shape
 are independent of the input array values; this is a necessary, but not
 sufficient, condition for the interpolation to be linear), it should
 set this parameter to 0.
 
 If the actual floating-point values of the Jacobian~$(\ref{eqn-Jacobian})$
 (for a given \verb|out|, \verb|in|, and \verb|pt|) depend on the actual
-floating-point values of the input arrays (i.e.\ if the interpolation
+floating-point values of the input arrays (\ie{} if the interpolation
 is nonlinear), the interpolator should set the parameter
 \begin{verbatim}
 CCTK_INT Jacobian_is_fn_of_input_array_values;
 \end{verbatim}
-to 1.  Otherwise (i.e.\ if the interpolation is linear) it should set
+to 1.  Otherwise (\ie{} if the interpolation is linear) it should set
 this parameter to 0.
 
 %%%%%%%%%%%%%%%%%%%%
@@ -714,7 +794,7 @@ There are three basic operations supported:
 	information in \verb|cache_handle|; this allows multiple caches
 	to be active concurrently.
 \item[Use a Cache]
-	To use a cache (i.e.\ to make an interpolation with the
+	To use a cache (\ie{} to make an interpolation with the
 	hoped-for speedup), just call the interpolator with
 	\verb|cache_handle| set to the value returned when the cache
 	was created.  Note that you still have to provide all the
@@ -725,7 +805,7 @@ There are three basic operations supported:
 	the ``will be the same'' arguments are still used, are up to
 	the interpolator.
 \item[Destroy a Cache]
-	To destroy a cache (i.e.\ free any memory allocated when
+	To destroy a cache (\ie{} free any memory allocated when
 	the cache was created), call the interpolator with
 	\verb|cache_handle| set to the value returned when the cache
 	was created, and  \verb|cache_control| set to the string
@@ -739,7 +819,7 @@ There are three basic operations supported:
 \section{The Uniform Cartesian Interpolator}
 
 The uniform Cartesian interpolator is the one which used to live
-in the PUGHInterp thorn.  It was written in C by Thomas Radke in
+in the {\bf PUGHInterp} thorn.  It was written in C by Thomas Radke in
 early 2001, drawing on earlier Fortran code by Paul Walker.  It
 supports the \verb|CCTK_InterpLocal()| API, and thus doesn't use
 any parameter table at all.  It provides Lagrange polynomial
@@ -791,7 +871,7 @@ section~\ref{sect-generic-options}:
 \item	interpolation order (this is a mandatory parameter)
 \item	handling of out-of-range interpolation points
 	(if there are multiple out-of-range points/axes, the
-	one reported will be the first, i.e.\ the out-of-range
+	one reported will be the first, \ie{} the out-of-range
 	point with the smallest \verb|pt|, and of that points
 	out-of-range axes, the one with the smallest \verb|axis|)
 \item	non-contiguous input arrays
@@ -831,7 +911,7 @@ easy to also do Savitzky-Golay smoothing.%%%
 	 Savitzky-Golay smoothing.
 	 }%%%
 {}  This is best described by way of an example:  Suppose we're doing
-1-D cubic interpolation, i.e.\ at each interpolation point we're using
+1-D cubic interpolation, \ie{} at each interpolation point we're using
 a cubic polynomial fitted to 4~surrounding data points.  For
 Savitzky-Golay smoothing, we would instead {\em least-squares fit\/}
 a cubic polynomial to some {\em larger\/} number of surrounding data
@@ -844,14 +924,14 @@ const CCTK_INT smoothing;
 \end{verbatim}
 specifies how much (how many points) to enlarge the interpolation
 molecule for this.  The default is 0 (no smoothing).  1 would mean to
-enlarge the molecule by 1 point, e.g.\  to use a 5-point molecule
+enlarge the molecule by 1 point, \eg{}  to use a 5-point molecule
 instead of the usual 4-point one for cubic interpolation.  2 would mean
-to enlarge by 2 points, e.g.\  to use a 6-point molecule for cubic
+to enlarge by 2 points, \eg{}  to use a 6-point molecule for cubic
 interpolation.  Etc etc.
 
 Note that in $>1$~dimension, the default hypercube-shaped molecules
 already use more data points than the number of free parameters in
-the interpolating polynomials, i.e.\ they already do some Savitzky-Golay
+the interpolating polynomials, \ie{} they already do some Savitzky-Golay
 smoothing.  For example, in 2-D a generic cubic polynomial
 $f(x,y) = \sum_{i+j \leq 3} c_{ij} x^i y^j$ has 10 free parameters
 $c_{ij}$, which we least-squares fit to the 16 data points in the
@@ -871,19 +951,19 @@ implemented, but the framework is all there for more general cases.
 This interpolator's basic design is to use separate specialized code
 for each combination of
 $(\verb|N_dims|, \verb|molecule_family|, \verb|order|, \verb|smoothing|)$,
-i.e.\ in practice for each distinct choice of interpolation molecule.
+\ie{} in practice for each distinct choice of interpolation molecule.
 Maple is used to generate all the interpolation coefficients.
 The C preprocessor is then used to generate all the specialized code
 from a single master ``template'' file.  The template code uses
 \verb|#ifdef|s to handle lower dimensions with no extra overhead,
-e.g.\ 1-D/2-D interpolation is basically just as efficient as in
+\eg{} 1-D/2-D interpolation is basically just as efficient as in
 a purpose-built 1-D/2-D interpolator, with no extra overhead imposed
 by the interpolator also supporting higher-dimensional interpolation.
 
 The Maple code which generates the interpolation coefficients is quite
 general-purpose, and can handle an arbitrary dimensionality and molecule
 size/shape.  Generating new coefficients can be rather time-consuming,
-though, e.g.\ the current coefficients for 3-D for orders~1-4
+though, \eg{} the current coefficients for 3-D for orders~1-4
 take about 8~cpu minutes to generate using Maple~7 on a 1.7~GHz~P4.
 
 See the \verb|README| file in the source code directory
@@ -896,8 +976,8 @@ pointers in \verb|template.c|.  Don't worry -- the code is actually ok,
 the problem is that C's \verb|const|-qualifier rules are overly strict
 in some cases.  See question 11.10 in the (excellent!) \verb|comp.lang.c|
 FAQ list (\verb|http://www.eskimo.com/~scs/C-faq/top.html|) for details.
-(I think \hbox{C\hspace{-.05em}\raisebox{.4ex}{\tiny\bf ++}} has at
-least partially fixed the \verb|const|-qualifier rules.)
+(I think \Cplusplus{} has at least partially fixed the
+\verb|const|-qualifier rules.)
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -911,9 +991,9 @@ Note that since C allows arrays to be initialized only if the
 initializer values are compile-time constants, we have to declare the
 \verb|interp_coords[]|, \verb|input_arrays[]|, and \verb|output_arrays[]|
 arrays as non-\verb|const|, and set their values with ordinary (run-time)
-assignment statements.  In \hbox{C\hspace{-.05em}\raisebox{.4ex}{\tiny\bf ++}},
-there's no restriction on initializer values, so we could declare the
-arrays \verb|const| and initialize them as part of their declarations.
+assignment statements.  In \Cplusplus, there's no restriction on initializer
+values, so we could declare the arrays \verb|const| and initialize them
+as part of their declarations.
 
 \begin{verbatim}
 #define N_DIMS   2
@@ -994,17 +1074,17 @@ Consider the problem described earlier: the computation of all the
 2nd~derivatives of the 3-metric at a set of interpolation points on
 a 2-sphere.  This example shows how we could do this in C.
 
-[Since we're not using \hbox{C\hspace{-.05em}\raisebox{.4ex}{\tiny\bf ++}},
-we again declare the pointer arrays non-\verb|const|, and ``initialize''
-them with ordinary (run-time) assignment statements.  However, in this
-example, for greater clarity we place these assignment statements right
-after the declarations.  Since C allows declarations only at the start
-of a \verb|{ }| block, not in the middle of a block, we nest the rest
-of the program in extra blocks (with the \verb|{ }| indented 2 spaces
-to distinguish them from ``normal'' \verb|{ }| pairs) to allow for
-further declarations.  The reader will have to decide whether this
-style is more or less ugly than separating the declarations and
-initializations of the pointer arrays.]
+[Since we're not using \Cplusplus, we again declare the pointer arrays
+non-\verb|const|, and ``initialize'' them with ordinary (run-time)
+assignment statements.  However, in this example, for greater clarity
+we place these assignment statements right after the declarations.
+Since C allows declarations only at the start of a \verb|{ }| block,
+not in the middle of a block, we nest the rest of the program in extra
+blocks (with the \verb|{ }| indented 2 spaces to distinguish them from
+``normal'' \verb|{ }| pairs) to allow for further declarations.  The
+reader will have to decide for herself whether this style is more or
+less ugly than separating the declarations and initializations of the
+pointer arrays.]
 \begin{verbatim}
 #define N_DIMS        3
 
@@ -1184,20 +1264,15 @@ if (CCTK_InterpLocalUniform(N_DIMS,
 
 \section{Acknowledgments}
 
-Thanks to Ian Hawke for helpful comments on the documentation,
+Thanks to Thomas Radke for contributing the former {\bf PUGHInterp}
+\verb|CCTK_InterpLocal()| interpolator,
+to Ian Hawke for helpful comments on the documentation,
 to Tom Goodale and Thomas Radke for many useful design discussions,
 and to all the Cactus crew for a great infrastructure!
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-%
-% Automatically created from the ccl files 
-% Do not worry for now.
-%
-\include{interface}
-\include{param}
-\include{schedule}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Do not delete next line
+% END CACTUS THORNGUIDE
 
 \end{document}