clarify wording on setting initial guess

git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinAnalysis/AHFinderDirect/trunk@873 f88db872-0e4f-0410-b76b-b9085cfa78c5

1 files changed, 31 insertions, 25 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 2295f5a..a72f8fd 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -182,7 +182,8 @@ but modified to work with $g_\ij$ and $K_\ij$ on a Cartesian ($xyz$) grid:
 
 I assume that a local coordinate origin has been chosen such that
 relative to that origin, the horizon is a \defn{Strahlk\"{o}rper}
-(``ray body''), defined by Minkowski
+(literally ``ray body'', or more commonly ``star-shaped region''),
+defined by Minkowski
 (\cite[p.~108]{AEIDevelopment_AHFinderDirect_Schroeder-1986-number-theory})
 as
    \begin{quote}
@@ -334,7 +335,7 @@ section in the top-level \code{README} file for details.
 Your Cactus configuration and run must satisfy a number of requirements
 in order to use \thorn{AHFinderDirect}:
 \begin{itemize}
-\item	You should use a current-CVS checkout of the Cactus flesh
+\item	I recommend using a current-CVS checkout of the Cactus flesh
 	and of all relevant thorns.  I haven't tested \thorn{AHFinderDirect}
 	at all with older versions of the flesh or other thorns.
 \item	Obviously, your Cactus configuration must include
@@ -342,6 +343,10 @@ in order to use \thorn{AHFinderDirect}:
 	must activate it.  \thorn{AHFinderDirect} inherits from \thorn{Grid},
 	\thorn{ADMBase}, and \thorn{StaticConformal}, so you'll need
 	those (or more precisely some thorns providing them), too.
+\item	\verb|Grid::domain = "full"|, \verb|"bitant"|,
+	\verb|"quadrant"|, and \verb|"octant"| are supported.
+	Alas, at present rotating (or more precisely nonlocal)
+	symmetry boundary conditions aren't supported.
 \item	The \verb|ADMBase::metric_type| values \verb|"physical"| and
 	\verb|"static conformal"| are supported; for the latter you must
 	have storage turned on for at least the conformal factor
@@ -360,10 +365,6 @@ in order to use \thorn{AHFinderDirect}:
 There are also some restrictions on the spacetime, or more precisely
 on each slice where you want to find apparent horizons:
 \begin{itemize}
-\item	At present rotating (or more precisely nonlocal)
-	symmetry boundary conditions aren't supported.
-	However, \verb|Grid::domain = "full"|, \verb|"bitant"|,
-	\verb|"quadrant"|, and \verb|"octant"| all work fine.
 \item	\thorn{AHFinderDirect} requires that the Cactus geometry
 	($g_{ij}$, $K_{ij}$, and optionally $\psi$) be nonsingular
 	in a neighborhood of the apparent horizon.  In particular,
@@ -444,11 +445,15 @@ examples in section~\ref{AEIDevelopment_AHFinderDirect_sect-examples}.
 \item[\code{N\_horizons}]
 \mbox{}\\
 	How many apparent horizons do you want to find in each slice?
-	Typical values are 1 (the default), 2 (for binary black hole systems),
-	and 3 (for binary black hole systems where you expect to evolve
-	long enough to also see a common apparent horizon).  This thorn
-	numbers the apparent horizons from 1 to \code{N\_horizons} inclusive.
-	There are a number of other parameters (described below)
+	Typical values are 1 (the default), 2, or 3.%%%
+\footnote{%%%
+	 Larger values are also possible.  The present upper
+	 limit is 4, but it would be very easy to raise this
+	 if desired -- see the comments in \code{param.ccl}
+	 for details.
+	 }%%%
+{}	This thorn numbers the apparent horizons from 1 to \code{N\_horizons}
+	inclusive.  There are a number of other parameters (described below)
 	which you need to set for of these each apparent horizons.
 
 	Note that \code{N\_horizons} sets the number of apparent horizons
@@ -456,13 +461,12 @@ examples in section~\ref{AEIDevelopment_AHFinderDirect_sect-examples}.
 	the whole spacetime.  For example, if you are simulating (say)
 	Misner data with \verb|Grid::domain = "bitant"|, with the two
 	throats at (say) roughly $z = \pm 1$, then you should set
-	\verb|N_horizons = 1|, since you're only finding a single
-	apparent horizon within the numerical grid.  Similarly,
-	to evolve such a slice to a final near-static state with a
-	common horizon centered on the origin, you should set
-	\verb|N_horizons = 2|, since you're finding at most 2
-	apparent horizons within the numerical grid (the initial-slice
-	one centered near $z = +1$ and the final common one).
+	\verb|N_horizons = 1| to find those two apparent horizons,
+	since you're only finding one apparent horizon within the
+	numerical grid.  If you also want to search for a common
+	apparent horizon surrounding both black holes, then you should
+	set \verb|N_horizons = 2|, since you're finding at most 2
+	apparent horizons within the numerical grid.
 \item[\code{verbose\_level}]
 \mbox{}\\
 	This controls how verbose this thorn is in printing
@@ -544,13 +548,15 @@ I hope to add such a provision soon.%%%
 for the apparent horizon's coordinate position and shape
 (that is, for the $h(\text{angle})$ function defined in
 section~\ref{AEIDevelopment_AHFinderDirect_sect-how-ahfinderdirect-works})
-for each apparent horizon you want to find.  If there really is an
-apparent horizon present, and this initial guess is within some radius
-of convergence (typically on the order of 1/2 of the horizon radius)
-of the apparent horizon, then this thorn will probably find the
-apparent horizon.  If not, then this thorn will fail to converge;
-there's no way to distinguish this case from the one where there's
-actually no apparent horizon present.
+for each apparent horizon you want to find.  Unlike some other apparent
+horizon finders (\eg{}~the curvature flow method in \thorn{AHFinder}),
+for \thorn{AHFinderDirect} there's no restriction on whether the initial
+guess is inside, outside, or crossing the actual apparent horizon: the
+only important thing is that it should be ``close''.  Just how close
+the initial guess needs to be for \thorn{AHFinderDirect} to find the
+(a) apparent horizon depends on the slice and the coordinates, but as
+a general rule of thumb any initial guess that's within 1/3 to 1/2 of
+the mean horizon radius will probably work.
 
 The ``initial guess'' specification is used the first time we try to
 find any given apparent horizon, and also any succeeding time when the