From 78c09364f059bb555cd5cd20974595674e1e9858 Mon Sep 17 00:00:00 2001 From: tradke Date: Fri, 18 Jul 2003 16:15:31 +0000 Subject: 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 --- doc/documentation.tex | 67 ++++++++++++++++++++++++++++++++++++++++----------- 1 file 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} -- cgit v1.2.3