Merge branch 'development' into update_templated_net_docs

Docs/source/conf.py

@@ -68,6 +68,7 @@ def get_version():
 
 # bibtex
 bibtex_bibfiles = ["refs.bib"]
+bibtex_default_style = "unsrt"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

Docs/source/getting_started.rst

@@ -27,7 +27,7 @@ to set the ``AMREX_HOME`` environment variable to point to the
 
 .. index:: burn_cell
 
-A good unit test to start with is ``burn_cell`` -- this is simply a
+A good unit test to start with is ``burn_cell`` --- this is simply a
 one-zone burn.  In ``Microphysics/`` do:
 
 .. prompt:: bash

Docs/source/index.rst

@@ -10,10 +10,11 @@ AMReX-Astro Microphysics is a collection of microphysics routines (equations of
 reaction networks, ...) and utilities (ODE integrators, NSE solvers)
 for astrophysical simulation codes.
 
-The original design was to support the `AMReX
-<https://github.com/amrex-codes/amrex>`_ codes `CASTRO
-<https://github.com/amrex-astro/Castro>`_ and MAESTRO (now `MAESTROeX
-<https://github.com/amrex-astro/MAESTROeX>`_). These all have a
+The original design was to support codes based on the `AMReX
+<https://github.com/amrex-codes/amrex>`_ adaptive mesh refinement library :cite:`amrex_joss`,
+including `CASTRO
+<https://github.com/amrex-astro/Castro>`_ :cite:`castro_I`, `MAESTROeX
+<https://github.com/amrex-astro/MAESTROeX>`_ :cite:`maestroex`, and Quokka :cite:`quokka`. These all have a
 consistent interface and the separate Microphysics repository allows
 them to share the same equation of state, reaction networks, and more.
 Later, Microphysics was adopted by the `Quokka <https://github.com/quokka-astro/quokka>`_

Docs/source/ode_integrators.rst

@@ -146,46 +146,80 @@ Tolerances
 Tolerances dictate how accurate the ODE solver must be while solving
 equations during a simulation.  Typically, the smaller the tolerance
 is, the more accurate the results will be.  However, if the tolerance
-is too small, the code may run for too long or the ODE solver will
-never converge.  In these simulations, ``rtol`` values will set the
-relative tolerances and ``atol`` values will set the absolute tolerances
-for the ODE solver.  Often, one can find and set these values in an
-input file for a simulation.
-
-:numref:`fig:tolerances` shows the results of a simple simulation using the
-burn_cell unit test to determine
-what tolerances are ideal for simulations.
-For this investigation, it was assumed that a run with a tolerance of :math:`10^{-12}`
-corresponded to an exact result,
-so it is used as the basis for the rest of the tests.
-From the figure, one can infer that the :math:`10^{-3}` and :math:`10^{-6}` tolerances
-do not yield the most accurate results
-because their relative error values are fairly large.
-However, the test with a tolerance of :math:`10^{-9}` is accurate
-and not so low that it takes incredible amounts of computer time,
-so :math:`10^{-9}` should be used as the default tolerance in future simulations.
+is too small, the code may run for too long, the ODE solver will
+never converge, or it might require at timestep that underflows.
+
+.. index:: integrator.rtol_spec, integrator.rtol_enuc, integrator.atol_spec, integrator.atol_enuc
+
+There are separate tolerances for the mass fractions and the energy,
+and there are both relative and absolute tolerances which act together.
+The tolerances are:
+
+* ``integrator.rtol_spec`` : the relative tolerance for the species
+  (mass fractions when running with Strang and partial densities when
+  running with SDC).
+
+* ``integrator.rtol_enuc`` : the relative tolerance on the energy
+  (specific internal energy when running with Strang, internal energy
+  density when running with SDC).
+
+* ``integrator.atol_spec`` : the absolute tolerance for the species
+  (this is always interpreted in terms of mass fraction and the appropriate
+  density weighting will be added for SDC).
+
+* ``integrator.atol_enuc`` : the absolute tolerance for energy -- this
+  is generally not interesting, since the energy is so large and therefore
+  best served via a relative tolerance.
+
+The tolerances are combined, e.g. for species, as:
+
+.. math::
+
+   \epsilon_{\mathrm{total}, k} = \epsilon_\mathrm{abs} + \epsilon_\mathrm{rel} |X_k|
+
+so if the mass fraction, $X_k$, is very small, then the absolute tolerance
+will set the error that the integrator tries to achieve.  If the mass fraction
+is large, $\mathcal{O}(1)$, then the relative tolerance dominates.
+
+Some suggestions when setting tolerances:
+
+.. index:: integrator.X_reject_buffer
+
+* If a burn does not converge with one type of Jacobian (analytic or
+  numerical) then it may do better with the other type.  This can be
+  automated via the ``integrator.use_burn_retry`` mechanism described
+  above.
+
+* Sometimes a burn completes better if the absolute tolerances are
+  made even smaller -- this will require the integrator to track trace
+  species better which can help with equilibrium better.
+
+* The VODE integrator has additional logic meant to ensure that
+  species don't change too much per timestep.  This is controlled by
+  ``integrator.X_reject_buffer``.  If a species $k$, has a mass
+  fraction $X_k > \mbox{X_reject_buffer} \cdot \mbox{atol_spec}$ then
+  we reject a VODE timestep if the mass fraction changes by more than
+  a factor of 4 in a single VODE timestep and we try again.  This is
+  all done internally to VODE.  Making ``X_reject_buffer`` larger will
+  allow it to ignore more trace species.
+
+Below is a comparison of how the tolerances affect the nucleosynthesis.
+This is run using ``burn_cell`` and the ``aprox13`` network.  Four separate
+runs were done, using tolerances of $10^{-3}$, $10^{-5}$, $10^{-8}$, and $10^{-12}$
+(all 4 tolerance parameters were set to the same value).  The run with the tightest
+tolerances ($10^{-12}$) was taken as the reference and relative errors were
+computed with respect to it.  The scripts for this are in ``Microphysics/unit_test/burn_cell/compare_tolerances/``.
 
 .. _fig:tolerances:
-.. figure:: tolerances.png
-   :alt: Relative error plot
+.. figure:: tolerance-compare.png
+   :alt: Relative error in mass fractions
    :width: 100%
 
    Relative error of runs with varying tolerances as compared
    to a run with an ODE tolerance of :math:`10^{-12}`.
 
-The integration tolerances for the burn are controlled by
-``rtol_spec`` and  ``rtol_enuc``,
-which are the relative error tolerances for
-:eq:`eq:spec_integrate` and :eq:`eq:enuc_integrate`,
-respectively. There are corresponding
-``atol`` parameters for the absolute error tolerances. Note that
-not all integrators handle error tolerances the same way—see the
-sections below for integrator-specific information.
-
-The absolute error tolerances are set by default
-to :math:`10^{-12}` for the species, and a relative tolerance of :math:`10^{-6}`
-is used for the temperature and energy.
-
+We see that using a tolerance of $10^{-5}$ generally gives reasonable mass
+fractions.  Looser than this can produce large errors.
 
 Controlling Species $\sum_k X_k = 1$
 ====================================
@@ -222,6 +256,7 @@ constraint on the intermediate states during the integration.
   This is enabled by default.
 
 
+
 Retry Mechanism
 ===============
 

Docs/source/refs.bib

@@ -701,3 +701,55 @@ @ARTICLE{itoh:1996
        adsurl = {https://ui.adsabs.harvard.edu/abs/1996ApJS..102..411I},
       adsnote = {Provided by the SAO/NASA Astrophysics Data System}
 }
+
+
+@article{amrex_joss,
+         doi = {10.21105/joss.01370},
+         url = {https://doi.org/10.21105/joss.01370},
+         year = {2019},
+         publisher = {The Open Journal},
+         volume = {4},
+         number = {37},
+         pages = {1370},
+         author = {Weiqun Zhang and Ann Almgren and Vince Beckner and John Bell and Johannes Blaschke and Cy Chan and Marcus Day and Brian Friesen and Kevin Gott and Daniel Graves and Max P. Katz and Andrew Myers and Tan Nguyen and Andrew Nonaka and Michele Rosso and Samuel Williams and Michael Zingale},
+         title = {AMReX: a framework for block-structured adaptive mesh refinement},
+         journal = {Journal of Open Source Software} }
+
+
+@ARTICLE{maestroex,
+       author = {{Fan}, Duoming and {Nonaka}, Andrew and {Almgren}, Ann S. and {Harpole}, Alice and {Zingale}, Michael},
+        title = "{MAESTROeX: A Massively Parallel Low Mach Number Astrophysical Solver}",
+      journal = {\apj},
+     keywords = {Stellar convective zones, Hydrodynamics, Computational methods, Nuclear astrophysics, Nucleosynthesis, Nuclear abundances, 301, 1963, 1965, 1129, 1131, 1128, Physics - Computational Physics, Astrophysics - Solar and Stellar Astrophysics},
+         year = 2019,
+        month = dec,
+       volume = {887},
+       number = {2},
+          eid = {212},
+        pages = {212},
+          doi = {10.3847/1538-4357/ab4f75},
+archivePrefix = {arXiv},
+       eprint = {1908.03634},
+ primaryClass = {physics.comp-ph},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/2019ApJ...887..212F},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+
+@ARTICLE{quokka,
+       author = {{Wibking}, Benjamin D. and {Krumholz}, Mark R.},
+        title = "{QUOKKA: a code for two-moment AMR radiation hydrodynamics on GPUs}",
+      journal = {\mnras},
+     keywords = {hydrodynamics, methods: numerical, Astrophysics - Instrumentation and Methods for Astrophysics},
+         year = 2022,
+        month = may,
+       volume = {512},
+       number = {1},
+        pages = {1430-1449},
+archivePrefix = {arXiv},
+       eprint = {2110.01792},
+ primaryClass = {astro-ph.IM},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/2022MNRAS.512.1430W},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+