***************
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.