start of some doc fixes (#1667)

this improves the landing page and eliminates the preface
also remove some old text that is no longer accurate
finally, start working on the index

Author: zingale

sphinx_docs/source/data_structures.rst

@@ -13,6 +13,8 @@ EOS
 ``eos_t``
 ---------
 
+.. index:: eos_t
+
 The main data structure for interacting with the EOS is ``eos_t``.
 This is a collection of data specifying the microphysical state of the
 fluid that we are evaluating. This has many components. For a
@@ -49,6 +51,8 @@ Networks
 ``burn_t``
 ----------
 
+.. index:: burn_t
+
 The main data structure for interacting with the reaction networks is
 ``burn_t``. This holds the composition (mass fractions), thermodynamic
 state, and a lot of internal information used by the reaction network
@@ -89,14 +93,18 @@ the user will only need to fill/use the following information:
 ``rate_t``, ``rate_fr_t``
 -------------------------
 
-The ``rate_t`` and ``rate_fr_t`` structures are used internally in a network to pass the
+.. index:: rate_t
+
+The ``rate_t`` structure is used internally in a network to pass the
 raw reaction rate information (usually just the temperature-dependent
 terms) between various subroutines. It does not come out of the
 network-specific righthand side or Jacobian routines.
 
 ``burn_type.H``
 ---------------
 
+.. index:: burn_type.H
+
 In addition to defining the ``burn_t`` type, the header ``burn_type.H``
 also defines integer indices into the solution vector that can be used
 to access the different components of the state:

sphinx_docs/source/eos.rst

@@ -9,6 +9,8 @@ an EOS module in case you want to build your own.
 Available Equations of State
 ============================
 
+.. index:: eos_t
+
 The following equations of state are available in Microphysics.
 Except where noted, each of these EOSs will provide the full
 thermodynamic data (including all derivatives) in the ``eos_t``
@@ -22,32 +24,27 @@ equation of state:
 
 .. math:: p = (\gamma - 1) \rho e.
 
-:math:`\gamma` is specified by the runtime parameter ``eos_gamma``. For
+:math:`\gamma` is specified by the runtime parameter ``eos.eos_gamma``. For
 an ideal gas, this represents the ratio of specific heats. The gas is
 assumed to be ideal, with the pressure given by
 
 .. math:: p = \frac{\rho k T}{\mu m_u}
 
 where :math:`k` is Boltzmann’s constant and :math:`\mu` is the mean molecular
 weight, calculated from the composition, :math:`X_k`. This EOS assumes
-the gas is either completely neutral (``assume_neutral = T``),
+the gas is either completely neutral (``eos.assume_neutral = 1``),
 giving:
 
 .. math:: \mu^{-1} = \sum_k \frac{X_k}{A_k}
 
-or completely ionized (``assume_neutral = F``), giving:
+or completely ionized (``eos.assume_neutral = 0``), giving:
 
 .. math:: \mu^{-1} = \sum_k \left ( 1 + Z_k \right ) \frac{X_k}{A_k}
 
 The entropy comes from the Sackur-Tetrode equation. Because of the
 complex way that composition enters into the entropy, the entropy
 formulation here is only correct for a :math:`\gamma = 5/3` gas.
 
-Note that the implementation provided in Microphysics is the same as
-the version shipped with MAESTRO, but more general than the
-``gamma_law`` EOS provided with CASTRO. CASTRO’s default EOS only
-fills the thermodynamic information in ``eos_t`` that is required
-by the hydrodynamics module in CASTRO.
 
 polytrope
 ---------
@@ -63,21 +60,21 @@ only independent variable; there is no temperature dependence. The
 user either selects from a set of predefined options reflecting
 physical polytropes (e.g. a non-relativistic, fully degenerate
 electron gas) or inputs their own values for :math:`K` and :math:`\gamma`
-via ``polytrope_K`` and ``polytrope_gamma``.
+via ``eos.polytrope_K`` and ``eos.polytrope_gamma``.
 
-The runtime parameter ``polytrope_type`` selects the pre-defined
+The runtime parameter ``eos.polytrope_type`` selects the pre-defined
 polytropic relations. The options are:
 
--  ``polytrope_type = 1``: sets :math:`\gamma = 5/3` and
+-  ``eos.polytrope_type = 1``: sets :math:`\gamma = 5/3` and
 
    .. math:: K = \left ( \frac{3}{\pi} \right)^{2/3} \frac{h^2}{20 m_e m_p^{5/3}} \frac{1}{\mu_e^{5/3}}
 
-   where :math:`mu_e` is the mean molecular weight per electron, specified via ``polytrope_mu_e``
+   where :math:`mu_e` is the mean molecular weight per electron, specified via ``eos.polytrope_mu_e``
 
    This is the form appropriate for a non-relativistic
    fully-degenerate electron gas.
 
--  ``polytrope_type = 2``: sets :math:`\gamma = 4/3` and
+-  ``eos.polytrope_type = 2``: sets :math:`\gamma = 4/3` and
 
    .. math:: K = \left ( \frac{3}{\pi} \right)^{1/3} \frac{hc}{8 m_p^{4/3}} \frac{1}{\mu_e^{4/3}}
 
@@ -161,12 +158,12 @@ and :math:`p = \rho e (\gamma_\mathrm{effective} - 1)`.
 This equation of state takes several runtime parameters that can set
 the :math:`\gamma_i` for a specific species. The parameters are:
 
--  ``eos_gamma_default``: the default :math:`\gamma` to apply for all
+-  ``eos.eos_gamma_default``: the default :math:`\gamma` to apply for all
    species
 
--  ``species_X_name`` and ``species_X_gamma``: set the
+-  ``eos.species_X_name`` and ``eos.species_X_gamma``: set the
    :math:`\gamma_i` for the species whose name is given as
-   ``species_X_name`` to the value provided by ``species_X_gamma``.
+   ``eos.species_X_name`` to the value provided by ``eos.species_X_gamma``.
    Here, ``X`` can be one of the letters: ``a``, ``b``, or
    ``c``, allowing us to specify custom :math:`\gamma_i` for up to three
    different species.
@@ -209,6 +206,8 @@ appropriate interpolation table from that site to use this.
 Interface and Modes
 ===================
 
+.. index:: eos_t, eos_re_t, eos_rep_t, eos_rh_t, chem_eos_t
+
 The EOS is called as:
 
 .. code:: c++
@@ -244,6 +243,11 @@ The *eos_type* passed in is one of
 
 * ``eos_rep_t`` : expands on ``eos_re_t`` to include pressure information
 
+* ``eos_rh_t`` : expands on ``eos_rep_t`` to include enthalpy information
+
+* ``chem_eos_t`` : adds some quantities needed for the primordial chemistry EOS
+  and explicitly does not include the mass fractions.
+
 In general, you should use the type that has the smallest set of
 information needed, since we optimize out needless quantities at
 compile type (via C++ templating) for ``eos_re_t`` and ``eos_rep_t``.
@@ -260,6 +264,7 @@ compile type (via C++ templating) for ``eos_re_t`` and ``eos_rep_t``.
 Auxiliary Composition
 ---------------------
 
+.. index:: USE_AUX_THERMO
 
 With ``USE_AUX_THERMO=TRUE``, we interpret the composition from the auxiliary variables.
 The auxiliary variables are
@@ -298,6 +303,21 @@ The equation of state also needs :math:`\bar{Z}` which is easily computed as
    \bar{Z} = \bar{A} Y_e
 
 
+Composition Derivatives
+-----------------------
+
+.. index:: eos_extra_t, eos_re_extra_t, eos_rep_extra_t
+
+The derivatives $\partial p/\partial A$, $\partial p/\partial Z$,
+and $\partial e/\partial A$, $\partial e/\partial Z$ are available via
+the ``eos_extra_t``, ``eos_re_extra_t``, ``eos_rep_extra_t``, which
+extends the non-"extra" variants with these additional fields.
+
+The composition derivatives can be used via the ``composition_derivatives()`` function
+in ``eos_composition.H``
+to compute :math:`\partial p/\partial X_k |_{\rho, T, X_j}`, :math:`\partial e/\partial X_k |_{\rho, T, X_j}`, and :math:`\partial h/\partial X_k |_{\rho, T, X_j}`.
+
+
 Initialization and Cutoff Values
 ================================
 
@@ -328,6 +348,3 @@ appropriate time for, say, loading an interpolation table into memory.
 
 The main evaluation routine is called ``actual_eos``. It should
 accept an eos_input and an eos_t state; see Section :ref:`data_structures`.
-
-
-

sphinx_docs/source/getting_started.rst

@@ -5,6 +5,8 @@ Getting Started
 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:
@@ -23,6 +25,8 @@ to set the ``AMREX_HOME`` environment variable to point to the
 
 (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 ``Microphysics/`` do:
 
@@ -45,6 +49,8 @@ Here ``inputs_aprox21`` is the inputs file that sets options.
 Running with AMReX Application Code
 ===================================
 
+.. index:: MICROPHYSICS_HOME
+
 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

sphinx_docs/source/index.rst

@@ -6,18 +6,36 @@
 AMReX-Astro Microphysics
 ************************
 
-A collection of microphysics routines (equations of state,
+AMReX-Astro Microphysics is a collection of microphysics routines (equations of state,
 reaction networks, ...) and utilities (ODE integrators, NSE solvers)
 for astrophysical simulation codes.
 
-.. toctree::
-   :maxdepth: 1
+The original design was to support the `AMReX
+<https://github.com/amrex-codes/amrex>`_ codes `CASTRO
+<https://github.com/amrex-astro/Castro>`_ and MAESTRO (now `MAESTROeX
+<https://github.com/amrex-astro/MAESTROeX>`_). 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.
+
+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.
 
-   preface
 
 .. toctree::
    :maxdepth: 1
    :caption: Microphysics overview
+   :hidden:
 
    getting_started
    design
@@ -28,13 +46,15 @@ for astrophysical simulation codes.
 .. toctree::
    :maxdepth: 1
    :caption: EOS and transport
+   :hidden:
 
    eos
    transport
 
 .. toctree::
    :maxdepth: 1
    :caption: Reaction networks
+   :hidden:
 
    networks-overview
    networks
@@ -44,6 +64,7 @@ for astrophysical simulation codes.
 .. toctree::
    :maxdepth: 1
    :caption: ODE integrators
+   :hidden:
 
    integrators
    ode_integrators
@@ -53,6 +74,7 @@ for astrophysical simulation codes.
 .. toctree::
    :maxdepth: 1
    :caption: Unit tests
+   :hidden:
 
    unit_tests
    comprehensive_tests
@@ -61,13 +83,13 @@ for astrophysical simulation codes.
 .. toctree::
    :maxdepth: 1
    :caption: References
+   :hidden:
 
    zreferences
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Index
+   :hidden:
 
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   genindex

sphinx_docs/source/integrators.rst

@@ -17,11 +17,13 @@ The equations we integrate to do a nuclear burn are:
    \frac{de}{dt} = f(\rho,X_k,T)
    :label: eq:enuc_integrate
 
-Here, :math:`X_k` is the mass fraction of species :math:`k`, :math:`e` is the specific
-nuclear energy created through reactions. Also needed are density :math:`\rho`,
-temperature :math:`T`, and the specific heat. The function :math:`f` provides the energy release from reactions and can often be expressed in terms of the
-instantaneous reaction terms, :math:`\dot{X}_k`. As noted in the previous
-section, this is implemented in a network-specific manner.
+Here, :math:`X_k` is the mass fraction of species :math:`k`, :math:`e`
+is the specific nuclear energy created through reactions. Also needed
+are density :math:`\rho`, temperature :math:`T`, and the specific
+heat. The function :math:`f` provides the energy release from
+reactions and can often be expressed in terms of the instantaneous
+reaction terms, :math:`\dot{X}_k`. As noted in the previous section,
+this is implemented in a network-specific manner.
 
 In this system, :math:`e` is equal to the total specific internal
 energy. This allows us to easily call the EOS during the burn to obtain the temperature.
@@ -223,7 +225,7 @@ flow is (for VODE):
    and zero out the temperature and energy derivatives if we are not integrating
    those quantities.
 
-#. apply any boosting if ``react_boost`` > 0
+#. apply any boosting if ``integrator.react_boost`` > 0
 
 
 Jacobian implementation

sphinx_docs/source/networks-overview.rst

@@ -114,9 +114,11 @@ There are two primary files within each network directory.
    state and (respectively) the time-derivatives and Jacobian
    elements to fill in.
 
-   Note: some networks do not provide an analytic Jacobian and instead
-   rely on the numerical difference-approximation to the Jacobian. In
-   this case, the interface ``actual_jac`` is still needed to compile.
+   .. note::
+
+      Some networks do not provide an analytic Jacobian and instead
+      rely on the numerical difference-approximation to the Jacobian. In
+      this case, the interface ``actual_jac`` is still needed to compile.
 
 Notice that these modules have initialization routines:
 

sphinx_docs/source/networks.rst

@@ -56,6 +56,8 @@ for plotfile variables, and the mass number, :math:`A`, and proton number, :math
 
 The name of the inputs file by one of two make variables:
 
+.. index:: NETWORK_INPUTS, GENERAL_NET_INPUTS
+
 * ``NETWORK_INPUTS`` : this is simply the name of the "`.net`" file, without
   any path.  The build system will look for it in the current directory
   and then in ``$(MICROPHYSICS_HOME)/networks/general_null/``.

sphinx_docs/source/nse.rst

@@ -7,6 +7,8 @@ instead of integrating the entire network when the conditions are
 appropriate.  There are 2 different implementations of NSE in
 Microphysics, that have slightly different use cases.
 
+.. index:: USE_NSE_TABLE, USE_NSE_NET
+
 * :ref:`tabulated_nse` : this uses a table of NSE abundances given
   :math:`(\rho, T, Y_e)` generate from a large network (125 isotopes).
   The table also returns :math:`dY_e/dt` resulting from

sphinx_docs/source/one_zone_tests.rst

@@ -9,6 +9,8 @@ on a single zone to inspect the output directly.
 ``burn_cell``
 =============
 
+.. index:: ``burn_cell``
+
 ``burn_cell`` is a simple one-zone burn that will evolve a state with
 a network for a specified amount of time.  This can be used to
 understand the timescales involved in a reaction sequence or to