From c895e5b15a407c5fc3f9109958e41a48844942f7 Mon Sep 17 00:00:00 2001 From: schnetter Date: Fri, 28 May 2004 15:44:34 +0000 Subject: 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 --- doc/documentation.tex | 183 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 178 insertions(+), 5 deletions(-) (limited to 'doc') 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 -- cgit v1.2.3