Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update the intro / getting started docs #1733

Merged
merged 1 commit into from
Jan 30, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 34 additions & 8 deletions Docs/source/getting_started.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
==========

Expand Down Expand Up @@ -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.



Expand All @@ -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.:

Expand All @@ -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.
21 changes: 13 additions & 8 deletions Docs/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand Down
Loading