clean-up and document jac_cell

.github/workflows/jac_cell.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Run jac_cell
         run: |
           cd unit_test/jac_cell
-          ./main3d.gnu.ex inputs_aprox13 > test.out
+          ./main3d.gnu.ex inputs > test.out
 
       - name: Compare to stored output
         run: |

Docs/source/eos_cell.rst

@@ -1,3 +1,5 @@
+.. _sec:eos_cell:
+
 ************
 ``eos_cell``
 ************

Docs/source/jac_cell.rst

@@ -0,0 +1,98 @@
+.. _sec:jac_cell:
+
+************
+``jac_cell``
+************
+
+.. index:: jac_cell, numerical_jacobian.H
+
+``jac_cell`` is used to test the accuracy of an analytic Jacobian
+provided by a network, but comparing to a finite-difference
+approximation.  Given a thermodynamic state, ``jac_cell`` evaluates
+the analytic Jacobian as well as a numerical approximation to it, and
+then outputs (to ``stdout``) the Jacobian elements side-by-side for
+each method of computing the Jacobian.
+
+.. note::
+
+   Some integrators, like VODE, have their own numerical Jacobian
+   routines.  This test uses the implementation in
+   ``integration/util/numerical_jacobian.H``, which closely follows the ideas
+   of the VODE numerical approximation, as described in :cite:`lsode`.
+
+
+Getting Started
+===============
+
+The ``jac_cell`` code is located in
+``Microphysics/unit_test/jac_cell``.  An inputs file which sets the
+default parameters for your thermodynamic state is needed to run the
+test.
+
+Setting the thermodynamics
+--------------------------
+
+The parameters that affect the thermodynamics are:
+
+* ``unit_test.density`` : the initial density
+
+* ``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
+
+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.
+
+
+Building and Running the Code
+=============================
+
+The code can be built simply as:
+
+.. prompt:: bash
+
+   make
+
+.. note::
+
+   By default, this will build with the ``aprox13`` network, which
+   uses the C++ templating method (:ref:`sec:templated_rhs`) of
+   building the analytic Jacobian at compile-time.  The network can be
+   changed via the build parameter ``NETWORK_DIR``.
+
+.. important::
+
+   The screening routines provided by Microphysics do not return the
+   derivative of the screening factor with respect to composition.  This
+   means that the analytic Jacobian provided by the network will ignore
+   this contribution, but the numerical Jacobian will implicitly include
+   it.
+
+   To compare just the network Jacobian elements, it is suggested that
+   you build with ``SCREEN_METHOD=null``.
+
+
+The build process will automatically create links in the build
+directory to any required EOS table.
+
+To run the code, in the ``jac_cell`` directory run::
+
+   ./main3d.gnu.ex inputs
+
+where ``inputs`` is the provided inputs file.  You may edit the
+thermodynamic state in that file prior to running.
+
+
+Output
+======
+
+All output is directed to ``stdout``.  Example output is shown below
+(this output includes screening, highlighting the difference that the
+screening composition derivatives make):
+
+
+.. literalinclude:: ../../unit_test/jac_cell/ci-benchmarks/jac_cell_aprox13.out

Docs/source/one_zone_tests.rst

@@ -12,3 +12,4 @@ have analysis scripts, which we describe in the next sections.
 
    burn_cell.rst
    eos_cell.rst
+   jac_cell.rst

Docs/source/refs.bib

@@ -774,3 +774,12 @@ @ARTICLE{tillotson:1962
       journal = {Internal Report, General Atomics},
       url = {https://apps.dtic.mil/sti/citations/AD0486711}
 }
+
+@article{lsode,
+        title = {Description and {Use} of {LSODE}, the {Livermore} {Solver} for {Ordinary} {Differential} {Equations}},
+        language = {en},
+        year = {1993},
+        author = {{Radhakrishnan}, Krishnan and {Hindmarsh}, Alan C.},
+        journal = {Lawrence Livermore National Laboratory Report UCRL-ID-113855},
+        pages = {124}
+}

Docs/source/templated_networks.rst

@@ -1,3 +1,5 @@
+.. _sec:templated_rhs:
+
 *********************************
 Templated Network Righthand Sides
 *********************************

Docs/source/unit_tests.rst

@@ -120,7 +120,7 @@ One-zone tests
 * ``burn_cell`` :
 
   given a $\rho$, $T$, and $X_k$, integrate a reaction network through a specified time
-  and output the new state.
+  and output the new state.  See :ref:`sec:burn_cell` for more information.
 
 * ``burn_cell_primordial_chem`` :
 
@@ -133,14 +133,14 @@ One-zone tests
 * ``eos_cell`` :
 
   given a $\rho$, $T$, and $X_k$, call the equation of state and print out
-  the thermodynamic information.
+  the thermodynamic information.  See :ref:`sec:eos_cell` for more information.
 
 * ``jac_cell`` :
 
   for a single thermodynamic state, compute the analytic Jacobian
   (using the functions provided by the network) and a numerical
   finite-difference approximation to the Jacobian and output them,
-  element-by-element, to the display.
+  element-by-element, to the display.  See :ref:`sec:jac_cell` for more information.
 
 * ``nse_table_cell`` :
 

unit_test/jac_cell/README.md

@@ -3,3 +3,9 @@
 For a single thermodynamic condition, evaluate the Jacobian using both
 the analytic version from the network and the finite-difference
 numerical approximation.
+
+Note: most analytic Jacobians do not consider the derivative of the
+screening factor with respect to composition.  To get a more accurate
+comparison of how the analytic and numerical terms compare, considering
+just the reactive part, build with `SCREEN_METHOD=null`.
+

unit_test/jac_cell/_parameters

@@ -1,19 +1,8 @@
 @namespace: unit_test
 
-run_prefix    string  ""
-
 small_temp    real       1.e5
 small_dens    real       1.e5
 
-# the final time to integrate to
-tmax          real       1.e-2
-
-# first output time -- we will output in nsteps logarithmically spaced steps between [tfirst, tmax]
-tfirst        real       0.0
-
-# number of steps (logarithmically spaced)
-nsteps        int    100
-
 density       real       1.e7
 
 temperature   real       3.e9