* add interface to Erik's SphericalSurface thorn

  ==> With this commit, AHFinderDirect now inherits from
      AEIThorns/SphericalSurface, so you must have that thorn in
      your configuration to be able to compile.
* add computation of surface quadrupole moments and areal radius
* expand BH_diagnostics file format to accomodate quadrupole moments
  and areal radius, and also to include not-implemented-yet columns
  for 9 more diagnostics which Erik has implemented in his branch
* some other small cleanups


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

1 files changed, 112 insertions, 37 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 5c3709a..616545d 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -106,7 +106,7 @@
 \def\defn#1{``#1''}			% definition of a term
 \def\arrangement#1{{\bf #1}}		% name of an arrangement
 \def\thorn#1{{\bf #1}}			% name of a thorn
-\def\cvsplace#1{{\bf #1}}		% name of a CVS repository/directory
+\def\cvsplace#1{{\bf #1}}		% name of a CVS repository/directory/tag
 \def\cf{\hbox{cf.\hbox{}}}
 \def\eg{\hbox{eg.\hbox{}}}
 \def\ie{\hbox{i.e.\hbox{}}}
@@ -254,13 +254,42 @@ here's what works and what doesn't:
 \item	\thorn{AHFinderDirect} works fine with the \thorn{PUGH} unigrid
 	driver and with the \thorn{Carpet} mesh-refinement driver.  So
 	far as I know it's never been tested with any other driver.
+\item	\thorn{AHFinderDirect} works fine in single- or multi-processor
+	Cactus runs.
 \item	Obviously, your Cactus configuration must include
 	\thorn{AHFinderDirect}, and your \code{ActiveThorns} parameter(s)
-	must activate it.  \thorn{AHFinderDirect} inherits from
-	\thorn{Grid}, \thorn{ADMBase}, \thorn{StaticConformal}, 
-	\thorn{SpaceMask}, and \thorn{IO}, so you'll need those
-	(or more precisely some thorns providing them),
+	must activate it.
+\item	\thorn{AHFinderDirect} inherits from the other thorns
+	(strictly speaking, implementations) listed in
+	table~\ref{AEIThorns/AHFinderDirect/tab-inherits-from},
+	so you'll need them (or more precisely some thorns providing them)
 	in your configuration and activated, too.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\begin{table}[tbp]
+\begin{center}
+\begin{tabular}{l@{\qquad}l}
+\thorn{Implementation}		& Typically provided by \thorn{Thorn}	\\
+\hline %---------------------------------------------------------------
+\thorn{Grid}			& \thorn{CactusBase/CartGrid3d}		\\
+\thorn{IO}			& \thorn{CactusBase/IOUtil}		\\
+\thorn{ADMBase}			& \thorn{CactusEinstein/ADMBase}	\\
+\thorn{StaticConformal}		& \thorn{CactusEinstein/StaticConformal}\\
+\thorn{SpaceMask}		& \thorn{CactusEinstein/SpaceMask}	\\
+\thorn{SphericalSurface}	& \thorn{AEIThorns/SphericalSurface}	%%%\\
+\end{tabular}
+\end{center}
+\caption[Other Thorns from which \thorn{AHFinderDirect} Inherits]
+	{
+	This table lists all the other implementations from which
+	\thorn{AHFinderDirect} inherits, and the thorns which typically
+	provide these implementations.
+	}
+\label{AEIThorns/AHFinderDirect/tab-inherits-from}
+\end{table}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
 \item	\verb|Grid::domain = "full"|, \verb|"bitant"|,
 	\verb|"quadrant"|, and \verb|"octant"| are supported.
 	Alas, at present rotating (or more precisely nonlocal)
@@ -280,8 +309,6 @@ here's what works and what doesn't:
 	in this API which at present are only supported by thorn
 	\thorn{AEILocalInterp} (so you must have this thorn compiled in
 	and activated)
-\item	\thorn{AHFinderDirect} works fine in single- or multi-processor
-	Cactus runs.
 \item	\thorn{AHFinderDirect} uses various Cactus reduction APIs to
 	coordinate multi-processor horizon finding, so (even if you're
 	only going to run on a single processor) you must have a reduction
@@ -297,18 +324,12 @@ here's what works and what doesn't:
 	files.  This is a bug, which I plan to fix soon (the right behavior
 	is/will be to {\em append\/} to the existing \verb|BH_diagnostics|
 	file).
-\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
-	(\verb|CCTK_INT|) mask bit-fields defined by \thorn{SpaceMask}
-	(or even both simultaneously).
-\item	\thorn{AHFinderDirect} can notify \thorn{DriftCorrect} about
-	a selected horizon's centroid position, for use in adjusting
-	corotating shift vectors.  This uses the new function-aliasing
-	version of \thorn{DriftCorrect}, not the old version which
-	worked with an auxiliary thorn \thorn{AHFSetDCCentroid}.
 \end{itemize}
 
+\thorn{AHFinderDirect} can pass information to the rest of Cactus in
+several ways; these are described in detail in
+section~\ref{AHFinderDirect/sect-parameters/communicating-with-other-thorns}.
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Obtaining and Compiling \thorn{AHFinderDirect}}
@@ -777,7 +798,8 @@ to data files:
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\subsection{Other I/O Parameters}
+\subsection{Parameters for the ``BH\_diagnostics'' Files}
+\label{AHFinderDirect/sect-parameters/BH-diagnostics-parameters}
 
 As well as the apparent horizon shape files, this thorn can also
 write files giving time series of various diagnostics.  These are
@@ -845,6 +867,8 @@ controlled by the following parameters:
 		\item	the proper area of the apparent horizon, $A$
 		\item	the irreducible mass of the apparent horizon,
 			$\sqrt{A/16\pi}$
+		\item	the areal radius of the apparent horizon,
+			$\sqrt{A/4\pi}$
 		\end{itemize}
 	\end{itemize}
 
@@ -1148,28 +1172,40 @@ to do this before \thorn{AHFinderDirect} tries to find the horizon(s).
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \subsection{Communicating with Other Thorns}
+\label{AHFinderDirect/sect-parameters/communicating-with-other-thorns}
 
 Besides the data files it writes, \thorn{AHFinderDirect} currently
 has three ways to communicate with other Cactus thorns:
 \begin{itemize}
-\item	It can set a mask grid function(s), which can be used
-	for excision or other purposes.  This is described in
-	section~\ref{AHFinderDirect/sect-parameters/mask-parameters}.
-\item	It can announce the horizon centroid to a some other
-	thorn (typicaly \thorn{DriftCorrect}) using a
-	function-aliasing mechanism; this is described below;
-	this is described in
-	section~\ref{AHFinderDirect/sect-parameters/communicating-with-other-thorns/announcing-centroid}.
-\item	It provides a set of aliased functions which any other
-	thorn(s) can call to find out the shape of a specified horizon;
-	this is described in
-	section~\ref{AHFinderDirect/sect-parameters/communicating-with-other-thorns/horizon-shape-functions}.
+\item	\thorn{AHFinderDirect} can set a mask grid function(s) based
+	on the (a) horizon's shape; other thorns may then use this for
+	excision or other purposes.  \thorn{AHFinderDirect} supports
+	both the old-style (\verb|CCTK_REAL|) mask
+	(compatible with \thorn{AHFinder}) or
+	the new-style (\verb|CCTK_INT|) mask bit-fields defined by
+	\thorn{SpaceMask}; you can even use both styles simultaneously.
+\item	\thorn{AHFinderDirect} can announce a selected horizon's centroid
+	position to another thorn (typically \thorn{DriftCorrect}, which
+	uses this to adjust its corotating shift vector).
+	This uses the new function-aliasing version of \thorn{DriftCorrect},
+	not the old version which worked with an auxiliary thorn
+	\thorn{AHFSetDCCentroid}.
+\item	\thorn{AHFinderDirect} provides a set of aliased functions
+	which any other thorn(s) can call to find out the shape of
+	a specified horizon.
+\item	\thorn{AHFinderDirect} can store information about the
+	horizon(s) it finds in the \thorn{SphericalSurface} variables
+	for other thorns to use.
 \end{itemize}
 
+\thorn{AHFinderDirect}'s mask features are described in
+section~\ref{AHFinderDirect/sect-parameters/mask-parameters};
+the other communication mechanisms are described in the following
+subsections.
+
 %%%%%%%%%%%%%%%%%%%%
 
 \subsubsection{Parameters for Announcing a Horizon Centroid to Other Thorns}
-\label{AHFinderDirect/sect-parameters/communicating-with-other-thorns/announcing-centroid}
 
 This thorn can optionally announce the centroid of a specified
 apparent horizon to another thorn (typically \thorn{DriftCorrect})
@@ -1188,7 +1224,6 @@ following parameter:
 %%%%%%%%%%%%%%%%%%%%
 
 \subsubsection{Aliased Functions to Provide Horizon-Shape Information}
-\label{AHFinderDirect/sect-parameters/communicating-with-other-thorns/horizon-shape-functions}
 
 \thorn{AHFinderDirect} provides the following aliased functions
 to allow other thorns to find out about the horizons.  Each function
@@ -1223,6 +1258,29 @@ CCTK_INT FUNCTION HorizonRadiusInDirection
     CCTK_REAL OUT ARRAY radius)
 \end{verbatim}
 
+%%%%%%%%%%%%%%%%%%%%
+
+\subsubsection{Storing Horizon-Shape Information in the \thorn{SphericalSurface} Variables}
+
+\thorn{SphericalSurface} (in the \thorn{AEIThorns} arrangement)
+defines a set of generic grid arrays which describe ``spherical surfaces''.
+\thorn{AHFinderDirect} can optionally store information about the
+horizons it finds in the \thorn{SphericalSurface} variables.
+This is controlled by the following parameters:
+\begin{description}
+\item[\code{which\_surface\_to\_store\_info[}$n$\code{]}]
+\mbox{}\\
+	This parameter should be set to the \thorn{SphericalSurface}
+	surface number into which information on a given \thorn{AHFinderDirect}
+	horizon should be stored, or to -1 to skip storing the information.
+	It defaults to -1 for each horizon.
+
+	At present, if multiple \thorn{AHFinderDirect} horizons
+	specify the same \thorn{SphericalSurface} surface, the
+	highest-numbered horizon will ``win'', \ie{} it will overwrite
+	the data from any lower-numbered horizons.
+\end{description}
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \subsection{Other Parameters}
@@ -1344,6 +1402,7 @@ CCTK_INT FUNCTION HorizonRadiusInDirection
 	in an Eddington-Finkelsteon slice of the unit-mass
 	Schwarzschild spacetime.
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \begin{figure}[htbp]
 \begin{center}
 \includegraphics{AEIThorns_AHFinderDirect_Schw_EF_Theta_of_r.eps}
@@ -1358,6 +1417,7 @@ CCTK_INT FUNCTION HorizonRadiusInDirection
 	}
 \label{AHFinderDirect/fig-Schwarzschild-EF-Theta(r)}
 \end{figure}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \end{description}
 
@@ -1370,7 +1430,7 @@ is doing during a Cactus run: the \verb|BH_diagnostics| files and the
 \verb|CCTK_INFO| messages written to the Cactus standard output:
 
 The \verb|BH_diagnostics| files are described in detail in
-section~\ref{AHFinderDirect/sect-parameters/other-parameters}.
+section~\ref{AHFinderDirect/sect-parameters/BH-diagnostics-parameters}.
 These files are written and ``flushed'' at each time step, so they're
 always up-to-date.
 
@@ -1682,9 +1742,19 @@ interested in some other related thorns:
 \item[\thorn{TGRapparentHorizon2D}] (in the \arrangement{TAT} arrangement)
 	was written by Erik Schnetter, and is another apparent horizon
 	finder.  It uses methods very similar to this thorn, and (like
-	this thorn) is very fast and accurate.  It's described in detail
-	in the papers~\cite{AEIThorns/AHFinderDirect/Schnetter02a}
+	this thorn) is very fast and accurate.  However, it's no longer
+	under active development.  It's described in detail in the
+	papers~\cite{AEIThorns/AHFinderDirect/Schnetter02a}
 	and~\cite{AEIThorns/AHFinderDirect/Schnetter03a}.
+\item[\thorn{AHFinderDirect} (\cvsplace{Erik} branch)]
+      (in the \arrangement{AEIThorns} arrangement)\\
+	Erik Schnetter has added a number of new features to
+	\thorn{AHFinderDirect} on a CVS branch with the tag \cvsplace{Erik},
+	including horizon pretracking (to locate places where horizons
+	are about to form), and the ability to find constant-expansion
+	and constant-mean-curvature surfaces specified by their areal radius.
+	We hope to integrate these into the main \thorn{AHFinderDirect}
+	branch during the summer of 2004.
 \end{description}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -1692,8 +1762,13 @@ interested in some other related thorns:
 \section{Acknowledgments}
 
 I thank Peter Diener, Ian Hawke, and Erik Schnetter for many valuable
-conversations, to Thomas Radke for his work on the new interpolators,
-and the whole Cactus crew for a great infrastructure!
+conversations.  I think Thomas Radke for his work on the new interpolators.
+I thank the whole Cactus crew for a great infrastructure!
+
+Erik Schnetter originally implemented a number of improvements to
+this thorn, notably the \thorn{SphericalSurface} interface and the
+new features in the \cvsplace{Erik} branch.
+
 I thank the Alexander von Humboldt foundation and the AEI visitors'
 and postdoctoral fellowships programs for financial support.