First attempt on the documentation of the EHFinder. Descriptions of most

of the parameters are in there. Still missing is a description of practical
usage.


git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinAnalysis/EHFinder/trunk@68 2a26948c-0e4f-0410-aee8-f1d3e353619c

1 files changed, 362 insertions, 0 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
new file mode 100644
index 0000000..697e670
--- /dev/null
+++ b/doc/documentation.tex
@@ -0,0 +1,362 @@
+% *======================================================================*
+%  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
+%       % BEGIN 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 BEGIN 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/ThornGuide/cactus}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{document}
+
+\author{Original code and documentation by Peter Diener}
+
+% The title of the document (not necessarily the name of the Thorn)
+\title{Thorn Guide for the {\bf EHFinder} Thorn}
+
+% the date your document was last changed, if your document is in CVS, 
+% please us:
+%    \date{$ $Date$ $}
+\date{$ $Date$ $}
+
+\maketitle
+
+% Do not delete next line
+% START CACTUS THORNGUIDE
+
+% Add all definitions used in this documentation here 
+%   \def\mydef etc
+
+% force a line break in a itemize/description/enumerate environment
+\def\forcelinebreak{\mbox{}\\[-\baselineskip]}
+
+\def\defn#1{{\bf #1}}
+
+\def\eg{e.g.\hbox{}}
+\def\ie{i.e.\hbox{}}
+\def\etal{{\it et~al.\/\hbox{}}}
+\def\nb{n.b.\hbox{}}
+\def\Nb{N.b.\hbox{}}
+
+% math stuff
+\def\diag{\text{diag}}
+\def\Gaussian{{\sf G}}
+\def\half{{\textstyle \frac{1}{2}}}
+\def\sech{\text{sech}}
+
+% Add an abstract for this thorn's documentation
+\begin{abstract}
+This thorn locates the Event Horizon (EH) in an analytic or numerical spacetime
+by evolving a null surface backwards in time. The null surface is described at
+each time step as the 0-level iso-surface of a 3D scalar function $f$. This
+level set description of the surface allows, trivially, changes of the topology
+of the surface so it is possible to follow the merger of two (or more) black
+holes into a final black hole. 
+
+\end{abstract}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Introduction}
+This thorn attempts to locate the Event Horizon (EH) in an analytic or 
+numerical spacetime by evolving a null surface backwards in time. This
+method depends on the fact that, except in cases where the coordinate are
+adapted to outgoing null geodesics, an outgoing null surface started close
+to the EH, when evolved forward in time, is diverging exponentially from the
+EH. Reversing the time evolutions then means that an outgoing null surface
+will converge exponentially to the EH. The level set function, $f$, is
+evolved according to
+\begin{equation}
+\partial_{t}f = \frac{-g^{ti}\partial_{i}f+\sqrt{(g^{ti}\partial_{i}f)^{2}-
+g^{tt}g^{ij}\partial_{i}f\partial_{j}f}}{g^{tt}}.
+\label{AEIDevelopment_EHFinder_evolve}
+\end{equation}
+For more details on the theory and implementation 
+see~\cite{AEIDevelopment_EHFinder_Diener02}. 
+
+This thorn uses a level set description of the null surface, \ie the surface
+is the 0-level isosurface of a 3D scalar function, $f$, that is negative 
+inside and positive outside the surface. With this choice of surface 
+description one level-set function can describe multiple surfaces at the
+same time, simply by having several, disconnected regions with negative
+values. The biggest advantage, however, is that any change of topology of
+the surface is handled naturally and simply by the level-set function 
+changing sign. Therefore this EHFinder can follow the EH during the
+merger of two (or more) black holes into one black hole.
+
+To find the EH in a numerical spacetime several points have to be taken into
+consideration. Since the null surface has to be evolved backwards in time, the
+EHFinder has to be seen as a pre-processing analysis thorn. Therefore it
+is necessary to evolve the initial data forward in time while outputting
+enough 3D data, that the full 4-metric can be recovered at each timestep.
+The 3D data is then read back in, in reverse order, while the level-set
+function is evolved backwards in time. More details about the actual use
+of the thorn in section~\ref{AEIDevelopment_EHFinder_UseThorn}
+
+\section{Re-parametrization}
+\label{AEIDevelopment_EHFinder_reparam}
+The evolution equation for $f$, 
+equation~(\ref{AEIDevelopment_EHFinder_evolve}), causes steepening of
+the gradient of $f$, which is undesireble numerically. For that reason, $f$
+is periodically re-parametrized to a distance function. That is, the values of
+$f$ are changed so that the the value of $f$ in a grid point is equal to the
+(signed) distance from the grid point to the surface $f=0$. This is done by
+evolving $f$ according to the following evolution equation (in the parameter
+$\lambda$)
+\begin{equation}
+\frac{df}{d\lambda} = -\frac{f}{\sqrt{f^{2}+1}}\left (|\nabla f|-1\right ).
+\label{AEIDevelopment_EHFinder_reinit}
+\end{equation}
+until a steady state is achieved. This method is called the {\tt pde}-method
+since it is basically evolving a pde. Sometimes the $f=0$ can be moved
+slightly during the re-parametrization procedure. This happens when
+the surface develops a narrow neck just before a topology change. For
+that reason, there is an option to detect when this is about to happen and
+undo the re-parametrization.
+
+There is also another approximate way of performing the re-parametrization, 
+however, even though it is faster, it is not recommended for use, since it
+seems to cause some instabilities and may cause larger movements of the $f=0$
+surface. This method is called {\tt approx}.
+
+The two methods can be mixed, but it is not clear how well this works before
+some more experiments have been done. 
+
+\section{The initial shape of the surface}
+\label{AEIDevelopment_EHFinder_initial}
+Currently three different choices for the initial shape of the surface are
+implemented. The simplest choice is a sphere in which case $f$ is set
+according to
+\begin{equation}
+f = \sqrt{(x-x_{0})^2+(y-y_{0})^2+(z-z_{0})^2} - r_{0},
+\label{AEIDevelopment_EHFinder_sphere}
+\end{equation}
+where $r_{0}$ is the radius of the sphere and $x_{0}$, $y_{0}$ and $z_{0}$
+are the coordinates of the center of the sphere. The second choice is a rotated
+and translated ellipsoid. The basic equation is here
+\begin{equation}
+f = \sqrt{\frac{x^{2}}{a^{2}}+\frac{y^{2}}{b^{2}}+\frac{z^{2}}{c^{2}}} - 1
+\label{AEIDevelopment_EHFinder_ellipsoid}
+\end{equation}
+This ellipsoid is first rotated an angle $\alpha$ around the $z$-axis, then
+rotated an angle $\beta$ around the $y$-axis, then rotated an angle $\gamma$
+around the $x$-axis and finally the rotated ellipsoid is translated to have
+its ``center'' at the point $(x_{0},y_{0},z_{0})$. The final possible shape
+of the initial surface is an ovaloid of Cassini. This was implented initially
+to test changing the topology in flat space. it is most likely not useful for
+numerical data. In this case $f$ is set according to
+\begin{equation}
+f = (x^{2}+y^{2}+z^{2})^{2} + a^{4} - 2 a^{2} (x^{2}-y^{2}-z^{2})-b^{4}.
+\label{AEIDevelopment_EHFinder_cassini}
+\end{equation}
+There are no translation or rotations implemented for the ovaloid of Cassini.
+
+\section{Excision}
+\label{AEIDevelopment_EHFinder_excise}
+
+\section{Upwinding}
+\label{AEIDevelopment_EHFinder_upwind}
+
+\section{The most important parameters}
+Here the most important parameters are described.
+\begin{itemize}
+\item {\tt ehfinder::mode} \\  
+  The mode can either be set to {\tt normal} (normal event horizon finder mode)
+  or {\tt test\_reparam} (mode to test the re-parametrization routine). The
+  default is {\tt normal} and should normally not be changed. This parameter
+  may be removed in the future.
+\item {\tt ehfinder::eh\_metric\_type} \\
+  The metric type can either be set to {\tt numerical} or {\tt analytic}. If 
+  it is set to {\tt numerical} the EHFinder will attempt to read in the
+  metric from files in the directory specified by the {\tt io::recover\_dir}
+  parameter. At present all the timesteps has to be saved in the same file.
+  Note that if the numerical data was produced with 
+  {\tt admbase::metric\_type = "static conformal"} this parameter has to be
+  specified again. In this case the EHFinder will attempt to also read in the
+  conformal factor from a file.
+  If metric type is set to {\tt analytic} another thorn needs to set up the
+  metric. It is possible to only set the metric on the initial slice, but it
+  is also possible to have a thorn (like thorn {\tt Exact}) set the metric at 
+  {\tt CCTK\_PRESTEP} if the analytic metric is time dependent.
+  The default is at present {\tt analytic}. This should probably be changed.
+\item {\tt ehfinder::eh\_lapse\_type} \\
+  The same for the lapse. 
+\item {\tt ehfinder::eh\_shift\_type} \\
+  The same for the shift. 
+\item {\tt initial\_f} \\
+  The initial shape of the null surface can currently be chosen from 
+  {\tt sphere}, {\tt ellipsoid} and {\tt cassini} as described in 
+  section~\ref{AEIDevelopment_EHFinder_initial}. The default is {\tt sphere}.
+\item {\tt initial\_rad} \\
+  The radius of the initial sphere ($r_{0}$ in 
+  equation~\ref{AEIDevelopment_EHFinder_sphere}). The deafault is 1.
+\item {\tt translate\_x} \\
+  How much to translate the initial surface in the $x$-direction ($x_{0}$ in
+  equation~\ref{AEIDevelopment_EHFinder_sphere}). Also used for the initial
+  ellipsoid. The default is 0.
+\item {\tt translate\_y} \\
+  How much to translate the initial surface in the $y$-direction ($y_{0}$ in
+  equation~\ref{AEIDevelopment_EHFinder_sphere}). Also used for the initial
+  ellipsoid. The default is 0.
+\item {\tt translate\_z} \\
+  How much to translate the initial surface in the $z$-direction ($z_{0}$ in
+  equation~\ref{AEIDevelopment_EHFinder_sphere}). Also used for the initial
+  ellipsoid. The default is 0.
+\item {\tt initial\_a} \\
+  $a$ in equation~\ref{AEIDevelopment_EHFinder_ellipsoid}. The default is 1.
+\item {\tt initial\_b} \\
+  $b$ in equation~\ref{AEIDevelopment_EHFinder_ellipsoid}. The default is 1.
+\item {\tt initial\_c} \\
+  $c$ in equation~\ref{AEIDevelopment_EHFinder_ellipsoid}. The default is 1.
+\item {\tt rotation\_alpha} \\
+  Rotation angle $\alpha$ for the ellipsoid around the $z$-axis. The default
+  is 0.
+\item {\tt rotation\_beta} \\
+  Rotation angle $\beta$ for the ellipsoid around the $y$-axis. The default
+  is 0.
+\item {\tt rotation\_gamma} \\
+  Rotation angle $\gamma$ for the ellipsoid around the $x$-axis. The default
+  is 0.
+\item {\tt shell\_width} \\
+  The width of the active evolution region. Grid points more than 
+  {\tt shell\_width} gridspacings away from the $f=0$ surface are marked
+  as inactive and are not evolved as described in 
+  section~\ref{AEIDevelopment_EHFinder_excise}. The default is $7$
+  gridspacings.
+\item {\tt upwind\_type} \\
+  The type of upwinding to be used (either {\tt intrinsic} or {\tt shift}). See
+  the detailed description of the upwinding types in 
+  section~\ref{AEIDevelopment_EHFinder_upwind}. The default is {\tt intrinsic}.
+\item {\tt reparam\_undo} \\
+  Should the re-parametrization be undone just before pinch-off or not as 
+  described in section~\ref{AEIDevelopment_EHFinder_reparam}. The
+  default is {\tt "no"}.
+\item {\tt re\_param\_method} \\
+  Choose the re-parametrization method. The choices are {\tt approx},
+  {\tt pde} or {\tt mixed}. As described in 
+  section~\ref{AEIDevelopment_EHFinder_reparam} the recommended method is 
+  {\tt pde}. Only use {\tt approx} if you really know what you are doing. The
+  default is {\tt pde}.
+\item {\tt re\_param\_int\_method} \\
+  Choose the integration method in the {\tt pde}-re-parametrization method.
+  Choose either a simple Euler ({\tt euler}) integration scheme or a second
+  order Runge-Kutta ({\tt rk2}) scheme. Since a pde is evolved to steady state,
+  it seems that the Euler scheme works just fine and is faster than the
+  Runge-Kutta scheme. The default is {\tt euler}.
+\item {\tt re\_param\_max\_iter} \\
+  The maximum number of iterations in the {\tt pde}-re-parametrization scheme,
+  before giving up. Unless you are working at high resolution the default
+  should be enough. The default is 800.
+\item {\tt pde\_differences} \\
+  Choose the type of finite differencing used in the {\tt pde} 
+  re-parametrization. Don't ever use anything else than second order
+  uwinding ({\tt upwind2}). The other choices ({\tt centered} and {\tt upwind})
+  are there only for testing purposes and might be removed.
+\item {\tt reparametrize\_every\_pde} \\
+  How often to re-parametrize using the {\tt pde} re-parametrization. This
+  depends on the problem. For some problems it is necessary to do it more
+  often than for other problems. You'll have to experiment to figure out
+  what works best. The default (too high) is 100.
+\item {\tt reparametrize\_every\_approx} \\
+  How often to re-parametrize using the {\tt approx} re-parametrization.
+  Again it depends on the problem. Can be used together with 
+  {\tt reparametrize\_every\_pde} if {\tt re\_param\_method} is set to
+  {\tt mixed}. The default is 10.
+\item {\tt last\_iteration\_number} The last iteration number of the numerical
+  simulation that produced the metric data. Active when {\tt eh\_metric\_type}
+  is equal to {\tt numerical}. This is used in the code to figure out which
+  data set iteration number to read in from file 
+  ({\tt last\_iteration\_number-cctk\_iteration}).
+\end{itemize}
+EHFinder also extends the following parameter from {\tt admbase} in order
+to be able to read in initial data.
+\begin{itemize}
+\item {\tt admbase::initial\_data} is extended with {\tt "read from file"}.
+\item {\tt admbase::initial\_lapse} is extended with {\tt "read from file"}.
+\item {\tt admbase::initial\_shift} is extended with {\tt "read from file"}.
+\end{itemize}
+\section{How to use with numerical data} 
+\label{AEIDevelopment_EHFinder_UseThorn}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{thebibliography}{9}
+
+\bibitem{AEIDevelopment_EHFinder_Diener02}
+   {P. Diener, {\em AEI preprint}, (2002),
+   1--16. {\tt http://www.nowhere.com/}}
+\end{thebibliography}
+
+% Do not delete next line
+% END CACTUS THORNGUIDE
+
+\end{document}