% *======================================================================*
%  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}