*************** Getting Started *************** Requirements ============ Microphysics requires * A C++17 or later compiler * 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) Usage Modes =========== There are two ways to use Microphysics: * As part of an application code, where Microphysics provides the network, EOS, etoc. * In a standalone fashion, where simple unit tests can be run to explore integration or thermodynamics. In each case, the physics choices (network, EOS, etc) need to be made 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 both of these modes. Standalone ========== .. index:: AMREX_HOME Microphysics can be used in a "standalone" fashion to run the unit tests and explore the behavior of the reaction networks. The main requirement is a copy of AMReX: .. prompt:: bash git clone https://github.com/AMReX-Codes/amrex.git We use this for some data structures and the build system. You need to set the ``AMREX_HOME`` environment variable to point to the ``amrex/`` directory: .. prompt:: bash export AMREX_HOME=/path/to/amrex (where you change ``/path/to/amrex`` to your actual path). .. index:: burn_cell A good unit test to start with is ``burn_cell``---this is simply a one-zone burn. In the ``Microphysics/`` directory, do: .. prompt:: bash cd unit_test/burn_cell make This will create an executable called ``main3d.gnu.ex``. By default, the test is built with the 13-isotope ``aprox13`` network, ``helmholtz`` EOS, and VODE integrator. Then you can run it as: .. prompt:: bash ./main3d.gnu.ex inputs_aprox13 Here ``inputs_aprox13`` is the inputs file that sets options. This will output information about the starting and final state to the terminal and produce a file ``state_over_time.txt`` that contains the thermodynamic history at different points in time. .. important:: Because the choice of physics is set at compile time, if you want to change a network or EOS, you must rebuild. In the Microphysics / AMReX build system, this is done via: .. prompt:: bash make clean .. note:: See the :ref:`sec:burn_cell` documentation for more details on this unit test and how to visualize the output. Running with AMReX Application Code =================================== .. index:: MICROPHYSICS_HOME 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. First we need to define the ``MICROPHYSICS_HOME`` environment variable, either on the command line or (if you use the bash shell) through your ``~/.bashrc``, e.g.: .. code:: bash export MICROPHYSICS_HOME=/path/to/Microphysics For CASTRO and MAESTROeX the name of the EOS and network are set via the make variables ``EOS_DIR`` and ``NETWORK_DIR``. These codes then rely on the Microphysics ``Make.Microphysics_extern`` makefile stub (found via the ``MICROPHYSICS_HOME`` variable) to add the necessary source to the build. All of the interfaces that these codes use are found in ``Microphysics/interfaces/``. Other AMReX-based codes can use Microphysics in the same fashion.