Initial implementation of the SymBase specification

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

1 files changed, 302 insertions, 0 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
new file mode 100644
index 0000000..c37694e
--- /dev/null
+++ b/doc/documentation.tex
@@ -0,0 +1,302 @@
+% *======================================================================*
+%  Cactus Thorn template for ThornGuide documentation
+%  Author: Ian Kelley
+%  Date: Sun Jun 02, 2002
+%  $Header$
+%
+%  Thorn documentation in the latex file doc/documentation.tex
+%  will be included in ThornGuides built with the Cactus make system.
+%  The scripts employed by the make system automatically include
+%  pages about variables, parameters and scheduling parsed from the
+%  relevant thorn CCL files.
+%
+%  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.
+%
+%  Guidelines:
+%   - Do not change anything before the line
+%       % START CACTUS THORNGUIDE",
+%     except for filling in the title, author, date, etc. fields.
+%        - Each of these fields should only be on ONE line.
+%        - Author names should be separated with a \\ or a comma.
+%   - You can define your own macros, but they must appear after
+%     the START CACTUS THORNGUIDE line, and must not redefine standard
+%     latex commands.
+%   - To avoid name clashes with other thorns, 'labels', 'citations',
+%     'references', and 'image' names should conform to the following
+%     convention:
+%       ARRANGEMENT_THORN_LABEL
+%     For example, an image wave.eps in the arrangement CactusWave and
+%     thorn WaveToyC should be renamed to CactusWave_WaveToyC_wave.eps
+%   - Graphics should only be included using the graphicx package.
+%     More specifically, with the "\includegraphics" command.  Do
+%     not specify any graphic file extensions in your .tex file. This
+%     will allow us to create a PDF version of the ThornGuide
+%     via pdflatex.
+%   - References should be included with the latex "\bibitem" command.
+%   - Use \begin{abstract}...\end{abstract} instead of \abstract{...}
+%   - Do not use \appendix, instead include any appendices you need as
+%     standard sections.
+%   - For the benefit of our Perl scripts, and for future extensions,
+%     please use simple latex.
+%
+% *======================================================================*
+%
+% 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}
+%    \end{figure}
+%
+% Example of using a label:
+%   \label{MyArrangement_MyThorn_MyLabel}
+%
+% Example of a citation:
+%    \cite{MyArrangement_MyThorn_Author99}
+%
+% Example of including a reference
+%   \bibitem{MyArrangement_MyThorn_Author99}
+%   {J. Author, {\em The Title of the Book, Journal, or periodical}, 1 (1999),
+%   1--16. {\tt http://www.nowhere.com/}}
+%
+% *======================================================================*
+
+% If you are using CVS use this line to give version information
+% $Header$
+
+\documentclass{article}
+
+% Use the Cactus ThornGuide style file
+% (Automatically used from Cactus distribution, if you have a
+%  thorn without the Cactus Flesh download this from the Cactus
+%  homepage at www.cactuscode.org)
+\usepackage{../../../../doc/latex/cactus}
+
+\begin{document}
+
+% The author of the documentation
+\author{Erik Schnetter \textless schnetter@aei.mpg.de\textgreater}
+
+% The title of the document (not necessarily the name of the Thorn)
+\title{SymBase}
+
+% the date your document was last changed, if your document is in CVS,
+% please use:
+\date{$ $Date$ $}
+
+\maketitle
+
+% Do not delete next line
+% START CACTUS THORNGUIDE
+
+% Add all definitions used in this documentation here
+%   \def\mydef etc
+
+% Add an abstract for this thorn's documentation
+\begin{abstract}
+Thorn SymBase contains a registry for symmetry conditions and for
+symmetry faces.
+\end{abstract}
+
+% The following sections are suggestive only.
+% Remove them or add your own.
+
+
+
+\section{Introduction}
+
+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
+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
+conditions and should not apply the physical boundary condition there.
+
+
+
+\section{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
+
+\begin{verbatim}
+CCTK_INT FUNCTION
+    SymmetryRegister (CCTK_STRING IN sym_name)
+
+CCTK_INT FUNCTION
+    SymmetryHandleOfName (CCTK_STRING IN sym_name)
+
+CCTK_POINTER_TO_CONST FUNCTION
+    SymmetryNameOfHandle (CCTK_INT IN sym_handle)
+\end{verbatim}
+
+The routine \texttt{SymmetryRegister} should be called in a routine
+that has been scheduled in the schedule group
+\texttt{SymmetryRegister}.
+
+\begin{quote}
+Note: We have the API in the specification, we have it in the
+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.
+\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:
+
+\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.
+
+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
+array group.
+
+The API for registering symmetries for faces is
+
+\begin{verbatim}
+CCTK_INT FUNCTION
+    SymmetryRegisterGrid
+         (CCTK_POINTER IN cctkGH,
+          CCTK_INT IN sym_handle,
+          CCTK_INT IN ARRAY which_faces,
+          CCTK_INT IN ARRAY symmetry_zone_width)
+
+CCTK_INT FUNCTION
+    SymmetryRegisterGI
+        (CCTK_POINTER IN cctkGH,
+         CCTK_INT IN sym_handle,
+         CCTK_INT IN ARRAY which_faces,
+         CCTK_INT IN ARRAY symmetry_zone_width,
+         CCTK_INT IN group_index)
+
+CCTK_INT FUNCTION
+    SymmetryRegisterGN
+        (CCTK_POINTER IN cctkGH,
+         CCTK_INT IN sym_handle,
+         CCTK_INT IN ARRAY which_faces,
+         CCTK_INT IN ARRAY symmetry_zone_width,
+         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
+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.
+\texttt{which\_faces} selects which faces to register, and
+\texttt{symmetry\_zone\_width} sets the number of symmetry zones for
+these faces.
+
+It is obviously not possible to register multiple symmetry conditions
+for the same face.
+
+
+
+\section{Querying Symmetries of Faces}
+
+Physical boundary conditions need to know to which faces they should
+apply the boundary condition.  They need to query SymBase for the set
+of faces that have a symmetry boundary condition, and they must not
+apply their physical boundary condition there.  The API is
+
+\begin{verbatim}
+CCTK_INT FUNCTION
+    SymmetryTableHandleForGrid (CCTK_POINTER_TO_CONST IN cctkGH)
+
+CCTK_INT FUNCTION
+    SymmetryTableHandleForGI
+        (CCTK_POINTER_TO_CONST IN cctkGH,
+         CCTK_INT IN group_index)
+
+CCTK_INT FUNCTION
+    SymmetryTableHandleForGN
+        (CCTK_POINTER_TO_CONST IN cctkGH,
+         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 code to find out which boundaries should have a physical boundary
+condition applied might look as follows:
+
+\begin{verbatim}
+#include <assert.h>
+#include "util_Table.h"
+
+CCTK_INT symtable;
+CCTK_INT symbnd[6];
+int face;
+int ierr;
+
+symtable = SymmetryTableHandleForGrid (cctkGH);
+assert (symtable>=0);
+
+ierr = Util_TableGetIntArray (symtable, 6, symbnd, "symmetry_handle");
+assert (ierr==6);
+
+for (face=0; face<6; ++face) {
+  if (cctk_bbox[face] && symbnd[face]<0) {
+    /* Apply physical boundary condition here */
+  }
+}
+\end{verbatim}
+
+\begin{verbatim}
+#include "util_Table.h"
+
+CCTK_INT symtable
+CCTK_INT symbnd(6)
+integer face
+integer ierr
+
+symtable = SymmetryTableHandleForGrid (cctkGH)
+if (symtable<0) call CCTK_WARN (0, "internal error")
+
+call Util_TableGetIntArray (ierr, int(symtable), 6, symbnd, "symmetry_handle")
+if (ierr/=6) call CCTK_WARN (0, "internal error")
+
+do face=1,6
+  if (cctk_bbox(face)/=0 .and. symbnd(face)<0) then
+    ! Apply physical boundary condition here
+  end if
+end do
+\end{verbatim}
+
+
+
+% Do not delete next line
+% END CACTUS THORNGUIDE
+
+\end{document}