path: root/param.ccl

# Parameter definitions for thorn AHFinderDirect
# $Header$

################################################################################

#
# overall parameters for the apparent horizon finding algorithm itself
#

boolean find_AHs_at_postinitial \
  "should we try to find apparent horizons at CCTK_POSTINITIAL?"
{
} "true"

boolean find_AHs_at_poststep \
  "should we try to find apparent horizons at CCTK_POSTSTEP?"
{
} "true"

keyword method "top-level method used to find the apparent horizon"
{
# options mostly for testing/debugging
"horizon function"  :: "evaluate the LHS function H(h)"
"Jacobian test"	    :: \
  "compute/print the J[H(h)] Jacobian matrix by all possible methods"
"Jacobian test (NP only)" :: \
  "compute/print the J[H(h)] Jacobian matrix by numerical perturbation only"
# normal AH finding
"Newton solve"	    :: "find the horizon via Newton's method"
} "Newton solve"

#
# at present we support up to 4 horizons
#
# to increase this, just raise the upper limit for this variable,
# and change all occurences of "[4]" in this file to whatever the new
# upper limit is (no changes are needed in the source code)
#
int N_horizons "number of apparent horizons to search for"
{
0   :: "turn this thorn into a fancy no-op :)"
1:4 :: "search for this many apparent horizons"
} 1

#
# This parameter controls which (how many) informational (non-error)
# messages are printed describing the operation of the apparent horizon
# finder.  This is analogous to the -W Cactus command-line option, except
# that this parameter controls (only) *non*-error messages.
#
keyword verbose_level \
  "controls which (how many) messages to print describing AH finding"
{
"physics highlights"   :: "just a few physics messages"
"physics details"      :: "more detailed physics messages"
"algorithm highlights" :: \
  "physics details + a few messages about the AH-finding algorithm"
"algorithm details"    :: \
  "physics details + lots of messages about the AH-finding algorithm"
} "physics details"

boolean print_timing_stats \
  "should we print timing stats for the whole apparent-horizon-finding process?"
{
} "false"

################################################################################

#
# parameters for the Jacobian matrix
#

keyword Jacobian_method "how do we compute the Jacobian matrix?"
{
"numerical perturbation"    :: \
  "*very* slow, but useful for debugging"
"symbolic differentiation with finite diff d/dr" :: \
  "fast, tricky programming, uses only gij, dx gij, Kij"
"symbolic differentiation"  :: \
  "fast, tricky programming, uses gij, dx gij, dxx gij, Kij, dx Kij"
} "symbolic differentiation with finite diff d/dr"

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,
# - the finite differencing part of the "symbolic differentiation
#   with finite diff d/dr" Jacobian computation
#
# 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
#
real Jacobian_perturbation_amplitude \
  "perturbation amplitude for 1-sided finite differencing for Jacobians"
{
(0.0:* :: "any real number > 0"
} 1.0e-6

################################################################################

#
# parameters for the Newton's-method solution of H(h) = 0
#

int max_Newton_iterations "maximum number of Newton iterations before giving up"
{
(0:* :: "any positive integer"
} 10

# if this is used, the file names are the usual ones with ".it%d" appended
boolean output_h_and_H_at_each_Newton_iteration \
  "should we output h and H at each Newton iteration (for debugging)?"
{
} "false"

#
# 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
#
real max_Delta_h_over_h \
  "don't let horizon move > this fraction of mean radius in a Newton iteration"
{
(0.0:* :: "any positive real number"
} 0.1

#
# we declare convergence if *either* of the following two criteria are met
#
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

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?"
{
} "false"

################################################################################

#
# input/output parameters
#

#
# These file names are actually just "base" file names, with the
# full file names being
#	"%s.t%d.ah%d[.it%d].dat"
# where
# the %s is the base file name,
# the first %d is the global Cactus time iteration number,
# the second %d is the apparent horizon number, ande
# the optional third %d is the horizon finder iteration number
#

string h_base_file_name \
  "base file name for horizon shape h input/output file(s)"
{
.* :: "any string"
} "h.dat"

string H_of_h_base_file_name "base file name for H(h) output file(s)"
{
.* :: "any string"
} "H.dat"

string Jacobian_base_file_name "base file name for Jacobian output file(s)"
{
.+ :: "any valid file name"
} "Jacobian.dat"

################################################################################

#
# parameters to define the patch systems
#
private:

real origin_x[4] "global x coordinate of patch system origin"
{
*:* :: "any real number"
} 0.0
real origin_y[4] "global y coordinate of patch system origin"
{
*:* :: "any real number"
} 0.0
real origin_z[4] "global z coordinate of patch system origin"
{
*:* :: "any real number"
} 0.0

keyword patch_system_type "what type of patch system should we use?"
{
"full sphere"	:: "full sphere, no symmetries"
"+z hemisphere"	:: "mirror symmetry across z=0 plane"
"+xy quadrant"	:: "90 degree periodic rotation symmetry about z axis"
"+xz quadrant"	:: "mirror symmetry across z=0 plane *and* \
		    180 degree periodic rotation symmetry about z axis"
"+xyz octant"	:: "mirror symmetry across z=0 plane *and* \
		    90 degree periodic rotation symmetry about z axis"
} "full sphere"

int N_ghost_points "number of ghost zones on each side of a patch"
{
0:* :: "any integer >= 0"
} 2

int N_overlap_points \
  "number of grid points that nominally-just-touching patches should overlap"
{
1:*:2 :: "any integer >= 0; current implementation requires that it be odd"
} 1

real delta_drho_dsigma "angular grid spacing of patches, in degrees"
{
(0.0:* :: "any real number > 0.0"
} 5.0

################################################################################

#
# parameters for how we compute the slice's geometry
# (gij, Kij, partial_k gij)
#

keyword geometry_method "how do we compute the slice's geometry?"
{
# for normal use
"interpolate from Cactus grid" :: "interpolate gij and Kij from Cactus grid"
# for testing/debugging
"Schwarzschild/EF"             :: \
  "hard-wire to Schwarzschild spacetime / Eddington-Finkelstein slice"
} "interpolate from Cactus grid"

########################################

#
# parameters for geometry_method = "interpolate from Cactus grid"
#

string geometry_interpolator_name \
  "name under which the geometry interpolation operator is registered in Cactus"
{
.* :: "any string"
} "generalized polynomial interpolation"

string geometry_interpolator_pars \
  "parameters for the geometry interpolator"
{
.* :: "any string acceptable to Util_TableSetFromString()"
} "order=4"

########################################

#
# parameters for geometry_method = "Schwarzschild/EF"
#

real geometry__Schwarzschild_EF__mass "mass of Schwarzschild BH"
{
(0.0:*		:: "BH mass = any real number > 0"
} 1.0

real geometry__Schwarzschild_EF__x_posn "x coordinate of Schwarzschild BH"
{
*:* :: "any real number"
} 0.0
real geometry__Schwarzschild_EF__y_posn "y coordinate of Schwarzschild BH"
{
*:* :: "any real number"
} 0.0
real geometry__Schwarzschild_EF__z_posn "z coordinate of Schwarzschild BH"
{
*:* :: "any real number"
} 0.0

# some of the formulas have 0/0 limits on the z axis; this parameter controls
# where we switch from the generic formulas to the L'Hopital's-rule z axis
# limits
# - don't set this parameter too small or roundoff errors will be excessive
# - don't set this parameter too large or finite differencing errors will
#   be excessive
# in practice the default value should be fine
# n.b. this is used for centered finite differencing, unlike the Jacobian
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

# 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
# - don't set this parameter too small or roundoff errors will be excessive
# - don't set this parameter too large or finite differencing errors will
#   be excessive
# in practice the default value should be fine
# ... n.b. this finite differencing is *centered*, unlike that in the
#          Jacobian computation
real geometry__Schwarzschild_EF__Delta_xyz \
  "finite diff pseuo-grid spacing for computing partial_k g_ij"
{
(0.0:* :: "any real number > 0"
} 1.0e-6

################################################################################

#
# parameters for the interpatch interpolator
#
string interpatch_interpolator_name \
  "name under which the interpatch interpolation operator is registered in Cactus"
{
.* :: "any string"
} "generalized polynomial interpolation"

string interpatch_interpolator_pars \
  "parameters for the interpatch interpolator"
{
.* :: "any string acceptable to Util_TableSetFromString()"
} "order=4"

################################################################################

#
# parameters specifying the initial guess for the apparent horizon shape
#

keyword initial_guess_method \
  "method used to set up initial guess for apparent horizon shape"
{
"read from file"   :: "read from input file"
"sphere"           :: "set up a coordinate sphere"
"ellipsoid"	   :: "set to a coordinate ellipsoid"
"Kerr/Kerr"	   :: "set to horizon of Kerr spacetime in Kerr coords"
"Kerr/Kerr-Schild" :: "set to horizon of Kerr spacetime in Kerr-Schild coords"
} "read from file"

boolean output_initial_guess \
  "should we write the initial guess back to the h data file?"
{
} "true"

# parameters for initial_guess_method = "sphere"
real initial_guess__sphere__x_center[4] "x coordinate of sphere center"
{
*:* :: "any real number"
} 0.0
real initial_guess__sphere__y_center[4] "y coordinate of sphere center"
{
*:* :: "any real number"
} 0.0
real initial_guess__sphere__z_center[4] "z coordinate of sphere center"
{
*:* :: "any real number"
} 0.0
real initial_guess__sphere__radius[4] "radius of sphere"
{
(0.0:* :: "any real number > 0.0"
} 2.0

# parameters for initial_guess_method = "ellipsoid"
real initial_guess__ellipsoid__x_center[4] "x coordinate of ellipsoid center"
{
*:* :: "any real number"
} 0.0
real initial_guess__ellipsoid__y_center[4] "y coordinate of ellipsoid center"
{
*:* :: "any real number"
} 0.0
real initial_guess__ellipsoid__z_center[4] "z coordinate of ellipsoid center"
{
*:* :: "any real number"
} 0.0
real initial_guess__ellipsoid__x_radius[4] "x radius of ellipsoid"
{
(0.0:* :: "any real number > 0.0"
} 2.0
real initial_guess__ellipsoid__y_radius[4] "y radius of ellipsoid"
{
(0.0:* :: "any real number > 0.0"
} 2.0
real initial_guess__ellipsoid__z_radius[4] "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[4] "x coordinate of Kerr BH"
{
*:* :: "any real number"
} 0.0
real initial_guess__Kerr__y_posn[4] "y coordinate of Kerr BH"
{
*:* :: "any real number"
} 0.0
real initial_guess__Kerr__z_posn[4] "z coordinate of Kerr BH"
{
*:* :: "any real number"
} 0.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[4] "mass of Kerr BH"
{
(0.0:*		:: "BH mass = any real number > 0"
} 1.0
real initial_guess__Kerr__spin[4] "dimensionless spin J/m^2 of Kerr BH"
{
(-1.0:1.0)	:: "BH spin = J/m^2 = any real number with absolute value < 1"
} 0.6

################################################################################

#
# parameters for the test driver  src/util/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
#
keyword which_test "which test should we do?"
{
"gridfn"	:: "set up test fn(x,y,z), print it"
"read gridfn"	:: "read in ghosted test fn(x,y,z), print it"
"synchronize"	:: "set up test fn(x,y,z), synchronize it, print errors"
"ghost zone Jacobian":: \
  "set up test fn(x,y,z), compute Jacobian of gz.synchronize(), compare with NP"
"derivatives"	:: "set up test fn(rho,sigma), take derivs, print errors"
} "gridfn"

int which_derivs "bit flags to specify which derivatives to test"
{
0:63 :: "any set of bit flags"
} 63

# true ==> gives a more thorough test of the Jacobian,
#          but makes the test run much slower
# false ==> gives a slightly less thorough test, but runs faster
boolean NP_Jacobian__perturb_all_y_patch_points \
  "should we perturb at *all* points in the y patch, or just those with the \
   iperp which is (supposedly) involved in the interpatch interpolation?"
{
} "true"

################################################################################