add more docs

Author: zingale

.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/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/templated_networks.rst

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

Docs/source/unit_tests.rst

@@ -140,7 +140,7 @@ One-zone tests
   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`` :