From 45c9777152441cd72b8afdb2777ee5831317eef3 Mon Sep 17 00:00:00 2001 From: Michael Zingale Date: Tue, 18 Feb 2025 12:51:03 -0500 Subject: [PATCH] document burn_cell_sdc (#1747) --- Docs/source/burn_cell.rst | 2 + Docs/source/burn_cell_sdc.rst | 144 ++++++++++++++++++ Docs/source/eos.rst | 10 +- Docs/source/one_zone_tests.rst | 1 + Docs/source/unit_test_runtime_parameters.rst | 2 + Docs/source/unit_tests.rst | 1 + .../parse_integration_failure.py | 10 +- 7 files changed, 163 insertions(+), 7 deletions(-) create mode 100644 Docs/source/burn_cell_sdc.rst diff --git a/Docs/source/burn_cell.rst b/Docs/source/burn_cell.rst index 7541d3f261..852faa54c1 100644 --- a/Docs/source/burn_cell.rst +++ b/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 ---------------- diff --git a/Docs/source/burn_cell_sdc.rst b/Docs/source/burn_cell_sdc.rst new file mode 100644 index 0000000000..bb0adb28b5 --- /dev/null +++ b/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. diff --git a/Docs/source/eos.rst b/Docs/source/eos.rst index 0c8778505c..7fe001505d 100644 --- a/Docs/source/eos.rst +++ b/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 diff --git a/Docs/source/one_zone_tests.rst b/Docs/source/one_zone_tests.rst index 2cf8ea57b8..6051152131 100644 --- a/Docs/source/one_zone_tests.rst +++ b/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 diff --git a/Docs/source/unit_test_runtime_parameters.rst b/Docs/source/unit_test_runtime_parameters.rst index fc6232c44a..793fe699ef 100644 --- a/Docs/source/unit_test_runtime_parameters.rst +++ b/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 diff --git a/Docs/source/unit_tests.rst b/Docs/source/unit_tests.rst index eb85893131..b63db30d9a 100644 --- a/Docs/source/unit_tests.rst +++ b/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`` : diff --git a/unit_test/burn_cell_sdc/parse_integration_failure.py b/unit_test/burn_cell_sdc/parse_integration_failure.py index 9ce9769b62..7dd195a454 100644 --- a/unit_test/burn_cell_sdc/parse_integration_failure.py +++ b/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)