finish a pass at documenting burn_cell_sdc

Docs/source/burn_cell.rst

@@ -63,6 +63,8 @@ normalization.  This normalization can be disabled by setting:
     unit_test.skip_initial_normalization = 1
 
 
+.. _sec:burn_cell_time:
+
 Controlling time
 ----------------
 

Docs/source/burn_cell_sdc.rst

@@ -53,48 +53,46 @@ The parameters that affect the thermodynamics are:
   set to be $< 0$), then it will be computed from the temperature
   using the EOS.
 
-* ``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
-
-As with ``burn_cell``, the composition can be set either by setting each mass fraction explicitly via the
-parameters, ``unit_test.X1``, ``unit_test.X2``, ..., or initialized to be
-uniform 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`.
 
 Aux composition
 ---------------
 
-Advective terms
----------------
+When built with ``USE_NSE_TABLE=TRUE`` (see :ref:`tabulated_nse`) or with
+``USE_AUX_THERMO=TRUE`` (see :ref:`aux_eos_comp`) then the auxiliary
+composition, $Y_e$, $\bar{A}$, $\langle
+B/A\rangle$, is defined.
 
-But default, the advective terms are set to zero.  In this mode, ``burn_cell_sdc``
-largely mimics ``burn_cell`` (although with a slightly different ODE system
-integrated).
+The auxiliary composition can either be initialized directly via
+``unit_test.Aux1``, ``unit_test.Aux2``, and ``unit_test.Aux3``, or
+their values can be computed at initialization from the mass fractions
+if ``unit_test.recompute_aux=1`` is set.
 
-The advective terms can be set
 
 
+Advective terms
+---------------
 
+But default, the advective terms are set to zero.  In this mode,
+``burn_cell_sdc`` largely mimics ``burn_cell`` (although with a
+slightly different ODE system integrated).
 
-Controlling time
-----------------
+The advective terms can be set manually via
 
-The test will run unit a time ``unit_test.tmax``, outputting the state
-at regular intervals.  The parameters controlling the output are:
+* ``unit_test.Adv_rho`` : $\Adv{\rho}^{n+1/2}$
+* ``unit_test.Adv_rhoe`` : $\Adv{\rho e}^{n+1/2}$
+* ``unit_test.Adv_X1``, ``unit_test.Adv_X2``, ... : $\Adv{\rho X_1}^{n+1/2}$, $\Adv{\rho X_2}^{n+1/2}$, ... (up to $X_{35}$)
+* ``unit_test.Adv_Aux1``, ``unit_test.Adv_Aux2``, ``unit_test.Adv_Aux3`` : $\Adv{\rho \alpha_1}^{n+1/2}$, $\Adv{\rho \alpha_2}^{n+1/2}$, $\Adv{\rho \alpha_3}^{n+1/2}$
 
-* ``unit_test.tmax`` : the end point of integration.
 
-* ``unit_test.tfirst`` : the first time interval to output.
 
-* ``unit_test.nsteps`` : the number of steps to divide the integration into,
-  logarithmically-spaced.
 
-If there is only a single step, ``unit_test.nsteps = 1``, then we integrate
-from $[0, \mathrm{tmax}]$.
+Controlling time
+----------------
 
-If there are multiple steps, then the first output will be at a time
-$\mathrm{tmax} / \mathrm{nsteps}$, and the steps will be
-logarithmically-spaced afterwards.
+The integration time and output frequency are controlled by the
+same set of parameters as in ``burn_cell``. see :ref:`sec:burn_cell_time`.
 
 
 Integration parameters
@@ -108,6 +106,18 @@ can be set via the usual Microphysics runtime parameters, e.g.
 Rerunning a burn fail
 ---------------------
 
+.. index:: parse_integration_failure.py, USE_GPU_PRINTF
+
+When a network integration encounters a failure, it will output the
+entire burn state to ``stdout`` (for GPU builds, this needs to be
+enabled explicity by building with ``USE_GPU_PRINTF``).
+
+The script ``unit_test/burn_cell_sdc/parse_integration_failure.py``
+can be used to parse the output (copy and paste the full error into a
+file) and produce the runtime parameter settings needed to reproduce
+the burn.  This is especially important with SDC, since it will contain
+all of the advective terms.
+
 
 Building and Running the Code
 =============================

Docs/source/eos.rst

@@ -15,7 +15,7 @@ the input and ``state`` is a C++ struct that holds all of the
 thermodynamic information.
 
 
-Interface and Modes
+Interface and modes
 ===================
 
 .. index:: eos_t, eos_re_t, eos_rep_t, eos_rh_t, chem_eos_t
@@ -85,7 +85,7 @@ stored in ``eos_t.aux[]``.
 
 .. _aux_eos_comp:
 
-Auxiliary Composition
+Auxiliary composition
 ---------------------
 
 .. index:: USE_AUX_THERMO
@@ -139,7 +139,7 @@ Many equations of state also need :math:`\bar{Z}` which is easily computed as
    \bar{Z} = \bar{A} Y_e
 
 
-Composition Derivatives
+Composition derivatives
 -----------------------
 
 .. index:: eos_extra_t, eos_re_extra_t, eos_rep_extra_t
@@ -161,7 +161,7 @@ to compute :math:`\partial p/\partial X_k |_{\rho, T, X_j}`, :math:`\partial e/\
 
 
 
-Initialization and Cutoff Values
+Initialization and cutoff values
 ================================
 
 
@@ -178,7 +178,7 @@ max ( ``small_temp``, T ).
    User’s are encourage to do their own validation of inputs before calling
    the EOS.
 
-EOS Structure
+EOS structure
 =============
 
 Each EOS should have two main routines through which it interfaces to the

Docs/source/one_zone_tests.rst

@@ -11,5 +11,6 @@ have analysis scripts, which we describe in the next sections.
    :hidden:
 
    burn_cell.rst
+   burn_cell_sdc.rst
    eos_cell.rst
    jac_cell.rst