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

3 files changed, 87 insertions, 20 deletions

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 =