% *======================================================================*
%  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 
%  relevent 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 sparated with a \\ or a comma
%   - You can define your own macros are OK, but they must appear after
%     the START CACTUS THORNGUIDE line, and do 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 graphix package. 
%     More specifically, with the "includegraphics" command. Do
%     not specify any graphic file extensions in your .tex file. This 
%     will allow us (later) 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{...}
%   - 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{The TAT arrangement}

% 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}
This is the TAT arrangement.  TAT is the name of my earlier home
department ``Theoretische Astrophysik T\"ubingen''.  This arrangement
contains thorns serving a variety of purposes.
\end{abstract}

\section{TAT thorns}

\begin{description}

\item[TGRPETSc]
is a wrapper for the nonlinear elliptic solver of the PETSc library.
It is the oldest, and I keep it around for compatibility.



\item[TATelliptic]
is a generic interface to nonlinear elliptic solvers.  Your thorn
calls TATelliptic, and can at run time / with parameter settings
choose between differen elliptic solvers.  I think the interface is
generic enough, so that it could be used by future solvers.  (It is
not suitable for BAM --- BAM is not modular enough.)

\item[TATPETSc]
is such a solver that interoperates with TATelliptic.  TATPETSc is the
same as TGRPETSc, except with a new interface.

\item[TATJacobi]
also uses the TATelliptic interface.  It is a Jacobi solver with an
adaptive step size, i.e.\ very slow for large grids.

\item[TATCG]
also uses the TATelliptic interface.  It is a nonlinear conjugate
gradient solver which offers diagonal preconditioning.

\item[TATMG]
is a multigrid solver which also uses the TATelliptic interface.  This
solver is rather new and not well tested.  It should be much faster
than using PETSc or a Jacobi solver.  One disadvantage of TATMG is
that you have to allocate storage for the coarser levels yourself (in
the interface.ccl file), and telling TATMG about these grid arrays
tends to turn into way too many calls to CCTK\_VarIndex.

\item[TATCactusMG]
is dead.



\item[IDScalarWavePETSc]
demonstrates how to use TGRPETSc (the outdated one) to solve an
elliptic equation for initial data.

\item[IDSWTE]
does the same, except using the new and shiny TATelliptic interface.

\item[IDSWTEF]
does again the same, except using the new and shiny TATelliptic
interface from Fortran, via C wrappers.

\item[IDSWTEsimple]
is the same as IDSWTE, except it does not contain any multigrid stuff
and is therefore much simpler.



\item[Cart3d]
is a coordinate and symmetry thorn.  It provides the same basic
functionality as CactusBase/CartGrid3D, and then some more.  The major
improvement is that this thorn offers an ``axial'' symmetry condition,
i.e.\ a 90-degree rotational symmetry as is e.g.\ needed to simulate
rotating black holes in octant mode.

\item[Cart3dTest]
contains a test suite for Cart3d.

\item[Cart3dIDScalarWave]
is a version of a Cactus WaveToy initial data thorn that uses Cart3d
instead of CartGrid3D.

\item[Cart3dWaveToyC]
is a version of the Cactus WaveToy that uses Cart3d instead of
CartGrid3D.



\item[FFTW]
provides routines for Fourier transformations.

\item[TATFourier]
also provides routines for Fourier transformations.  It is outdated.

\item[WaveToyFourierHelper]
contains an example parameter file using FFTW for the Cactus WaveToy.



\item[Slab]
provides generic slabbing facilities.  A slab is a sub-array of
another array.  Both can be multidimensional, and the slab can have a
non-unit stride.  The Slab thorn provides a routine to copy a slab
from one array into a slab of another array, while possibly
transposing or inverting the slab.  This combines get-slab and
put-slab interfaces.  The Slab thorn is driver independent, i.e.\ not
tied to PUGH or Carpet, and does not require MPI.

\item[SlabTest]
tests the Slab thorn.



\item[TGRtensor]
contains a host of useful utilities in Fortran 90.  It contains
interfaces for Cactus routines, some useful constants, generic tensor
utilities, interfaces to Lapack and BLAS, and code for numeric
derivatives, and maybe some other stuff.

\item[TGRapparentHorizon2D]
is an apparent horizon finder.  It solves the apparent horizon
equation as elliptic equation, using either a fast solver through the
TATelliptic interface, or a slow flow method.  It is much faster than
CactusEinstein/AHFinder.

\item[TGRisolatedHorizon2D]
calculates quantities of isolated horizons.  An isolated horizon is a
special case of an apparent horizon --- it is in a certain way a
``static'' apparent horizon.  This permits unique definitions of e.g.\
total mass and spin.



\item[AdvectionToy]
couples to the standard WaveToy of Cactus.  It evolves an advection
equation in a 3D grid patch, represented using Cactus arrays.  This is
an example showing how to evolve different equations in different
domains in Cactus.



\item[CheckSync]
provides a routine that checks whether grid functions are
synchronised.

\item[CheckTimestepSize]
checks whether the time step size follows the CFL criterion set by
lapse and shift.  Untested.

\item[Megaflop]
enhances the megaflop rate of an application.  Unfortunately it does
so on the expense of the total run time.  That is, while an
application runs more ``efficiently'', it also runs more slowly.

\item[NaNCatcher]
enables, on x86 processors, the FPU flag that makes a process abort as
soon as a nan is encountered.

\item[always]
provides a grid variable ``always'' that always needs output.  With
the statement ``TRIGGERS: always'', a scheduling block at the analysis
stage is always executed.

\end{description}

% Do not delete next line
% END CACTUS THORNGUIDE

\end{document}
