hjhp and pdmullen comments

doc/sphinx/src/models.rst

@@ -164,6 +164,8 @@ functional forms for :math:`\Gamma` and the reference curves, the task of
 calculating a **thermodynamically consistent** temperature becomes more
 complicated.
 
+.. _3T-Model:
+
 The 3T Model
 ``````````````
 
@@ -182,11 +184,11 @@ as
 
 .. math::
 
-  n = \left\langle Z \right\rangle \frac{\rho}{\left\langle A\right\rangle m_p}
+  n = \left\langle Z \right\rangle \frac{\rho}{\overline{A} m_p}
 
 where here :math:`\left\langle Z\right\rangle` is the average number
 of electrons contributed per atom, also called mean ionization state,
-:math:`\rho` is the ion mass density, :math:`\bar{A}` is the mean
+:math:`\rho` is the ion mass density, :math:`\overline{A}` is the mean
 atomic mass (in grams per mole) of a given material and :math:`m_p` is
 the proton mass.
 
@@ -196,7 +198,7 @@ the proton mass.
   ionization state and the average atomic number, as the symbol for
   both is :math:`Z`. To disambiguate in ``singularity-eos``, we use
   overbars to reference mean atomic properties such as mean atomic
-  mass :math:`\bar{A}` and mean atomic number :math:`\bar{Z}` while we
+  mass :math:`\overline{A}` and mean atomic number :math:`\overline{Z}` while we
   use :math:`\left\langle Z\right\rangle` to denote mean ionizaiton
   state.
 
@@ -549,13 +551,13 @@ The pressure is given by the number density of electrons times
 
 .. math::
 
-  P = \frac{\rho}{m_p \bar{A}}\left\langle Z \right\rangle k_b T
+  P = \frac{\rho}{m_p \overline{A}}\left\langle Z \right\rangle k_b T
 
-The specific heat is then
+for proton mass :math:`m_p`. The specific heat is then
 
 .. math::
 
-  C_V = \frac{\left\langle Z \right\rangle k_b}{\Gamma m_p \bar{A}}
+  C_V = \frac{\left\langle Z \right\rangle k_b}{\Gamma m_p \overline{A}}
 
 so that
 
@@ -564,7 +566,7 @@ so that
   P = \Gamma \rho C_V T
 
 as expected. (Note that the total mass per nucleus isn't exactly
-:math:`\left\langle A\right\rangle m_p`, as protons and neutrons are
+:math:`\overline{A} m_p`, as protons and neutrons are
 not exactly the same mass. However, it's close enough for all intents
 and purposes.)
 
@@ -579,6 +581,22 @@ Optionally reference values may be provided for the entropy
 calculation, which is computed in the same way as the standard ideal
 gas.
 
+.. note::
+
+  Since the mean ionization state is built into the heat capacity, the
+  entropy is zero until the material is ionized. This is physically
+  consistent, if there are no electrons, the total electron entropy
+  should be zero.
+
+.. note::
+
+  The electron entropy reference should probably be chosen to be
+  consistent with the chosen ionization model, such as a reference
+  temperature where ionization begins. This is about :math:`10^4`
+  Kelvin but will depend on the model and the material. This means
+  that the entropy reference temperature may be very different between
+  ions and electrons.
+
 Calls to compute state variables require the mean ionization state,
 which must be passed in the ``lambda`` parameter, e.g.,
 

doc/sphinx/src/modifiers.rst

@@ -192,7 +192,7 @@ and temperature.
 Z-Split EOS
 -------------
 
-For 3T physics (as described in the models section) it is often
+For 3T physics (as described in the :ref:`models section<3T-Model>`) it is often
 desirable to have a separate equation of state for electrons and a
 separate equation of state for ions. The Z-split model takes a total
 equation of state and splits it into electron and ion components. The
@@ -206,12 +206,12 @@ molecular bonds have been broken, the total pressure is given by
 
 .. math::
 
-  P_t = (\left\langle Z\right\rangle + 1) \frac{\rho}{m_p \bar{A}} k_b T
+  P_t = (\left\langle Z\right\rangle + 1) \frac{\rho}{m_p \overline{A}} k_b T
 
 where :math:`\left\langle Z\right\rangle` is the mean ionization
 state, :math:`rho` is the ion mass density (the electron ion mass
 density is negligible), :math:`m_p` is the proton mass,
-:math:`\bar{A}` is the mean atomic mass, :math:`k_b` is Boltzmann's
+:math:`\overline{A}` is the mean atomic mass, :math:`k_b` is Boltzmann's
 constant, and :math:`T` is temperature. The contribution from
 electrons is proportional to :math:`\left\langle Z\right\rangle`.
 
@@ -268,6 +268,14 @@ and similarly for electrons,
 
   auto electron_eos = ZSPlitE<IdealGas>(IdealGas(gm1, Cv);
 
+.. note::
+
+  The Z-split modifier uses the mean atomic properties methods
+  provided by the underlying equation of state to pick, e.g., the
+  total number of nuclei per unit mass. This means you must specify
+  ``MeanAtomicProperties`` when constructing the underlying equation
+  of state. If you don't specify anything, hydrogen is assumed.
+
 The Z-split modifier takes the ionization state as an additional
 parameter via the lambda. For example:
 
@@ -276,6 +284,17 @@ parameter via the lambda. For example:
   Real lambda[1] = {Z};
   Real Pe = electron_eos.PressureFromDensityTemperature(rho, temperature, lambda);
 
+.. warning::
+
+  Several thermodynamic properties are approximated in the z-split
+  model due to incomplete information. Notably, the specific heat and
+  bulk modulus should depend on the electron chemical potential and
+  the ionization model: how much does the ionization state change with
+  respect to temperature? However, the ionization model is typically
+  decoupled from the equation of state and treated separately. As
+  such, this dependence is neglected here. This treatment may be
+  extended in the future.
+
 .. note::
 
   For now, the Z-split EOS is not in the default variant provided by

singularity-eos/eos/modifiers/zsplit_eos.hpp

@@ -109,6 +109,11 @@ class ZSplit : public EosBase<ZSplit<ztype, T>> {
     return scale * t_.EntropyFromDensityInternalEnergy(rho, iscale * sie, lambda);
   }
 
+  // TODO(JMM): Formally, this should be d/dT (scale * sie_base) but
+  // we don't have access to d/dT scale, as it depends on d/dT <Z>
+  // which depends on the ionization model. In principle, we could
+  // request a derivative in the lambda or do something more
+  // sophisticated. We should keep that in mind going forward.
   template <typename Indexer_t = Real *>
   PORTABLE_INLINE_FUNCTION Real SpecificHeatFromDensityTemperature(
       const Real rho, const Real temperature,
@@ -125,6 +130,12 @@ class ZSplit : public EosBase<ZSplit<ztype, T>> {
     return scale * t_.SpecificHeatFromDensityInternalEnergy(rho, iscale * sie, lambda);
   }
 
+  // TODO(JMM): Formally this may also depend on the derivative of the
+  // ionization state with respect to volume along an
+  // isentrope. However, this cannot be included without more
+  // information from the ionization model. As with Cv we could in
+  // principle request a derivative in the lambda or do something more
+  // sophisticated. We should keep that in mind going forward.
   template <typename Indexer_t = Real *>
   PORTABLE_INLINE_FUNCTION Real BulkModulusFromDensityTemperature(
       const Real rho, const Real temperature,