Provide infrastructure to take symmetries into account for global

interpolations.


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

1 files changed, 178 insertions, 5 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index c37694e..8e1808b 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -45,11 +45,11 @@
 %
 % Example of including a graphic image:
 %    \begin{figure}[ht]
-% 	\begin{center}
-%    	   \includegraphics[width=6cm]{MyArrangement_MyThorn_MyFigure}
-% 	\end{center}
-% 	\caption{Illustration of this and that}
-% 	\label{MyArrangement_MyThorn_MyLabel}
+%       \begin{center}
+%          \includegraphics[width=6cm]{MyArrangement_MyThorn_MyFigure}
+%       \end{center}
+%       \caption{Illustration of this and that}
+%       \label{MyArrangement_MyThorn_MyLabel}
 %    \end{figure}
 %
 % Example of using a label:
@@ -296,6 +296,179 @@ 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 is 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\_Interp} 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 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.
+\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
+  \texttt{SymmetryInterpolateFaces}, passing along the arguments with
+  the changed interpolation locations.
+\item After the actual interpolation has happened in the driver, the
+  recursive call will return.  The ``symmetry interpolation'' routine
+  then examines the tensor types of the interpolated quantities and
+  un-maps the values back onto their original locations.  That is,
+  e.g., after a reflection on the lower $x$-boundary, $x$-components
+  of vectors need their sign changed.
+\item The chain of recursive calls unravels until the call to
+  \texttt{CCTK\_Interp} 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\_Interp} as before, and
+  everything happens transparently for him.
+\end{itemize}
+
+
+
+\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\_Interp}, 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}
+
+
+
+\subsection{Interaction With Symmetry Conditions}
+
+The symmetry conditions have to register their ``symmetry
+interpolation'' routines by calling SymBase's aliased function
+\texttt{SymmetryRegisterGridInterpolator}.  The ``symmetry
+interpolation'' routine must use C linkage and must have the prototype
+
+\begin{verbatim}
+CCTK_INT symmetry_interpolate
+    (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}
+
+These arguments are essentially the same as those for
+\texttt{CCTK\_Interp}, except that the bit field \texttt{faces} flags
+those faces that still their symmetry boundary condition applied to
+the interpolation points.  The aliased function
+\texttt{SymmetryRegisterGridInterpolator} has the prototype
+
+\begin{verbatim}
+CCTK_INT FUNCTION                                           \
+    SymmetryRegisterGridInterpolator                        \
+        (CCTK_POINTER IN cctkGH,                            \
+         CCTK_INT IN sym_handle,                            \
+         CCTK_INT CCTK_FPOINTER IN symmetry_interpolate     \
+             (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}
+
+which takes a function pointer to the aforementioned ``symmetry
+interpolation'' routine, while \texttt{sym\_handle} specifies which
+symmetry condition this routine is for.  This handle must have been
+obtained from \texttt{SymmetryRegister}.
+
+\begin{quote}
+  The routine \texttt{SymmetryRegisterGridInterpolator} must be called
+  \emph{after} the symmetry faces have been selected by the call to
+  \texttt{SymmetryRegisterGrid}.
+\end{quote}
+
+
+
 % Do not delete next line
 % END CACTUS THORNGUIDE