various small wording clarifications suggested by Thomas Radke

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

1 files changed, 46 insertions, 26 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index fcf0ebb..a9cba6b 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -27,7 +27,7 @@
 	 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 \verb|CCTK_InterpLocalUniform()| APIs.
+	 newer and more generic \verb|CCTK_InterpLocalUniform()| APIs.
 	 }  
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -38,7 +38,7 @@
 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 \verb|CCTK_InterpLocalUniform()| APIs.
+newer and more generic \verb|CCTK_InterpLocalUniform()| APIs.
 
 At present there are 2~interpolators provided (we hope to add other
 interpolators in the future):
@@ -114,7 +114,7 @@ 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,
-\ie{} its The 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
@@ -123,7 +123,7 @@ algorithms (\eg{} Hermite polynomial and spline interpolation) which
 give better smoothness, but none of the present interpolators implement
 them. :(
 
-As given in the function reference section of the Cactus User's Guide,
+As given in the Function Reference section of the Cactus User's Guide,
 \verb|interp_coords|, \verb|input_arrays|, and \verb|output_arrays| are
 actually all pointers to arrays of \verb|void *| pointers, since we
 support a number of different Cactus data types.  Internally, the
@@ -177,6 +177,14 @@ located at the position \verb|posn|!  (This may become clearer once
 you look at the example in
 section~\ref{sect-generic-options/Jacobian/fixed-sized-hypercube}.)
 
+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, \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.
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Generic Interpolator Options}
@@ -185,10 +193,10 @@ section~\ref{sect-generic-options/Jacobian/fixed-sized-hypercube}.)
 The newer \verb|CCTK_InterpLocalUniform()| and
 \verb|CCTK_InterpLocalNonUniform()| APIs specify a \defn{parameter table}
 (a Cactus key-value table, manipulated by the \verb|Util_Table*()| APIs)
-as a generic mechanism for passing optional input to, and/or returning
-optional results from, the interpolator.  Different interpolators support
-different options; in this section we describe some options which are,
-or will plausibly, be common to multiple interpolators.
+as a generic mechanism for passing optional or mandatory input/output
+to/from the interpolator.  Different interpolators support different
+options; in this section we describe some options which are, or will
+plausibly, be common to multiple interpolators.
 
 Note that except as described in section~\ref{sect-generic-options/caching}
 (``Caching''), all interpolator arguments and parameters apply only to
@@ -227,9 +235,15 @@ The semantics of this are as follows:  For each \verb|axis|,
 	if and only if the interpolation point is
 	$> \verb|out_of_range_tolerance[axis]|
 	   \times \verb|coord_delta[axis]|$
-	outside the grid in any coordinate.
-\item[\rm If $\hbox{\tt out\_of\_range\_tolerance[axis]} = -1.0$,]
-	then an interpolation point is considered to be ``out of range''
+	outside the grid in this coordinate direction.
+\item[\rm If $\hbox{\tt out\_of\_range\_tolerance[axis]} = -1.0$,]%%%
+\footnote{%%%
+	 Note that this is an exact floating-point equality test!
+	 Although such tests are normally very dangerous, this
+	 one is ok, because -1.0 can be exactly represented in
+	 any reasonable floating-point format.
+	 }%%%
+{}	then an interpolation point is considered to be ``out of range''
 	if and only if a centered molecule (or more generally,
 	a molecule whose centering is chosen pretending that
 	the grid is of infinite extent), would require data
@@ -256,10 +270,11 @@ floating-point precision used,%%%
 	 }%%%
 {} but none of the interpolators do this at present.)
 
-If any interpolation points are out of range, interpolators should
-return the error code \verb|CCTK_ERROR_INTERP_POINT_X_RANGE|, and
-report further details about the error by setting the following
-parameter-table entries:
+If any interpolation points are out of range (as determined by the
+\verb|out_of_range_tolerance[]| critera described above), the
+interpolator should return the error code
+\verb|CCTK_ERROR_INTERP_POINT_X_RANGE|, and report further details
+about the error by setting the following parameter-table entries:
 \begin{verbatim}
 /* which interpolation point is out of range? */
 /* (value is  pt  for out-of-range point) */
@@ -318,11 +333,11 @@ sets the molecule family/shape based on that string.
 \subsection{Non-Contiguous Input Arrays}
 \label{sect-generic-options/non-contiguous-inputs}
 
-Sometimes one of the input ``arrays'' used by the interpolator might not
+Sometimes the input ``arrays'' used by the interpolator might not
 be contiguous in memory.  For example, we might want to do 2-D interpolation
-within a plane of a 3-D grid array, but the plane might or might not be
-contiguous in memory.  (Another example would be that the input array
-might be a member of a compact group.)
+within a plane of a 3-D grid array, but the plane might or might not
+be contiguous in memory.  (Another example would be that the input
+arrays might be members of a compact group.)
 
 One way to do this would be to use the hyperslab API to explicitly compute
 the input data on an appropriate hyperslab, then interpolate within that.
@@ -722,7 +737,7 @@ be easy to add additional orders and/or dimensions if desired.)
 The code allows arbitrarily-shaped interpolation molecules, but at
 the moment only hypercube-shaped molecules are implemented.
 
-This interpolator supports a number of the options described in
+This interpolator supports a number of the features described in
 section~\ref{sect-generic-options}:
 \begin{itemize}
 \item	interpolation order
@@ -731,7 +746,6 @@ section~\ref{sect-generic-options}:
 	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
 \item	derivatives
 	(when taking derivatives with this interpolator,
@@ -740,6 +754,12 @@ section~\ref{sect-generic-options}:
 	and \verb|operation_codes| arrays, as in the example in
 	section~\ref{sect-example-derivatives})
 \end{itemize}
+This interpolator also supports other features,,, described below.
+
+The interpolation order is a mandatory parameter which must be
+present in the parameter table when the interpolator is called;
+all the other parameter-table oparameters are optional.
+
 At present this interpolator does not support computing the Jacobian,
 but we hope to add this in the near future.  This interpolator also
 does not support any caching features; at present (Feb 2002) we have
@@ -846,11 +866,11 @@ const void *const interp_coords[N_DIMS]
 
 /* input arrays */
 /* ... note Cactus uses Fortran storage ordering, i.e. X is contiguous */
-#define N_X   10
-#define N_Y   20
-const CCTK_REAL    input_real   [N_Y][N_X];
-const CCTK_COMPLEX input_complex[N_Y][N_X];
-const CCTK_INT input_array_dims[N_DIMS] = { N_X, N_Y };
+#define NX   10
+#define NY   20
+const CCTK_REAL    input_real   [NY][NX];
+const CCTK_COMPLEX input_complex[NY][NX];
+const CCTK_INT input_array_dims[N_DIMS] = { NX, NY };
 const CCTK_INT input_array_type_codes[N_INPUT_ARRAYS]
         = { CCTK_VARIABLE_REAL, CCTK_VARIABLE_COMPLEX };
 const void *const input_arrays[N_INPUT_ARRAYS]