document recent changes to code in this thorn:

* add the ability to return per-point error status
* drop support for returning info on which side of the grid an
  "outside the grid" point is outside on (this was tricky to implement
  in combination with the per-point status)


git-svn-id: http://svn.aei.mpg.de/numrel/AEIThorns/AEILocalInterp/trunk@10 0f49ee68-0e4f-0410-9b9c-b2c123ded7ef

1 files changed, 31 insertions, 28 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index b27d206..2883518 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -518,6 +518,7 @@ Interpolation Operator				& Order	& Size
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \subsection{Handling of Grid Boundaries}
+\label{AEIThorns/AEILocalInterp/sect-grid-boundaries}
 
 Near grid boundaries and/or excised points the interpolator can either
 off-center the interpolation molecules, or refuse to interpolate
@@ -813,39 +814,41 @@ This would leave Lagrange interpolation unchanged, while for Hermite
 interpolation the defaults would forbid any significant off-centering
 of the interpolation molecules.]
 
-%%%%%%%%%%%%%%%%%%%%
-
-\subsubsection{Out-of-Range Interpolation Point Error Handling}
-
-If the interpolator finds an interpolation point which is ``out of range''
-as described above, it sets the following parameter-table entries to
-give more information about the out-of-range point:
-\begin{verbatim}
-/* which interpolation point is it? */
-/* (value gives 0-origin  pt  for the offending point) */
-CCTK_INT error_pt;
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-/* in which coordinate axis and direction is the point out of range? */
-/* (value gives 0-origin  ibndry  for the offending point) */
-CCTK_INT error_ibndry;
+\subsection{Per-Point Status Reporting}
 
-/* in which coordinate axis is the point outside the grid or excised? */
-/* (value gives 0-origin  axis  for the offending point) */
-CCTK_INT error_axis;
+By default, an interpolator just returns a single result, either
+0 for success or some (negative) error code.  If there are multiple
+interpolation points causing errors, an interpolator should return
+0 for success, or the error code for the first point in error
+(the one with the smallest \verb|pt|).
 
-/* in which direction is the point out of range? */
-/* (value is -1 for min, +1 for max) */
-CCTK_INT error_direction;
+However, sometimes you would like to know the status of the interpolation
+for {\em each\/} point.  The following (optional) parameter-table entries
+may be used to request this, and to query if the interpolator supports this:
+\begin{verbatim}
+/*
+ * To query whether the interpolator supports per-point status, set this
+ * to a NULL pointer.  To actually request per-point status, set this to
+ * a non-NULL pointer pointing to a buffer of  N_interp_points  CCTK_INTs
+ * into which the interpolator should store the per-point status.  The status
+ * for point  pt  is defined to be the result which CCTK_InterpLocalUnifom()
+ * would return if that were the only point being interpolated.
+ */
+CCTK_POINTER per_point_status;
 \end{verbatim}
 
-The interpolator then returns a \verb|CCTK_ERROR_INTERP_POINT_OUTSIDE|
-error code.
-
-Note that if the point is out of range in multiple axes, it's undefined
-which of them will be reported.  Also, if there are multiple out-of-range
-points, user code shouldn't make any assumptions about which of them
-will be reported -- the only safe assumption is that {\em some\/}
-out-of-range point will be reported.
+If the interpolator supports returning per-point status, and if the key
+\verb|per_point_status| is present in the parameter table, then the
+interpolator will set
+\begin{verbatim}
+CCTK_INT error_point_status;
+\end{verbatim}
+in the parameter table.  If $\verb|per_point_status| = \verb|NULL|$,
+the interpolator will set \verb|error_point_status| to~0.  Otherwise,
+the interpolator will set \verb|error_point_status| to the negative of
+the number of points for which the per-point status is non-zero.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%