From 86807d6ba1bb4bc731cb7d7efb9518d56d6b8969 Mon Sep 17 00:00:00 2001 From: Michael Zingale Date: Mon, 26 Feb 2024 14:28:59 -0500 Subject: [PATCH] update the SDC docs (#1469) including removing the vestiges of "starkiller" --- sphinx_docs/source/mathsymbols.tex | 1 + sphinx_docs/source/sdc.rst | 110 ++++++++++++++++++++++++++--- 2 files changed, 102 insertions(+), 9 deletions(-) diff --git a/sphinx_docs/source/mathsymbols.tex b/sphinx_docs/source/mathsymbols.tex index 200b2924b1..c9e1993733 100644 --- a/sphinx_docs/source/mathsymbols.tex +++ b/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)}} diff --git a/sphinx_docs/source/sdc.rst b/sphinx_docs/source/sdc.rst index 379874f75f..fdb7f03196 100644 --- a/sphinx_docs/source/sdc.rst +++ b/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.