fix a bug found by Yosef Zlochower:

   In a multiprocessor run, AHFinderDirect finds different horizons
   in parallel on different processors, and doesn't broadcast horizon
   shapes to all processors unless it thinks they'll be needed.  However,
   the "the information will be needed" calculation doesn't take into
   account the possibility of the  HorizonRadiusInDirection()  aliased
   function being called on another processor, and in this case this
   function returns a wrong result if AHFinderDirect hasn't broadcast
   the horizon shapes.

* introduce a new Boolean parameter   always_broadcast_horizon_shape
  (defaults to false)
* document in interface.ccl, param.ccl, and doc/documentation.tex,
  that this parameter should be set to  true  if you expect
  HorizonRadiusInDirection() to be used
* inclusive-or this parameter into the "should we broadcast the horizon shape?"
  calculation in  src/driver/find_horizons.cc


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

1 files changed, 27 insertions, 17 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index b341c35..6cf6183 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -80,7 +80,7 @@
 \author{Jonathan Thornburg \quad {\tt <jthorn@aei.mpg.de>}}
 
 % The title of the document (not necessarily the name of the Thorn)
-\title{Thorn Guide for the {\bf AHFinderDirect} Thorn}
+\title{{\bf AHFinderDirect} -- A Fast Apparent Horizon Finder}
 
 % the date your document was last changed, if your document is in CVS,
 % please us:
@@ -1209,32 +1209,42 @@ following parameter:
 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,
+#
+# 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,
+#
+# 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.  
+#
+# If this function is to be used in a multiprocessor run on a horizon
+# which was found on some other processor, the parameter
+#   AHFinderDirect::always_broadcast_horizon_shape
+# must be set to true to get the correct answer.
+#
+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}