From 76cbfa3a28bb0293a81d7fb11b22336da216bcdb Mon Sep 17 00:00:00 2001 From: Michael Zingale Date: Thu, 30 Jan 2025 10:40:45 -0500 Subject: [PATCH 1/2] update the intro / getting started docs (#1733) --- Docs/source/getting_started.rst | 42 ++++++++++++++++++++++++++------- Docs/source/index.rst | 21 ++++++++++------- 2 files changed, 47 insertions(+), 16 deletions(-) diff --git a/Docs/source/getting_started.rst b/Docs/source/getting_started.rst index 02aab8f7a..18e09c065 100644 --- a/Docs/source/getting_started.rst +++ b/Docs/source/getting_started.rst @@ -2,6 +2,29 @@ Getting Started *************** +Requirements +============ + +Microphysics requires + +* A C++17 or later compilers +* AMReX (https://github.com/amrex-codes/amrex) +* python (>= 3.10) +* GNU make + +optional dependencies are: + +* CUDA (>= 11) +* ROCm (>= 6.3.1 --- earlier versions have register allocation bugs) + +Microphysics is meant to be compiled into an application code as part +of its build process, with the network, EOS, integrator, and more +picked at compile time. As such, there is not a single library that +can be built and linked against. + +Below we describe how to use Microphysics in a "standalone" fashion, +using the provided unit tests, and as part of an application code. + Standalone ========== @@ -39,10 +62,11 @@ This will create an executable called ``main3d.gnu.ex``. Then you can run it as .. prompt:: bash - ./main3d.gnu.ex inputs_aprox21 + ./main3d.gnu.ex inputs_aprox13 -By default, the test is built with the 21-isotope ``aprox21`` network. -Here ``inputs_aprox21`` is the inputs file that sets options. +By default, the test is built with the 13-isotope ``aprox13`` network, +``helmholtz`` EOS, and VODE integrator. +Here ``inputs_aprox13`` is the inputs file that sets options. @@ -51,11 +75,15 @@ Running with AMReX Application Code .. index:: MICROPHYSICS_HOME -Getting started with Microphysics using either CASTRO or MAESTROeX is +Getting started with Microphysics using either `CASTRO +`_ or `MAESTROeX +`_ is straightforward. Because the modules here are already in a format that the AMReX codes understand, you only need to provide to the code calling these routines their location on your system. The code will do -the rest. To do so, define the ``MICROPHYSICS_HOME`` environment +the rest. + +First we need to define the ``MICROPHYSICS_HOME`` environment variable, either at a command line or (if you use the bash shell) through your ``~/.bashrc``, e.g.: @@ -70,6 +98,4 @@ rely on the Microphysics ``Make.Microphysics_extern`` makefile stub source to the build. All of the interfaces that these codes use are found in ``Microphysics/interfaces/``. -Other codes can use Microphysics in the same fashion. Unit tests in -``Microphysics/unit_test/`` provide some examples of using the -interfaces. +Other AMReX-based codes can use Microphysics in the same fashion. diff --git a/Docs/source/index.rst b/Docs/source/index.rst index 345db4178..a366bd78c 100644 --- a/Docs/source/index.rst +++ b/Docs/source/index.rst @@ -14,11 +14,14 @@ The original design was to support codes based on the `AMReX `_ adaptive mesh refinement library :cite:`amrex_joss`, including `CASTRO `_ :cite:`castro_I`, `MAESTROeX -`_ :cite:`maestroex`, and Quokka :cite:`quokka`. These all have a +`_ :cite:`maestroex`, and, later, 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 `_ -simulation code. + +Microphysics is written in C++ as a (mostly) header-only library, making +extensive use of templating and C++ `constexpr` features to be performant +on both CPU and GPU architectures. It is compatible with both NVIDIA CUDA +and AMD HIP/ROCm. While there are a number of unit tests that exercise the functionality, Microphysics is primarily intended to be used along with another simulation @@ -26,11 +29,13 @@ code. At the moment, the interfaces and build stubs are compatible with the AMReX codes and use the AMReX build system. -A number of the routines contained here we authored by other people. -We bundle them here with permission, usually changing the interfaces -to be compatible with our standardized interface. We in particular -thank Frank Timmes for numerous reaction networks and his equation -of state routines. +.. note:: + + A number of the routines contained here we authored by other people. + We bundle them here with permission, usually changing the interfaces + to be compatible with our standardized interface. We in particular + thank Frank Timmes for numerous reaction networks and his equation + of state routines. .. toctree:: From b0839d14d6eca2d22cd6bb58811f32c247defbe8 Mon Sep 17 00:00:00 2001 From: Michael Zingale Date: Mon, 3 Feb 2025 07:56:19 -0500 Subject: [PATCH 2/2] update the CHANGES.md for 25.02 (#1734) Co-authored-by: Eric T. Johnson --- CHANGES.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 51 insertions(+), 2 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index cf85c9983..df0a3906f 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,5 +1,54 @@ # Changelog +## 25.02 + + * documentation updates (#1678, #1690, #1692, #1695, #1700, #1702, + #1703, #1707, #1709, #1712, #1713, #1714, #1715, #1716, #1723, + #1726, #1732, #1733) including renaming the docs directory to + `Docs` (#1689) and the addition of a CITATION.md (#1731) + + * codespell fixes (#1724) + + * rename `test_nse_net` -> `nse_net_cell`; `test_part_func` -> + `part_func_cell` (#1729) + + * remove old testing scripts (#1727) + + * update `test_react` `README.md` (#1722) + + * implement Debye-Huckel screening and allow it to be used as a test + for whether screening is needed (#1688) + + * remove the `use_raw_inputs` option from the EOS (#1721) + + * remove some old Fortran references (#1718, #1719) + + * switch from `std::clamp` to `amrex::Clamp` due to HIP compiler + issues (#1711) + + * reorganize the He nets -- they are now all under + `networks/he-burn` and share a common python setup (#1687, #1710) + also update these nets with pynucastro (#1685). This also + add a new network with 31. + + Renamed nets are: + * `subch_base` -> `he-burn/he-burn-18a` + * `subch_simple` -> `he-burn/he-burn-22a` + * `He-C-Fe-group` -> `he-burn/he-burn-36a` + * `CNO_He_burn` -> `he-burn/cno-he-burn-33a` + + * fix the Chapman-Jouguet detonation utility (#1699) + + * update the mailmap (#1706) + + * switch `std::pow(x, 1./3.)` to `std::cbrt(x)` (#1705) + + * remove `do_acc` option (#1708) + + * make the breakout EOS check if 1/mu is defined (#1694) + + * remove old Doxygen (#1697) and skynet (#1698) scripts from `util/` + ## 25.01 * update HIP/CUDA dependences to include sparse libraries (#1686) @@ -834,7 +883,7 @@ ## 19.01 * the docs are now automatically build from the sphinx source - using travis on github. + using travis on github. ## 18.12 @@ -894,7 +943,7 @@ * some fixes to the numerical Jacobian involving X vs. Y (#100) - * a new `subCh` network for He burning was added. + * a new `subCh` network for He burning was added. * implemented the new c12(a,g)o16 nuclear reaction rate and its corresponding inverse from the work of Deboer et al. 2017 (Rev Mod