Added paragraph about status of EHFinder and Carpet. Changed labels from AEIDevelopment_* to AEIThorns_*. Updated (finally) the reference.

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

1 files changed, 42 insertions, 32 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index f8e7431..3b66c28 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -140,11 +140,11 @@ evolved according to
 g^{tt}g^{ij}\partial_{i}f\partial_{j}f}}{g^{tt}} \nonumber \\
  & = & \beta^{i}\partial_{i}f-
                 \sqrt{\alpha^{2}\gamma^{ij}\partial_{i}f\partial_{j}f},
-\label{AEIDevelopment_EHFinder_evolve}
+\label{AEIThorns_EHFinder_evolve}
 \end{eqnarray}
 where in the second equation the lapse, shift and 3-metric has been substituted
 for the 4-metric. For more details on the theory and implementation
-see~\cite{AEIDevelopment_EHFinder_Diener02}.
+see~\cite{AEIThorns_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
@@ -166,12 +166,12 @@ function is evolved backwards in time. The thorn can evolve more than one
 level set function at a time using different initial guesses for the surfaces
 (NOTE: this is a quite recent feature and has not yet been tested extensively).
 More details about the actual use of the thorn in
- section~\ref{AEIDevelopment_EHFinder_UseThorn}
+ section~\ref{AEIThorns_EHFinder_UseThorn}
 
 \section{Re-initialization}
-\label{AEIDevelopment_EHFinder_re_init}
+\label{AEIThorns_EHFinder_re_init}
 The evolution equation for $f$, 
-equation~(\ref{AEIDevelopment_EHFinder_evolve}), causes steepening of
+equation~(\ref{AEIThorns_EHFinder_evolve}), causes steepening of
 the gradient of $f$, which is undesireble numerically. For that reason, $f$
 is periodically re-initialized 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
@@ -180,7 +180,7 @@ 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}
+\label{AEIThorns_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$ surface can be
@@ -194,20 +194,20 @@ inferior to the {\tt pde}-method and was removed. Other methods may be
 implemented in the future.
 
 \section{The initial shape of the surface}
-\label{AEIDevelopment_EHFinder_initial}
+\label{AEIThorns_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}
+\label{AEIThorns_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}
+\label{AEIThorns_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$
@@ -218,14 +218,15 @@ 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}
+\label{AEIThorns_EHFinder_cassini}
 \end{equation}
 There are no translation or rotations implemented for the ovaloid of Cassini.
 
 Different initial shapes can be used for the different level set functions
 used in the same run.
 \section{Excision}
-\label{AEIDevelopment_EHFinder_excise}
+\label{AEIThorns_EHFinder_excise}
+
 Even though the level set function, $f$, in principle can be defined
 everywhere it is often advantageous to only evolve it in a certain region
 around the surface $f=0$. Since $f$ is re-initialized regularly to become
@@ -243,14 +244,14 @@ region, this might fail. To avoid a similiar problem at the outer excised
 boundary, this boundary is shaped as a rectangular box. The box is chosen
 so that all points with $f<{\mbox{\tt ehfinder::shell\_width}}$ are in the
 active region. This is illustrated in
-Figure~\ref{AEIDevelopment_EHFinder_excisefig}, for the case
+Figure~\ref{AEIThorns_EHFinder_excisefig}, for the case
 \begin{figure}[ht]
   \begin{center}
     \includegraphics[width=8cm]{excision.eps}
   \end{center}
   \caption{Illustration of the excision regions used internally by
            {\tt EHFinder}. The hashed regions are excised.}
-  \label{AEIDevelopment_EHFinder_excisefig}
+  \label{AEIThorns_EHFinder_excisefig}
 \end{figure}
 {\tt ehfinder::shell\_width = 4}, where the excised regions are hashed.
 
@@ -264,7 +265,7 @@ numerical excision region. The {\tt EHFinder} currently only supports the
 old style excision mask but the support of the new style excision mask
 should be trivial and fast to implement.
 \section{Upwinding}
-\label{AEIDevelopment_EHFinder_upwind}
+\label{AEIThorns_EHFinder_upwind}
 All finite differences used in the evolution of the null surface are second
 order one sided differences. For that reason a {\tt ghost\_size} larger or
 equal to 2 should always be used. It is possible to choose between three
@@ -275,14 +276,14 @@ different upwinding schemes. This is done by setting the parameter
 The {\tt intrinsic} scheme, looks at the values of $f$ itself, to determine
 the direction of the stencil. This is basically in order to be able to handle
 situations like the one illustrated in 1D in
-Figure~\ref{AEIDevelopment_EHFinder_upwindfig}.
+Figure~\ref{AEIThorns_EHFinder_upwindfig}.
 \begin{figure}[ht]
   \begin{center}
     \includegraphics[width=8cm]{upwind.eps}
   \end{center}
   \caption{An illustration of how to choose the upwinding stencil when $f$
            is not differntiable everywhere}
-  \label{AEIDevelopment_EHFinder_upwindfig}
+  \label{AEIThorns_EHFinder_upwindfig}
 \end{figure}
 If the stencil for calculating derivatives in the point labeled 1 is taken
 to consist of the points 1, 2 and 3', the non differentiablility of $f$ may
@@ -307,7 +308,7 @@ sided finite differences in the appropriate direction.
 
 It might happen that the upwinding direction based on the characteristic
 direction results in the stencil to consist of the points 1, 2, 3' in 
-Figure~\ref{AEIDevelopment_EHFinder_upwindfig}. However, if the 
+Figure~\ref{AEIThorns_EHFinder_upwindfig}. However, if the 
 re-initialization is done often enough, this turns out not to cause
 any problems.
 
@@ -359,31 +360,31 @@ Here the most important parameters are described.
   A vector parameter specifying the initial shape of the null surface for
   the individual level set functions. The initial shape 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}.
+  section~\ref{AEIThorns_EHFinder_initial}. The default is {\tt sphere}.
 \item {\tt initial\_rad[i]} \\
   A vector parameter specifying the radius of the initial sphere ($r_{0}$ in
-  equation~\ref{AEIDevelopment_EHFinder_sphere}). The deafault is 1.
+  equation~\ref{AEIThorns_EHFinder_sphere}). The deafault is 1.
 \item {\tt translate\_x[i]} \\
   A vector parameter specifying how much to translate the initial surface in
-  the $x$-direction ($x_{0}$ in equation~\ref{AEIDevelopment_EHFinder_sphere}).
+  the $x$-direction ($x_{0}$ in equation~\ref{AEIThorns_EHFinder_sphere}).
   Also used for the initial ellipsoid. The default is 0.
 \item {\tt translate\_y[i]} \\
   A vector parameter specifying how much to translate the initial surface in
-  the $y$-direction ($y_{0}$ in equation~\ref{AEIDevelopment_EHFinder_sphere}).
+  the $y$-direction ($y_{0}$ in equation~\ref{AEIThorns_EHFinder_sphere}).
   Also used for the initial ellipsoid. The default is 0.
 \item {\tt translate\_z[i]} \\
   A vector parameter specifying how much to translate the initial surface in
-  the $z$-direction ($z_{0}$ in equation~\ref{AEIDevelopment_EHFinder_sphere}).
+  the $z$-direction ($z_{0}$ in equation~\ref{AEIThorns_EHFinder_sphere}).
   Also used for the initial ellipsoid. The default is 0.
 \item {\tt initial\_a[i]} \\
   A vector parameter specifying $a$ in
-  equation~\ref{AEIDevelopment_EHFinder_ellipsoid}. The default is 1.
+  equation~\ref{AEIThorns_EHFinder_ellipsoid}. The default is 1.
 \item {\tt initial\_b[i]} \\
   A vector parameter specifying $b$ in
-  equation~\ref{AEIDevelopment_EHFinder_ellipsoid}. The default is 1.
+  equation~\ref{AEIThorns_EHFinder_ellipsoid}. The default is 1.
 \item {\tt initial\_c[i]} \\
   A vector parameter specifying $c$ in
-  equation~\ref{AEIDevelopment_EHFinder_ellipsoid}. The default is 1.
+  equation~\ref{AEIThorns_EHFinder_ellipsoid}. The default is 1.
 \item {\tt rotation\_alpha[i]} \\
   A vector parameter specifying the rotation angle $\alpha$ for the ellipsoid
   around the $z$-axis. The default is 0.
@@ -397,7 +398,7 @@ Here the most important parameters are described.
   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$
+  section~\ref{AEIThorns_EHFinder_excise}. The default is $7$
   gridspacings.
 \item {\tt use\_inner\_excision} \\
   A boolean parameter specifying whether the interior excision should be
@@ -408,7 +409,7 @@ Here the most important parameters are described.
 \item {\tt upwind\_type} \\
   The type of upwinding to be used (either {\tt intrinsic}, {\tt shift} or 
   {\tt characteristic}). See the detailed description of the upwinding types
-  in section~\ref{AEIDevelopment_EHFinder_upwind}. The default is 
+  in section~\ref{AEIThorns_EHFinder_upwind}. The default is 
   {\tt characteristic}.
 \item {\tt surface\_direction} \\
   The code can track both outgoing and ingoing null surfaces. Choose the 
@@ -417,7 +418,7 @@ Here the most important parameters are described.
   when evolving outward going null surfaces backwards in time.
 \item {\tt re\_init\_undo} \\
   Should the re-initialization be undone just before pinch-off or not as
-  described in section~\ref{AEIDevelopment_EHFinder_re_init}. The
+  described in section~\ref{AEIThorns_EHFinder_re_init}. The
   default is {\tt "no"}.
 \item {\tt re\_init\_int\_method} \\
   Choose the integration method in the {\tt pde}-re-initialization method.
@@ -483,7 +484,7 @@ to be able to read in initial data.
 \item {\tt admbase::initial\_shift} is extended with {\tt "read from file"}.
 \end{itemize}
 \section{How to use {\tt EHFinder} with numerical data}
-\label{AEIDevelopment_EHFinder_UseThorn}
+\label{AEIThorns_EHFinder_UseThorn}
 In this section I will try to describe in little more detail how {\tt EHFinder}
 can be used to find the EH in a numerical spacetime.
 
@@ -546,7 +547,7 @@ be completely inside the
 apparent horizon (AH). To get an initial guess that is outside of the EH
 is not as easy. One way is to choose a surface, that starts to contract
 everywhere when evolved according to
-equation~(\ref{AEIDevelopment_EHFinder_evolve}). However this is not a
+equation~(\ref{AEIThorns_EHFinder_evolve}). However this is not a
 guarantee, since the EH can be expanding in the numerical coordinates.
 This of course means that it is necessary to do it by trial and error.
 Set up some initial guess evolve it for a little while, look at 3D output
@@ -575,6 +576,13 @@ if it is not re-initialized. Good values guesses for
 low or medium resolutions but can usually be increased for higher
 resolutions. For {\tt ehfinder::shell\_width} I normally use at least 7.
 
+{\tt EHFinder} does not yet work fully with the fixed mesh refinement driver
+{\tt Carpet}, but this is under development. Currently the evolution of the
+level set function and the re-initialization works, but only with no inner
+and outer excision. The analysis routines to find areas of the surfaces does
+not work with {\tt Carpet}. Reading in metric data has not been tested with
+{\tt Carpet}.
+
 This documentation will be updated, as input comes in from users.
 
 Happy event horizon finding.
@@ -582,8 +590,10 @@ Happy event horizon finding.
 
 \begin{thebibliography}{9}
 
-\bibitem{AEIDevelopment_EHFinder_Diener02}
-   {P. Diener, {\em In preparation}, (2002)}
+\bibitem{AEIThorns_EHFinder_Diener02}
+   {Diener P., 2003, 2003, Classical and Quantum Gravity, 20, 4901--4917,
+    A New General Purpose Event Horizon Finder for 3D Numerical Spacetimes,
+    gr-qc/0305039}
 % ,
 %   1--16. {\tt http://www.nowhere.com/}}
 \end{thebibliography}