Some more tweaks to the documentation of CCTK_InterpGridArrays() return codes.

git-svn-id: http://svn.cactuscode.org/arrangements/CactusPUGH/PUGHInterp/trunk@67 1c20744c-e24a-42ec-9533-f5004cb800e5

1 files changed, 34 insertions, 30 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 84d25c6..8d682fe 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -197,41 +197,45 @@ about per-point status codes between the global and the local interpolator
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\section{\InterpGridArrays\ Return Codes}
+\subsection{\InterpGridArrays\ Return Codes}
 \label{PUGHInterp_return_codes}
 
-In the single-processor case the return code of \InterpGridArrays will be set
-to the return code of \verb|CCTK_InterpLocalUniform()|.
-
-In the multi-processor case, an error condition occuring only locally on a
-processor ({\tt CCTK\_\-ERROR\_\-INTERP\_\-POINT\_OUTSIDE} for points which
-could not be mapped onto any processor, {\tt CCTK\_\-ERROR\_\-INTERP\_\-%
-GHOST\_SIZE\_\-TOO\_SMALL} if
-the size of the ghostzones is too small for the given local local interpolator,
-or any error codes returned by \verb|CCTK_InterpLocalUniform()| for the query
-call) will cause all processors to return immediately from the collective call
-to {\tt CCTK\_InterpGridArrays()} with that error code.
-If a local error occured on more than one processor, the actual global error
-code returned by all processors is implementation-dependent: for
-{\tt PUGHInterp} it will be the error code from the processor with the lowest
-processor ID.
-
-In addition to this global interpolation status (coded in the return value
-of {\tt CCTK\_InterpGridArrays()}), a local interpolation status code will be
-stored in the user-supplied parameter table (if given) as
+The return code from \InterpGridArrays%%%
+\footnote{%%%
+	 In C the return code is the \InterpGridArrays\
+	 function result; in Fortran it's returned through
+	 the first ({\tt status}) argument.%%%
+	 }%%%
+is determined as follows:
+\begin{itemize}
+\item	If any of the arguments are invalid (e.g. $\verb|N_dims| < 0$),
+	the return code is \verb|UTIL_ERROR_BAD_INPUT|.
+\item	If any errors are encountered when processing the
+	parameter table, the return code is the
+	appropriate \verb|UTIL_ERROR_TABLE_*| error code.
+\item	If the query call determines that
+	the number of ghost zones in the grid is too small
+	for the local interpolator, the return code is
+	\verb|CCTK_ERROR_INTERP_POINT_OUTSIDE|.
+\item	Otherwise, the return code from \InterpGridArrays\ is
+	the minimum over all processors of the return code
+	from the local interpolation on that processor.
+\end{itemize}
+
+If the local interpolator supports per-point status returns
+and the user supplies an interpolator parameter table,
+then in addition to this global interpolation return code,
+\InterpGridArrays\ also returns a ``local'' status code which
+describes the outcome of the local interpolation for all the
+interpolation points which originated on {\em this\/} processor:
 \begin{verbatim}
   CCTK_INT local_interpolator_status;
 \end{verbatim}
-Depending on whether the local interpolator does provide such status information
-about the interpolation result at individual points, this local interpolation
-status code will be determined as the overall minimum of the status
-values for all the points a processor had requested for the interpolation
-(for this purpose, the table options \verb|per_point_status| and \verb|error_point_status| are used to pass per-point status values between the local and the
-global interpolator).
-
-If the local interpolator does not support the feature of providing
-per-point status information, the local interpolation status code will be set
-to the return code of \verb|CCTK_InterpLocalUniform()| on that processor.
+This gives the minimum over all the interpolation points originating
+on {\em this\/} processor, of the \verb|CCTK_InterpLocalUniform()|
+return codes for those points.  (It doesn't matter on which processor(s)
+the points were actually interpolated -- \InterpGridArrays\ takes care
+of gathering all the status information back to the originating processors.)
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%