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

% The title of the document (not necessarily the name of the Thorn)
\title{CactusEinstein}

% 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
%This doesn't work from here; why not?
%\def\sep{\hspace{3mm}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Add an abstract for this thorn's documentation
\begin{abstract}
  Set of thorns for performing simulations of Einstein's equations,
  which encode the dynamics of General Relativity.  The package
  includes initial data, evolution codes, analysis tools, and various
  `utility' thorns which provide infrastructure such as a time
  invariant conformal factor and a spatial `mask' which can be used to
  put various flags on your special grid points.
\end{abstract}

\section{Purpose}

This document is intended to be a `third read' quick start guide to
using the \texttt{CactusEinstein} toolkit to do fully general relativistic
simulations.  (The first and second reads may be the QuickStart HOWTO
and a skim through parts A and B of the Users' Guide, respectively.)
Since it will be improved vastly by input from \emph{first-time
user} experiences, please send comments and suggestions to
\texttt{users@cactuscode.org}.  Better yet, ask for a
cvs\footnote{What is cvs?  See the cvs appendix of the Users'
Guide.}
account so that you can edit this document directly yourself!


\section{Overview}

The \texttt{CactusEinstein} arrangement provides a suite of thorns for doing
numerical relativity simulations.  The basic variables are those of the ADM
formulation of Einstein's equations, namely the spatial \mbox{3-metric}
$\gamma_{ij}$, the lapse $\alpha$, the shift $\beta$, and the extrinsic
curvature $K_{ij}$.  The 4-metric is given by
%
\begin{displaymath}
ds^2 = -(\alpha^2 - \beta^i \beta_i) dt^2 + \beta_i dt dx^i + \gamma_{ij} dx^i
dx^j \;.
\end{displaymath}
If $\gamma_{ij}$ is the 3-metric of a spacelike Cauchy surface with normal
$n$, then
\begin{displaymath}
K_{ij} = \frac{1}{2}{\cal L}_n \gamma_{ij} \;.
\end{displaymath}

These variables are defined in the thorn \texttt{ADMBase}, and are the ones
that are used to communicate the geometry to other thorns.  It is not
necessary to use these as the basic variables of your computation, however.
All you need do is compute these quantities at each iteration in order to
communicate with the \texttt{CactusEinstein} thorns.

There are a number of initial data thorns, an \texttt{ADM} thorn for
evolution, and thorns which provide many other pieces of infrastructure.  It
is not necessary to use all of these thorns to make use of
\texttt{CactusEinstein}, however.  The only thorn which is necessary is
\texttt{ADMBase}, since it defines the variables and parameters on which the
rest of the \texttt{CactusEinstein} thorns depend.


\section{Matter Interface}

Matter is handled in \texttt{CactusEinstein} via the fabled
``\verb|CalcTmunu|'' interface.

This is documented in detail in the ThornGuide for \texttt{ADMCoupling}.


\section{The Thorns}

Here we give a brief description of each of the thorns contained in
this arrangement.

\begin{itemize}

\item{\bf ADM} \hspace{3mm}
        evolves $\gamma_{ij}$ and $K_{ij}$ via the standard ADM equations;
        this thorn is semi-obselete, as it doesn't use the modern
        method of lines generic evolution scheme (provided by the
        \textbf{MoL} thorn in the \textbf{CactusBase} arrangement);
        it's not clear if there's any Cactus thorn which evolves the
        ADM equations using the method of lines%%%
\footnote{%%%
         The \textbf{BSSN\_MoL} thorn (in the \textbf{AEIThorns}
         arrangement) evolves the BSSN system of equations using
         the method of lines.  The BSSN system uses a reparameterization
         of the ADM variables $\gamma_{ij}$ and $K_{ij}$ and their
         evolution equations, which usually gives more stable evolutions.
         }%%%

\item{\bf ADMAnalysis} \hspace{3mm} routines run at CCTK\_ANALYSIS to compute various
quantities

\item{\bf ADMConstraints} \hspace{3mm}
        computes the $3+1$ Hamiltonian (energy) and momentum constraints

\item{\bf ADMCoupling} \hspace{3mm} allows thorns to `register' their matter field
contributions to the stress energy tensor

\item{\bf ADMMacros} \hspace{3mm}
        macros for computing various quantities which are
        commonly used in $3+1$ numerical relativity, such as
        Christoffel symbols, covariant derivatives, the Ricci tensor, etc etc;
        some of these support both 2nd and 4th~order finite differencing

\item{\bf AHFinder} \hspace{3mm}
        searches for apparent horizons%%%
\footnote{%%%
         There are also two other apparent-horizon-finder
         thorns in Cactus.  The \textbf{TAT} arrangement has the
         \textbf{TGRapparentHorizon2D} thorn, and the \textbf{AEIThorns}
         arrangement has the \textbf{AHFinderDirect} thorn.  As of
         late~2004, \textbf{AHFinderDirect} seems to be the only Cactus
         apparent horizon finder which is actively maintained, and
         most new work is using it.
         }%%%

\item{\bf CoordGauge} \hspace{3mm} manages gauge quantities

\item{\bf EvolSimple} \hspace{3mm} a demo evolution thorn

\item{\bf Extract} \hspace{3mm} `extracts' gravitational-wave waveforms

\item{\bf IDAnalyticBH} \hspace{3mm} analytic black hole initial data

\item{\bf IDAxiBrillBH} \hspace{3mm} axisymmetric Brill wave with black hole initial data

\item{\bf IDBrillData} \hspace{3mm} Brill wave initial data

\item{\bf IDLinearWaves} \hspace{3mm} linearized wave initial data

\item{\bf IDSimple} \hspace{3mm} a demo initial data thorn, provides Minkowski space with
conformal factor

\item{\bf Maximal} \hspace{3mm} maximal slicing gauge condition

\item{\bf PsiKadelia} \hspace{3mm} computes various Neumann-Penrose quantities

\item{\bf SpaceMask} \hspace{3mm} provides a `mask' for the spatial grid

\item{\bf StaticConformal} \hspace{3mm} provides for a static conformal factor

\item{\bf TimeGeodesic} \hspace{3mm} computes timelike geodesics


\end{itemize}

\section{Some Useful Thorns in Other Arrangements}

There are lots of other thorns in Cactus; some particularly useful ones
include
\begin{description}
\item[CactusBase arrangement]\mbox{}\\[-\baselineskip]
        \begin{description}
        \item[CartGrid3D]
                sets up the 3-D Cartesian grid
        \item[CoordBase]
                provides an elegant and powerful way of specifying
                the grid size and shape, including any ghost zones
        \end{description}
\item[AEIThorns arrangement]\mbox{}\\[-\baselineskip]
        \begin{description}
        \item[Exact]
                analytical solutions where the full 4-metric is known
                throughout the entire spacetime, eg.{} Schwarzschild,
                Kerr, various cosmological solutions, etc etc
        \end{description}
\end{description}

% Do not delete next line
% END CACTUS THORNGUIDE

\end{document}
% LocalWords:  QuickStart HOWTO ds dt dx CalcTmunu ADMCoupling ADMAnalysis
% LocalWords:  ADMConstraints ADMMacros AHFinder CoordGauge EvolSimple
% LocalWords:  IDAnalyticBH IDAxiBrillBH IDBrillData
