From 5b7ed06405db0b3747b6c1a19192e93bde21cb05 Mon Sep 17 00:00:00 2001
From: Michael Zingale <michael.zingale@stonybrook.edu>
Date: Mon, 13 Jan 2025 13:29:31 -0500
Subject: [PATCH] update docs

---
 Docs/source/eos_implementations.rst | 62 +++++++++++++++++++++++++++--
 Docs/source/refs.bib                |  7 ++++
 2 files changed, 65 insertions(+), 4 deletions(-)

diff --git a/Docs/source/eos_implementations.rst b/Docs/source/eos_implementations.rst
index 72a968c86..57a6d5f18 100644
--- a/Docs/source/eos_implementations.rst
+++ b/Docs/source/eos_implementations.rst
@@ -16,6 +16,17 @@ The following equations of state are available in Microphysics.
 ``breakout``
 ============
 
+The ``breakout`` EOS is essentially the same as ``gamma_law``, but it gets
+its composition information from the auxiliary data.  In particular,
+it expects an auxiliary quantity named ``invmu`` which is the inverse
+of the mean molecular weight:
+
+.. math::
+
+   \frac{1}{\mu} = \sum_k \frac{Z_k X_k}{A_k}
+
+The ``general_null`` network provides this when used with the ``breakout.net``
+network inputs.
 
 ``gamma_law``
 =============
@@ -76,7 +87,11 @@ calling this.
 
 The following runtime parameters affect the EOS:
 
-* ``eos.use_eos_coulomb``
+* ``eos.use_eos_coulomb`` : do we include Coulomb corrections?  This
+  is enabled by default.  Coulomb corrections can cause problems in
+  some regimes, because the implementation in ``helmholtz`` doesn't
+  have the correct asymptotic behavior and can lead to negative
+  pressures or energies.
 
 * ``eos.eos_input_is_constant`` : when inverting the EOS for find the
   density and/or temperature that match the inputs, there is a choice
@@ -86,10 +101,19 @@ The following runtime parameters affect the EOS:
   input thermodynamic quantities unchanged, respecting energy
   conservation.
 
-* ``eos.eos_ttol``, ``eos.eos_dtol``
-
-* ``eos.prad_limiter_rho_c``, ``eos.prad_limiter_delta_rho``
+* ``eos.eos_ttol``, ``eos.eos_dtol`` : these are the tolerances
+  for temperature and density used by the Newton solver when
+  inverting the EOS.
 
+* ``eos.prad_limiter_rho_c``, ``eos.prad_limiter_delta_rho`` : by
+  default, radiation pressure is included in the optically-thick, LTE
+  limit (with $p_\gamma = (1/3)a T^4$).  At low densities, this can
+  cause issues, leading to an artificially high soundspeed dominated
+  by radiation when, in fact, we should be optically thin.  These
+  parameters allow us turn off the radiation component smoothly,
+  starting at a density ``eos.prad_limiter_rho_c`` and transitioning
+  via a $\tanh$ profile to zero over a scale
+  ``eos.prad_limiter_delta_rho``.
 
 We thank Frank Timmes for permitting us to modify his code and
 publicly release it in this repository.
@@ -97,6 +121,7 @@ publicly release it in this repository.
 ``metal_chem``
 ==============
 
+This is a multi-gamma equation of state for metal ISM chemistry.
 
 ``multigamma``
 ==============
@@ -146,6 +171,8 @@ 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:
 
+.. index:: eos.eos_gamma_default
+
 -  ``eos.eos_gamma_default``: the default :math:`\gamma` to apply for all
    species
 
@@ -199,12 +226,39 @@ polytropic relations. The options are:
 ``primordial_chem``
 ===================
 
+This is a version of the multi-gamma equation of state that models primordial chemistry.
+
 ``rad_power_law``
 =================
 
+This is an artificial equation of state for radiation transport test problems.  It uses
+a parameterization of the specific heat at constant volume:
+
+.. math::
+
+   c_v = A \rho^m T^{-n}
+
+and energy:
+
+.. math::
+
+   e = \frac{A}{1 - n} \rho^m T^{1-n}
+
+where the runtime parameters provide the constants:
+
+* ``eos.eos_const_c_v`` $= A$
+
+* ``eos.eos_c_v_exp_m`` $= m$
+
+* ``eos.eos_c_v_exp_n`` $= n$
+
+
 ``tillotson``
 =============
 
+This is an equation of state for hypervelocity impacts based on :cite:`tillotson:1962`.
+
+
 ``ztwd``
 ========
 
diff --git a/Docs/source/refs.bib b/Docs/source/refs.bib
index 425718a5f..7d95b59a9 100644
--- a/Docs/source/refs.bib
+++ b/Docs/source/refs.bib
@@ -753,3 +753,10 @@ @ARTICLE{quokka
       adsnote = {Provided by the SAO/NASA Astrophysics Data System}
 }
 
+@ARTICLE{tillotson:1962,
+      author = {{Tillotson}, J. H.},
+      title = "{Metallic Equations of State for Hypervelocity Impact}",
+      year = {1962},
+      journal = {Internal Report, General Atomics},
+      url = {https://apps.dtic.mil/sti/citations/AD0486711}
+}