Centralize some runtime parameters and their docs (#1749)

zingale · web-flow · commit f9d54de7bdf2 · 2025-02-13T13:08:05.000-05:00
in particular, this moves small_temp and small_dens to the top-level unit_test/_parameters, since every test needs them. We override it in a few tests, since they need much different defaults.

This also moves the documentation about initializing composition up to a new centralized page, so we don't need to repeat it for every test.
diff --git a/Docs/source/burn_cell.rst b/Docs/source/burn_cell.rst
@@ -52,39 +52,17 @@ The parameters that affect the thermodynamics are:
 
 * ``unit_test.temperature`` : the initial temperature
 
-* ``unit_test.small_temp`` : the low temperature cutoff used in the equation of state
+The composition can be set either by specifying individual mass fractions
+or setting ``unit_test.uniform_xn`` as described in :ref:`sec:defining_unit_test_composition`.
 
-* ``unit_test.small_dens`` : the low density cutoff used in the equation of state
-
-The composition can be set either by setting each mass fraction explicitly via the
-parameters, ``unit_test.X1``, ``unit_test.X2``, ...,
-e.g.:
-
-::
-
-    unit_test.X1 = 0.5
-    unit_test.X2 = 0.2
-    unit_test.X3 = 0.2
-    unit_test.X4 = 0.1
-
-where parameters up to ``X35`` are available.  If the values don't sum to ``1``
-initially, then the test will do a normalization.  This normalization can be
-disabled by setting:
+If the values don't sum to ``1`` initially, then the test will do a
+normalization.  This normalization can be disabled by setting:
 
 ::
 
     unit_test.skip_initial_normalization = 1
 
 
-Alternately, the composition can be set automatically by initializing all
-of the mass fractions equally (to $1/N$, where $N$ is the number of species),
-by setting:
-
-::
-
-    unit_test.uniform_xn = 1
-
-
 Controlling time
 ----------------
 
diff --git a/Docs/source/comprehensive_tests.rst b/Docs/source/comprehensive_tests.rst
@@ -1,3 +1,5 @@
+.. _sec:comprehensive_tests:
+
 ************************
 Comprehensive Unit Tests
 ************************
diff --git a/Docs/source/eos_cell.rst b/Docs/source/eos_cell.rst
@@ -28,14 +28,8 @@ The parameters that affect the thermodynamics are:
 
 * ``unit_test.temperature`` : the initial temperature
 
-* ``unit_test.small_temp`` : the low temperature cutoff used in the equation of state
-
-* ``unit_test.small_dens`` : the low density cutoff used in the equation of state
-
-The composition can be set in the same way as in ``burn_cell``, either
-by setting each mass fraction explicitly via the parameters,
-``unit_test.X1``, ``unit_test.X2``, ..., or forcing them to be all
-equal via ``unit_test.uniform_xn=1``.
+The composition can be set either by specifying individual mass fractions
+or setting ``unit_test.uniform_xn`` as described in :ref:`sec:defining_unit_test_composition`.
 
 
 Building and Running the Code
diff --git a/Docs/source/index.rst b/Docs/source/index.rst
@@ -92,6 +92,7 @@ system.
    :hidden:
 
    unit_tests
+   unit_test_runtime_parameters
    comprehensive_tests
    one_zone_tests
 
diff --git a/Docs/source/jac_cell.rst b/Docs/source/jac_cell.rst
@@ -38,14 +38,15 @@ The parameters that affect the thermodynamics are:
 
 * ``unit_test.temperature`` : the initial temperature
 
-* ``unit_test.small_temp`` : the low temperature cutoff used in the equation of state
+The composition can be set either by specifying individual mass fractions
+or setting ``unit_test.uniform_xn`` as described in :ref:`sec:defining_unit_test_composition`.
 
-* ``unit_test.small_dens`` : the low density cutoff used in the equation of state
+If the values don't sum to ``1`` initially, then the test will do a
+normalization.  This normalization can be disabled by setting:
 
-While the mass fractions can be set individually (using
-``unit_test.X1``, ``unit_test.X2``, ...), it is recommended to use
-``unit_test.uniform_xn=1`` to initialize all the mass fractions to be
-equal.
+::
+
+    unit_test.skip_initial_normalization = 1
 
 
 Building and Running the Code
diff --git a/Docs/source/one_zone_tests.rst b/Docs/source/one_zone_tests.rst
@@ -1,3 +1,5 @@
+.. _sec:one_zone_tests:
+
 **************
 One Zone Tests
 **************
diff --git a/Docs/source/unit_test_runtime_parameters.rst b/Docs/source/unit_test_runtime_parameters.rst
@@ -0,0 +1,58 @@
+***********************************
+Unit Test Common Runtime Parameters
+***********************************
+
+There are a number of runtime parameters that are common to all (or most) of the unit tests.
+These are defined in the top-level ``unit_test/_parameters`` file.
+
+Thermodynamics
+==============
+
+The equation of state enforces minimum density and temperatures, which must be set
+upon initialization.  These are controlled by the following runtime parameters:
+
+* ``unit_test.small_temp`` : the low temperature cutoff used in the equation of state
+
+* ``unit_test.small_dens`` : the low density cutoff used in the equation of state
+
+
+.. _sec:defining_unit_test_composition:
+
+Defining composition
+====================
+
+Most of the unit tests require a composition to be defined (for the
+initial mass-fractions, $X_k$).  There are a few ways this can be done
+(depending on the test).
+
+* One-zone (``*_cell``) tests (see :ref:`sec:one_zone_tests`) usually do one of:
+
+  * *Explicitly setting the individual mass fractions.*  This is
+    controlled by the parameters ``unit_test.X1``, ``unit_test.X2``, ..., ``unit_test.X35``,
+    e.g.:
+
+    ::
+
+        unit_test.X1 = 0.5
+        unit_test.X2 = 0.2
+        unit_test.X3 = 0.2
+        unit_test.X4 = 0.1
+
+    While many of the tests will renormalize the abundances, the user
+    should take care to ensure that the mass fractions sum to unity.
+
+  * *Setting the composition to be uniform.*  This is controlled by
+    ``unit_test.uniform_xn``.  If this is set to ``1``, then each mass fraction
+    is initialized to ``1 / NumSpec``.
+
+* Comprehensive tests (see :ref:`sec:comprehensive_tests`) need many different compositions, since they are creating a cube
+  of varying thermodynamic properties, and thus require a prescription
+  to create the composition.  This is done by setting ``unit_test.primary_species_1``,
+  ``unit_test.primary_species_2``, and ``unit_test.primary_species_3`` to one of the
+  *names* of the species in the network.
+
+  The function ``setup_composition()`` is then used to set limits on
+  the species abundances (it takes a parameter which is the index into
+  the cube of data that is being initialized) which is then used by
+  ``get_xn()`` to create the individual mass fractions.  Both of these
+  routines are contained in ``react_util.H``.
diff --git a/unit_test/_parameters b/unit_test/_parameters
@@ -40,5 +40,12 @@ X33           real       0.0e0
 X34           real       0.0e0
 X35           real       0.0e0
 
+# do we set all of the mass fractions equal (to 1/NumSpec)?
 uniform_xn    bool        0
 
+# lowest temperature allowed in the EOS
+small_temp    real       1.e5
+
+# lowest density allowed in the EOS
+small_dens    real       1.e5
+
diff --git a/unit_test/burn_cell/_parameters b/unit_test/burn_cell/_parameters
@@ -1,8 +1,5 @@
 @namespace: unit_test
 
-small_temp    real       1.e5
-small_dens    real       1.e5
-
 # the final time to integrate to
 tmax          real       1.e-2
 
diff --git a/unit_test/burn_cell_metal_chem/_parameters b/unit_test/burn_cell_metal_chem/_parameters
@@ -3,8 +3,8 @@
 run_prefix    string  "burn_cell_metal_chem"
 
 # floor values of temperature and density
-small_temp    real       1.e1
-small_dens    real       1.e-30
+small_temp    real       1.e1           100
+small_dens    real       1.e-30         100
 
 # the final time to integrate to
 tmax          real       1.e20
diff --git a/unit_test/burn_cell_primordial_chem/_parameters b/unit_test/burn_cell_primordial_chem/_parameters
@@ -3,8 +3,8 @@
 run_prefix    string  "burn_cell_primordial_chem"
 
 # floor values of temperature and density
-small_temp    real       1.e1
-small_dens    real       1.e-30
+small_temp    real       1.e1           100
+small_dens    real       1.e-30         100
 
 # the final time to integrate to
 tmax          real       1.e20
diff --git a/unit_test/burn_cell_sdc/_parameters b/unit_test/burn_cell_sdc/_parameters
@@ -1,8 +1,5 @@
 @namespace: unit_test
 
-small_temp    real       1.e5
-small_dens    real       1.e5
-
 # the final time to integrate to
 tmax          real       1.e-2
 
diff --git a/unit_test/eos_cell/_parameters b/unit_test/eos_cell/_parameters
@@ -1,7 +1,4 @@
 @namespace: unit_test
 
-small_temp    real       1.e5
-small_dens    real       1.e5
-
 density       real       1.e7
 temperature   real       3.e9
diff --git a/unit_test/jac_cell/_parameters b/unit_test/jac_cell/_parameters
@@ -1,8 +1,5 @@
 @namespace: unit_test
 
-small_temp    real       1.e5
-small_dens    real       1.e5
-
 density       real       1.e7
 
 temperature   real       3.e9
diff --git a/unit_test/nse_net_cell/_parameters b/unit_test/nse_net_cell/_parameters
@@ -2,9 +2,6 @@
 
 run_prefix    string     ""
 
-small_temp    real       1.e5
-small_dens    real       1.e5
-
 density       real       1.e7
 
 temperature   real       3.e9
diff --git a/unit_test/nse_net_cell/make_table/_parameters b/unit_test/nse_net_cell/make_table/_parameters
@@ -1,8 +1,5 @@
 @namespace: unit_test
 
-small_dens  real  1.e5
-small_temp  real  1.e5
-
 rho_min   real   1.e6
 rho_max   real   1.e10
 
diff --git a/unit_test/nse_table_cell/_parameters b/unit_test/nse_table_cell/_parameters
@@ -1,8 +1,5 @@
 @namespace: unit_test
 
-small_temp    real       1.e5
-small_dens    real       1.e5
-
 density       real    1.23e9
 temperature   real    5.18e9
 ye            real    0.472
diff --git a/unit_test/part_func_cell/_parameters b/unit_test/part_func_cell/_parameters
@@ -1,7 +1,4 @@
 @namespace: unit_test
 
-small_temp    real       1.e5
-small_dens    real       1.e5
-
 temperature   real    5.e9
 
diff --git a/unit_test/test_aprox_rates/_parameters b/unit_test/test_aprox_rates/_parameters
@@ -6,6 +6,3 @@ temp_min      real       1.e6
 temp_max      real       1.e12
 
 metalicity_max  real     0.1e0
-
-small_temp    real        1.e4
-small_dens    real        1.e-4
diff --git a/unit_test/test_conductivity/_parameters b/unit_test/test_conductivity/_parameters
@@ -6,6 +6,3 @@ temp_min      real       1.e6
 temp_max      real       1.e12
 
 metalicity_max  real     0.1e0
-
-small_temp    real        1.e4
-small_dens    real        1.e-4
diff --git a/unit_test/test_eos/_parameters b/unit_test/test_eos/_parameters
@@ -6,6 +6,3 @@ temp_min      real       1.e6
 temp_max      real       1.e12
 
 metalicity_max  real     0.1e0
-
-small_temp    real        1.e4
-small_dens    real        1.e-4
diff --git a/unit_test/test_jac/_parameters b/unit_test/test_jac/_parameters
@@ -9,6 +9,3 @@ uniform_xn    int        0
 
 tmax          real       0.1e0
 
-small_temp    real       1.e5
-small_dens    real       1.e5
-
diff --git a/unit_test/test_linear_algebra/_parameters b/unit_test/test_linear_algebra/_parameters
@@ -1,4 +1 @@
 @namespace: unit_test
-
-small_temp    real       1.e5
-small_dens    real       1.e5
diff --git a/unit_test/test_neutrino_cooling/_parameters b/unit_test/test_neutrino_cooling/_parameters
@@ -6,6 +6,3 @@ temp_min      real       1.e6
 temp_max      real       1.e12
 
 metalicity_max  real     0.1e0
-
-small_temp    real        1.e4
-small_dens    real        1.e-4
diff --git a/unit_test/test_nse_interp/_parameters b/unit_test/test_nse_interp/_parameters
@@ -1,8 +1,5 @@
 @namespace: unit_test
 
-small_temp    real       1.e5
-small_dens    real       1.e5
-
 density       real    1.23e9
 temperature   real    5.18e9
 ye            real    0.472
diff --git a/unit_test/test_parameters/_parameters b/unit_test/test_parameters/_parameters
@@ -5,7 +5,4 @@ dens_max      real       1.e9
 temp_min      real       1.e6
 temp_max      real       1.e12
 
-small_temp    real        1.e4
-small_dens    real        1.e-4
-
 test_string   string      "test"
diff --git a/unit_test/test_react/_parameters b/unit_test/test_react/_parameters
@@ -7,6 +7,3 @@ temp_max      real       1.e15
 
 tmax          real       0.1e0
 
-small_temp    real       1.e5
-small_dens    real       1.e5
-
diff --git a/unit_test/test_rhs/_parameters b/unit_test/test_rhs/_parameters
@@ -4,8 +4,3 @@ dens_min      real       1.e6
 dens_max      real       1.e9
 temp_min      real       1.e6
 temp_max      real       1.e15
-
-uniform_xn    int        0
-
-small_temp    real       1.e5
-small_dens    real       1.e5
diff --git a/unit_test/test_screening_templated/_parameters b/unit_test/test_screening_templated/_parameters
@@ -7,7 +7,4 @@ temp_max      real       1.e12
 
 metalicity_max  real     0.1e0
 
-small_temp    real        1.e4
-small_dens    real        1.e-4
-
 loops         int        1
diff --git a/unit_test/test_sdc/_parameters b/unit_test/test_sdc/_parameters
@@ -5,11 +5,4 @@ dens_max      real       1.e9
 temp_min      real       1.e6
 temp_max      real       1.e15
 
-# uniform composition
-uniform_xn    int        0
-
 tmax          real       0.1e0
-
-small_temp    real       1.e5
-small_dens    real       1.e3
-
diff --git a/unit_test/test_sdc_vode_rhs/_parameters b/unit_test/test_sdc_vode_rhs/_parameters
@@ -1,8 +1,5 @@
 @namespace: unit_test
 
-small_temp    real       1.e5
-small_dens    real       1.e5
-
 density       real       1.e7
 
 temperature   real       3.e9
diff --git a/unit_test/test_sdc_vode_rhs/vode_rhs_test.H b/unit_test/test_sdc_vode_rhs/vode_rhs_test.H
@@ -23,7 +23,7 @@ void do_vode_rhs()
 
     for (int n = 1; n <= NumSpec; ++n) {
 
-        massfractions[n-1] = get_xn(n);
+        massfractions[n-1] = get_xn(n, unit_test_rp::uniform_xn);
 
         if (massfractions[n-1] < 0 || massfractions[n-1] > 1) {
             amrex::Error("mass fraction for " + short_spec_names_cxx[n-1] + " not initialized in the interval [0,1]!");

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _sec:comprehensive_tests:`
	`2`	`+`
`1`	`3`	`************************`
`2`	`4`	`Comprehensive Unit Tests`
`3`	`5`	`************************`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _sec:one_zone_tests:`
	`2`	`+`
`1`	`3`	`**************`
`2`	`4`	`One Zone Tests`
`3`	`5`	`**************`