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, 52 insertions, 26 deletions

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
-
 ################################################################################