some initial documentation

git-svn-id: http://svn.aei.mpg.de/numrel/AEIThorns/ADMMass/trunk@45 54511f98-0e4f-0410-826e-eb8b393f5a1e

1 files changed, 169 insertions, 0 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
new file mode 100644
index 0000000..33c6dd8
--- /dev/null
+++ b/doc/documentation.tex
@@ -0,0 +1,169 @@
+% *======================================================================*
+%  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{Frank Löffler}
+
+% The title of the document (not necessarily the name of the Thorn)
+\title{ADMMass}
+
+% the date your document was last changed, if your document is in CVS,
+% please use:
+%    \date{$ $Date: 2004-01-07 14:12:39 -0600 (Wed, 07 Jan 2004) $ $}
+\date{2012-05-07}
+
+\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 ADMMass can compute the ADM mass from quantities in ADMBase.
+\end{abstract}
+
+% The following sections are suggestive only.
+% Remove them or add your own.
+
+\section{Introduction}
+The ADM mass evaluated as either surface integrals at infinity or volume
+integrals over entire hypersurfaces give a measure of the total energy in the
+spacetime.
+
+ The ADM mass can be defined~\cite{Omurchadha74} as a surface integral over a
+ sphere with infinite radius:
+ \begin{equation}
+ \label{eq:ADM_mass}
+  M_{\mbox{\tiny ADM}}=\frac{1}{16\pi}\oint_\infty
+  \sqrt{\gamma}\gamma^{ij}\gamma^{kl}
+  (\gamma_{ik,j}-\gamma_{ij,k})\textrm{d}\! S_l
+ \end{equation}.
+ This is, assuming $\alpha=1$ at infinity, equivalent to
+ \begin{equation}
+ \label{eq:ADM_mass_volume}
+  M_{\mbox{\tiny ADM}}=\frac{1}{16\pi}\int
+  \left(\alpha\sqrt{\gamma}\gamma^{ij}\gamma^{kl}
+  (\gamma_{ik,j}-\gamma_{ij,k})\right)_{,l}\textrm{d}\!^{\,3}\!\!x
+ \end{equation}.
+In practice, the following equation can also be used within the thorn:
+  \begin{equation}
+   \label{eq:ADM_mass_lapse}
+   M_{\mbox{\tiny ADM}}=\frac{1}{16\pi}\oint_\infty
+   \alpha\sqrt{\gamma}\gamma^{ij}\gamma^{kl}
+   (\gamma_{ik,j}-\gamma_{ij,k})\textrm{d}\! S_l.
+  \end{equation}
+  This differs from equation~(\ref{eq:ADM_mass}) by the factor $\alpha$ inside
+  the integral. For evaluations of those equations at infinity, $\alpha=1$ is
+  assumed, and they are equal. For evaluations at a finite distance, however,
+  this is usually not the case and the approximation of the ADM mass is
+  gauge-dependent~\cite{Omurchadha74}. Depending on circumstances,
+  either~(\ref{eq:ADM_mass}),~(\ref{eq:ADM_mass_lapse} or~~(\ref{eq:ADM_mass_volume})
+  might give better results.
+
+\section{Using This Thorn}
+
+\subsection{Basic Usage}
+
+
+
+\subsection{Special Behaviour}
+
+\subsection{Interaction With Other Thorns}
+
+\subsection{Examples}
+
+\subsection{Support and Feedback}
+
+\section{History}
+
+\subsection{Thorn Source Code}
+
+\subsection{Thorn Documentation}
+
+\subsection{Acknowledgements}
+
+
+% Do not delete next line
+% END CACTUS THORNGUIDE
+
+\end{document}