This is a general code cleanup, and also adds some new features to

this thorn.

[Unforunately, for the reasons explained in today's E-mail discussion
on the developers@cactuscode.org mailing list, it's not practical for
me to break this up into multiple smaller single-purposed commits.]


param.ccl
* add comments
* add additional interpolator parameters (described in detail below)
* add "output psi on 2D grid" parameters (described in detail below)
* add debugging parameters

doc/documentation.tex
* add "IDAxiBrillBH/" prefix to make LaTeX labels unique across thorns
* correct a few typos
* clarify explanation of how we solve on a 2-D grid and then interpolate
  to the Cactus 3-D grid
* explain the new interpolator and output-psi-on-2D-grid parameters
* add some comments on choosing the 2-D grid resolution parameters
* mention debug parameters

doc/TODO
* new file noting some problems with this thorn which I found, but
  didn't fix

src/IDAxiBrillBH.F
* use new CCTK_WARN(CCTK_WARN_ABORT, ...) instead of old CCTK_WARN(0, ...)
* more flexible interpolator parameters:
 	This thorn first solves the Brill-wave equation on an internal
 	(axisymmetric) 2D grid, then uses uses the standard Cactus
 	CCTK_InterpLocalUniform() local-interpolator API to interpolate
 	this to the 3D grid points.  Before this patch, this thorn
 	hard-wired the interpolation operator to "uniform cartesian",
 	only allowed orders 1, 2, and 3, and didn't allow any other
 	interpolator parameters to be set.  This patch adds two new
 	parameters to allow any interpolation operator and parameters
 	to be specified.  Either the old or the new parameters can be
 	used (see doc/documentation.tex for details of how this works);
 	the defaults leave the behavior of this thorn unchanged.
* add option to output psi on 2D grid
 	When using this thorn, I found it hard to choose the parameters
 	defining the resolution and extent of the internal 2D grid.
 	To help with this, I added an option to output the solution
 	on that grid to an ASCII data file, so it can be examined
 	and plotted.
* add debugging code
 	I've added debug options which, if enabled, print the values
 	of various internal quantities at specified 2D and/or 3D grid
 	points.  I've left these in the final "production" code as
 	possibly being useful for future debugging.
* add many comments
* correct or remove some old comments which were out of date
* adjust whitespace to make the code a bit more readable:
   I've changed code like
        allocate(cc(neb,nqb),ce(neb,nqb),cw(neb,nqb),cn(neb,nqb),cs(neb,nqb),
       $     rhs(neb,nqb),psi2d(neb,nqb),detapsi2d(neb,nqb),dqpsi2d(neb,nqb),
       $     detaetapsi2d(neb,nqb),detaqpsi2d(neb,nqb),dqqpsi2d(neb,nqb),
       $     etagrd(neb),qgrd(nqb))
   to make it clearer which arrays have the same size:
        allocate(          cc(neb,nqb))
        allocate(          ce(neb,nqb))
        allocate(          cw(neb,nqb))
        allocate(          cn(neb,nqb))
        allocate(          cs(neb,nqb))
        allocate(         rhs(neb,nqb))
        allocate(       psi2d(neb,nqb))
        allocate(   detapsi2d(neb,nqb))
        allocate(     dqpsi2d(neb,nqb))
        allocate(detaetapsi2d(neb,nqb))
        allocate(  detaqpsi2d(neb,nqb))
        allocate(    dqqpsi2d(neb,nqb))

        allocate(etagrd(neb))
        allocate(  qgrd(nqb))
* change some Fortran write statements to CCTK_INFO
 	[so they're properly synchronized with output from C routines,
 	even when stdout+stderr are redirected to a log file]
* include more information about what went wrong, in various error messages
 	[eg if the interpolator returns an error code, the code
 	now includes that error code in the error message]
* rename a few variables to make their purpose clearer:
 	ep1 --> error_at_this_grid_point
 	ep2 --> max_error_in_grid


git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinInitialData/IDAxiBrillBH/trunk@69 0a4070d5-58f5-498f-b6c0-2693e757fa0f

1 files changed, 115 insertions, 6 deletions

diff --git a/param.ccl b/param.ccl
index e458cf7..b20a0df 100644
--- a/param.ccl
+++ b/param.ccl
@@ -18,6 +18,78 @@ USES KEYWORD metric_type
 
 private:
 
+############################################################
+
+#
+# ***** debugging parameters *****
+#
+
+#
+# If this parameter is set to true, we output an ASCII data file
+# giving psi on the 2D grid.  The file format should be directly usable
+# by a gnuplot 'splot' command.
+#
+Boolean output_psi2D							\
+  "should we output the conformal factor psi on the 2D grid?"
+{
+} false
+
+string output_psi2D_file_name						\
+  "if we output the conformal factor psi on the 2D grid,		\
+   what file name should we use for the output file?"
+{
+".+" :: "any non-empty string that's a valid file name"
+} "psi2D.dat"
+
+#
+# this parameter controls the amount of (potentially very detailed)
+# debugging information this thorn prints
+#
+CCTK_INT debug                                                          \
+  "level of debugging information to print                              \
+   (0 = none, 2 = a little, 6 = a lot, 10 = huge amounts)"
+{
+0:* :: "any integer >= 0"
+} 0
+
+#
+# to keep the output size quasi-finite, some debug printing which is
+# logicially "per grid point" on the 2-D (eta,q) grid, is actually only
+# done for this single 2-D grid point
+#
+CCTK_INT debug_ii "i coordinate for per-2D-grid-point debug printing"
+{
+* :: "any integer"
+} 14
+CCTK_INT debug_jj "j coordinate for per-2D-grid-point debug printing"
+{
+* :: "any integer"
+} 15
+
+#
+# to keep the output size quasi-finite, some debug printing which is
+# logicially "per Cactus grid point" is actually only done for this single
+# Cactus grid point
+#
+CCTK_INT debug_i "i coordinate for per-grid-point debug printing"
+{
+* :: "any integer"
+} 14
+CCTK_INT debug_j "j coordinate for per-grid-point debug printing"
+{
+* :: "any integer"
+} 15
+CCTK_INT debug_k "k coordinate for per-grid-point debug printing"
+{
+* :: "any integer"
+} 10
+
+############################################################
+
+#
+# ***** parameters controlling the Brill wave itself *****
+#
+
 REAL amp "Brill wave amplitude"
 {
   *:* :: "No restriction"
@@ -33,28 +105,65 @@ REAL sigma "Brill wave width (in eta)"
   *:* :: "No restriction"
 } 1.0
 
-REAL etamax "Eta value for outer edge of grid"
+REAL etamax "eta value for outer edge of grid"
 {
   *:* :: "No restriction"
 } 5.0
 
-
-INT n "sin^n theta in brill wave"
+INT n "sin^n theta in Brill wave"
 {
   *:* :: "No restriction"
 } 2
 
-INT ne "Eta resolution for solve"
+############################################################
+
+#
+# ***** parameters for the numerical solution of the *****
+# ***** Brill-wave equation on the 2-D (eta,q) grid *****
+#
+
+INT ne "eta resolution for solve"
 {
   *:* :: "No restriction"
 } 300
 
-INT nq "Theta resolution for solve"
+INT nq "theta resolution for solve"
 {
   *:* :: "No restriction"
 } 50
 
+REAL error_tolerance "tolerance parameter for elliptic solver"
+{
+(0:* :: "any positive real number"
+} 1.0e-12
+
+############################################################
+
+#
+# ***** interpolation parameters *****
+#
+
+#
+# This thorn first computes the Brill wave solution on an internal 2-D
+# grid, then interpolates this to the 3-D Cactus grid.  The following
+# parameters control this interpolation.
+#
+
+STRING interpolator_name \
+  "name of CCTK_InterpLocalUniform() interpolation operator"
+{
+".*" :: "any string"
+} "uniform cartesian"
+
+STRING interpolator_pars "parameters for the interpolation operator"
+{
+".*" :: \
+  "any nonempty string acceptable to Util_TableSetFromString()		\
+   and to the interpolator, or the empty string to use 'order=n',	\
+   where  n  is specified by the  interpolation_order  parameter"
+} ""
+
 INT interpolation_order "Order for interpolation" STEERABLE = ALWAYS
 {
-  1:3 :: "Choose between first, second, and third-order"
+0:9 :: "any integer accepted by the interpolator"
 } 1