update the SDC docs (#1469)

including removing the vestiges of "starkiller"

sphinx_docs/source/mathsymbols.tex

@@ -101,6 +101,7 @@
 \newcommand{\Sc}{\mathbf{S}}
 \newcommand{\Shydro}{{{\bf S}^{\mathrm{hydro}}}}
 \newcommand{\Rb}{{\bf R}}
+\newcommand{\Rbs}[1]{{\bf R} \left ( #1 \right )}
 \newcommand{\Rq}{{\bf R}}
 \newcommand{\Adv}[1]{{\left [\boldsymbol{\mathcal{A}} \left(#1\right)\right]}}
 \newcommand{\Advs}[1]{{\boldsymbol{\mathcal{A}} \left(#1\right)}}

sphinx_docs/source/sdc.rst

@@ -5,10 +5,10 @@ Spectral Deferred Corrections
 Introduction
 ============
 
-The Simplified-SDC method provides a means to more strongly couple the
-reactions to the hydrodynamics by evolving the reactions together with
-an approximation of the advection over the timestep.  The full details
-of the algorithm are presented in :cite:`castro_simple_sdc`.
+Spectral deferred correction (SDC) methods strongly couple reactions
+and hydrodynamics, eliminating the splitting error that arises with
+Strang (operator) splitting.  Microphysics supports two different
+SDC formulations.
 
 We want to solve the coupled equations:
 
@@ -33,14 +33,100 @@ hydrodynamical sources),
 and :math:`\Rb(\Uc)`
 is the reaction source term.
 
+
+.. note::
+
+   Application codes can set the make variables ``USE_TRUE_SDC`` or
+   ``USE_SIMPLIFIED_SDC``.  But in Microphysics, both SDC formulations
+   are supported by the same integrators, and both of these options
+   will set the ``SDC`` preprocessor flag.
+
+"True" SDC
+----------
+
+The true SDC implementation is described in :cite:`castro_sdc`.  It divides
+the timestep into temporal nodes and uses low-order approximations to update
+from one temporal node to the next.  Iteration is used to increase the order of accuracy.
+
+The update from one temporal node, $m$, to the next, $m$, for iteration
+$k+1$ appears as:
+
+.. math::
+
+   \begin{align*}
+    \Uc^{m+1,(k+1)} = \Uc^{m,(k+1)}
+     &+ \delta t_m\left[\Advs{\Uc^{m,(k+1)}} - \Advs{\Uc^{m,(k)}}\right] +\\
+     &+ \delta t_m\left[\Rbs{\Uc^{m+1,(k+1)}} - \Rbs{\Uc^{m+1,(k)}}\right]\\
+     &+ \int_{t^m}^{t^{m+1}}\Advs{\Uc^{(k)}} + \Rbs{\Uc^{(k)}}d\tau.
+   \end{align*}
+
+Solving this requires a nonlinear solve of:
+
+.. math::
+
+   \Uc^{m+1,(k+1)} - \delta t_m \Rbs{\Uc}^{m+1,(k+1)} = \Uc^{m,(k+1)} + \delta t_m {\bf C}
+
+where the right-hand side is constructed only from known states, and we
+define ${\bf C}$ for convenience as:
+
+.. math::
+
+   \begin{align}
+   {\bf C} &= \left [ {\Advs{\Uc}}^{m,(k+1)} - {\Advs{\Uc}}^{m,(k)} \right ]
+                  -  {\Rbs{\Uc}}^{{m+1},(k)}  \nonumber \\
+               &+ \frac{1}{\delta t_m} \int_{t^m}^{t^{m+1}} \left  ( {\Advs{\Uc}}^{(k)} + {\Rbs{\Uc}}^{(k)}\right ) d\tau
+   \end{align}
+
+This can be cast as an ODE system as:
+
+.. math::
+
+  \frac{d\Uc}{dt} \approx \frac{\Uc^{m+1} - \Uc^m}{\delta t_m} = \Rbs{\Uc} + {\bf C}
+
+Simplified SDC
+--------------
+
+The Simplified-SDC method uses the ideas of the SDC method above, but instead
+of dividing time into discrete temporary notes, it uses a piecewise-constant-in-time
+approximation to the advection update over the timestep (for instance, computed by the CTU PPM method) and solves the ODE system:
+
+.. math::
+
+  \frac{\partial \Uc}{\partial t} = [\Advs{\Uc}]^{n+1/2} + \Rb(\Uc)
+
+and uses iteration to improve the advective term based on the
+reactions.  The full details of the algorithm are presented in
+:cite:`castro_simple_sdc`.
+
+Common ground
+-------------
+
+Both SDC formulations result in an ODE system of the form:
+
+.. math::
+
+   \frac{d\Uc}{dt} = \Rb(\Uc) + \mbox{advective terms}
+
+where $\Uc$ is only
+
+.. math::
+
+   \Uc = \left ( \begin{array}{c} \rho X_k \\ \rho e \end{array} \right )
+
+since those are the only components with reactive sources.
+The ``SDC`` burner includes storage for the advective terms.
+
 Interface and Data Structures
 =============================
 
-burn_t
-------
+For concreteness, we use the simplified-SDC formulation in the description below,
+but the true-SDC version is directly analogous.
+
+``burn_t``
+----------
 
 To accommodate the increased information required to evolve the
-coupled system, the `burn_t` used for Strang integration is extended
+coupled system, the ``burn_t`` used for Strang integration is extended
 to include the conserved state and the advective sources.  This is
 used to pass information to/from the integration routine from the
 hydrodynamics code.
@@ -128,8 +214,8 @@ system we are integrating, including the advective terms.
    :math:`\dot{Y}_k` and the nuclear energy release, :math:`\dot{S}`.
 
 #. Convert back to the integrator’s internal representation via ``rhs_to_int``
-   This converts the ``ydot``s to mass fractions and adds the advective terms
-   to all ``ydots``.
+   This converts the ``ydot`` to mass fractions and adds the advective terms
+   to ``ydot``.
 
 Jacobian
 --------
@@ -147,3 +233,9 @@ the Jacobian as:
 where :math:`{\bf w} = (X_k, T)^\intercal` are the more natural variables
 for a reaction network.
 
+.. note::
+
+   In the original "true SDC" paper :cite:`castro_sdc`, the matrix
+   system was more complicated, and we included density in ${\bf w}$.
+   This is not needed, and we use the Jacobian defined in
+   :cite:`castro_simple_sdc` instead.