Merge branch 'development' into fix_cj

AMReX-Astro · Jan 6, 2025 · c50e16c · c50e16c
2 parents 644d6ad + bb3b040
commit c50e16c
Show file tree

Hide file tree

Showing 75 changed files with 2,332 additions and 2,892 deletions.
diff --git a/.github/workflows/docs-test.yml b/.github/workflows/docs-test.yml
@@ -35,10 +35,10 @@ jobs:
 
       - name: Build docs
         run: |
-          cd sphinx_docs/
+          cd Docs/
           make SPHINXOPTS='-v -W --keep-going' html
 
       - name: Link check
         run: |
-          cd sphinx_docs/
+          cd Docs/
           make SPHINXOPTS=-v linkcheck
diff --git a/.gitignore b/.gitignore
@@ -78,7 +78,7 @@ extern.f90
 # sphinx
 build/
 doxy_files
-sphinx_docs/source/runtime_parameters.rst
+Docs/source/runtime_parameters.rst
 
 
 # C++ parameters

diff --git a/sphinx_docs/Doxyfile → Docs/Doxyfile b/sphinx_docs/Doxyfile → Docs/Doxyfile
diff --git a/sphinx_docs/Makefile → Docs/Makefile b/sphinx_docs/Makefile → Docs/Makefile
diff --git a/sphinx_docs/converting_docs.txt → Docs/converting_docs.txt b/sphinx_docs/converting_docs.txt → Docs/converting_docs.txt
diff --git a/sphinx_docs/notes.txt → Docs/notes.txt b/sphinx_docs/notes.txt → Docs/notes.txt
diff --git a/sphinx_docs/pandoc.sh → Docs/pandoc.sh b/sphinx_docs/pandoc.sh → Docs/pandoc.sh
diff --git a/sphinx_docs/rp.py → Docs/rp.py b/sphinx_docs/rp.py → Docs/rp.py
diff --git a/sphinx_docs/source/CNO_He_burn.png → Docs/source/CNO_He_burn.png b/sphinx_docs/source/CNO_He_burn.png → Docs/source/CNO_He_burn.png
diff --git a/sphinx_docs/source/ECSN.png → Docs/source/ECSN.png b/sphinx_docs/source/ECSN.png → Docs/source/ECSN.png
diff --git a/...x_docs/source/_static/theme_overrides.css → Docs/source/_static/theme_overrides.css b/...x_docs/source/_static/theme_overrides.css → Docs/source/_static/theme_overrides.css
diff --git a/...nx_docs/source/_templates/dev_layout.html → Docs/source/_templates/dev_layout.html b/...nx_docs/source/_templates/dev_layout.html → Docs/source/_templates/dev_layout.html
diff --git a/sphinx_docs/source/_templates/layout.html → Docs/source/_templates/layout.html b/sphinx_docs/source/_templates/layout.html → Docs/source/_templates/layout.html
diff --git a/sphinx_docs/source/autodiff.rst → Docs/source/autodiff.rst b/sphinx_docs/source/autodiff.rst → Docs/source/autodiff.rst
diff --git a/sphinx_docs/source/cno_extras_hide_alpha.png → Docs/source/cno_extras_hide_alpha.png b/sphinx_docs/source/cno_extras_hide_alpha.png → Docs/source/cno_extras_hide_alpha.png
diff --git a/sphinx_docs/source/comprehensive_tests.rst → Docs/source/comprehensive_tests.rst b/sphinx_docs/source/comprehensive_tests.rst → Docs/source/comprehensive_tests.rst
diff --git a/sphinx_docs/source/conf.py → Docs/source/conf.py b/sphinx_docs/source/conf.py → Docs/source/conf.py
diff --git a/sphinx_docs/source/data_structures.rst → Docs/source/data_structures.rst b/sphinx_docs/source/data_structures.rst → Docs/source/data_structures.rst
diff --git a/sphinx_docs/source/design.rst → Docs/source/design.rst b/sphinx_docs/source/design.rst → Docs/source/design.rst
@@ -12,6 +12,8 @@ and the generic solvers:
 
 * ``constants``: fundamental constants
 
+* ``Docs``: the sphinx source for this documentation
+
 * ``EOS/``: the various equations of state
 
 * ``integration/``: the ODE integration routines used for the
@@ -34,8 +36,6 @@ and the generic solvers:
 * ``screening/``: common electron screening factors used by some of the
   reaction networks.
 
-* ``sphinx_docs``: the sphinx source for this documentation
-
 * ``unit_test/``: self-contained unit tests for Microphysics. These don’t
   need any application code to build, but will require AMReX.
 

diff --git a/sphinx_docs/source/doxygen_network.png → Docs/source/doxygen_network.png b/sphinx_docs/source/doxygen_network.png → Docs/source/doxygen_network.png
diff --git a/sphinx_docs/source/eos.rst → Docs/source/eos.rst b/sphinx_docs/source/eos.rst → Docs/source/eos.rst
diff --git a/sphinx_docs/source/getting_started.rst → Docs/source/getting_started.rst b/sphinx_docs/source/getting_started.rst → Docs/source/getting_started.rst
diff --git a/sphinx_docs/source/index.rst → Docs/source/index.rst b/sphinx_docs/source/index.rst → Docs/source/index.rst
@@ -60,6 +60,7 @@ of state routines.
    networks
    templated_networks
    screening
+   neutrinos
 
 .. toctree::
    :maxdepth: 1
@@ -71,6 +72,13 @@ of state routines.
    nse
    sdc
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Util / external libraries
+   :hidden:
+
+   util
+
 .. toctree::
    :maxdepth: 1
    :caption: Unit tests

diff --git a/sphinx_docs/source/integrators.rst → Docs/source/integrators.rst b/sphinx_docs/source/integrators.rst → Docs/source/integrators.rst
@@ -14,13 +14,13 @@ The equations we integrate to do a nuclear burn are:
    :label: eq:spec_integrate
 
 .. math::
-   \frac{de}{dt} = f(\rho,X_k,T)
+   \frac{de}{dt} = \epsilon(\rho,X_k,T)
    :label: eq:enuc_integrate
 
 Here, :math:`X_k` is the mass fraction of species :math:`k`, :math:`e`
 is the specific nuclear energy created through reactions. Also needed
 are density :math:`\rho`, temperature :math:`T`, and the specific
-heat. The function :math:`f` provides the energy release from
+heat. The function :math:`\epsilon` provides the energy release from
 reactions and can often be expressed in terms of the instantaneous
 reaction terms, :math:`\dot{X}_k`. As noted in the previous section,
 this is implemented in a network-specific manner.
@@ -46,7 +46,7 @@ energy. This allows us to easily call the EOS during the burn to obtain the temp
       :label: eq:spec_n_integrate
 
    .. math::
-      \frac{de}{dt} = f(\rho,n_k,T)
+      \frac{de}{dt} = \epsilon(\rho,n_k,T)
       :label: eq:enuc_n_integrate
 
    The effect of this flag in the integrators is that we don't worry
@@ -355,7 +355,7 @@ with the initial temperature, density, and composition:
 As the system is integrated, :math:`e` is updated to account for the
 nuclear energy release (and thermal neutrino losses),
 
-.. math:: e(t) = e_0 + \int_{t_0}^t f(\dot{Y}_k) dt
+.. math:: e(t) = e_0 + \int_{t_0}^t \epsilon(\dot{Y}_k) dt
 
 .. note::
 

diff --git a/sphinx_docs/source/mathsymbols.tex → Docs/source/mathsymbols.tex b/sphinx_docs/source/mathsymbols.tex → Docs/source/mathsymbols.tex
diff --git a/sphinx_docs/source/networks-overview.rst → Docs/source/networks-overview.rst b/sphinx_docs/source/networks-overview.rst → Docs/source/networks-overview.rst
diff --git a/sphinx_docs/source/networks.rst → Docs/source/networks.rst b/sphinx_docs/source/networks.rst → Docs/source/networks.rst
@@ -26,10 +26,10 @@ is stored as ``mion(:)`` in the network.
 
 The energy release per gram is converted from the rates as:
 
-.. math:: \edot = -N_A c^2 \sum_k \frac{dY_k}{dt} M_k - \edotnu
+.. math:: \epsilon = -N_A c^2 \sum_k \frac{dY_k}{dt} M_k - \epsilon_\nu
 
 where :math:`N_A` is Avogadro’s number (to convert this to “per gram”)
-and :math:`\edotnu` is the neutrino loss term.
+and :math:`\edotnu` is the neutrino loss term (see :ref:`neutrino_loss`).
 
 
 ``general_null``
@@ -137,7 +137,7 @@ network is interpolated based on the density. It is stored as the
 binding energy (ergs/g) *per nucleon*, with a sign convention that
 binding energies are negative. The energy generation rate is then:
 
-.. math:: \edot = q \frac{dX(\isotm{C}{12})}{dt} = q A_{\isotm{C}{12}} \frac{dY(\isotm{C}{12})}{dt}
+.. math:: \epsilon = q \frac{dX(\isotm{C}{12})}{dt} = q A_{\isotm{C}{12}} \frac{dY(\isotm{C}{12})}{dt}
 
 (this is positive since both :math:`q` and :math:`dY/dt` are negative)
 
@@ -244,7 +244,7 @@ Finally, for the
 energy generation, we take our reaction to release a specific energy,
 :math:`[\mathrm{erg~g^{-1}}]`, of :math:`\qburn`, and our energy source is
 
-.. math:: \edot = -\qburn \frac{dX_f}{dt}
+.. math:: \epsilon = -\qburn \frac{dX_f}{dt}
 
 There are a number of parameters we use to control the constants in
 this network. This is one of the few networks that was designed

diff --git a/Docs/source/neutrinos.rst b/Docs/source/neutrinos.rst
@@ -0,0 +1,47 @@
+.. _neutrino_loss:
+
+***************
+Neutrino Losses
+***************
+
+We model thermal neutrino losses (plasma, photo-, pair-,
+recombination, and Bremsstrahlung) using the method described in
+:cite:`itoh:1996`.  This neutrino loss term is included in all of the
+reaction networks by default, and modifies the energy equation to have
+the form (for Strang splitting):
+
+.. math::
+
+   \frac{de}{dt} = \epsilon - \epsilon_\nu
+
+where $\epsilon_\nu$ are the thermal neutrino losses.
+
+.. note::
+
+   Thermal neutrino losses can be disabled at compile time by setting the make
+   variable ``USE_NEUTRINOS = FALSE``.
+
+The interface for the neutrino loss function is:
+
+.. code:: c++
+
+   template <int do_derivatives>
+   AMREX_GPU_HOST_DEVICE AMREX_INLINE
+   void sneut5(const amrex::Real temp, const amrex::Real den,
+               const amrex::Real abar, const amrex::Real zbar,
+               amrex::Real& snu, amrex::Real& dsnudt, amrex::Real& dsnudd,
+               amrex::Real& dsnuda, amrex::Real& dsnudz)
+
+Here, the template parameter, ``do_derivatives``, can be used to disable the code
+the computes the derivatives of the neutrino loss, for example, if a numerical Jacobian
+is used.  The output is
+
+* ``snu`` : $\epsilon_\nu$, the neutrino loss in erg/g/s
+
+* ``dsnudt`` : $d\epsilon_\nu/dT$
+
+* ``dsnudd`` : $d\epsilon_\nu/d\rho$
+
+* ``dsnuda`` : $d\epsilon_\nu/d\bar{A}$
+
+* ``dsnudz`` : $d\epsilon_\nu/d\bar{Z}$
diff --git a/sphinx_docs/source/nova.png → Docs/source/nova.png b/sphinx_docs/source/nova.png → Docs/source/nova.png
diff --git a/sphinx_docs/source/nova2.png → Docs/source/nova2.png b/sphinx_docs/source/nova2.png → Docs/source/nova2.png
diff --git a/sphinx_docs/source/nse.rst → Docs/source/nse.rst b/sphinx_docs/source/nse.rst → Docs/source/nse.rst
diff --git a/sphinx_docs/source/ode_integrators.rst → Docs/source/ode_integrators.rst b/sphinx_docs/source/ode_integrators.rst → Docs/source/ode_integrators.rst
diff --git a/Docs/source/one_zone_tests.rst b/Docs/source/one_zone_tests.rst
@@ -0,0 +1,182 @@
+**************
+One Zone Tests
+**************
+
+There are several tests that let you call the EOS or reaction network
+on a single zone to inspect the output directly.
+
+
+``burn_cell``
+=============
+
+.. index:: burn_cell
+
+``burn_cell`` is a simple one-zone burn that will evolve a state with
+a network for a specified amount of time.  This can be used to
+understand the timescales involved in a reaction sequence or to
+determine the needed ODE tolerances.  This is designed to work
+with the Strang-split integration wrappers.  The system that is evolved
+has the form:
+
+.. math::
+
+   \begin{align*}
+      \frac{dX_k}{dt} &= \dot{\omega}_k(\rho, X_k, T) \\
+      \frac{de}{dt} &= \epsilon(\rho, X_k, T)
+   \end{align*}
+
+with density held constant and the temperature found via the equation of state,
+$T = T(\rho, X_k, e)$.
+
+
+.. note::
+
+   Since the energy evolves due to the heat release (or loss)
+   from reactions, the temperature will change during the burn
+   (unless ``integrator.call_eos_in_rhs=0`` is set).
+
+
+Getting Started
+---------------
+
+The ``burn_cell`` code is located in
+``Microphysics/unit_test/burn_cell``.  An inputs file which sets the
+default parameters for your choice of network is needed to run the
+test.  There are a number of inputs files in the unit test directory
+already with a name list ``inputs_network``, where ``network``
+is the network you wish to use for your testing.  These can be
+used as a starting point for any explorations.
+
+
+Setting the thermodynamics
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The parameters that affect the thermodynamics are:
+
+* ``unit_test.density`` : the initial density
+
+* ``unit_test.temperature`` : the initial temperature
+
+* ``unit_test.small_temp`` : the low temperature cutoff used in the equation of state
+
+* ``unit_test.small_dens`` : the low density cutoff used in the equation of state
+
+The composition can be set either by setting each mass fraction explicitly via the
+parameters, ``unit_test.X1``, ``unit_test.X2``, ...,
+e.g.:
+
+::
+
+    unit_test.X1 = 0.5
+    unit_test.X2 = 0.2
+    unit_test.X3 = 0.2
+    unit_test.X4 = 0.1
+
+where parameters up to ``X35`` are available.  If the values don't sum to ``1``
+initially, then the test will do a normalization.  This normalization can be
+disabled by setting:
+
+::
+
+    unit_test.skip_initial_normalization = 1
+
+
+Alternately, the composition can be set automatically by initializing all
+of the mass fractions equally (to $1/N$, where $N$ is the number of species),
+by setting:
+
+::
+
+    unit_test.init_species_all_equal = 1
+
+
+Controlling time
+^^^^^^^^^^^^^^^^
+
+The test will run unit a time ``unit_test.tmax``, outputting the state
+at regular intervals.  The parameters controlling the output are:
+
+* ``unit_test.tmax`` : the end point of integration.
+
+* ``unit_test.tfirst`` : the first time interval to output.
+
+* ``unit_test.nsteps`` : the number of steps to divide the integration into,
+  logarithmically-spaced.
+
+If there is only a single step, ``unit_test.nsteps = 1``, then we integrate
+from $[0, \mathrm{tmax}]$.
+
+If there are multiple steps, then the first output will be at a time
+$\mathrm{tmax} / \mathrm{nsteps}$, and the steps will be
+logarithmically-spaced afterwards.
+
+
+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``.
+
+
+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, e.g.,
+
+.. prompt:: bash
+
+   make NETWORK_DIR=aprox19 INTEGRATOR_DIR=rkc
+
+The build process will automatically create links in the build
+directory to the EOS table and any reaction rate tables needed by your
+choice of network.
+
+
+.. important::
+
+   You need to do a ``make clean`` before rebuilding with a different
+   network or integrator.
+
+
+To run the code, enter the burn_cell directory and run::
+
+   ./main3d.gnu.ex inputs
+
+where ``inputs`` is the name of your inputs file.
+
+Working with Output
+-------------------
+
+.. note::
+
+   For this part, we'll assume that the default ``aprox13`` and
+   ``VODE`` options were used for the network and integrator, and the
+   test was run with ``inputs.aprox13``.
+
+As the code runs, it will output to ``stdout`` details of the initial
+and final state and the number of integration steps taken (along with whether
+the burn was successful).  The full history of the thermodynamic state will also be output to a file,
+``state_over_time.txt``, with each line corresponding to one of the
+``nsteps`` requested in the time integration.
+
+The script ``plot_burn_cell.py`` can be used to visualize the evolution:
+
+.. prompt:: bash
+
+   python plot_burn_cell.py state_over_time.txt
+
+This will generate the following figure:
+
+.. figure:: state.png
+   :alt: An example of a plot output by the burn_cell unit test.
+
+Only the most abundant species are plotted.  The number of species to plot and the
+limits of $X$ can be set via runtime parameters (see ``python plot_burn_cell.py -h``).
diff --git a/sphinx_docs/source/react_aprox13_logX.png → Docs/source/react_aprox13_logX.png b/sphinx_docs/source/react_aprox13_logX.png → Docs/source/react_aprox13_logX.png
diff --git a/sphinx_docs/source/refs.bib → Docs/source/refs.bib b/sphinx_docs/source/refs.bib → Docs/source/refs.bib
@@ -688,3 +688,16 @@ @article{langanke:2001
 abstract = {The weak interaction rates in stellar environments are computed for pf-shell nuclei in the mass range A=45–65 using large-scale shell-model calculations. The calculated capture and decay rates take into consideration the latest experimental energy levels and log ft-values. The rates are tabulated at the same grid points of density and temperature as those used by Fuller, Fowler, and Newman for densities ρY e =10–1011 g/cm3 and temperatures T=107–1011 K, and hence are relevant for both types of supernovae (Type Ia and Type II). Effective 〈ft〉 values for capture rates and average neutrino (antineutrino) energies are also given to facilitate the use of interpolated rates in stellar evolution codes.}
 }
 
+@ARTICLE{itoh:1996,
+       author = {{Itoh}, Naoki and {Hayashi}, Hiroshi and {Nishikawa}, Akinori and {Kohyama}, Yasuharu},
+        title = "{Neutrino Energy Loss in Stellar Interiors. VII. Pair, Photo-, Plasma, Bremsstrahlung, and Recombination Neutrino Processes}",
+      journal = {\apjs},
+     keywords = {DENSE MATTER, ELEMENTARY PARTICLES, RADIATION MECHANISMS: NONTHERMAL, STARS: INTERIORS, METHODS: NUMERICAL},
+         year = 1996,
+        month = feb,
+       volume = {102},
+        pages = {411},
+          doi = {10.1086/192264},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/1996ApJS..102..411I},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
diff --git a/sphinx_docs/source/rp_intro.rst → Docs/source/rp_intro.rst b/sphinx_docs/source/rp_intro.rst → Docs/source/rp_intro.rst