From b82e5c3aa78561c654999489f9a63879af452876 Mon Sep 17 00:00:00 2001 From: schnetter Date: Sun, 7 Mar 2004 09:48:53 +0000 Subject: Initial implementation of the SymBase specification git-svn-id: http://svn.cactuscode.org/arrangements/CactusBase/SymBase/trunk@2 906471b6-c639-44d1-9ea0-3e3d6879f074 --- doc/documentation.tex | 302 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 302 insertions(+) create mode 100644 doc/documentation.tex (limited to 'doc') 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 +#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} -- cgit v1.2.3