document burn_cell_sdc (#1747)

Author: zingale

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

@@ -0,0 +1,144 @@
+.. _sec:burn_cell_sdc:
+
+*****************
+``burn_cell_sdc``
+*****************
+
+.. index:: burn_cell_sdc
+
+``burn_cell_sdc`` is a simple one-zone burn analogous to :ref:`sec:burn_cell` that
+exercises the simplified-SDC code paths in the integrator.
+The system that is evolved
+has the form:
+
+.. math::
+
+   \begin{align*}
+      \frac{d(\rho X_k)}{dt} &= \Adv{\rho X_k}^{n+1/2} + \rho \dot{\omega}_k(\rho, X_k, T) \\
+      \frac{d(\rho e)}{dt} &= \Adv{\rho e}^{n+1/2} + \rho \epsilon(\rho, X_k, T)
+   \end{align*}
+
+with density constructed as needed via:
+
+$$\rho(t) = \rho^n + \Adv{\rho}^{n+1/2} (t - t^n)$$
+
+In this system, we now need to specify the advective terms for the unit test.
+
+.. note::
+
+   This test can also be used with NSE to test how the integration
+   bails out into NSE if the ``in_nse()`` test is true.
+
+
+
+
+Getting Started
+===============
+
+The ``burn_cell_sdc`` code is located in
+``Microphysics/unit_test/burn_cell_sdc``.   By default, ``USE_SIMPLIFIED_SDC=TRUE``
+is set in the ``GNUmakefile``.
+
+
+Setting the thermodynamics
+--------------------------
+
+The parameters that affect the thermodynamics are:
+
+* ``unit_test.density`` : the initial density
+
+* ``unit_test.temperature`` : the initial temperature
+
+* ``unit_test.rhoe`` : the initial $(rho e)$.  If this is not set (or
+  set to be $< 0$), then it will be computed from the temperature
+  using the EOS.
+
+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
+---------------
+
+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.
+
+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.
+
+
+
+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).
+
+The advective terms can be set manually via
+
+* ``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}$
+
+
+
+
+Controlling time
+----------------
+
+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
+----------------------
+
+The tolerances, choice of Jacobian, and other integration parameters
+can be set via the usual Microphysics runtime parameters, e.g.
+``integrator.atol_spec``.
+
+
+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 explicitly 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
+=============================
+
+The code can be built simply as:
+
+.. prompt:: bash
+
+   make
+
+and the network and integrator can be changed using the normal
+Microphysics build system parameters.
+
+.. important::
+
+   You need to do a ``make clean`` before rebuilding with a different
+   network or integrator.
+
+
+To run the code, in the ``burn_cell_sdc`` directory run::
+
+   ./main3d.gnu.ex inputs
+
+where ``inputs`` is the name of your inputs file.

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

@@ -13,5 +13,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

Docs/source/unit_test_runtime_parameters.rst

@@ -25,6 +25,7 @@ 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
@@ -46,6 +47,7 @@ initial mass-fractions, $X_k$).  There are a few ways this can be done
     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

Docs/source/unit_tests.rst

@@ -131,6 +131,7 @@ One-zone tests
 * ``burn_cell_sdc`` :
 
   similar to ``burn_cell`` except this uses the SDC integration code paths.
+   See :ref:`sec:burn_cell_sdc` for more information.
 
 * ``eos_cell`` :
 

unit_test/burn_cell_sdc/parse_integration_failure.py

@@ -47,10 +47,16 @@ def doit(string):
     # figure out if it is the VODE failure or burn_t that was provided
 
     is_vode = False
+
+    density = None
+    temperature = None
     rhoe = None
     tmax = None
-
+    xn = None
     aux = None
+    A_rho = None
+    A_rhoe = None
+    A_X_k = None
     A_aux_k = None
 
     for line in string:
@@ -163,7 +169,7 @@ def doit(string):
 
 if __name__ == "__main__":
     err_file = sys.argv[1]
-    with open(err_file, "r") as f:
+    with open(err_file) as f:
         lines = f.readlines()
 
     doit(lines)