various clarifications,

also document move to AEIThorns and s/LocalInterp/AEILocalInterp/g


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

1 files changed, 48 insertions, 22 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index a66fba2..a341495 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -145,10 +145,12 @@ This thorn guide describes how to use the thorn.
 
 \section{Introduction}
 
-An apparent horizon (also known as a marginally trapped surface),
-is a closed 2-surface in a slice whose congruence of future-pointing
-outgoing null geodesics has zero expansion.  In terms of the usual
-$3+1$ variables, an apparent horizon satisfies the equation
+A \defn{marginally trapped surface} is a closed 2-surface in a slice whose
+congruence of future-pointing outgoing null geodesics has zero expansion.
+There may be several such surfaces, some nested inside others; an
+\defn{apparent horizon} is an outermost marginally trapped surface.
+In terms of the usual $3+1$ variables, an apparent horizon satisfies
+the equation
 \begin{equation}
 H \equiv \del_i n^i + K_\ij n^i n^j - K = 0
 					\label{AHFinderDirect/eqn-horizon}
@@ -270,10 +272,12 @@ here's what works and what doesn't:
 	which in turn uses the new \verb|CCTK_InterpLocalUniform()|
 	local interpolator API.  At present these interpolators
 	are only provided by the thorns \thorn{PUGHInterp} and
-	\thorn{LocalInterp} respectively, so you need to have
+	\thorn{AEILocalInterp} respectively, so you need to have
 	these thorns compiled into your configuration and activated.
 \item	\thorn{AHFinderDirect} works fine in single- or multi-processor
 	Cactus runs.
+\item	At present none of \thorn{AHFinderDirect}'s parameters are steerable.
+\item	At present \thorn{AHFinderDirect} doesn't work with checkpoint/restart.
 \item	\thorn{AHFinderDirect} can set an excision mask based on
 	each horizon's shape, using either the old-style (\verb|CCTK_REAL|)
 	mask (compatible with \thorn{AHFinder}) or the new-style
@@ -335,28 +339,21 @@ section~\ref{AHFinderDirect/sect-examples} should make this clear.
 \subsection{Overall Parameters}
 
 \begin{description}
-\item[%%%
-     \begin{tabular}{@{}l@{}}
-     \code{find\_AHs\_at\_postinitial}	\\
-     \code{find\_AHs\_at\_poststep}	%%%\\
-     \end{tabular}
-     ]
+\item[\code{find\_AHs}]
 \mbox{}\\
-	These are Boolean parameters specifying whether
-	\thorn{AHFinderDirect} should try to find apparent horizons
-	in the initial data (at the \code{CCTK\_POSTINITIAL} Cactus
-	schedule bin), at each time step of a time evolution
-	(at the \code{CCTK\_POSTSTEP} Cactus schedule bin),
-	or both (the default).
-
+	These is a Boolean parameters specifying whether or not
+	\thorn{AHFinderDirect} should try to find apparent horizons.
+	at each time step (at the \code{CCTK\_POSTSTEP} Cactus schedule bin).
+	By default it's \verb|true|, \ie{} you just need to activate
+	\thorn{AHFinderDirect} for it to try to find apparent horizons.
 \item[\code{N\_horizons}]
 \mbox{}\\
 	How many apparent horizons do you want to find in each slice?
 	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}
+	 limit is 10, but it would be very easy to raise this
+	 further if desired -- see the comments in \code{param.ccl}
 	 for details.
 	 }%%%
 {}	{\bf This thorn numbers the apparent horizons from 1 to\
@@ -388,7 +385,7 @@ section~\ref{AHFinderDirect/sect-examples} should make this clear.
 		Print only a line or two each time
 		\thorn{AHFinderDirect} runs, giving the
 		number of horizons found and their irreducible masses.
-		(This doesn't work yet.)
+		(This isn't implemented yet.)
 	\item[\code{"physics details"}]
 	\mbox{}\\
 		Give more detailed description of each horizon found,
@@ -1031,6 +1028,35 @@ to do this before \thorn{AHFinderDirect} tries to find the horizon(s).
 \subsection{Other Parameters}
 
 \begin{description}
+\item[%%%
+     \begin{tabular}{@{}l@{}}
+     \code{geometry\_interpolator\_name}	\\
+     \code{geometry\_interpolator\_pars}	%%%\\
+     \end{tabular}
+     ]
+\mbox{}\\
+	These parameters control the (3-D) \\defn{geometry interpolation}
+	of the spacetime geometry ($g_{ij}$ and $K_{ij}$, or their
+	\thorn{StaticConformal} equivalents) to the apparent horizon
+	position.  The defaults are set to use a cubic Hermite
+	interpolator.  This works well, but because of the interpolator
+	molecule size you must use $\verb|driver::ghost_size| \ge 3$.
+	If you want to use a smaller value of \verb|driver::ghost_size|
+	you need to use a geometry interpolator with a smaller molecule
+	size.  In particular, to use $\verb|driver::ghost_size| = 2$
+	you should use
+	\begin{verbatim}
+	AHFinderDirect::geometry_interpolator_pars = \
+ "order=2 \
+  boundary_off_centering_tolerance={1.0e-10 1.0e-10 1.0e-10 1.0e-10 1.0e-10 1.0e-10} \
+  boundary_extrapolation_tolerance={0.0 0.0 0.0 0.0 0.0 0.0}"
+	\end{verbatim}
+	\thorn{AHFinderDirect} should still work well with these
+	parameters, though the lower geometry-interpolation order
+	will slightly degrade the accuracy.  The sample parameter file
+	\verb|par/misner-ghost2-mask-noshrink.par| shows an example
+	of using these parameters.
+
 \item[\code{N\_zones\_per\_right\_angle[}$n$\code{]}]
 \mbox{}\\
 	This parameter sets the angular resolution used to compute
@@ -1101,7 +1127,7 @@ tests.  The \verb|Kerr-tiny.par| parameter file is close to a minimal
 
 # next two lines is actually one long line
 # (Cactus doesn't seem to grok \-newline continuation here :( :( )
-ActiveThorns = "CartGrid3D LocalInterp PUGH ADMBase ADMCoupling \
+ActiveThorns = "CartGrid3D AEILocalInterp PUGH ADMBase ADMCoupling \
                 StaticConformal CoordGauge Exact AHFinderDirect"
 
 # flesh