path: root/doc/documentation.tex

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