update the intro / getting started docs (#1733)

Author: zingale

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
+<https://amrex-astro.github.io/Castro/docs/index.html>`_ or `MAESTROeX
+<https://amrex-astro.github.io/MAESTROeX/docs/index.html>`_ 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.

Docs/source/index.rst

@@ -14,23 +14,28 @@ 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
+<https://github.com/amrex-astro/MAESTROeX>`_ :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 <https://github.com/quokka-astro/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
 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::