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

5 files changed, 203 insertions, 48 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}
diff --git a/interface.ccl b/interface.ccl
index 83cc539..2dbaa97 100644
--- a/interface.ccl
+++ b/interface.ccl
@@ -4,39 +4,65 @@
 implements: AHFinderDirect
 inherits: Grid ADMBase StaticConformal SpaceMask IO always
 
-# include file provided by SpaceMask
+# we use an include file provided by SpaceMask
 USES INCLUDE: SpaceMask.h
 
-# provides aliased functions for various other thorns
-# FIXME: this really belongs in Erik Schnetter's "generic surface" thorn
-# ... returns local coordinate origin for a given horizon
-SUBROUTINE HorizonLocalCoordinateOrigin					\
-	(CCTK_INT IN horizon_number,					\
-	 CCTK_REAL OUT origin_x, CCTK_REAL OUT origin_y, CCTK_REAL OUT origin_z)
-# ... computes horizon radius in the direction of each (x,y,z) point,
-#     or -1.0 if this horizon wasn't found
-# ... 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 last time we searched for it.
-SUBROUTINE 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)
+################################################################################
+
+# we use an aliased function maybe provided by DriftCorrect
+SUBROUTINE SetDriftCorrectPosition					\
+   (CCTK_POINTER IN GH,							\
+    CCTK_REAL IN x, CCTK_REAL IN y, CCTK_REAL IN z)
+USES FUNCTION SetDriftCorrectPosition
+
+################################################################################
+
+#
+# This thorn provides an aliased-function interface which other thorns
+# can use to find out about the horizons.  Each function returns a status
+# code which is >= 0 for ok, or < 0 for an error.
+#
+
+########################################
+
+# This function returns the local coordinate origin for a given 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)
+
+########################################
+
+# all these functions are in src/driver/aliased_functions.cc
 PROVIDES FUNCTION HorizonLocalCoordinateOrigin				\
 	WITH AHFinderDirect_local_coordinate_origin			\
 	LANGUAGE C
+PROVIDES FUNCTION HorizonWasFound					\
+	WITH AHFinderDirect_horizon_was_found				\
+	LANGUAGE C
 PROVIDES FUNCTION HorizonRadiusInDirection				\
 	WITH AHFinderDirect_radius_in_direction				\
 	LANGUAGE C
 
-# uses aliased function maybe provided by DriftCorrect
-SUBROUTINE SetDriftCorrectPosition(CCTK_POINTER IN GH, CCTK_REAL IN x,	\
-						       CCTK_REAL IN y,	\
-						       CCTK_REAL IN z)
-USES FUNCTION SetDriftCorrectPosition
-
 ################################################################################
diff --git a/src/driver/horizon_radius.cc b/src/driver/aliased_functions.cc
index a5982b6..b3ea530 100644
--- a/src/driver/horizon_radius.cc
+++ b/src/driver/aliased_functions.cc
@@ -3,6 +3,7 @@
 //
 // <<<access to persistent data>>>
 // AHFinderDirect_local_coordinate_origin - provide our local coordinate origin
+// AHFinderDirect_horizon_was_found - query if a given horizon was found
 // AHFinderDirect_radius_in_direction - provide r(angle) function
 //
 
@@ -14,6 +15,7 @@
 #include "cctk.h"
 #include "cctk_Arguments.h"
 #include "cctk_Parameters.h"
+#include "cctk_Functions.h"
 
 #include "config.h"
 #include "stdc.h"
@@ -55,22 +57,28 @@ extern struct state state;
 //******************************************************************************
 
 //
-// This function is called (via the magic of function aliasing) by
-// other thorns to find out our local coordinate origin for a given AH.
+// This function is called (via the Cactus flesh function-aliasing mechanism)
+// by other thorns to find out our local coordinate origin for a given AH.
+//
+// Results:
+// This function returns 0 for ok, or -1 if the horizon number is invalid.
 //
 extern "C"
-  void AHFinderDirect_local_coordinate_origin
-     (CCTK_INT horizon_number,
-      CCTK_REAL* origin_x_ptr, CCTK_REAL* origin_y_ptr, CCTK_REAL* origin_z_ptr)
+  CCTK_INT AHFinderDirect_local_coordinate_origin
+    (CCTK_INT horizon_number,
+     CCTK_REAL* origin_x_ptr, CCTK_REAL* origin_y_ptr, CCTK_REAL* origin_z_ptr)
 {
 const struct verbose_info& verbose_info = state.verbose_info;
 
-if (!  ((horizon_number >= 1) && (horizon_number < state.N_horizons))  )
-   then CCTK_VWarn(1, __LINE__, __FILE__, CCTK_THORNSTRING,
+if (!  ((horizon_number >= 1) && (horizon_number <= state.N_horizons))  )
+   then {
+	CCTK_VWarn(1, __LINE__, __FILE__, CCTK_THORNSTRING,
 "AHFinderDirect_local_coordinate_origin():\n"
 "        horizon_number=%d must be in the range [1,N_horizons=%d]!\n"
 		   ,
-		   int(horizon_number), state.N_horizons);	/*NOTREACHED*/
+		   int(horizon_number), state.N_horizons);
+	return -1;					// *** ERROR RETURN ***
+	}
 
 assert(state.AH_data_array[horizon_number] != NULL);
 const struct AH_data& AH_data = *state.AH_data_array[horizon_number];
@@ -81,13 +89,49 @@ const patch_system& ps = *AH_data.ps_ptr;
 *origin_x_ptr = ps.origin_x();
 *origin_y_ptr = ps.origin_y();
 *origin_z_ptr = ps.origin_z();
+
+return 0;						// *** NORMAL RETURN ***
+}
+
+//******************************************************************************
+
+//
+// This function is called (via the Cactus flesh function-aliasing mechanism)
+// by other thorns to query whether or not the specified horizon was found
+// the last time we searched for it.
+//
+// Results:
+// This function returns
+//  1 if the horizon was found
+//  0 if the horizon was not found
+//  -1 if the horizon number is invalid.
+//
+extern "C"
+  CCTK_INT AHFinderDirect_horizon_was_found(CCTK_INT horizon_number)
+{
+const struct verbose_info& verbose_info = state.verbose_info;
+
+if (!  ((horizon_number >= 1) && (horizon_number <= state.N_horizons))  )
+   then {
+	CCTK_VWarn(1, __LINE__, __FILE__, CCTK_THORNSTRING,
+"AHFinderDirect_horizon_was_found():\n"
+"        horizon_number=%d must be in the range [1,N_horizons=%d]!\n"
+		   ,
+		   int(horizon_number), state.N_horizons);
+	return -1;					// *** ERROR RETURN ***
+	}
+
+assert(state.AH_data_array[horizon_number] != NULL);
+const struct AH_data& AH_data = *state.AH_data_array[horizon_number];
+
+return AH_data.found_flag ? 1 : 0;
 }
 
 //******************************************************************************
 
 //
-// This function is called (via the magic of function aliasing) by
-// other thorns to find out a given AH's radius in the direction from
+// This function is called (via the Cactus flesh function-aliasing mechanism)
+// by other thorns to find out a given AH's radius in the direction from
 // its local coordinate origin to a given (x,y,z) coordinate or coordinates.
 //
 // FIXME:
@@ -103,21 +147,27 @@ const patch_system& ps = *AH_data.ps_ptr;
 //	      from the local coordinate origin), or to all -1.0 if we didn't
 //	      find this horizon the last time we looked for it
 //
+// Results:
+// This function returns 0 for ok, or -1 if the horizon number is invalid.
+//
 extern "C"
-  void AHFinderDirect_radius_in_direction
-	(CCTK_INT horizon_number,
-	 CCTK_INT N_points,
-	 const CCTK_REAL* const x, const CCTK_REAL* const y, const CCTK_REAL* const z,
-	 CCTK_REAL* const radius)
+  CCTK_INT AHFinderDirect_radius_in_direction
+    (CCTK_INT horizon_number,
+     CCTK_INT N_points,
+     const CCTK_REAL* const x, const CCTK_REAL* const y, const CCTK_REAL* const z,
+     CCTK_REAL* const radius)
 {
 const struct verbose_info& verbose_info = state.verbose_info;
 
-if (! ((horizon_number >= 1) && (horizon_number < state.N_horizons)) )
-   then CCTK_VWarn(1, __LINE__, __FILE__, CCTK_THORNSTRING,
+if (! ((horizon_number >= 1) && (horizon_number <= state.N_horizons)) )
+   then {
+	CCTK_VWarn(1, __LINE__, __FILE__, CCTK_THORNSTRING,
 "AHFinderDirect_distance_outside_thorn():\n"
 "        horizon_number=%d must be in the range [1,N_horizons=%d]!\n"
 		   ,
-		   int(horizon_number), state.N_horizons);	/*NOTREACHED*/
+		   int(horizon_number), state.N_horizons);
+	return -1;					// *** ERROR RETURN ***
+	}
 
 assert(state.AH_data_array[horizon_number] != NULL);
 const struct AH_data& AH_data = *state.AH_data_array[horizon_number];
@@ -138,6 +188,8 @@ const struct AH_data& AH_data = *state.AH_data_array[horizon_number];
 		}
 	   else radius[point] = -1.0;
 	}
+
+return 0;						// *** NORMAL RETURN ***
 }
 
 //******************************************************************************
diff --git a/src/driver/driver.hh b/src/driver/driver.hh
index b08a551..dc73f84 100644
--- a/src/driver/driver.hh
+++ b/src/driver/driver.hh
@@ -384,6 +384,21 @@ extern "C"
 extern "C"
   void AHFinderDirect_maybe_do_masks(CCTK_ARGUMENTS);
 
+// aliased_functions.cc
+// ... called from other thorns via the Cactus flesh function-aliasing mechanism
+extern "C"
+  CCTK_INT AHFinderDirect_local_coordinate_origin
+    (CCTK_INT horizon_number,
+     CCTK_REAL* origin_x_ptr, CCTK_REAL* origin_y_ptr, CCTK_REAL* origin_z_ptr);
+extern "C"
+  CCTK_INT AHFinderDirect_horizon_was_found(CCTK_INT horizon_number);
+extern "C"
+  CCTK_INT AHFinderDirect_radius_in_direction
+    (CCTK_INT horizon_number,
+     CCTK_INT N_points,
+     const CCTK_REAL* const x, const CCTK_REAL* const y, const CCTK_REAL* const z,
+     CCTK_REAL* const radius);
+
 // initial_guess.cc
 void setup_initial_guess(patch_system& ps,
 			 const struct initial_guess_info& igi,
diff --git a/src/driver/make.code.defn b/src/driver/make.code.defn
index b973728..737cb3d 100644
--- a/src/driver/make.code.defn
+++ b/src/driver/make.code.defn
@@ -6,8 +6,8 @@ SRCS = state.cc \
        setup.cc find_horizons.cc \
        initial_guess.cc Newton.cc \
        io.cc misc-driver.cc \
-       announce.cc horizon_radius.cc mask.cc \
-       BH_diagnostics.cc horizon_sequence.cc
+       BH_diagnostics.cc horizon_sequence.cc \
+       mask.cc announce.cc aliased_functions.cc
 
 # Subdirectories containing source files
 SUBDIRS =