Cleanup the aliased-function interface:

* rename (delete-and-add in CVS :( ) the file which implements it from
   src/driver/horizon_radius.cc   to   src/driver/aliased_functions.cc
* fix some off-by-one errors in checking the horizon number
* add a new aliased function to allow querying of whether or not a
  given horizon was found the last time we looked for it
* all the aliased functions are now *functions* returning a status
  code (>= 0 for ok, < 0 for error), instead of subroutines before
* document the whole thing in the thorn guide (this was missing before :( )

N.b. you will need a    make YOUR_CONFIG_NAME-cleandeps
after this cvs update


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

1 files changed, 64 insertions, 2 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index cca181d..eb72a17 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -874,6 +874,7 @@ controlled by the following parameters:
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \subsection{(Excision) Mask Parameters}
+\label{AHFinderDirect/sect-parameters/mask-parameters}
 
 This thorn can optionally set a mask grid function (or functions)
 at each point of the Cactus grid, to indicate where that point is
@@ -1150,11 +1151,34 @@ to do this before \thorn{AHFinderDirect} tries to find the horizon(s).
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\subsection{Parameters for Announcing a Horizon Centroid to Other Thorns}
+\subsection{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}.
+\end{itemize}
+
+%%%%%%%%%%%%%%%%%%%%
+
+\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})
-each time that apparent horizon is found:
+each time that apparent horizon is found.  This is controlled by the
+following parameter:
 
 \begin{description}
 \item[\code{which\_horizon\_to\_announce\_centroid}]
@@ -1165,6 +1189,44 @@ each time that apparent horizon is found:
 	horizon number to have its centroid announced.
 \end{description}
 
+%%%%%%%%%%%%%%%%%%%%
+
+\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
+returns a status code which is $\ge 0$~for ok, or negative for an error.
+\begin{verbatim}
+# The following function computes the local coordinate origin
+# for the specified horizon:
+CCTK_INT FUNCTION HorizonLocalCoordinateOrigin
+   (CCTK_INT IN horizon_number,
+    CCTK_REAL OUT origin_x, CCTK_REAL OUT origin_y, CCTK_REAL OUT origin_z)
+
+# The following function queries whether or not the specified horizon
+# was found the most recent time AHFinderDirect searched for it.
+# The return value is:
+#  1 if the horizon was found
+#  0 if the horizon was not found
+#  negative for an error
+CCTK_INT FUNCTION HorizonWasFound(CCTK_INT IN horizon_number)
+
+# The following function computes the horizon radius in the
+# direction of each (x,y,z) point, or -1.0 if this horizon wasn't found
+# the most recent time AHFinderDirect searched for it.  More precisely,
+# For each (x,y,z), consider the ray from the local coordinate origin
+# through (x,y,z).  This function computes the Euclidean distance
+# between the local coordinate origin and this ray's intersection with
+# the horizon, or -1.0 if this horizon wasn't found the most recent time
+# AHFinderDirect searched for it.
+CCTK_INT FUNCTION HorizonRadiusInDirection
+   (CCTK_INT IN horizon_number,
+    CCTK_INT IN N_points,
+    CCTK_REAL IN ARRAY x, CCTK_REAL IN ARRAY y, CCTK_REAL IN ARRAY z,
+    CCTK_REAL OUT ARRAY radius)
+\end{verbatim}
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \subsection{Other Parameters}