Better documentation of CCTK_InterpGridArrays()'s global return codes

and how local interpolation status information is returned.


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

1 files changed, 53 insertions, 14 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index b48f73b..84d25c6 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -109,11 +109,11 @@ The query gets passed the same user-supplied function arguments as for the
 real interpolation call, apart from the interpolation points coordinates (which
 now describe a processor's physical bounding box coordinates) and the output
 array pointers (which are all set to NULL in order to indicate that this is a
-query call only). Any error code returned by the local interpolator for this
-query (eg. {\tt CCTK\_ERROR\_INTERP\_POINT\_OUTSIDE} if the local interpolator
-potentially requires values from grid points which are outside of the available
-processor-local patch of the global grid) cause \InterpGridArrays\ to return
-immediately with that error code.
+query call only). A return code of \verb|CCTK_ERROR_INTERP_POINT_OUTSIDE|
+from \verb|CCTK_InterpLocalUniform()| for this query call (meaning the local interpolator potentially requires values
+from grid points which are outside of the available processor-local patch of
+the global grid) causes \InterpGridArrays\ to return immediately with
+a \verb|CCTK_ERROR_INTERP_GHOST_SIZE_TOO_SMALL| error code on all processors.
 
 Otherwise the \InterpGridArrays\ routine will continue and map the user-supplied
 interpolation points onto the processors which own these points. In a subsequent
@@ -180,20 +180,59 @@ implemented. Instead, if any point cannot be mapped onto a processor
 (i.e.\  the point is outside the global grid), a level-1 warning is printed to
 stdout by default, and the error code \verb|CCTK_ERROR_INTERP_POINT_OUTSIDE| is
 returned. The warning will not be printed if the parameter table contains an
-entry with the key \verb|"suppress_warnings"|.
+entry (of any type) with the key \verb|"suppress_warnings"|.
 
-An error condition occuring only locally on a processor
-(\verb|CCTK_ERROR_INTERP_POINT_OUTSIDE| or error codes returned by
-\verb|CCTK_InterpLocalUniform()|) will cause all processors to return from the
-collective call to {\tt CCTK\_InterpGridArrays()} with an error code.
+The local interpolation status will be stored in the user-supplied parameter
+table (if given) as an integer scalar value with the option key
+\verb|"local_interpolator_status"| (see section \ref{PUGHInterp_return_codes} for details).
+
+The table options
+\begin{verbatim}
+  CCTK_POINTER per_point_status;
+  CCTK_INT     error_point_status;
+\end{verbatim}
+are used internally by \InterpGridArrays\ to pass information
+about per-point status codes between the global and the local interpolator
+(again see section \ref{PUGHInterp_return_codes} for details).
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{\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 error code (coded in the return value
-of {\tt CCTK\_InterpGridArrays()}), the local interpolation status is stored
-in the parameter table (if given) as an integer scalar value with the option
-key \verb|"local_interpolator_status"|.
+
+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
+\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.
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{\PUGHInterp\ and the old Cactus Interpolation API}