From 8638acc8e55c842872e707b5a8eeff46b64d8fd0 Mon Sep 17 00:00:00 2001
From: Michael Zingale <michael.zingale@stonybrook.edu>
Date: Sun, 5 Jan 2025 19:33:07 -0500
Subject: [PATCH] document the util/ directory

---
 sphinx_docs/source/index.rst |  7 ++++++
 sphinx_docs/source/util.rst  | 46 ++++++++++++++++++++++++++++++++++++
 2 files changed, 53 insertions(+)
 create mode 100644 sphinx_docs/source/util.rst

diff --git a/sphinx_docs/source/index.rst b/sphinx_docs/source/index.rst
index c0e9fc762..c12d22286 100644
--- a/sphinx_docs/source/index.rst
+++ b/sphinx_docs/source/index.rst
@@ -71,6 +71,13 @@ of state routines.
    nse
    sdc
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Util / external libraries
+   :hidden:
+
+   util
+
 .. toctree::
    :maxdepth: 1
    :caption: Unit tests
diff --git a/sphinx_docs/source/util.rst b/sphinx_docs/source/util.rst
new file mode 100644
index 000000000..1ac479819
--- /dev/null
+++ b/sphinx_docs/source/util.rst
@@ -0,0 +1,46 @@
+******************************
+Helper Functions and Libraries
+******************************
+
+The ``util/`` directory contains a number of external libraries and simple
+utilities that are used by the different components of Microphysics.
+
+* ``approx_math/`` : these are a set of headers that implement
+  approximations to ``atan()``, ``exp()``, ``log()``, and ``pow()``.
+  These can be much faster than the C++ library versions, especially
+  on GPUs.
+
+* ``autodiff/`` : this is a clone of the C++ autodiff library from
+  https://github.com/autodiff/autodiff
+
+  The header ``microphysics_autodiff.H`` provides a set of interfaces
+  for working with the AMReX datatypes and interfacing with the
+  autodiff library.
+
+* ``build_scripts/`` : a set of python scripts used during the build
+  process to parse the runtime parameters.
+
+* ``cj_detonation/`` : a simple routine to compute the Chapman-Jouguet
+  detonation speed for one of our networks.
+
+* ``esum.H`` : an implementation of the exact sum algorithm based on the
+  msum algorithm by Raymond Hettinger.  It is generated automatically
+  by the ``esum_cxx.py`` script and creates implementations for exact
+  numbers of terms (``esum3()``, ``esum4()``, ...)
+
+* ``gcem/`` : a templated math library that provides implementations of
+  the standard library math functions that can be used in ``constexpr``
+  expressions.  This is from https://github.com/kthohr/gcem
+
+  Some of the constants are redefined in 64-bit floating point in
+  ``microphysics_math.H`` to avoid ``long double`` issues on some
+  architectures.
+
+* ``hybrj/`` : a C++ port of the MINPACK hybrid Powell minimization function
+  to zero a set of functions.
+
+* ``linpack.H`` : a C++ port of the LINPACK ``dgesl`` and ``dgefa`` LU
+  decomposition Gaussian elimination routines.
+
+* ``microphysics_sort.H`` : a set of sorting routines for
+  ``amrex::Array1D`` data.