1 files changed, 309 insertions, 0 deletions
diff --git a/doc/documentation.tex b/doc/documentation.tex
new file mode 100644
index 0000000..7699b35
--- /dev/null
+++ b/doc/documentation.tex
@@ -0,0 +1,309 @@
+% *======================================================================*
+%  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{SphericalSurface}
+
+% 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
+
+\begin{abstract}
+This thorn provides a repository for two-dimensional surfaces with
+spherical topology.  This thorn does not actually do anything with
+these surfaces, but allow other thorns to store and retrieve the
+surfaces and some associated information.  The exact interpretation of
+the stored quantities is up to the using thorns, but certain standard
+definitions are suggested.
+\end{abstract}
+
+
+
+\section{Introduction}
+
+Many thorns work on manifolds that are two-dimensional, closed
+surfaces.  Examples are apparent and event horizons, or the surfaces
+on which gravitational waves are extracted.  Other such surfaces might
+be excision or outer boundaries (although these are currently not
+treated as such).  There is a need to have a common representation for
+such surfaces, so that the surface-finding thorns and the thorns
+working with these surfaces can be independent.  A common
+representation will also facilitate visualisation.  This thorn
+\texttt{SphericalSurface} provides just such a common representation.
+
+This thorn is not meant to do anything else but be a ``repository''
+for surfaces.  It is up to the surface-finding and surface-using
+thorns to agree on the details of the information stored.  Of course,
+standard definitions for the stored quantities are suggested.  (For
+example, there is no exact definition of the quadrupole moment,
+because this definition will depend on the kind of surface that is
+stored.  However, it is specified that the quadrupole moment should be
+calculate with respect to the centroid, and that it should not be
+trace-free.)
+
+This thorn provides storage for several independent surfaces,
+identified by an \emph{index}.  It is up to the user to specify,
+probably in the parameter file, which thorns use what surfaces for
+what purpose.
+
+
+
+\section{Surface Definition}
+
+This thorn provides, for each surface, a two-dimensional grid array
+\texttt{sf\_radius} and grid scalars \texttt{sf\_origin\_x},
+\texttt{sf\_origin\_y}, and \texttt{sf\_origin\_z}.  The number of
+surfaces is determined by the parameter \texttt{nsurfaces}, which has
+to be set in the parameter file.
+
+\texttt{sf\_radius} should contain the radius of the surface as
+measured from its origin, where the arrays indices vary in the
+$\theta$ and $\phi$ direction, respectively.  Both the radius array
+and the surface origin are supposed to be set when a surface is
+stored.
+
+The coordinates on the surface, i.e.\ the grid origin and spacing in
+the $\theta$ and $\phi$ directions, is available from the grid scalars
+\texttt{sf\_origin\_theta}, \texttt{sf\_origin\_phi},
+\texttt{sf\_delta\_theta}, and \texttt{sf\_delta\_phi}.  These grid
+scalars are set by the thorn SphericalSurface in the \texttt{basegrid}
+bin, and are meant to be read-only for other thorns.
+
+
+
+\begin{quotation}
+\subsection*{A note on vector grid variables}
+
+A relatively new addition to Cactus (in November 2003) are vector grid
+variables.  These are essentially arrays of grid variables.  Thorn
+SphericalSurface makes use of these by storing the surfaces in such
+arrays.  That means that in order to access data from a single
+surface, on has to use the corresponding surface index as array index.
+In a similar manner, thorn SurfaceIndex uses array parameters for its
+parameters (except certain global ones).
+
+This should be kept in mind when writing source code.  C has the
+unfortunate property of converting arrays into meaningless integers if
+an array subscript is accidentally omitted.  Fortran knows whole-array
+expressions, meaning that it would act on all surfaces instead of a
+single one if an array subscript is accidentally omitted.
+
+Each element of a vector grid function is a grid function.  (The term
+``grid function vector'' might have been more appropriate.)  As such,
+it has a name, which can be used e.g.\ for output.  The name consists
+of the vector grid function name to which the surface index in square
+brackets has been appended.
+\end{quotation}
+
+
+
+\subsection{Global Surface Quantities}
+
+In many cases, only some abstract information about the surface is of
+interest, such as its mean radius or its quadrupole moment.  For that
+purpose there are additional grid scalars that carry this information.
+These grid scalars are also supposed to be set when a surface is
+stored.  These grid scalars are
+\begin{description}
+
+\item[\texttt{sf\_mean\_radius}] Mean of the surface radius.  This
+should be the arithmetic mean where the radii have been weighted with
+$\sin\theta$, or a suitable generalisation thereof.  This quantity is
+also supposed to be a measure of the surface's monopole moment.  One
+suggested expression is $M=\sqrt{A}$ with $A = \int_S d\Omega\, r^2 /
+\int_S d\Omega$.
+
+\item[\texttt{sf\_min\_radius}, \texttt{sf\_max\_radius}] Minimum and
+maximum of the surface radius.
+
+\item[\texttt{sf\_centroid\_x}, \texttt{sf\_centroid\_y},
+\texttt{sf\_centroid\_z}] The centre of the surface.  While the
+quantities \texttt{sf\_origin\_*} denote the point from which the
+radius of the surface is measured, the quantities
+\texttt{sf\_centroid\_*} should contain the point which is
+``logically'' the centre of the surface.  This quantity is supposed to
+be a measure of the dipole moment of the surface.  One suggested
+expression is $D^i = \int_S d\Omega\, x^i / A$.
+
+\item[\texttt{sf\_quadrupole\_xx}, \texttt{sf\_quadrupole\_xy},
+\texttt{sf\_quadrupole\_xz}, \texttt{sf\_quadrupole\_yy},
+\texttt{sf\_quadrupole\_yz}, \texttt{sf\_quadrupole\_zz}] The
+quadrupole moment of the surface. This should be the full quadrupole
+moment and not a trace-free quantity.  One suggested expression is
+$Q^{ij} = \int_S d\Omega\, y^i y^j / A$ with $y^i = x^i - D^i$.
+
+\item[\texttt{sf\_min\_x}, \texttt{sf\_min\_y}, \texttt{sf\_min\_z},
+\texttt{sf\_max\_x}, \texttt{sf\_max\_y}, \texttt{sf\_max\_z}] The
+bounding box of the surface.
+
+\end{description}
+Note that the integral expressions are only suggestions which should
+be adapted to whatever is natural for the stored surface.  The
+suggested integral expressions also depend on the metric which is
+used; this should be a ``natural'' metric for the surface.  E.g.\ for
+apparent horizons, this might be the induced two-metric $q_{ij}$ from
+the projection of the ADM three-metric $\gamma_{ij}$.
+
+
+
+\subsection{Validity of Surface Data}
+
+There is also an integer flag \texttt{valid} available.  Its
+definition is up to the surface-providing thorn.  The following
+interpretations are \emph{suggested}:
+\begin{description}
+
+\item[zero:] No surface is provided at this time step.
+
+\item[negative:] No surface could be found at this time step.  This
+indicates an error.
+
+\item[positive:] The surface data are valid.
+
+\end{description}
+Note that, if this flag is used, it is necessary to set this flag at
+every iteration.  This flag is not automatically reset to zero.
+
+
+
+\section{Surface Array Shape}
+
+The number of grid points in the radius array \texttt{sf\_radius} is
+determined by the parameters \texttt{ntheta} and \texttt{nphi}.  These
+arrays exist for each surface.  (Internally, thorn SphericalSurface
+stores all surfaces with the same array shape \texttt{maxntheta} and
+\texttt{maxnphi}, so that the parameters  \texttt{ntheta} and
+\texttt{nphi} must not be used for index calculations.  Use the
+surfaces \texttt{lsh} instead.)  The surface array shape includes
+ghost or boundary zones at the array edges.  These ghost zones have
+the same size for all surfaces.
+
+
+
+\section{Surface Symmetries}
+
+It is often the case that one uses symmetries to reduce the size of
+the simulation domain, such as octant or quadrant mode.  Whenever a
+symmetry plane intersects a surface, only part of the surface is
+actually stored.  The user has to define the symmetries of each
+surface in the parameter file via the parameters
+\texttt{sf\_symmetry\_x}, \texttt{sf\_symmetry\_y}, and
+\texttt{sf\_symmetry\_z}.  The indicate that a 
+reflection symmetry exists in the corresponding direction.  The
+surface origin is required to lie in the corresponding symmetry
+planes.
+
+Thorn SphericalSurface takes these symmetries into account when it
+calculates the grid spacing and the origin of the surface coordinates
+$\theta$ and $\phi$.
+
+
+
+\section{Input and Output}
+
+As the surfaces are stored as grid variables, the standard input and
+output routines will work for them.  The standard visualisation tools
+will be able to visualise them.  The surfaces will also automatically
+be checkpointed and restored.
+
+
+
+\subsection{Acknowledgements}
+
+This thorn was suggested during meetings of the numerical relativity
+group at the AEI.  Jonathan Thornburg provided many detailed and
+useful suggestions.  Ed Evans, Carsten Gundlach, Ian Hawke, and Denis
+Pollney contributed comments and suggestions.
+
+% Do not delete next line
+% END CACTUS THORNGUIDE
+
+\end{document}