Various clarifications

Moved paragraph from interior of doc to the abstract

Prototype for SymmetryInterpolateFaces


git-svn-id: http://svn.cactuscode.org/arrangements/CactusBase/SymBase/trunk@26 906471b6-c639-44d1-9ea0-3e3d6879f074

1 files changed, 163 insertions, 120 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 193ac2b..ef80e9e 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -12,7 +12,7 @@
 %
 %  This template contains guidelines which help to assure that your
 %  documentation will be correctly added to ThornGuides. More
-%  information is available in the Cactus UsersGuide.
+%  information is available in the Cactus Users Guide.
 %
 %  Guidelines:
 %   - Do not change anything before the line
@@ -98,8 +98,13 @@
 
 % Add an abstract for this thorn's documentation
 \begin{abstract}
-Thorn SymBase contains a registry for symmetry conditions and for
-symmetry faces.
+When the computational domain has symmetries, then it is often very
+convenient to be able to interpolate at points that are not present on
+the actual computational grid, but can be mapped into the grid through
+the symmetries.  Thorn SymBase provides a mechanism by which symmetry
+conditions can register routines that handle this mapping when a
+global interpolator is called. 
+
 \end{abstract}
 
 % The following sections are suggestive only.
@@ -111,10 +116,10 @@ symmetry faces.
 
 Thorn SymBase contains a registry for symmetry conditions and for
 symmetry faces.  Other thorns that implement symmetry boundary
-conditions register themselves with this thorn and reserve certain
+conditions register themselves with SymBase and reserve certain
 faces of the grid, so that no other boundary condition is applied
 there.  Thorns that implement physical boundary conditions should
-query this thorn about the set of faces that have symmetry boundary
+query SymBase about the set of faces that have symmetry boundary
 conditions and should not apply the physical boundary condition there.
 
 \begin{figure}[ht]
@@ -132,14 +137,19 @@ conditions and should not apply the physical boundary condition there.
 \label{SymBase.faces}
 \end{figure}
 
+The driver has to be aware that it calls thorn SymBase's mapping
+routine before it actually interpolates.  The whole mechanism is
+transparent for the user.
+
 
 
 \section{Registering Symmetry Conditions}
+\label{SymBase.registering_symmetry_conditions}
 
 Each thorn that implements a symmetry boundary condition should
 register itself with thorn SymBase.  This has no consequences per se,
-but it reservers a symmetry handle for later use.  The API for
-registering and querying symmetry names and handles is
+but it reserves a \emph{symmetry handle} for later reference. 
+The API for registering and querying symmetry names and handles is
 
 \begin{verbatim}
 CCTK_INT FUNCTION
@@ -162,32 +172,34 @@ interface file, in the source code, and in a header file, and I
 duplicated it into grdoc headers.  I refuse to write and describe and
 cross-check the API a \emph{sixth} time in latex.  At some point, we
 have to start using tools for that.  Please read the grdoc headers or
-the grdoc-produced html files for a detailed description.
+the grdoc-produced HTML files for a detailed description.
 \end{quote}
 
 
 
 \section{Registering Symmetries for Faces}
 
-Thorn SymBase keeps two registries.  The first, described in the
-previous section, contains the set of symmetry boundary conditions
-that exist at all.  The second, described here, describes which face
-of the grids have which symmetry condition applied to it, if any.
-Each such mapping from grid face to symmetry condition is described by
-a symmetry table with the following entries:
+Thorn SymBase keeps two registries.  The first, mentioned in the
+previous section, is the set of symmetry boundary conditions. 
+The second, the \emph{symmetry table}, prescribes to which faces
+of the grids which symmetry boundary condition is to be applied.
+Each entry of this table constitutes a mapping from grid faces to
+symmetry boundary conditions, described by arrays whose elements
+correspond to grid faces:
 
 \begin{verbatim}
 CCTK_INT symmetry_handle[]
 CCTK_INT symmetry_zone_width[]
 \end{verbatim}
 
-Each of these arrays contains one element per face, numbered in the
-same way as the \texttt{cctk\_bbox} array.  The
-\texttt{symmetry\_handle} is a symmetry handle as described in the
-previous section, and the \texttt{symmetry\_zone\_width} is the width
-of the symmetry zone.
+The faces are numbered in the same way those of the \texttt{cctk\_bbox} array. 
+Each element of \texttt{symmetry\_handle} is a symmetry handle as
+described in section~\ref{SymBase.registering_symmetry_conditions}. 
+The \emph{symmetry zone} is the same as a Cactus ghost zone, just in the
+context of a symmetry boundary, so the \texttt{symmetry\_zone\_width} will
+be typically be the same as the ghost zone width.
 
-Code outside SymBase should not modify these table entries.
+%Code outside SymBase should not modify these table entries.
 
 There is one such table for the grid hierarchy, which is valid for all
 grid functions.  There is additionally one such table for each grid
@@ -220,9 +232,10 @@ CCTK_INT FUNCTION
          CCTK_STRING IN group_name)
 \end{verbatim}
 
-The first routine registers a symmetry condition for certain faces for
-the grid hierarchy, the other two routines register for grid array
-groups.  \texttt{sym\_handle} must be a symmetry handle obtained as
+The first routine registers a symmetry condition for the grid hierarchy;
+the other two routines register for grid array groups (by index or 
+name, respectively)
+\texttt{sym\_handle} must be a symmetry handle obtained as
 described in the previous section.  \texttt{which\_faces} and
 \texttt{symmetry\_zone\_width} are arrays with one element per face,
 numbered in the same way as the \texttt{cctk\_bbox} array.
@@ -230,7 +243,9 @@ numbered in the same way as the \texttt{cctk\_bbox} array.
 \texttt{symmetry\_zone\_width} sets the number of symmetry zones for
 these faces.
 
-It is obviously not possible to register multiple symmetry conditions
+These routines may be called at anytime after \texttt{SymmetryRegister}.
+
+It is not possible to register multiple symmetry boundary conditions
 for the same face.
 
 
@@ -257,11 +272,13 @@ CCTK_INT FUNCTION
          CCTK_STRING IN group_name)
 \end{verbatim}
 
-These functions return the the handle for the symmetry table for the
-grid hierarchy or for the grid array group, respectively.  The table
-entry \texttt{symmetry\_handle} contains the symmetry handle for the
-symmetry boundary condition, or a negative number if the face has no
-symmetry boundary condition associated with it.
+The first of these functions returns the symmetry table handle for the
+grid hierarchy; the second and third return the that for the grid array group
+(by index or name, respectively).
+
+The table entry with key \texttt{symmetry\_handle} contains the symmetry
+handle for the symmetry boundary condition, or a negative number if the face
+has no symmetry boundary condition associated with it.
 
 The code to find out which boundaries should have a physical boundary
 condition applied might look as follows:
@@ -317,35 +334,27 @@ end do
 
 \section{Symmetry Interpolation}
 
-When the computational domain has symmetries, then it is often very
-convenient to be able to interpolate at points that are not present on
-the actual computational grid, but can be mapped into the grid through
-the symmetries.  Thorn SymBase provides a mechanism by which symmetry
-conditions can register routines that handle this mapping when a
-global interpolator is called.  Additionally, the driver has to be
-aware that it calls thorn SymBase's mapping routine before it actually
-interpolates.  The whole mechanism is transparent for the user.
-
 The mechanism by which the grid points are mapped into the domain
 works as follows:
 \begin{enumerate}
-\item The user calls \texttt{CCTK\_InterpGridArrays} with a list of coordinates.
-\item The flesh forwards this call to the driver.
-\item The driver calls SymBase's aliased function,
-  \texttt{SymmetryInterpolate}, passing along all arguments.
-\item SymBase sets a flag for all boundaries that have a symmetry
-  condition associated with it, and then calls
-  \texttt{SymmetryInterpolateFaces}, passing along all arguments.
-  This is the beginning of a chain of recursive calls.
-\item \texttt{SymmetryInterpolateFaces} checks whether any faces are
-  flagged.
-\item If no faces are flagged, SymBase calls the driver's aliased
-  function \texttt{DriverInterpolate}, which performs the actual
-  interpolation.  This ends the chain of recursive calls.
+	\item The user calls \texttt{CCTK\_InterpGridArrays} with a list of
+	  coordinates.
+	\item The Flesh forwards this call to the driver.
+	\item The driver calls SymBase's aliased function,
+	  \texttt{SymmetryInterpolate}, passing along all arguments.
+	\item SymBase sets a flag for each face for which a symmetry
+	  condition has been registered, and then calls
+	  \texttt{SymmetryInterpolateFaces}, passing along all arguments.
+	  This is the beginning of a chain of recursive calls.
+	\item \texttt{SymmetryInterpolateFaces} checks whether any faces are
+	  flagged.
+	\item If no faces are flagged, SymBase calls the driver's aliased
+	  function \texttt{DriverInterpolate}, which performs the actual
+	  interpolation.  This ends the chain of recursive calls.
 	\item If there are faces with symmetry conditions flagged, SymBase
-	  chooses one such face, and then calls this face's symmetry
-	  condition's ``symmetry interpolation'' routine, passing along all
-	  arguments.
+	  chooses one such face, and then calls the ``symmetry interpolation''
+	  routine of the symmetry condition registered for this face,
+	  passing along all arguments.
 	\item The ``symmetry interpolation'' routine maps the coordinates into
 	  the domain by applying the symmetry condition for this face.  It
 	  then removes the flag for the corresponding face, and calls
@@ -359,28 +368,16 @@ works as follows:
 	  of vectors need their sign changed.
 	\item The chain of recursive calls unravels until the call to
 	  \texttt{CCTK\_InterpGridArrays} returns.
-	\end{enumerate}
-	This mechanism has thus four players:
-	\begin{itemize}
-	\item The driver forwards the call to SymBase so that the list of
-	  interpolation points can be mapped into the domain.
-	\item Thorn SymBase controls which symmetry conditions perform this
-	  mapping on which faces.
-\item Each symmetry boundary condition has to register a ``symmetry
-  interpolation'' routine that first maps the points into the domain,
-  then calls SymBase recursively, and finally corrects the tensor
-  types of the interpolated quantities.
-\item Finally, the user calls \texttt{CCTK\_InterpGridArrays} as before, and
-  everything happens transparently for her.
-\end{itemize}
+\end{enumerate}
+
 
 \begin{figure}[tb]
 \begin{center}
 \includegraphics[scale=.833,clip=true]{fig/recursion}
 \end{center}
 \caption[Symmetry interpolation] {
-	  The recursive calls involved in symmety interpolation.
-	  Values of grid functions $a$ at global cartesian coordinates $x$ are 
+	  The recursive calls involved in symmetry interpolation.
+	  Values of grid functions $a$ at global Cartesian coordinates $x$ are 
 	  calculated by nested calls to the symmetry interpolators, which first
 	  apply the symmetry transformation to the coordinates.  When all
 	  the symmetries have been applied, the local interpolator is called,
@@ -391,51 +388,22 @@ works as follows:
 \label{SymBase.recursion}
 \end{figure}
 
-
-
-
-\subsection{Driver Interaction}
-
-The driver has to call SymBase's aliased function
-\texttt{SymmetryInterpolate}, and has to provide an aliased function
-\texttt{DriverInterpolate}.  Both functions have essentially the same
-prototype as \texttt{CCTK\_InterpGridArrays}, which are:
-
-\begin{verbatim}
-CCTK_INT FUNCTION
-    SymmetryInterpolate
-        (CCTK_POINTER_TO_CONST IN cctkGH,
-         CCTK_INT IN N_dims,
-         CCTK_INT IN local_interp_handle,
-         CCTK_INT IN param_table_handle,
-         CCTK_INT IN coord_system_handle,
-         CCTK_INT IN N_interp_points,
-         CCTK_INT IN interp_coords_type,
-         CCTK_POINTER_TO_CONST ARRAY IN interp_coords,
-         CCTK_INT IN N_input_arrays,
-         CCTK_INT ARRAY IN input_array_indices,
-         CCTK_INT IN N_output_arrays,
-         CCTK_INT ARRAY IN output_array_types,
-         CCTK_POINTER ARRAY IN output_arrays)
-\end{verbatim}
-
-\begin{verbatim}
-CCTK_INT FUNCTION
-    DriverInterpolate
-        (CCTK_POINTER_TO_CONST IN cctkGH,
-         CCTK_INT IN N_dims,
-         CCTK_INT IN local_interp_handle,
-         CCTK_INT IN param_table_handle,
-         CCTK_INT IN coord_system_handle,
-         CCTK_INT IN N_interp_points,
-         CCTK_INT IN interp_coords_type,
-         CCTK_POINTER_TO_CONST ARRAY IN interp_coords,
-         CCTK_INT IN N_input_arrays,
-         CCTK_INT ARRAY IN input_array_indices,
-         CCTK_INT IN N_output_arrays,
-         CCTK_INT ARRAY IN output_array_types,
-         CCTK_POINTER ARRAY IN output_arrays)
-\end{verbatim}
+This mechanism has thus four players:
+\begin{itemize}
+	\item The driver forwards any \texttt{CCTK\_InterpGridArrays} call
+	  to SymBase \texttt{SymmetryInterpolate} so that the list of
+	  interpolation points can be mapped into the domain. (See section
+	  \ref{SymBase.driver_interaction}.)
+	\item Thorn SymBase controls which symmetry conditions perform this
+	  mapping on which faces.
+	\item Each symmetry boundary condition has to register a ``symmetry
+	  interpolation'' routine that first maps the points into the domain,
+	  then calls SymBase \texttt{SymmetryInterpolateFaces} recursively.
+	  Before returning, it performs the inverse coordinate transformation
+	  on the interpolated quantities.
+	\item The user calls \texttt{CCTK\_InterpGridArrays}.  For them
+	  the rest of the mechanism is transparent.
+\end{itemize}
 
 
 
@@ -464,11 +432,13 @@ CCTK_INT symmetry_interpolate
      CCTK_INT IN faces)
 \end{verbatim}
 
-These arguments are essentially the same as those for
-\texttt{CCTK\_InterpGridArrays}, except that the bit field \texttt{faces} flags
-those faces that still need their symmetry boundary condition applied to
-the interpolation points.  The aliased function
-\texttt{SymmetryRegisterGridInterpolator} has the prototype
+These arguments are the same as those for \texttt{CCTK\_InterpGridArrays},
+except that here the bit field \texttt{faces} is used to flag those faces
+that remain to have their symmetry boundary condition applied to the
+interpolation points. 
+
+The aliased function \texttt{SymmetryRegisterGridInterpolator} has the
+prototype
 
 \begin{verbatim}
 CCTK_INT FUNCTION                                           \
@@ -503,6 +473,79 @@ obtained from \texttt{SymmetryRegister}.
   \texttt{SymmetryRegisterGrid}.
 \end{quote}
 
+For convenience, the macro \texttt{CCTK\_ALL\_FACES} is provided.
+It may be used to initialize the \texttt{faces} bit field in cases
+where the interpolation is to occur on all grid faces.
+
+After it has removed from the \texttt{faces} variable the faces whose
+symmetry condition it has applied, the symmetry interpolator routine
+must call the SymBase function \texttt{SymmetryInterpolateFaces}, which
+has the prototype
+
+\begin{verbatim}
+CCTK_INT FUNCTION                                           \
+    SymmetryInterpolateFaces                                \
+        (CCTK_POINTER_TO_CONST IN cctkGH,                   \
+         CCTK_INT IN N_dims,                                \
+         CCTK_INT IN local_interp_handle,                   \
+         CCTK_INT IN param_table_handle,                    \
+         CCTK_INT IN coord_system_handle,                   \
+         CCTK_INT IN N_interp_points,                       \
+         CCTK_INT IN interp_coords_type,                    \
+         CCTK_POINTER_TO_CONST ARRAY IN interp_coords,      \
+         CCTK_INT IN N_input_arrays,                        \
+         CCTK_INT ARRAY IN input_array_indices,             \
+         CCTK_INT IN N_output_arrays,                       \
+         CCTK_INT ARRAY IN output_array_types,              \
+         CCTK_POINTER ARRAY IN output_arrays,               \
+         CCTK_INT IN faces)
+\end{verbatim}
+
+
+
+\subsection{Driver Interaction}
+\label{SymBase.driver_interaction}
+
+The driver has to call SymBase's aliased function
+\texttt{SymmetryInterpolate}, and has to provide an aliased function
+\texttt{DriverInterpolate}.  Both functions have prototypes similar to 
+\texttt{CCTK\_InterpGridArrays}:
+
+\begin{verbatim}
+CCTK_INT FUNCTION
+    SymmetryInterpolate
+        (CCTK_POINTER_TO_CONST IN cctkGH,
+         CCTK_INT IN N_dims,
+         CCTK_INT IN local_interp_handle,
+         CCTK_INT IN param_table_handle,
+         CCTK_INT IN coord_system_handle,
+         CCTK_INT IN N_interp_points,
+         CCTK_INT IN interp_coords_type,
+         CCTK_POINTER_TO_CONST ARRAY IN interp_coords,
+         CCTK_INT IN N_input_arrays,
+         CCTK_INT ARRAY IN input_array_indices,
+         CCTK_INT IN N_output_arrays,
+         CCTK_INT ARRAY IN output_array_types,
+         CCTK_POINTER ARRAY IN output_arrays)
+\end{verbatim}
+
+\begin{verbatim}
+CCTK_INT FUNCTION
+    DriverInterpolate
+        (CCTK_POINTER_TO_CONST IN cctkGH,
+         CCTK_INT IN N_dims,
+         CCTK_INT IN local_interp_handle,
+         CCTK_INT IN param_table_handle,
+         CCTK_INT IN coord_system_handle,
+         CCTK_INT IN N_interp_points,
+         CCTK_INT IN interp_coords_type,
+         CCTK_POINTER_TO_CONST ARRAY IN interp_coords,
+         CCTK_INT IN N_input_arrays,
+         CCTK_INT ARRAY IN input_array_indices,
+         CCTK_INT IN N_output_arrays,
+         CCTK_INT ARRAY IN output_array_types,
+         CCTK_POINTER ARRAY IN output_arrays)
+\end{verbatim}
 
 
 \section{Tensor Types}