[[This is a redo of my "cvs import" of 2002/06/11, this time using proper

cvs operations (commit/delete/add) to preserve the full CVS history of this
thorn.]]

This is a major cleanup/revision of AEIThorns/Exact.

Major user-visible changes:
* major expansion of doc/documentation.tex
* major expansion of documentation in param.ccl file,
  including a long "how to add a new model" block comment
* rename all parameters, systematize spacetime/coordinate/parameter names
  (there is a perl script in par/convert-pars.pl to convert old parameter
  files to the new names)
* [from Mitica Vulcanov] many additions and fixes to
  cosmological solutions and Schwarzschild-Lemaitre
* fix stress-energy tensor computations so they work -- before they were
  all disabled in CVS (INCLUDES lines were commented out in interface.ccl)
  due to requiring excessive friendship with evolution thorns
  and/or public parameters; new code copies parameters to restricted
  grid scalars, which Cactus automagically "pushes" to friends
* added some more tests to testsuite, though these don't yet work fully

Additional internal changes:
* rename many Fortran subroutines (and a few C ones too)
  so their names start with the thorn name
  to reduce the chances of name collisions with other thorns
* move all metrics to subdirectory so the main source directory isn't
  so cluttered
* move two files containing subroutines which were never called
  (they didn't belong in this thorn, but somehow got into cvs by accident)
  into new archive/ directory
* some (small) improvements in efficiency -- the exact_model parameter
  is now decoded from a keyword (string) to an integer once at INITIAL,
  and that integer tested by the stress-energy tensor code,
  rather than requiring a separate series of string tests at each grid
  point (!) like the old stress-energy tensor code did


git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinInitialData/Exact/trunk@92 e296648e-0e4f-0410-bd07-d597d9acff87

1 files changed, 697 insertions, 251 deletions

diff --git a/param.ccl b/param.ccl
index 857559f..ba11100 100644
--- a/param.ccl
+++ b/param.ccl
@@ -1,91 +1,54 @@
-# Parameter definitions for thorn Exact
+# parameter definitions for thorn Exact
 # $Header$
 
 shares: admbase
 
+################################################################################
+##### keyword parameters from other thorns #####################################
+################################################################################
+
 USES KEYWORD metric_type
 
 EXTENDS KEYWORD initial_data 
 {
   "exact"   :: "Initial data from exact solution"
   "slice"   :: "Initial data from exact solution on arbitrary slice"
-} ""
+}
 
 EXTENDS KEYWORD lapse_evolution_method
 {
   "exact" :: "Use lapse from exact solution"
-} ""
-
+}
 EXTENDS KEYWORD shift_evolution_method
 {
   "exact" :: "Use shift from exact solution"
-} ""
+}
 
 EXTENDS KEYWORD initial_lapse 
 {
   "exact"   :: "Initial lapse from exact solution"
-} ""
-
+}
 EXTENDS KEYWORD initial_shift 
 {
   "exact"   :: "Initial shift from exact solution"
-} ""
+}
 
 EXTENDS KEYWORD evolution_method
 {
   "slice" :: "Evolve arbitrary slice and  extract Cauchy data"
-} ""
-
-
-# In view of using this thorn in conjunction with other thorns
-# his parameters are declared global
-
-global:
-
-#This is a trial. 
+}
 
-KEYWORD overwrite_boundary "Overwrite g and K on the boundary"
-{
-  "no" :: "Do nothing"
-  "exact" :: "Use boundary data from an exact solution on a trivial slice"
-} "no"
+################################################################################
+##### parameters for the blended boundary conditions ###########################
+################################################################################
 
 private:
 
-# General parameters
-
-KEYWORD exactmodel "The exact solution used in thorn exact"
-{
-  "minkowski"   :: "Minkowski spacetime"
-  "boostrot"    :: "Boost rotation symmetric spacetime"
-  "finkelstein" :: "Black hole in Eddington-Finkelstein coordinates"
-  "kerrschild"  :: "Kerr-Schild form of boosted rotating black hole"
-  "flatschwarz" :: "Schwarzschild black-hole with flat spatial metric"
-  "starschwarz" :: "Schwarzschild (constant density) star"
-  "novikov"     :: "Black hole in Novikov coordinates"
-  "multiBH"     :: "Maximally charged multi BH solutions"
-  "bowl"        :: "Non-Einstein bowl (bag-of-gold) spacetime"
-  "fakebinary"  :: "Non-Einstein fake-binary of Thorn et al"
-  "flatfunny"   :: "Minkowski spacetime in non-trivial spatial coordinates"
-  "flatshift"   :: "Minkowski spacetime in non-trivial slices with shift"
-  "bianchiI"    :: "Bianchi I spacetime"
-  "rob-wal"     :: "Robertson-Walker cosmology (near t= 0,pure radiation case)"
-  "godel"       :: "Godel spacetime"
-  "kerr"        :: "Kerr spacetime in cartesian coordinates"
-  "desitter"    :: "DeSitter spacetime (R-W cosmology, near t=0, p=0)"
-  "kasner"      :: "Kasner like spacetime"
-  "milne"       :: "De Milne spacetime for pre-big-bang cosmology"
-  "gauge_wave"  :: "Carlos Bonas' suggestion of a gauge wave"
-} "minkowski"
-
-
-# Parameters for the blended boundaries.
-
 BOOLEAN exblend_Ks "Blend the K variables with the exact solution?"
 {
 } "yes"
 
-BOOLEAN exblend_gs "Blend the g variables with the exact solution?"
+BOOLEAN exblend_gs "Blend the g variables with6~6~ the exact solution?"
 {
 } "yes"
 
@@ -103,366 +66,849 @@ REAL exblend_width "Width of blending zone"
 : :: "Positive means width in radius, negative means width = exbeldn_width*dx"
 } -3.0
 
+################################################################################
+##### parameters for slice initialize ##########################################
+################################################################################
 
-# Parameters for slice
+private:
 
-REAL slice_gauss_ampl "Amplitude of Gauss slice in exact"
+REAL slice_Gauss_ampl "Amplitude of Gauss slice in exact"
 {
 0.0:  ::  "Positive please"
 } 0.0
 
-REAL slice_gauss_width "Width of Gauss slice in exact"
+REAL slice_Gauss_width "Width of Gauss slice in exact"
 {
 0.0:  ::  "Positive please"
 } 1.0
 
+# this parameter is used directly in our schedule.ccl file
+KEYWORD overwrite_boundary "Overwrite g and K on the boundary"
+{
+  "no" :: "Do nothing"
+  "exact" :: "Use boundary data from an exact solution on a trivial slice"
+} "no"
+
+################################################################################
+##### general comments #########################################################
+################################################################################
+
+#
+# All remaining parameters *should* be visible only to this thorn
+# and its friends.  In particular, the stress-energy tensor code in
+# src/include/Scalar_CalcTmunu.inc needs to look at various parameters to
+# see what to do... and (via the magic of #include and the Cactus
+# USES INCLUDE SOURCE mechanism) this code is effectively part of
+# various evolution thorns.
+#
+# Alas, Cactus doesn't (yet) provide any way for a (this) thorn to "push"
+# parameters into friends without the friends having to know where the
+# pushed parameters came from... and we don't want the evolution thorns
+# themselves to have to know our name and those of all the other thorns
+# which provide pieces of the stress-energy tensor.
+#
+# Instead, we use a kludge: we copy all the relevant parameters
+# (exact_model and all those for models which have stress-energy tensor
+# computations) into restricted grid scalars.  These _are_ "pushed" into
+# friends... and because friendship is transitive, it suffices for us to
+# be friends of ADMCoupling.
+#
+# Since grid scalars can't be varying-length character strings, we also
+# have to decode keyword parameters into integers in this process.  The
+# values for those integers are given by #define constants in
+# src/include/param_defs.inc .
+#
+
+################################################################################
+
+#
+# ***** naming conventions *****
+#
+# A "model" refers to the combination of a spacetime and a coordinate
+# system; we use the model name "spacetime/coordinates" in cases where
+# we have the same spacetime in different coordinate systems.
+#
+# We use "spacetime+Lambda" to describe a with-cosmological-constant
+# variant of a given spacetime.
+#
+# All the parameters for individual models have names which begin
+# with the model name (with any '/' or '-' characters converted to '_'),
+# followed by '__'.  The description comment for each parameter begins
+# with the model name followed by ':'.  For example:
+#
+#	REAL Schwarzschild_EF__mass "Schwarzschild/EF: BH mass"
+#	{
+#	*:* :: "any real number"
+#	} 1.0
+#
+
+################################################################################
+
+#
+# ***** how to add a new model *****
+#
+
+#
+# First a general note:  When adding new models or modifying existing
+# ones, please follow the naming conventions described in
+# doc/documentation.tex.  Also, please keep the sections for various
+# models in the same order in all the files.
+#
+
+#
+# To add a new model you need to modify a number of files:
+#   doc/documentation.tex:
+#	Add a section describing your new model.  Please try to give
+#	references for the "big picture" of the physics, preferably to
+#	gr-qc and/or well-known books.  Please also explain the physics
+#	meanings of all the parameters -- users shouldn't have to look
+#	at your source code to figure out what a given parameter means!
+#   this file:
+#	Add the new model's character-string name as another possible value
+#	for the exact_model parameter.
+#   this file:
+#	Add a section later in this file giving the new model's parameters.
+#	(If there are no parameters this section should still be present,
+#	with a comment that there are no parameters.)
+#   src/include/param_defs.inc:
+#	Add a #define for your new model.
+#  	(You can renumber the existing values if you need to... but if
+#  	you do, make sure you do a make your-configuration-name-realclean
+#  	and recompile not just this thorn, but also all the evolution
+#  	thorns.)
+#   src/decode_pars.F:
+#	Add a case for your new model to the decode of the character-string
+#	model name into the integer decoded_exact_model.
+#   src/metric.F:
+#	Add a case for your new model to the decode of decoded_exact_model,
+#	calling a (new) subroutine named for your new model.
+#   src/metrics/your_model_name.F
+#	Create a new file in this directory with a Fortran 77/90 subroutine
+#	to compute the metric and the inverse metric for your new model
+#	(this is the subroutine you just added a call to, in src/metric.F).
+#	It's probably easiest to start with a copy of an existing file and
+#	modify it to compute your new metric -- that will help you get all
+#	the "boilerplate" code right.
+#   src/metrics/make.code.defn:
+#	Add the new file name to the list of files to be compiled.
+#
+# If your model needs to set up a stress-energy tensor (n.b. as described
+# in doc/documentation.tex, this also includes the case of a vacuum solution
+# with a cosmological constant), then you need to modify some additional
+# files:
+#   interface.ccl:
+#	Add copies of all your model's CCTK_INT and/or CCTK_REAL parameters
+#	to the Exact_pars_int and/or Exact_pars_real variable groups as
+#	appropriate, changing the "__" in the parameter names to "___".  
+#	If you have CCTK_COMPLEX parameters, add a corresponding variable
+#	group and do the same thing.  If you have KEYWORD or STRING
+#	parameters, see below.
+#   src/decode_pars.F:
+#	Add a block of code for your new model to copy all the model's
+#	parameters to the corresponding "___" grid scalars.
+#   src/include/Scalar_CalcTmunu.inc:
+#	Add a case for your new model to *add* the stress-energy tensor
+#	contribution on to the variables Ttt ... Tzz.  Note that this code
+#	will be compiled as part of various evolution thorns -- it doesn't
+#	have access to this thorn's parameters, only to the "___" grid
+#	scalars (that's why the "___" stuff is there in the first place!).
+#   src/include/Scalar_CalcTmunu_temps.inc:
+#	If you need temporary variables in your Scalar_CalcTmunu.inc
+#	code, declare them here.
+#
+# If your model has a KEYWORD or STRING parameter(s) and needs to set up
+# a stress-energy tensor, then because Cactus doesn't allow grid scalars
+# of these data types, you need to decode these parameter(s) into integers:
+#   interface.ccl
+#	Add CCTK_INT parameters for the decoded integer values.
+#   src/include/param_defs.inc:
+#	Add a new set of #defines giving all the possible values
+#	of the decoded integer(s) for your keyword/string parameter(s).
+#   src/decode_pars.F
+#	Add a block of code for your new model to decode the KEYWORD
+#	and/or STRING parameters into integers.  Don't forget to
+#	include a CCTK_WARN(0, "...") if the code doesn't recognize
+#	the string -- this helps to catch bugs where you (or someone
+#	else) misspells one of the strings somewhere.
+#
+# Finally, please add a test suite for your new model to the test/
+# directory.  (Alas, many of the existing models lack tests.  Sigh...)
+# The Cactus Users' Guide has a section  "Adding a test suite" (as of
+# this writing it's section B9.5) which explains how this works; basically
+# you just need to create
+#	test/my-test-name.par
+#	test/my-test-name/output-file-1
+#	test/my-test-name/output-file-2
+#	test/my-test-name/output-file-3
+# etc.  (The test should create the subdirectory itself, and write ASCII
+# output files there.  You can do this by including IOUtil in your thorn
+# list and putting
+#	IO::out_dir = "my-test-name"
+#	IO::parfile_write = "false"
+# in your test parameter file.)
+#
+
+################################################################################
+##### exact_model ##############################################################
+################################################################################
 
-# Parameters for boostrot
+private:
 
-REAL boostrotscale "Length scale of boost rotation data"
+KEYWORD exact_model "The exact solution used in thorn exact"
+{
+#
+# Minkowski spacetime
+#
+"Minkowski"            :: "Minkowski spacetime"
+"Minkowski/shift"      :: "Minkowski spacetime with time-dependent shift vector"
+"Minkowski/funny"      :: "Minkowski spacetime in non-trivial spatial coordinates"
+"Minkowski/gauge wave" :: "Minkowski spacetime in gauge-wave coordinates"
+#
+# black hole spacetimes
+#
+"Schwarzschild/EF"     :: "Schwarzschild spacetime in Eddington-Finkelstein coordinates"
+"Schwarzschild/PG"     :: "Schwarzschild spacetime in Painleve-Gullstrand coordinates"
+"Schwarzschild/Novikov":: "Schwarzschild spacetime in Novikov coordinates"
+"Schwarzschild-Lemaitre":: "Schwarzschild metric in Schwarzschild coordinates, with cosmological constant"
+"Kerr/Boyer-Lindquist" :: "Kerr spacetime in Boyer-Lindquist coordinates"
+"Kerr/Kerr-Schild"     :: "Kerr spacetime in Kerr-Schild coordinates"
+"multi-BH"             :: "Majumdar-Papapetrou or Kastor-Traschen maximally charged multi BH solutions"
+"Alvi"                 :: "Alvi post-Newtonian 2BH spacetime (not fully implemented yet)"
+"Thorne-fakebinary"    :: "Thorne's fake-binary spacetime (non-Einstein)"
+#
+# cosmological spacetimes
+#
+"Lemaitre"             :: "Lemaitre-type spacetime"
+"Robertson-Walker"     :: "Robertson-Walker spacetime"
+"de Sitter"            :: "de Sitter spacetime (R-W cosmology, near t=0, p=0)"
+"de Sitter+Lambda"     :: "de Sitter spacetime with cosmological constant"
+"anti-de Sitter+Lambda":: "anti-de Sitter spacetime with cosmological constant"
+"Bianchi I"            :: "approximate Bianchi type I spacetime"
+"Goedel"               :: "Goedel spacetime"
+"Bertotti"             :: "Bertotti spacetime"
+"Kasner-like"          :: "Kasner-like spacetime"
+"Kasner-axisymmetric"  :: "axisymmetric Kasner spacetime"
+"Kasner-generalized"   :: "generalized Kasner spacetime"
+"Milne"                :: "Milne spacetime for pre-big-bang cosmology"
+#
+# miscelaneous spacetimes
+#
+"boost-rotation symmetric":: "boost-rotation symmetric spacetime"
+"bowl"                 :: "bowl (bag-of-gold) spacetime (non-Einstein)"
+"constant density star":: "constant density (Schwarzschild) star"
+} "Minkowski"
+
+################################################################################
+##### Minkowski spacetime ######################################################
+################################################################################
+
+#
+# parameters for Minkowski spacetime (trivial txyz coordinates)
+#
+
+# there are no parameters
+
+################################################################################
+
+#
+# parameters for Minkowski spacetime with time-dependent shift vector
+#
+
+REAL Minkowski_shift__amplitude "Minkowski/shift: amplitude of Gaussian"
+{
+(-1:1) :: "any real number < 1 in absolute value"
+} 0.5
+
+REAL Minkowski_shift__sigma "Minkowski/shift: width of Gaussian"
 {
-0.0:  ::  "Positive please"
+(0.0:* :: "any real number > 0"
 } 1.0
 
-REAL boostrotstrength "Dimensionless strength parameter"
+################################################################################
+
+#
+# parameters for Minkowski spacetime with non-trivial spatial coordinates
+#
+
+# FIXME: can this also be negative, i.e. range (-1,1)?
+REAL Minkowski_funny__amplitude "Minkowski/funny: amplitude of Gaussian"
 {
-0.0:  ::  "Positive please"
-} 0.1
+[0.0:1.0 :: "any real number in the range [0,1)"
+} 0.5
 
-REAL boostrotsafedistance "Dimensionless safety distance"
+REAL Minkowski_funny__sigma "Minkowski/funny: width of Gaussian"
 {
-0.0:  ::  "Positive please"
-} 0.01
+(0.0: :: "any real number > 0"
+} 1.0
 
+################################################################################
 
-# Parameters for finkelstein and kerrschild.
+#
+# parameters for Minkowski spacetime in gauge-wave coordinates
+#
 
-REAL kerrschild_boostv "Boost speed of black hole"
+KEYWORD Minkowski_gauge_wave__what_fn \
+  "Minkowski/gauge wave: what function to use"
+{
+"sin"     :: "1-a*sin(x)"
+"expsin"  :: "exp(a*sin(x)*cos(t))"
+"Gaussian":: "1-a*exp(-x**2)"
+}"sin"
+ 
+REAL Minkowski_gauge_wave__amplitude \
+  "Minkowski/gauge wave: amplitude of the wave"
+{
+(-1:1)  ::  "any real number with absolute value < 1"
+}0.5
+  
+REAL Minkowski_gauge_wave__omega \
+  "Minkowski/gauge wave: angular frequency of the wave in time"
+{
+*:* :: "any real number"
+}1.0
+    
+BOOLEAN Minkowski_gauge_wave__diagonal \
+  "Minkowski/gauge wave: should the wave run diagonally across the grid?"
 {
-:  ::  "Positive or negative"
+} "no"
+   
+REAL Minkowski_gauge_wave__lambda \
+  "Minkowski/gauge wave: wavelength of waves"
+{
+*:* :: "any real number"
+} 0.5    
+
+REAL Minkowski_gauge_wave__phase \
+  "Minkowski/gauge wave: phase shift of wave"
+{
+*:* :: "any real number"
 } 0.0
 
-REAL kerrschild_eps "Fudge parameter"
+################################################################################
+##### black hole spacetimes ####################################################
+################################################################################
+
+#
+# parameters for Schwarzschild metric in Eddington-Finkelstein coordinates
+#
+
+REAL Schwarzschild_EF__mass "Schwarzschild/EF: BH mass"
 {
-:  ::  "Positive or negative"
+*:* :: "any real number"
+} 1.0
+
+REAL Schwarzschild_EF__epsilon "Schwarzschild/EF: numerical fudge"
+{
+0.0:*  ::  "any real number >= 0.0"
 } 1.e-16
 
-REAL kerrschild_m "Black hole mass"
+################################################################################
+
+#
+# parameters for Schwarzschild metric in Painleve-Gustrand coordinates
+#
+
+REAL Schwarzschild_PG__mass "Schwarzschild/PG: BH mass"
 {
-0.0:  ::  "Positive please"
+(0.0:*  ::  "any real number > 0.0"
 } 1.0
 
-REAL kerrschild_a "Black hole a = J/m"
+REAL Schwarzschild_PG__epsilon "Schwarzschild/PG: numerical fudge"
 {
-0.0:  ::  "Positive or negative"
-} 0.0
+0.0:*  ::  "any real number >= 0.0"
+} 1.e-16
 
+################################################################################
 
-# Parameters for Schwarzschild star.
+# parameters for Schwarzschild metric in Novikov coordinates
 
-REAL starschwarz_m "Mass of Schwarzschild star"
+REAL Schwarzschild_Novikov__mass "Schwarzschild/Novikov: BH mass"
 {
-0.0:  ::  "Positive please"
+(0.0:*  ::  "any real number > 0.0"
 } 1.0
 
+REAL Schwarzschild_Novikov__epsilon "Schwarzschild/Novikov: numerical fudge"
+{
+0.0:*  ::  "any real number >= 0.0"
+} 1.e-16
+
+################################################################################
+
+# parameters for Schwarzschild-Lemaitre metric
+# (Schwarzschild black hole with cosmological constant)
 
-REAL  starschwarz_r "Radius of Schwarzschild star"
+REAL Schwarzschild_Lemaitre__Lambda "Schwarzschild-Lemaitre: cosmological constant"
 {
-0.0:  ::  "Positive please"
+*:* :: "any real number"
+} 1.0
+
+REAL Schwarzschild_Lemaitre__mass "Schwarzschild-Lemaitre: BH mass"
+{
+(0.0:* :: "any real number > 0"
 } 1.0
 
+################################################################################
 
-# Parameters for bowl metric.
+# parameters for Kerr metric in Boyer-Lindquist coordinates
 
-KEYWORD bowl_type "Type of bowl metric"
+REAL Kerr_BoyerLindquist__spin "Kerr/Boyer-Lindquist: spin parameter a = J/m^2"
 {
-  gauss :: "Gaussian bowl"
-  fermi :: "Fermi bowl"
-} "gauss"
+-1.0:1.0 :: "spin parameter for Kerr black hole"
+} 0.6
 
-BOOLEAN bowl_evolve "Evolving bowl metric?"
+REAL Kerr_BoyerLindquist__mass "Kerr/Boyer-Lindquist: BH mass"
 {
-} "no"
+(0.0:*  ::  "any real number > 0"
+} 1.0
+
+################################################################################
 
-REAL bowl_a "Bowl strength"
+#
+# parameters for Kerr metric in Kerr-Schild coordinates
+#
+
+REAL Kerr_KerrSchild__boost_v "Kerr/Kerr-Schild: boost velocity of black hole"
 {
-0.0:  ::  "Positive please" 
-} 0.5
+(-1:1)  ::  "any real number with absolute value < 1"
+} 0.0
 
-REAL bowl_c "Center of deformation"
+REAL Kerr_KerrSchild__epsilon "Kerr/Kerr-Schild: numerical fudge"
 {
-0.0:  ::  "Positive please" 
-} 2.5
+0.0:*  ::  "any real number >= 0.0"
+} 1.e-16
 
-REAL bowl_s "Width of deformation"
+REAL Kerr_KerrSchild__mass "Kerr/Kerr-Schild: BH mass"
 {
-0.0:  ::  "Positive please" 
+(0.0:*  ::  "any real number > 0"
 } 1.0
 
-REAL bowl_dx "Scale factor in x direction"
+REAL Kerr_KerrSchild__spin "Kerr/Kerr-Schild: spin parameter a = J/m^2"
 {
-0.0:  ::  "Positive please" 
-} 1.0
+-1.0:1.0 :: "spin parameter for Kerr black hole"
+} 0.6
+
+################################################################################
 
-REAL bowl_dy "Scale factor in y direction"
+#
+# parameters for Majumdar-Papapetrou or Kastor-Traschen
+# maximally-charged multiple black hole solution
+#
+
+INT multi_BH__nBH "multi-BH: number of black holes 0-4"
 {
-0.0:  ::  "Positive please" 
-} 1.0
+0:4 :: "any integer in the range [0,4]"
+} 0
 
-REAL bowl_dz "Scale factor in z direction"
+REAL multi_BH__Hubble "multi-BH: Hubble constant = +/- sqrt{Lambda/3}"
 {
-0.0:  ::  "Positive please" 
-} 1.0
+*:* :: "any real number"
+} 0.0
+
+# black hole #1
+REAL multi_BH__mass1 "multi-BH: mass of black hole number 1"
+{
+0.0: :: "any real number >= 0"
+} 0.0
+REAL multi_BH__x1 "multi-BH: x coord of black hole number 1"
+{
+*:* :: "any real number"
+} 0.0
+REAL multi_BH__y1 "multi-BH: y coord of black hole number 1"
+{
+*:* :: "any real number"
+} 0.0
+REAL multi_BH__z1 "multi-BH: z coord of black hole number 1"
+{
+*:* :: "any real number"
+} 0.0
 
-REAL bowl_t0 "Center of Fermi step in time"
+# black hole #2
+REAL multi_BH__mass2 "multi-BH: mass of black hole number 2"
+{
+0.0: :: "any real number >= 0"
+} 0.0
+REAL multi_BH__x2 "multi-BH: x coord of black hole number 2"
+{
+*:* :: "any real number"
+} 0.0
+REAL multi_BH__y2 "multi-BH: y coord of black hole number 2"
+{
+*:* :: "any real number"
+} 0.0
+REAL multi_BH__z2 "multi-BH: z coord of black hole number 2"
 {
-0.0:  ::  "Positive please" 
+*:* :: "any real number"
+} 0.0
+
+# black hole #3
+REAL multi_BH__mass3 "multi-BH: mass of black hole number 3"
+{
+0.0: :: "any real number >= 0"
+} 0.0
+REAL multi_BH__x3 "multi-BH: x coord of black hole number 3"
+{
+*:* :: "any real number"
+} 0.0
+REAL multi_BH__y3 "multi-BH: y coord of black hole number 3"
+{
+*:* :: "any real number"
+} 0.0
+REAL multi_BH__z3 "multi-BH: z coord of black hole number 3"
+{
+*:* :: "any real number"
+} 0.0
+
+# black hole #4
+REAL multi_BH__mass4 "multi-BH: mass of black hole number 4"
+{
+0.0: :: "any real number >= 0"
+} 0.0
+REAL multi_BH__x4 "multi-BH: x coord of black hole number 4"
+{
+*:* :: "any real number"
+} 0.0
+REAL multi_BH__y4 "multi-BH: y coord of black hole number 4"
+{
+*:* :: "any real number"
+} 0.0
+REAL multi_BH__z4 "multi-BH: z coord of black hole number 4"
+{
+*:* :: "any real number"
+} 0.0
+
+################################################################################
+
+#
+# parameters for Alvi spacetime
+#
+
+REAL Alvi__mass1 "Alvi: mass of BH number 1"
+{
+0.0: :: "any real number >= 0"
 } 1.0
 
-REAL bowl_st "Width of Fermi step in time"
+REAL Alvi__mass2 "Alvi: mass of BH number 2"
 {
-0.0:  ::  "Positive please" 
+0.0: :: "any real number >= 0"
 } 1.0
 
+REAL Alvi__separation "Alvi: spatial separation of the black holes"
+{
+0.0:* :: "must be greater than m1+m2 + 2 sqrt(m1 m2)"
+} 20.0
 
-# Parameters for Thorne's fake finary.
+################################################################################
 
-KEYWORD fakebinary_atype "Thorne's binary type"
+#
+# parameters for Thorne's fake binary solution
+#
+
+KEYWORD Thorne_fakebinary__atype "Thorne-fakebinary: binary type"
 {
   "constant"  :: ""
   "quadrupole :: ""
 } "constant"
 
-BOOLEAN fakebinary_retarded "Use retarded time?"
+BOOLEAN Thorne_fakebinary__retarded "Thorne-fakebinary: use retarded time?"
 {
 } "no"
 
-REAL fakebinary_eps "Thorne's binary: fudge parameter"
+# FIXME: can this really be exactly 0.0?
+REAL Thorne_fakebinary__epsilon "Thorne-fakebinary: numerical fudge"
 {
-0.0: :: "Positive please"
+0.0:*  ::  "any real number >= 0.0"
 } 1.e-16
 
-REAL fakebinary_a0 "Thorne's binary: initial separation"
+REAL Thorne_fakebinary__separation "Thorne-fakebinary: initial separation"
 {
-0.0: :: "Positive please"
+(0.0:* :: "any real number > 0"
 } 5.0
 
-REAL fakebinary_omega0 "Thorne's binary: initial angular frequency"
+REAL Thorne_fakebinary__Omega0 "Thorne-fakebinary: initial angular frequency"
 {
-: :: "Positive or negative"
+(0.0:* :: "any real number > 0"
 } 1.0
 
-REAL fakebinary_m "Thorne's binary: mass"
+REAL Thorne_fakebinary__mass "Thorne-fakebinary: mass"
 {
-0.0: :: "Positive please"
-} 0.1
+(0.0:* :: "any real number > 0"
+} 1.0
 
-REAL fakebinary_bround "Thorne's binary: smoothing for Newtonian potential"
+# FIXME: can this really be exactly 0.0?
+REAL Thorne_fakebinary__smoothing \
+  "Thorne-fakebinary: smoothing for Newtonian potential"
 {
-: :: "Positive or negative"
+0.0:* :: "any real number >= 0"
 } 0.0
 
+################################################################################
+##### cosmological spacetimes ##################################################
+################################################################################
 
-# Parameters for multiBH.
+#
+# parameters for Lemaitre-type spacetime
+#
 
-INT kt_nBH "number of black holes 0-4"
+REAL Lemaitre__kappa "Lemaitre: multiplicative factor in equation of state"
 {
-0: :: "Positive please"
-} 0
+*:* :: "any real number"
+} -0.5
 
-REAL kt_hubble "Hubble constant= pm sqrt{Lambda/3}"
+REAL Lemaitre__Lambda "Lemaitre: cosmological constant"
 {
-: :: "Positive or negative"
-} 0.0
+*:* :: "any real number"
+} 1.0
 
-REAL m_bh1 "mass of black hole 1"
+REAL Lemaitre__epsilon0 "Lemaitre: density of the universe at time t=0"
 {
-0.0: :: "Positive please"
-} 0.0
+0.0:* :: "any real number >= 0"
+} 1.0
 
-REAL m_bh2 "mass of black hole 2"
+REAL Lemaitre__R0 "Lemaitre: scale factor (radius) of the universe at time t=0"
 {
-0.0: :: "Positive please"
-} 0.0
+(0.0:* :: "any positive real number"
+} 1.0
 
-REAL m_bh3 "mass of black hole 3"
-{
-0.0: :: "Positive please"
-} 0.0
+################################################################################
 
-REAL m_bh4 "mass of black hole 4"
-{
-0.0: :: "Positive please"
-} 0.0
+#
+# parameters for Robertson-Walker spacetime
+#
 
-REAL co_bh1x "x coord of black hole 1"
+REAL Robertson_Walker__R0 \
+  "Robertson-Walker: scale factor (radius) of the universe at time t=0"
 {
-: :: "Positive or negative"
-} 0.0
+(0.0:* :: "any positive real number"
+} 0.1
 
-REAL co_bh1y "y coord of black hole 1"
+REAL Robertson_Walker__rho "Robertson-Walker: density parameter"
 {
-: :: "Positive or negative"
-} 0.0
+0.0:* :: "any real number >= 0"
+} 0.1
 
-REAL co_bh1z "z coord of black hole 1"
+INT Robertson_Walker__k "Robertson-Walker: geometry type parameter"
 {
-: :: "Positive or negative"
-} 0.0
+-1:1:1 :: "one of the values -1, 0, 1"
+} 0
 
-REAL co_bh2x "x coord of black hole 2"
+# true ==> include pressure terms (radiation-dominated universe)
+# false ==> don't include pressure terms (matter-dominated universe)
+BOOLEAN Robertson_Walker__pressure \
+  "Robertson-Walker: are pressure terms included?"
 {
-: :: "Positive or negative"
-} 0.0
+} "true"
 
-REAL co_bh2y "y coord of black hole 2"
-{
-: :: "Positive or negative"
-} 0.0
+################################################################################
 
-REAL co_bh2z "z coord of black hole 2"
+#
+# parameters for de Sitter spacetime
+#
+
+REAL de_Sitter__scale "de Sitter: multiplicative scale factor"
 {
-: :: "Positive or negative"
-} 0.0
+(0.0:*  :: "any positive real number"
+} 0.1
+
+################################################################################
 
-REAL co_bh3x "x coord of black hole 3"
+#
+# parameters for de Sitter spacetime with cosmological constant
+#
+
+REAL de_Sitter_Lambda__scale "de Sitter+Lambda: multiplicative scale factor"
 {
-: :: "Positive or negative"
-} 0.0
+(0.0:*  :: "any positive real number"
+} 0.1
 
-REAL co_bh3y "y coord of black hole 3"
+################################################################################
+
+#
+# parameters for anti-de Sitter spacetime with cosmological constant
+#
+
+REAL anti_de_Sitter_Lambda__scale \
+  "anti-de Sitter+Lambda: multiplicative scale factor"
 {
-: :: "Positive or negative"
-} 0.0
+(0.0:*  :: "any positive real number"
+} 0.1
 
-REAL co_bh3z "z coord of black hole 3"
+################################################################################
+
+#
+# parameters for Bianchi type I cosmology
+#
+
+REAL Bianchi_I__scale "Bianchi I: multiplicative scale factor"
 {
-: :: "Positive or negative"
-} 0.0
+(0.0:* :: "any positive real number"
+} 0.1
+
+################################################################################
+
+#
+# parameters for Goedel spacetime
+#
 
-REAL co_bh4x "x coord of black hole 4"
+REAL Goedel__scale "Goedel: multiplicative scale factor"
 {
-: :: "Positive or negative"
-} 0.0
+(0.0:* :: "any positive real number"
+} 0.1
+
+################################################################################
 
-REAL co_bh4y "y coord of black hole 4"
+#
+# parameters for Bertotti spacetime
+#
+
+REAL Bertotti__Lambda "Bertotti: cosmological constant"
 {
-: :: "Positive or negative"
-} 0.0
+*:*    :: "any real number"
+} -1.0
+
+################################################################################
 
-REAL co_bh4z "z coord of black hole 4"
+#
+# parameters for Kasner-like spacetime
+#
+
+# FIXME: can we somehow use the expression 2.0/3.0 for the default value?
+REAL Kasner_like__q "Kasner-like: q parameter"
 {
-: :: "Positive or negative"
-} 0.0
+*:* :: "any real number"
+} 0.66666666666666666666
+
+################################################################################
 
+#
+# parameters for axisymmetric Kasner spacetime
+#
 
-# Parameters for flatfunny.
+# there are no parameters
 
-REAL flatfunny_a "Amplitude of gaussian"
+################################################################################
+
+#
+# parameters for generalized Kasner spacetime
+#
+
+REAL Kasner_generalized__p1 "Kasner-generalized: x exponent parameter"
 {
-0.0:1.0 :: "Positive and smaller than 1 please"
-} 0.0
+[-1.0:1.0] :: "any real number in the range [-1,1]"
+} 0.1
 
-REAL flatfunny_s "Width of gaussian"
+REAL Kasner_generalized__p2 "Kasner-generalized: y exponent parameter"
 {
-0.0: :: "Positive please"
-} 1.0
+[-1.0:1.0] :: "any real number in the range [-1,1]"
+} 0.1
 
-# Parameters for flatshift.
+################################################################################
 
-REAL flatshift_a "Amplitude of gaussian"
-{
-:1 :: "Anything goes"
-} 0.0
+#
+# parameters for Milne spacetime
+#
+
+# there are no parameters
+
+################################################################################
+##### miscellaneous spacetimes #################################################
+################################################################################
+
+#
+# parameters for boost-rotation symmetricmetric spacetime
+#
 
-REAL flatshift_s "Width of gaussian"
+REAL boost_rotation_symmetric__scale "boost-rotation symmetric: length scale"
 {
-0.0: :: "Positive please"
+0.0:  ::  "Positive please"
 } 1.0
 
-# Parameters for Kasner_like metric
+REAL boost_rotation_symmetric__amp \
+  "boost-rotation symmetric: dimensionless amplitude"
+{
+0.0:  ::  "Positive please"
+} 0.1
 
-REAL kasner_q "...  "
+REAL boost_rotation_symmetric__min_d \
+  "boost-rotation symmetric: dimensionless safety distance"
 {
-0.0:100 :: "Can be also negativ, but here is ...     "
-} 0.66666
+(0.0:  ::  "any positive real number"
+} 0.01
 
+################################################################################
 
-# Parameters for bianchiI
+#
+# parameters for bowl (bag-of-gold) spacetime (non-Einstein)
+#
 
-REAL bia "Parameter for bianchi I space-time"
+KEYWORD bowl__shape "bowl: what shape of bowl should we use?"
 {
-0.0:1.7 :: "Positive please"
-} 0.1
+  "Gaussian" :: "Gaussian bowl"
+  "Fermi"    :: "Fermi-function bowl"
+} "Gaussian"
 
-# Parameters for godel
+BOOLEAN bowl__evolve "bowl: are we evolving the metric?"
+{
+} "false"
 
-REAL godel_a "Parameter for Godel space-time "
+# FIXME: can this really be arbitrarily large?
+# FIXME: can this be negative?
+REAL bowl__strength "bowl: deformation strength"
 {
-0.0:1.7 :: "Positive please"
-} 0.1
+0.0:* ::  "any real number >= 0"
+} 0.5
 
-# Parameters for kerr
+REAL bowl__center "bowl: deformation center"
+{
+(0.0:*  ::  "any positive real number"
+} 2.5
 
-REAL kerrc_a "Paramater for Kerr space-time in cartezian coord"
+# n.b. for bowl__shape = "Gaussian", this parameter is actually
+#      sqrt(2) times the standard deviation of the Gaussian
+REAL bowl__sigma "bowl: width of deformation"
 {
-0.0:7.0 :: "Positive please"
+(0.0:*  ::  "any positive real number"
 } 1.0
 
-REAL kerrc_m "Kerr mass"
+REAL bowl__x_scale "bowl: scale for x coordinate"
 {
-0.0:7.0   :: "Positive please"
+(0.0:*  ::  "any positive real number"
 } 1.0
 
-# Paramaters for DeSitter
+REAL bowl__y_scale "bowl: scale for y coordinate"
+{
+(0.0:*  ::  "any positive real number"
+} 1.0
 
-REAL desitt_a "Parameter for DeSitter space-time"
+REAL bowl__z_scale "bowl: scale for z coordinate"
 {
-0.0:1000.0 :: "Positive please"
-} 0.1
+(0.0:*  ::  "any positive real number"
+} 1.0
 
-REAL desitt_b "Parameter for DeSitter space-time"
+REAL bowl__t0 "bowl: center of Fermi step in time"
 {
-0.0:1000.0 :: "Positive please"
-} 0.1
+*:* ::  "any real number"
+} 1.0
 
+REAL bowl__sigma_t "bowl: width of Fermi step in time"
+{
+(0.0:*  ::  "any positive real number"
+} 1.0
 
-#########################
-### GaugeWave Params  ###
-#########################
-shares: driver
+################################################################################
 
-USES INT ghost_size
-USES INT global_nx
+#
+# parameters for constant density (Schwarzschild) star
+#
 
-private:
-KEYWORD GW_H "what function to use"
-{
-"sin"    :: "1-a*sin(x)"
-"expsin" :: "exp(a*sin(x)*cos(t))"
-"gau"    :: "1-a*exp(-x**2)"
-}"sin"
- 
-REAL GW_a "amplitude of the wave"
-{
-*:: "anything (better smaller than 1)"
-}0.5
-  
-REAL GW_omega "amplitude of the wave"
-{
-*:: "anything"
-}1.0
-    
-BOOLEAN GW_diagonal "let the wave run diagonally across the grid"
+REAL constant_density_star__mass "constant density star: mass of star"
 {
-}"no"
-   
-REAL GW_del "distance of waves"
-{
-*:: "anything"
-}0.5    
+(0.0:*  ::  "any positive real number"
+} 1.0
 
-REAL GW_phase_shift "phase shift of 1d wave"
+# FIXME: is this default value ok? (does it give a star or a BH?)
+REAL  constant_density_star__radius "constant density star: radius of star"
 {
-*:: "anything"
-} 0.0
+(0.0:*  ::  "any positive real number"
+} 1.0
+
+################################################################################