add lots more comments about various parameters

add new "automatic choice" option for surface_integral_method
  and make it the default


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

1 files changed, 61 insertions, 25 deletions

diff --git a/param.ccl b/param.ccl
index b37aac5..0e040d5 100644
--- a/param.ccl
+++ b/param.ccl
@@ -39,8 +39,10 @@ keyword method "top-level method used to find the apparent horizon"
 } "Newton solve"
 
 #
-# At present we support up to 4 horizons; for user-friendliness we
-# number these 1, 2, 3, ... .   Since Cactus arrays are 0-origin, we
+# We support searching for up to N_horizons distinct apparent horizons
+# (some of which may be nested inside others) in a slice.  We number
+# these 1, 2, 3, ... (this seems a bit more user-friendly than Cactus's
+# native 0-origin numbering).  Since Cactus arrays are 0-origin, we
 # make the arrays be of size N_horizons+1, and don't use the [0] array
 # elements.
 #
@@ -103,21 +105,29 @@ keyword Jacobian_method "how do we compute the Jacobian matrix?"
   "fast, tricky programming, uses gij, dx gij, dxx gij, Kij, dx Kij"
 } "symbolic differentiation with finite diff d/dr"
 
+#
+# This parameter lists all known storage methods.  See
+# "src/include/config.hh" for which of these are actually compiled in at
+# the moment.  N.b. each compiled-in method requires linking with the
+# corresponding linear-solver library; see "src/make.configuration.defn"
+# for details on these libraries.
+#
 keyword Jacobian_storage_method "how do we store the Jacobian matrix?"
 {
 "dense matrix"	:: "dense matrix (inefficient, but good for debugging)"
 } "dense matrix"
 
 #
-# this is used for two different sorts of one-sided finite differencing:
-# - numerical-perturbation Jacobian computations,
+# This parameter controls two different sorts of one-sided finite
+# differencing:
+# - numerical-perturbation Jacobian computations
 # - the finite differencing part of the "symbolic differentiation
 #   with finite diff d/dr" Jacobian computation
 #
-# notes on this parameter:
+# Notes on this parameter:
 # - don't set it too small or roundoff errors will become large
 # - don't set it too large or finite differencing errors will become large
-# in practice the default value should be fine
+# In practice the default value should be fine
 #
 real Jacobian_perturbation_amplitude \
   "perturbation amplitude for 1-sided finite differencing for Jacobians"
@@ -137,10 +147,10 @@ int max_Newton_iterations "maximum number of Newton iterations before giving up"
 } 10
 
 #
-# to avoid the Newton iteration diverging if there is no horizon present,
-# we limit the distance the horizon may move in any single Newton iteration
-# (i.e. the infinity-norm of Delta_h) to <= this fraction of the mean horizon
-# radius
+# To avoid the Newton iteration diverging if there is no horizon present
+# or if the initial guess is bad, we limit the distance the horizon may
+# move in any single Newton iteration (i.e. the infinity-norm of Delta_h)
+# to <= this fraction of the mean horizon radius
 #
 real max_Delta_h_over_h \
   "don't let horizon move > this fraction of mean radius in a Newton iteration"
@@ -155,13 +165,17 @@ real H_norm_for_convergence "declare convergence if ||H||_inf <= this"
 {
 (0.0:* :: "any positive real number"
 } 1.0e-10
-
 real Delta_h_norm_for_convergence \
   "declare convergence after any Newton step with ||Delta_h||_inf <= this"
 {
 (0.0:* :: "any positive real number"
 } 1.0e-10
 
+#
+# This only needs to be set to true for very careful convergence studies
+# etc.  On the other hand, setting it to true probably only slows down
+# the apparent horizon finder by a few percent.
+#
 boolean final_H_update_if_exit_x_H_small \
   "should we do a final H(h) update after a h += Delta_h update which is\
    so small it meets the Delta_h_norm_for_convergence convergence criterion?"
@@ -197,7 +211,7 @@ keyword file_format \
   "what file format should we use for h and H(h) data files?"
 {
 "ASCII"	:: "simple ASCII format, directly readable by gnuplot"
-"HDF5"	:: "HDF5 surface format (not implemented yet)"
+"HDF5"	:: "HDF5 surface format (alas not implemented yet)"
 } "ASCII"
 
 boolean output_ghost_zones_for_h \
@@ -249,6 +263,25 @@ string Jacobian_base_file_name "base file name for Jacobian output file(s)"
 #
 private:
 
+#
+# For each apparent horizon, you need to set these parameters to the
+# Cactus xyz coordinates of an "origin point" inside the horizon, which
+# will serve as the origin for the apparent horizon finder's local angular
+# coordinate system.
+#
+# The apparent horizon surface (and in fact all the trial surfaces the
+# apparent horizon finder generates while iteratively solving the apparent
+# horizon equation) is restricted to being a Strahlkoerper ("star-shaped
+# region") about the origin point.  That is, each surface must be of
+# the form r = h(angle) with h a single-valued function.
+#
+# If the origin point is too far from the actual horizon centroid, i.e.
+# if it's too close to the horizon surface itself, then the apparent
+# horizon finder's Newton iteration won't converge as quickly or robustly.
+# However, in practice the tolerances on this are quite loose -- 1/4
+# of the horizon radius is no problem, and even 1/2 the horizon radius
+# only slows the convergence by an extra iteration or two.
+#
 real origin_x[5] "global x coordinate of patch system origin"
 {
 *:* :: "any real number"
@@ -320,15 +353,17 @@ real delta_drho_dsigma "angular grid spacing of patches, in degrees"
 keyword surface_integral_method \
   "how do we compute surface integrals over the horizon?"
 {
-"trapezoid"		:: ""
+"trapezoid"		:: "alternate name for trapezoid rule"
 "trapezoid rule"	:: "trapezoid rule (2nd order for smooth functions)"
-"Simpson"		:: ""
+"Simpson"		:: "alternate name for Simpson's rule"
 "Simpson's rule"	:: \
   "Simpson's rule (4th order for smooth fns, requires N to be even)"
-"Simpson (variant)"	:: ""
+"Simpson (variant)"	:: "alternate name for Simpson's rule variant"
 "Simpson's rule (variant)":: \
   "Simpson's rule variant (4th order for smooth fns, requires N >= 7)"
-} "trapezoid"
+"automatic choice"	:: \
+  "choose Simpson's rule or variant if applicable, otherwise trapezoid rule"
+} "automatic choice"
 
 ################################################################################
 
@@ -362,10 +397,10 @@ keyword geometry_method "how do we compute the slice's geometry?"
 #   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
+# - It should give at least $C^1$ 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
+#   fail to converge all the way down to tight error tolerances.  $C^2$
+#   would be even better, but in practice a ($C^1$) Hermite interpolant
 #   works well.
 #
 
@@ -417,7 +452,7 @@ real geometry__Schwarzschild_EF__epsilon \
   "threshold for sin^2 theta = (x^2+y^2)/r^2 below which we use z axis limits"
 {
 (0.0:*	:: "this should be somewhat above the floating-point roundoff level"
-} 1.0e-12
+} 1.0e-9
 
 # we compute partial_k g_ij by numerical finite differencing of the exact
 # analytical g_ij values; this parameter sets the "grid spacing" for this
@@ -573,16 +608,17 @@ real initial_guess__Kerr_KerrSchild__spin[5] "dimensionless spin a=J/m^2 of Kerr
 ################################################################################
 
 #
-# parameters for the test driver  src/util/test_patch_system.cc
+# parameters for the test driver "src/patch/test_patch_system.cc"
 #
 # By default this test driver isn't compiled into the cactus executable,
 # and these parameters are ignored.  To compile this test driver into
 # the cactus executable (and have these parameters used),
 # - edit the list of "source files in this directory" in
-#    src/util/make.code.defn  to add  test_patch_system.cc
-# - edit the list of "subdirectories containing source files" in
-#    src/make.code.defn  to disable the higher-level directories
-#    elliptic and  gr
+#   "src/patch/make.code.defn" to add  test_patch_system.cc
+# - comment out the list of "subdirectories containing source files" in
+#   "src/make.code.defn", and uncomment the alternate list which is
+#   normally commented out there (this omits the higher-level directories
+#   src/elliptic/, src/gr/, and src/driver/)
 #
 keyword which_test "which test should we do?"
 {