some reorganization of the docs into sections

sphinx_docs/source/basics.rst → sphinx_docs/source/design.rst

@@ -1,72 +1,6 @@
-*********************
-Microphysics Overview
-*********************
-
-Getting Started (Standalone)
-============================
-
-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).
-
-A good unit test to start with is ``burn_cell`` -- this is simply a
-one-zone burn.  In ``Microphysics/`` do:
-
-.. prompt:: bash
-
-   cd unit_test/burn_cell
-   make
-
-This will create an executable called ``main3d.gnu.ex``.  Then you can run it as:
-
-.. prompt:: bash
-
-   ./main3d.gnu.ex inputs_aprox21
-
-By default, the test is built with the 21-isotope ``aprox21`` network.
-Here ``inputs_aprox21`` is the inputs file that sets options.
-
-
-
-Getting Started (Running with MAESTROeX or CASTRO)
-==================================================
-
-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
-variable, either at a 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 codes can use Microphysics in the same fashion.  Unit tests in
-``Microphysics/unit_test/`` provide some examples of using the
-interfaces.
+******
+Design
+******
 
 Structure
 =========

sphinx_docs/source/getting_started.rst

@@ -0,0 +1,69 @@
+***************
+Getting Started
+***************
+
+Standalone
+==========
+
+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).
+
+A good unit test to start with is ``burn_cell`` -- this is simply a
+one-zone burn.  In ``Microphysics/`` do:
+
+.. prompt:: bash
+
+   cd unit_test/burn_cell
+   make
+
+This will create an executable called ``main3d.gnu.ex``.  Then you can run it as:
+
+.. prompt:: bash
+
+   ./main3d.gnu.ex inputs_aprox21
+
+By default, the test is built with the 21-isotope ``aprox21`` network.
+Here ``inputs_aprox21`` is the inputs file that sets options.
+
+
+
+Running with AMReX Application Code
+===================================
+
+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
+variable, either at a 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 codes can use Microphysics in the same fashion.  Unit tests in
+``Microphysics/unit_test/`` provide some examples of using the
+interfaces.

sphinx_docs/source/index.rst

@@ -2,28 +2,58 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-************
-Microphysics
-************
+************************
+AMReX-Astro Microphysics
+************************
+
+A collection of microphysics routines (equations of state,
+reaction networks, ...) and utilities (ODE integrators, NSE solvers)
+for astrophysical simulation codes.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Microphysics basics
 
    preface
-   basics
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Microphysics overview
+
+   getting_started
+   design
    data_structures
    rp_intro
+   unit_tests
+
+.. toctree::
+   :maxdepth: 1
+   :caption: EOS and transport
+
    eos
+   transport
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Reaction networks
+
    networks-overview
    networks
    templated_networks
    screening
+
+.. toctree::
+   :maxdepth: 1
+   :caption: ODE integrators
+
    integrators
+   ode_integrators
    nse
-   transport
-   unit_tests
    sdc
+
+.. toctree::
+   :maxdepth: 1
+   :caption: references
+
    zreferences
 
 

sphinx_docs/source/integrators.rst

@@ -1,9 +1,6 @@
-*********************
-Integrating a Network
-*********************
-
+*******************
 Reaction ODE System
-===================
+*******************
 
 .. note::
 
@@ -312,152 +309,3 @@ because it is most consistent with the operator split methodology we use (densit
 is held constant during the burn when doing Strang splitting).
 Similar to temperature, this will automatically be updated at each integration
 step (unless you set ``integrator.call_eos_in_rhs = 0``).
-
-
-
-Renormalization
-===============
-
-The ``renormalize_abundances`` parameter controls whether we
-renormalize the abundances so that the mass fractions sum to one
-during a burn. This has the positive benefit that in some cases it can
-prevent the integrator from going off to infinity or otherwise go
-crazy; a possible negative benefit is that it may slow down
-convergence because it interferes with the integration
-scheme. Regardless of whether you enable this, we will always ensure
-that the mass fractions stay positive and larger than some floor
-``small_x``.
-
-
-.. _ch:networks:integrators:
-
-Stiff ODE Solvers
-=================
-
-We use a high-order implicit ODE solver for integrating the reaction
-system.  A few alternatives, including first order implicit and explicit integrators are also
-provided.  Internally, the integrators use different data structures
-to store the integration progress, and each integrator needs to
-provide a routine to convert from the integrator’s internal
-representation to the ``burn_t`` type required by the ``actual_rhs``
-and ``actual_jac`` routine.
-
-The name of the integrator can be selected at compile time using
-the ``INTEGRATOR_DIR`` variable in the makefile. Presently,
-the allowed options are:
-
-* ``BackwardEuler``: an implicit first-order accurate backward-Euler
-  method.  An error estimate is done by taking 2 half steps and
-  comparing to a single full step.  This error is then used to control
-  the timestep by using the local truncation error scaling.
-
-* ``ForwardEuler``: an explicit first-order forward-Euler method.  This is
-  meant for testing purposes only.  No Jacobian is needed.
-
-* ``QSS``: the quasi-steady-state method of :cite:`mott_qss` (see also
-  :cite:`guidry_qss`). This uses a second-order predictor-corrector method,
-  and is designed specifically for handling coupled ODE systems for chemical
-  and nuclear reactions. However, this integrator has difficulty near NSE,
-  so we don't recommend its use in production for nuclear astrophysics.
-
-.. index:: integrator.use_circle_theorem
-
-* ``RKC``: a stabilized explicit Runge-Kutta-Chebyshev integrator based
-  on :cite:`sommeijer_rkc_1998`.  This does not require a Jacobian, but
-  does need to estimate the spectral radius of the system, which is
-  done internally.  This works for moderately stiff problems.
-
-  The spectral radius is estimated by default using the power method,
-  built into RKC.  Alternately, by setting ``integrator.use_circle_theorem=1``,
-  the `Gershgorin circle theorem <https://en.wikipedia.org/wiki/Gershgorin_circle_theorem>`_
-  is used instead.
-
-* ``VODE``: the VODE :cite:`vode` integration package.  We ported this
-  integrator to C++ and removed the non-stiff integration code paths.
-
-We recommend that you use the VODE solver, as it is the most
-robust.
-
-.. index:: integrator.scale_system
-
-.. important::
-
-   The integrator will not abort if it encounters trouble.  Instead it will
-   set ``burn_t burn_state.success = false`` on exit.  It is up to the
-   application code to handle the failure.
-
-.. note::
-
-   The runtime parameter ``integrator.scale_system``
-   will scale the internal energy that the integrator sees by the initial
-   value of :math:`e` to make the system :math:`\mathcal{O}(1)`.  The value
-   of ``atol_enuc`` will likewise be scaled.  This works for both Strang
-   and simplified-SDC.  For the ``RKC`` integrator, this is enabled by
-   default.
-
-   For most integrators this algebraic change should not affect the output
-   to more than roundoff, but the option is included to allow for some
-   different integration approaches in the future.
-
-   This option currently does not work with the ForwardEuler or QSS integrators.
-
-Tolerances
-----------
-
-Tolerances dictate how accurate the ODE solver must be while solving
-equations during a simulation.  Typically, the smaller the tolerance
-is, the more accurate the results will be.  However, if the tolerance
-is too small, the code may run for too long or the ODE solver will
-never converge.  In these simulations, ``rtol`` values will set the
-relative tolerances and ``atol`` values will set the absolute tolerances
-for the ODE solver.  Often, one can find and set these values in an
-input file for a simulation.
-
-:numref:`fig:tolerances` shows the results of a simple simulation using the
-burn_cell unit test to determine
-what tolerances are ideal for simulations.
-For this investigation, it was assumed that a run with a tolerance of :math:`10^{-12}`
-corresponded to an exact result,
-so it is used as the basis for the rest of the tests.
-From the figure, one can infer that the :math:`10^{-3}` and :math:`10^{-6}` tolerances
-do not yield the most accurate results
-because their relative error values are fairly large.
-However, the test with a tolerance of :math:`10^{-9}` is accurate
-and not so low that it takes incredible amounts of computer time,
-so :math:`10^{-9}` should be used as the default tolerance in future simulations.
-
-.. _fig:tolerances:
-.. figure:: tolerances.png
-   :alt: Relative error plot
-   :width: 100%
-
-   Relative error of runs with varying tolerances as compared
-   to a run with an ODE tolerance of :math:`10^{-12}`.
-
-The integration tolerances for the burn are controlled by
-``rtol_spec`` and  ``rtol_enuc``,
-which are the relative error tolerances for
-:eq:`eq:spec_integrate` and :eq:`eq:enuc_integrate`,
-respectively. There are corresponding
-``atol`` parameters for the absolute error tolerances. Note that
-not all integrators handle error tolerances the same way—see the
-sections below for integrator-specific information.
-
-The absolute error tolerances are set by default
-to :math:`10^{-12}` for the species, and a relative tolerance of :math:`10^{-6}`
-is used for the temperature and energy.
-
-
-Overriding Parameter Defaults on a Network-by-Network Basis
-===========================================================
-
-Any network can override or add to any of the existing runtime
-parameters by creating a ``_parameters`` file in the network directory
-(e.g., ``networks/triple_alpha_plus_cago/_parameters``). As noted in
-:doc:`rp_intro`, the fourth column in the ``_parameter``
-file definition is the *priority*. When a duplicate parameter is
-encountered by the scripts writing the runtime parameter header files, the value
-of the parameter with the highest priority is used. So picking a large
-integer value for the priority in a network’s ``_parameter`` file will
-ensure that it takes precedence.
-