* add output_ghost_zones_for_h parameter

* add a bunch of comments about choosing the interpolator parameters
* change the default interpatch interpolator parameters to use
  Lagrange rather than Hermite, because the current Hermite interpolator
  is rather inaccurate when off-centered
* split up   initial_guess__Kerr__*  parameters into separate
  initial_guess__Kerr_Kerr__*  and  initial_guess__Kerr_KerrSchild__*
  parameters to match the thorn Exact conventions


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

1 files changed, 66 insertions, 19 deletions

diff --git a/param.ccl b/param.ccl
index 627817c..b37aac5 100644
--- a/param.ccl
+++ b/param.ccl
@@ -200,6 +200,11 @@ keyword file_format \
 "HDF5"	:: "HDF5 surface format (not implemented yet)"
 } "ASCII"
 
+boolean output_ghost_zones_for_h \
+  "should we include the ghost zones in h data files?"
+{
+} "false"
+
 string ASCII_file_name_extension "extension for ASCII data files"
 {
 .* :: "any string"
@@ -347,9 +352,21 @@ keyword geometry_method "how do we compute the slice's geometry?"
 #
 # parameters for geometry_method = "interpolate from Cactus grid"
 #
-# Note that the interpolated gij and Kij should be at least C1, otherwise
-# the Newton iteration may fail to converge all the way down to tight
-# error tolerances.  In practice a Hermite interpolant works well.
+# This 3D interpolator is used to interpolate gij and Kij from the
+# Cactus grid to the position of each trial horizon surface, giving
+# gij, Kij, and partial_x gij as outputs.  This interpolator must have
+# the following properties:
+# - It must be able to accept the Cactus grid as an input domain.  The
+#   current implementation uses the  CCTK_InterpLocalUniform()  API; this
+#   is processor-local and so restricts the whole apparent horizon finder
+#   to single-processor operation.
+# - It must support taking at least 1st derivatives as part of the
+#   interpolation.
+# - It should give at least C1 interpolants for smooth data, otherwise
+#   the H(h) function will have "spikes" and the Newton iteration may
+#   fail to converge all the way down to tight error tolerances.  C2
+#   would be even better, but in practice a (C1) Hermite interpolant
+#   works well.
 #
 
 string geometry_interpolator_name \
@@ -361,7 +378,7 @@ string geometry_interpolator_name \
 string geometry_interpolator_pars \
   "parameters for the geometry interpolator"
 {
-.* :: "any string acceptable to Util_TableSetFromString()"
+.* :: "any string acceptable to Util_TableSetFromString() and to the interpolator"
 } "order=3"
 
 ########################################
@@ -419,24 +436,27 @@ real geometry__Schwarzschild_EF__Delta_xyz \
 ################################################################################
 
 #
-# parameters for the (1-D angular) interpatch interpolator
+# parameters for the interpatch interpolator
 #
-# Note there's no necessary relationship between this interpolator and
-# the geometry interpolator.  In particular, this interpolator could
-# reasonably use a different interpolation operator and/or order from
-# the geometry interpolator.
+# This 1D interpolator is used to interpolate the h function between
+# angular patches.  Because any given patch boundary only interpolates
+# from a single neighboring patch (this is to simplify the bookkeeping),
+# near the patch corners this interpolator will have to be used off-centered.
+# Thus it's desirable to use an interpolator which retains reasonable
+# accuracy right up to the edge of the data range.  In practice a Lagrange
+# polynomial interpolant works well.
 #
 string interpatch_interpolator_name \
   "name under which the interpatch interpolation operator is registered in Cactus"
 {
 .* :: "any string"
-} "Hermite polynomial interpolation"
+} "Lagrange polynomial interpolation"
 
 string interpatch_interpolator_pars \
   "parameters for the interpatch interpolator"
 {
-.* :: "any string acceptable to Util_TableSetFromString()"
-} "order=3"
+.* :: "any string acceptable to Util_TableSetFromString() and to the interpolator"
+} "order=5"
 
 ################################################################################
 
@@ -444,6 +464,7 @@ string interpatch_interpolator_pars \
 # parameters specifying the initial guess for the apparent horizon shape
 #
 
+# n.b. Schwarzschild/EF is the special case spin=0 of Kerr/Kerr
 keyword initial_guess_method \
   "method used to set up initial guess for apparent horizon shape"
 {
@@ -499,28 +520,54 @@ real initial_guess__ellipsoid__z_radius[5] "z radius of ellipsoid"
 (0.0:* :: "any real number > 0.0"
 } 2.0
 
-# parameters for initial_guess_method = "Kerr/Kerr" and "Kerr/Kerr-Schild"
-real initial_guess__Kerr__x_posn[5] "x coordinate of Kerr BH"
+# parameters for initial_guess_method = "Kerr/Kerr"
+real initial_guess__Kerr_Kerr__x_posn[5] "x coordinate of Kerr BH"
 {
 *:* :: "any real number"
 } 0.0
-real initial_guess__Kerr__y_posn[5] "y coordinate of Kerr BH"
+real initial_guess__Kerr_Kerr__y_posn[5] "y coordinate of Kerr BH"
 {
 *:* :: "any real number"
 } 0.0
-real initial_guess__Kerr__z_posn[5] "z coordinate of Kerr BH"
+real initial_guess__Kerr_Kerr__z_posn[5] "z coordinate of Kerr BH"
 {
 *:* :: "any real number"
 } 0.0
+real initial_guess__Kerr_Kerr__mass[5] "mass of Kerr BH"
+{
+(0.0:*		:: "BH mass = any real number > 0"
+} 1.0
 # n.b. my convention is that a=J/m^2 is dimensionless,
 #      while MTW take a=J/m=m * (my a)
-real initial_guess__Kerr__mass[5] "mass of Kerr BH"
+real initial_guess__Kerr_Kerr__spin[5] "dimensionless spin a=J/m^2 of Kerr BH"
+{
+(-1.0:1.0)	:: \
+  "dimensionless BH spin = J/m^2 = any real number with absolute value < 1"
+} 0.6
+
+# parameters for initial_guess_method = "Kerr/Kerr-Schild"
+real initial_guess__Kerr_KerrSchild__x_posn[5] "x coordinate of Kerr BH"
+{
+*:* :: "any real number"
+} 0.0
+real initial_guess__Kerr_KerrSchild__y_posn[5] "y coordinate of Kerr BH"
+{
+*:* :: "any real number"
+} 0.0
+real initial_guess__Kerr_KerrSchild__z_posn[5] "z coordinate of Kerr BH"
+{
+*:* :: "any real number"
+} 0.0
+real initial_guess__Kerr_KerrSchild__mass[5] "mass of Kerr BH"
 {
 (0.0:*		:: "BH mass = any real number > 0"
 } 1.0
-real initial_guess__Kerr__spin[5] "dimensionless spin J/m^2 of Kerr BH"
+# n.b. my convention is that a=J/m^2 is dimensionless,
+#      while MTW take a=J/m=m * (my a)
+real initial_guess__Kerr_KerrSchild__spin[5] "dimensionless spin a=J/m^2 of Kerr BH"
 {
-(-1.0:1.0)	:: "BH spin = J/m^2 = any real number with absolute value < 1"
+(-1.0:1.0)	:: \
+  "dimensionless BH spin = J/m^2 = any real number with absolute value < 1"
 } 0.6
 
 ################################################################################