update description of defaults for

   boundary_off_centering_tolerance
   boundary_extrapolation_tolerance
to describe the actual present code; move my plans for the future
into [brackets].


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

1 files changed, 58 insertions, 35 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 6845291..1873478 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -210,7 +210,10 @@ guarantees a smooth ($C^1$) interpolant and (for smooth input data)
 interpolation error.  Unfortunately, this comes at the cost of a
 larger molecule size than the same-order Lagrange interplator, and
 a much larger interpolation error if the interpolation molecules are
-off-centered.
+off-centered.  (By default, the Hermite interpolator doesn't allow
+off-centered molecules, though this can be changed via the
+\verb|boundary_off_centering_tolerance[]| and
+\verb|excision_off_centering_tolerance[]| parameter-table entries.)
 
 For most purposes Lagrange polynomial interpolation is better;
 only use Hermite polynomial interpolation if you need a smooth
@@ -734,8 +737,7 @@ its molecules (if and) only if the interpolation point is both
 where we use ``\verb|*|'' to denote \verb|boundary| or \verb|excision|
 as appropriate.
 
-In practice the default-centering region is always a (normally proper)
-subset of the valid-data region, so there are three cases of interest:
+There are four cases for these parameters:
 \begin{description}
 \item[\mathversion{bold}
       $\text{\tt *\!\_off\_centering\_tolerance[ibdnry]} = 0.0$ and
@@ -755,37 +757,55 @@ subset of the valid-data region, so there are three cases of interest:
 	direction, then the interpolator reports an error.
 \item[\mathversion{bold}
       $\text{\tt *\!\_off\_centering\_tolerance[ibdnry]} = \infty$%%%
-\footnotemark%%%
-\addtocounter{footnote}{-1}%%%
+\footnotemark{}%%%
 {}    and
       $\text{\tt *\!\_extrapolation\_tolerance[ibndry]} > 0.0$:]\mbox{}\\
+\footnotetext{%%%
+	     In practice $999.0$ is a conventional value here.
+	     The actual value doesn't matter so long as it's
+	     larger than any possible molecule radius.
+	     }%%%
 	The interpolator allows interpolation points to be up to ($\leq$)
 	\verb|*_extrapolation_tolerance[ibndry]| grid spacings outside
 	the valid-data region in this direction.
 	If an interpolation point is beyond this limit in any
 	direction, then the interpolator reports an error.
+\item[\mathversion{bold}
+      $\text{\tt *\!\_off\_centering\_tolerance[ibdnry]} = 0.0$ and
+      $\text{\tt *\!\_extrapolation\_tolerance[ibndry]} > 0.0$:]\mbox{}\\
+	In practice the default-centering region is always a
+	(normally proper) subset of the valid-data region, so this
+	case is nonsensical: the positive value for
+	\verb|*_extrapolation_tolerance[ibndry]| has no effect
+	because of the $\verb|*_off_centering_tolerance[ibndry]| = 0.0$
+	setting.  The interpolator gives a warning for this case.
 \end{description}
 
-(Note that setting $\verb|*_off_centering_tolerance[ibndry]| = 0.0$ and\\
-$\verb|*_extrapolation_tolerance[ibndry]| > 0.0$ is almost always a
-mistake: the positive value for\\
-\verb|*_extrapolation_tolerance[ibndry]| has no effect because of the
-$\verb|*_off_centering_tolerance[ibndry]| = 0.0$
-setting.  The interpolator gives a warning if you make such a setting.)
-
 If any of these table entries aren't specified, the defaults are
-$\verb|*_off_centering_tolerance[ibndry]| = +\infty$%%%
-\footnotemark%%%
-\footnotetext{%%%
-	     In practice any positive value larger than the molecule
-	     radius is fine; $999.0$ is a conventional value here.%%%
-	     }%%%
-{} and $\verb|*_extrapolation_tolerance[ibndry]| = 10^{-10}$ for all
-\verb|ibndry|, \ie{} interpolation points may be anywhere within
-the valid-data region or up to $10^{-10}$ of a grid spacing outside it.
-(The latter criterion avoids error returns if floating-point roundoff
-moves an interpolation point which was supposed to be just on the
-boundary of the valid-data region, slightly outside it.)
+\begin{verbatim}
+boundary_off_centering_tolerance[ibndry] = 999.0   # effectively infinity
+boundary_extrapolation_tolerance[ibndry] = 1.0e-10
+\end{verbatim}
+In other words, the interpolation points may be anywhere within the
+valid-data region or up to $10^{-10}$ grid spacing outside it.  (The
+$10^{-10}$ ``fudge factor'' helps to avoid spurious errors in case
+floating-point roundoff moves an interpolation point which was supposed
+to be just on the boundary of the valid-data region, slightly outside it.)
+
+[In the near future these defaults may be changed:  For Lagrange
+polynomial interpolation the new defaults would be
+\begin{verbatim}
+boundary_off_centering_tolerance[ibndry] = 999.0   # effectively infinity
+boundary_extrapolation_tolerance[ibndry] = 1.0e-10
+\end{verbatim}
+while for Hermite polynomial interpolation they would be
+\begin{verbatim}
+boundary_off_centering_tolerance[ibndry] = 1.0e-10
+boundary_extrapolation_tolerance[ibndry] = 0.0
+\end{verbatim}
+This would leave Lagrange interpolation unchanged, while for Hermite
+interpolation the defaults would forbid any significant off-centering
+of the interpolation molecules.]
 
 %%%%%%%%%%%%%%%%%%%%
 
@@ -1140,15 +1160,15 @@ CCTK_INT const molecule_min_m[N_dims];
 CCTK_INT const molecule_max_m[N_dims];
 \end{verbatim}
 The semantics of these are that if both of these keys are present
-(the values don't matter), then the interpolator will (re)set the
-values to give the (inclusive) minimum and maximum \verb|m|~molecule
-coordinates.  (Note that either both of these keys should be present,
-or neither should be present.  This simplifies the logic in the
-interpolator slightly.)
+(the values and datatypes don't matter), then the interpolator will
+(re)set the values to give the (inclusive) minimum and maximum
+\verb|m|~molecule coordinates.  (Note that either both of these
+keys should be present, or neither should be present.  This
+simplifies the logic in the interpolator slightly.)
 
 The following parameter may be used to query the molecule positions:
 \begin{verbatim}
-CCTK_INT *const molecule_positions[N_dims];
+CCTK_INT* const molecule_positions[N_dims];
 \end{verbatim}
 The semantics of this is that the caller should set
 \verb|molecule_positions[]| to an array of \verb|N_dims| pointers to
@@ -1160,15 +1180,17 @@ The following parameters may be used to query the
 Jacobian~$(\ref{localinterp/eqn-Jacobian})$ itself:
 \begin{verbatim}
 CCTK_REAL* const Jacobian_pointer[N_output_arrays];
-const CCTK_INT   Jacobian_offset [N_output_arrays]; /* optional */
+const CCTK_INT   Jacobian_offset [N_output_arrays];   # optional, default=all 0
 
 /* the next 3 table entries are shared by all Jacobians */
 const CCTK_INT Jacobian_interp_point_stride;
 const CCTK_INT Jacobian_m_strides[N_dims];
-const CCTK_INT Jacobian_part_stride;                /* optional */
+const CCTK_INT Jacobian_part_stride;                  # optional, default=1
 \end{verbatim}
-All the optional entries default to 0 if omitted.
-Then for each \verb|out| where \verb|Jacobian_pointer[out] != NULL|,%%%
+If \verb|Jacobian_pointer| is present in the table, then
+\verb|Jacobian_interp_point_stride| and \verb|Jacobian_m_strides|
+must also be present.  For each \verb|out| where
+\verb|Jacobian_pointer[out] != NULL|,%%%
 \footnote{%%%
 	 That is, setting {\tt Jacobian\_pointer[out] = NULL}
 	 supresses the Jacobian query.  If (as is often the
@@ -1177,7 +1199,8 @@ Then for each \verb|out| where \verb|Jacobian_pointer[out] != NULL|,%%%
 	 supressing the queries in this manner for any remaining
 	 output arrays.
 	 }%%%
-{} the interpolator would store the Jacobian~$(\ref{localinterp/eqn-Jacobian})$ in
+{} the interpolator would then store the
+Jacobian~$(\ref{localinterp/eqn-Jacobian})$ in
 \begin{verbatim}
 Jacobian_pointer[out][offset
                       + pt*Jacobian_interp_point_stride