Add mean atomic mass and number

CHANGELOG.md

@@ -5,7 +5,8 @@
 ### Added (new features/APIs/variables/...)
 
 ### Fixed (Repair bugs, etc)
-- [[OR437]](https://github.com/lanl/singularity-eos/pull/437) Fix segfault on HIP, clean up warnings, add strict sanitizer test
+- [[PR439]](https://github.com/lanl/singularity-eos/pull/439) Add mean atomic mass and number to EOS API
+- [[PR437]](https://github.com/lanl/singularity-eos/pull/437) Fix segfault on HIP, clean up warnings, add strict sanitizer test
 
 ### Changed (changing behavior/API/variables/...)
 

doc/sphinx/src/models.rst

@@ -338,6 +338,38 @@ Note: sometimes temperatures are measured in eV for which the conversion is
 
 Sesame units are equivalent to the mm-mg-µs unit system.
 
+The ``MeanAtomicProperties`` struct
+------------------------------------
+
+Several analytic equations of state optionally accept mean atomic mass
+and number as physics properties. These are the average number of
+nucleons and protons in a constituent nucleus respectively. They are
+not necessarily integers, as a given material may be made up of
+multiple kinds of atom. For example, dry air contains both nitrogen
+and oxygen.
+
+The mean atomic mass and number are frequently carried in the
+container struct
+
+.. code-block:: cpp
+
+  struct MeanAtomicProperties {
+    Real Abar, Zbar;
+
+    // default is hydrogen
+    static constexpr Real DEFAULT_ABAR = 1.0;
+    static constexpr Real DEFAULT_ZBAR = 1.0;
+
+    PORTABLE_INLINE_FUNCTION
+    MeanAtomicProperties(Real Abar_, Real Zbar_) : Abar(Abar_), Zbar(Zbar_) {}
+    PORTABLE_INLINE_FUNCTION
+    MeanAtomicProperties() : Abar(DEFAULT_ABAR), Zbar(DEFAULT_ZBAR) {}
+  };
+
+which owns the atomic mass ``Abar`` and atomic number ``Zbar``. You
+may set these by constructing the struct or by setting the fields in a
+pre-constructed struct. The defaults are for hydrogen.
+
 Implemented EOS models
 ----------------------
 
@@ -429,6 +461,14 @@ these values are not set, they will be the same as those returned by the
 conditions are given, the return values of the :code:`ValuesAtReferenceState()`
 function will not be the same.
 
+Both constructors also optionally accept `MeanAtomicProperties` for
+the atomic mass and number as a final optional parameter, e.g.,
+
+.. code-block:: cpp
+
+   IdealGas(Real gm1, Real Cv, MeanAtomicProperties(Abar, Zbar));
+   IdealGas(Real gm1, Real Cv, Real EntropyT0, Real EntropyRho0, MeanAtomicProperties(Abar, Zbar));
+
 Stiffened Gas
 `````````````
 
@@ -486,6 +526,15 @@ these values are not set, they will be the same as those returned by the
 conditions are given, the return values of the :code:`ValuesAtReferenceState()`
 function will not be the same.
 
+Both constructors also optionally accept `MeanAtomicProperties` for
+the atomic mass and number as a final optional parameter, e.g.,
+
+.. code-block:: cpp
+
+   StiffGas(Real gm1, Real Cv, Real Pinf, Real q, MeanAtomicProperties(Abar, Zbar));
+   StiffGas(Real gm1, Real Cv, Real Pinf, Real q, Real qp, Real T0, Real P0,
+            EntropyRho0, MeanAtomicProperties(Abar, Zbar));
+
 Noble-Abel
 ``````````
 
@@ -544,6 +593,17 @@ these values are not set, they will be the same as those returned by the
 conditions are given, the return values of the :code:`ValuesAtReferenceState()`
 function will not be the same.
 
+Both constructors also optionally accept `MeanAtomicProperties` for
+the atomic mass and number as a final optional parameter, e.g.,
+
+.. code-block:: cpp
+
+   NobleAbel(Real gm1, Real Cv, Real b, Real q,
+             MeanAtomicProperties(Abar, Zbar));
+   NobleAbel(Real gm1, Real Cv, Real b, Real q, Real qp, Real T0, Real P0,
+             MeanAtomicProperties(Abar, Zbar));
+
+
 Carnahan-Starling
 `````````````````
 
@@ -630,6 +690,16 @@ these values are not set, they will be the same as those returned by the
 conditions are given, the return values of the :code:`ValuesAtReferenceState()`
 function will not be the same.
 
+Both constructors also optionally accept `MeanAtomicProperties` for
+the atomic mass and number as a final optional parameter, e.g.,
+
+.. code-block:: cpp
+
+    CarnahanStarling(Real gm1, Real Cv, Real b, Real q,
+                     MeanAtomicProperties(Abar, Zbar))
+    CarnahanStarling(Real gm1, Real Cv, Real b, Real q, Real qp, Real T0, Real P0,
+                     MeanAtomicProperties(Abar, Zbar))
+
 Gruneisen EOS
 `````````````
 
@@ -767,6 +837,9 @@ There is an overload of the ``Gruneisen`` class which computes
   Gruneisen(const Real C0, const Real s1, const Real s2, const Real s3, const Real G0,
             const Real b, const Real rho0, const Real T0, const Real P0, const Real Cv)
 
+Both constructors also optionally accept `MeanAtomicProperties` for
+the atomic mass and number as a final optional parameter.
+
 Extendended Vinet EOS
 `````````````````````
 
@@ -849,6 +922,9 @@ is :math:`S_0`, and ``expconsts`` is a pointer to the constant array of length
 :math:`d_2` to :math:`d_{40}`. Expansion coefficients not used should be set to
 0.0.
 
+This constructor also optionally accepts `MeanAtomicProperties` for
+the atomic mass and number as a final optional parameter.
+
 Mie-Gruneisen linear :math:`U_s`- :math:`u_p` EOS
 `````````````````````````````````````````````````
 
@@ -995,6 +1071,9 @@ where
 ``G0`` is :math:`\Gamma(\rho_0)`, ``Cv0`` is :math:`C_V`,
 ``E0`` is :math:`E_0`, and ``S0`` is :math:`S_0`. 
 
+This constructor also optionally accepts `MeanAtomicProperties` for
+the atomic mass and number as a final optional parameter.
+
 Mie-Gruneisen power expansion EOS
 `````````````````````````````````
 As we noted above, the assumption of a linear :math:`U_s`- :math:`u_p` relation is simply not valid at large compressions. At 
@@ -1075,6 +1154,8 @@ where
 :math:`K_0` to :math:`K_{40}`. Expansion coefficients not used should be set to
 :math:`0.0`.
 
+This constructor also optionally accepts `MeanAtomicProperties` for
+the atomic mass and number as a final optional parameter.
 
 
 JWL EOS
@@ -1127,6 +1208,9 @@ where ``A`` is :math:`A`, ``B`` is :math:`B`, ``R1`` is :math:`R_1`,
 ``R2`` is :math:`R_2`, ``w`` is :math:`w`, ``rho0`` is :math:`\rho_0`,
 and ``Cv`` is :math:`C_V`.
 
+This constructor also optionally accepts `MeanAtomicProperties` for
+the atomic mass and number as a final optional parameter.
+
 Davis EOS
 ```````````
 
@@ -1274,6 +1358,9 @@ where ``rho0`` is :math:`\rho_0`, ``e0`` is :math:`e_0`, ``P0`` is
 :math:`Z`, ``alpha`` is :math:`\alpha`, and ``Cv0`` is the specific
 heat capacity at the reference state.
 
+This constructor also optionally accepts `MeanAtomicProperties` for
+the atomic mass and number as a final optional parameter.
+
 Davis Products EOS
 '''''''''''''''''''
 
@@ -1381,6 +1468,9 @@ where ``a`` is :math:`a`, ``b`` is :math:`b`, ``k`` is :math:`k`,
 ``n`` is :math:`n`, ``vc`` is :math:`V_\mathrm{C}`, ``pc`` is
 :math:`P_\mathrm{C}`, ``Cv`` is :math:`C_{V,0}`.
 
+This constructor also optionally accepts `MeanAtomicProperties` for
+the atomic mass and number as a final optional parameter.
+
 Spiner EOS
 ````````````
 
@@ -1443,6 +1533,12 @@ of the material in the file, and ``reproducability_mode`` is a boolean
 which slightly changes how initial guesses for root finds are
 computed. The constructor for ``SpinerEOSDependsRhoSie`` is identical.
 
+.. note::
+
+  Mean atomic mass and number are loaded from input tables. The
+  ``SpinerEOS`` model does **not** support the
+  ``MeanAtomicProperties`` struct.
+
 ``sp5`` files and ``sesame2spiner``
 `````````````````````````````````````
 
@@ -1630,6 +1726,8 @@ values in expansion and compression.
 
 and similar expressions for :math:`b_2^*`.
 
+The SAP polynomial EOS also optionally accepts a
+``MeanAtomicProperties`` struct.
 
 
 Stellar Collapse EOS
@@ -1711,6 +1809,17 @@ where ``filename`` is the file containing the tabulated model,
 original `Stellar Collapse`_ format, and ``filter_bmod`` specifies
 whether or not to apply the above-described median filter.
 
+.. note::
+
+  The ``StellarCollapse`` EOS assumes nuclear statistical equilibrium
+  and as such mean atomic mass and number are state variables. As such
+  class does not accept the ``MeanAtomicProperties`` struct. The
+  ``MeanAtomicMassFromDensityTemperature`` and
+  ``MeanAtomicNumberFromDensityTemperature`` functions return the
+  relevant quantities for some thermodynamic state. The
+  ``MeanAtomicMass()`` and ``MeanAtomicNumber()`` functions raise an
+  error.
+
 ``StellarCollapse`` also provides 
 
 .. cpp:function:: void Save(const std::string &filename)
@@ -1796,6 +1905,14 @@ of the Helmholtz free energy (hence the name Helmholtz EOS). The free
 energy is pre-computed via integrals over the Fermi sphere and
 tabulated in a file provided from `Frank Timmes's website`_.
 
+.. note::
+
+  Since mean atomic mass and number are required inputs, the
+  ``MeanAtomicMassFromDensityTemperature`` and
+  ``MeanAtomicNumberFromDensityAndTemperature`` functions simply
+  return the input values. The ``MeanAtomicMass()`` and
+  ``MeanAtomicNumber`` functions produce an error.
+
 The table is a simple small ascii file. To ensure thermodyanic
 consistency, the table is interpolated using either biquintic or
 bicubic Hermite polynomials, which are sufficiently high order that
@@ -1897,6 +2014,13 @@ and :math:`splitCowan` uses the cold curve plus Cowan-nuclear model
 for ions and the final option ``linear_interp`` uses linear instead of 
 bilinear interpolation. 
 
+.. note::
+
+  Mean atomic mass and number are loaded from input tables. The
+  ``EOSPAC`` model does **not** support the ``MeanAtomicProperties``
+  struct.
+
+
 Note for performance reasons this EOS uses a slightly different vector API.
 See :ref:`EOSPAC Vector Functions <eospac_vector>` for more details.
 

doc/sphinx/src/using-eos.rst

@@ -1037,6 +1037,56 @@ specific internal energy in :math:`erg/g`.
 
 The function
 
+.. code-block:: cpp
+
+   template<typename Indexer_t Real*>
+   void MeanAtomicMassFromDensityTemperature(const Real rho, const Real T,
+                                             Indexer_t &&lambda = nullpter) const;
+
+returns the mean atomic mass (i.e., the number of nucleons) of a
+material given density in :math:`g/cm^3` and temperature in
+Kelvin. The reason this is allowed to vary with density and
+temperature is that some equations of state, such as the Stellar
+Collapse and Helmholtz equations of state encapsulate reactive flows
+where the average nucleus may depend on thermodynamic variables. For
+most materials, however, this is not the case and a convenience
+function that drops the dependence is available:
+
+.. code-block:: cpp
+
+   Real MeanAtomicMass() const;
+
+The function
+
+.. code-block:: cpp
+
+   template<typename Indexer_t Real*>
+   void MeanAtomicNumberFromDensityTemperature(const Real rho, const Real T,
+                                               Indexer_t &&lambda = nullpter) const;
+
+returns the mean atomic number (i.e., the number of protons in the
+nucleus) of a material given density in :math:`g/cm^3` and temperature
+in Kelvin. The reason this is allowed to vary with density and
+temperature is that some equations of state, such as the Stellar
+Collapse and Helmholtz equations of state encapsulate reactive flows
+where the average nucleus may depend on thermodynamic variables. For
+most materials, however, this is not the case and a convenience
+function that drops the dependence is available:
+
+.. code-block:: cpp
+
+   Real MeanAtomicNumber() const;
+
+
+
+.. warning::
+
+  For materials where the mean atomic mass and number **do** vary with
+  density and temperature, the convenience call without this
+  dependence will produce an error.
+
+The function
+
 .. code-block:: cpp
 
    template <typename Indexer_t = Real*>