Merge pull request #444 from lanl/jmm/zsplit

Analytic electron EOS and zsplit modifier

.github/workflows/docs.yml

@@ -40,7 +40,7 @@ jobs:
                   -DSINGULARITY_USE_SPINER_WITH_HDF5=OFF \
                   -DSINGULARITY_FORCE_SUBMODULE_MODE=ON \
                   -B build .
-            cmake --build build
+            cmake --build build --parallel 4
             sudo cmake --install build
         - name: build docs
           run: |

.github/workflows/formatting.yml

@@ -9,7 +9,7 @@ on:
 jobs:
     formatting:
       name: Check Formatting
-      runs-on: ubuntu-latest
+      runs-on: ubuntu-22.04
 
       steps:      
         - name: Checkout code

.github/workflows/tests.yml

@@ -21,13 +21,15 @@ jobs:
         - name: install dependencies
           run: |
             sudo apt-get update -y -qq
-            sudo apt-get install -y --allow-downgrades --allow-remove-essential --allow-change-held-packages -qq build-essential gfortran libhdf5-serial-dev
+            sudo apt-get install -y --allow-downgrades --allow-remove-essential --allow-change-held-packages -qq build-essential gfortran libhdf5-serial-dev binutils-gold
             pip install numpy
             pip install h5py
         - name: build and run tests
           run: |
             mkdir -p bin
             cd bin
+            ulimit -m unlimited
+            ulimit -v unlimited
             mkdir -p ${HOME}/install
             cmake -DCMAKE_INSTALL_PREFIX=${HOME}/install \
                   -DSINGULARITY_USE_SPINER=ON \
@@ -38,11 +40,14 @@ jobs:
                   -DSINGULARITY_USE_HELMHOLTZ=ON \
                   -DSINGULARITY_TEST_HELMHOLTZ=ON \
                   -DSINGULARITY_FORCE_SUBMODULE_MODE=ON \
+                  -DSINGULARITY_USE_V_AND_V_EOS=OFF \
                   -DSINGULARITY_PLUGINS=$(pwd)/../example/plugin \
+                  -DCMAKE_LINKER=ld.gold \
+                  -DCMAKE_BUILD_TYPE=Release \
                   ..
                   #-DSINGULARITY_TEST_PYTHON=ON \
                   #-DSINGULARITY_TEST_STELLAR_COLLAPSE=ON \
                   #..
-            make
+            make -j4
             make install
             ctest --output-on-failure

.github/workflows/tests_minimal.yml

@@ -34,6 +34,6 @@ jobs:
                   -DSINGULARITY_FORCE_SUBMODULE_MODE=ON \
                   -DSINGULARITY_USE_KOKKOS=OFF \
                   ..
-            make
+            make -j4
             make install
             make test

.github/workflows/tests_minimal_kokkos.yml

@@ -34,6 +34,6 @@ jobs:
                   -DSINGULARITY_FORCE_SUBMODULE_MODE=ON \
                   -DSINGULARITY_USE_KOKKOS=ON \
                   ..
-            make
+            make -j4
             make install
             make test

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Current develop
 
 ### Added (new features/APIs/variables/...)
+- [[PR444]](https://github.com/lanl/singularity-eos/pull/444) Add Z split modifier and electron ideal gas EOS
 
 ### Fixed (Repair bugs, etc)
 - [[PR439]](https://github.com/lanl/singularity-eos/pull/439) Add mean atomic mass and number to EOS API

CMakeLists.txt

@@ -85,6 +85,13 @@ cmake_dependent_option(
   SINGULARITY_USE_HELMHOLTZ "Include Helmholtz equation of state" OFF
   "SINGULARITY_USE_SPINER;SINGULARITY_USE_SPINER_WITH_HDF5" OFF)
 
+# Enables polynomial, carnahan starling, and NobleAbel in variant.
+# Off by default, as they are not in the default python bindings or used
+# by default in downstream codes.
+option(SINGULARITY_USE_V_AND_V_EOS
+  "Add analytic EOSs for V&V to the variant"
+  OFF)
+
 # testing options
 option(SINGULARITY_BUILD_TESTS "Compile tests" OFF)
 
@@ -332,6 +339,9 @@ endif()
 if(SINGULARITY_USE_HELMHOLTZ)
   target_compile_definitions(singularity-eos_Interface INTERFACE SINGULARITY_USE_HELMHOLTZ)
 endif()
+if (SINGULARITY_USE_V_AND_V_EOS)
+  target_compile_definitions(singularity-eos_Interface INTERFACE SINGULARITY_USE_V_AND_V_EOS)
+endif()
 if(SINGULARITY_USE_SPINER_WITH_HDF5)
   target_compile_definitions(singularity-eos_Interface INTERFACE SINGULARITY_USE_SPINER_WITH_HDF5)
 endif()
@@ -440,8 +450,8 @@ if(SINGULARITY_BUILD_TESTS)
     FetchContent_Declare(
       Catch2
       GIT_REPOSITORY https://github.com/catchorg/Catch2.git
-      # or later is fine too
-      GIT_TAG v3.0.1)
+      # jmm: updated Dec 17, 2024 to avoid build errors on modern gcc
+      GIT_TAG v3.7.1)
     FetchContent_MakeAvailable(Catch2)
     list(APPEND CMAKE_MODULE_PATH ${Catch2_SOURCE_DIR}/contrib)
   endif()
@@ -560,6 +570,13 @@ target_compile_options(
          -use_fast_math
          > # release
          > # cuda
+
+         # Suppresses annoying ABI notes. See:
+         # https://stackoverflow.com/questions/52020305/what-exactly-does-gccs-wpsabi-option-do-what-are-the-implications-of-supressi
+         $<$<AND:$<CXX_COMPILER_ID:GNU>,$<COMPILE_LANGUAGE:CXX>>:-Wno-psabi>
+         # `-Wclass-memaccess now default with -Wall but we explicitly
+         # manage this ourselves in our serialization routines.
+         $<$<AND:$<CXX_COMPILER_ID:GNU>,$<COMPILE_LANGUAGE:CXX>>:-Wno-class-memaccess>
 )
 if (SINGULARITY_STRICT_WARNINGS)
   target_compile_options(singularity-eos_Interface INTERFACE

doc/sphinx/src/building.rst

@@ -119,6 +119,7 @@ The main CMake options to configure building are in the following table:
  ``SINGULARITY_NQT_ORDER_1``             OFF      For fast logs, use the less accurate but faster 1st-order version.
  ``SINGULARITY_NQT_PORTABLE``            OFF      For fast logs, use the slower but endianness-independent implementation.
  ``SINGULARITY_STRICT_WARNINGS``         OFF      For testing. Adds -Wall and -Werror to builds.
+ ``SINGULARITY_USE_V_AND_V_EOS``         OFF      Enables several additional EOS models and adds them to the default variant
 ====================================== ======= ===========================================
 
 More options are available to modify only if certain other options or
@@ -729,6 +730,9 @@ supports a number of relevant variants:
 +-----------------------------+-----------------+-----------------------------+
 | tests [off]                 | on, off         | Build tests                 |
 +-----------------------------+-----------------+-----------------------------+
+| vandv [on]                  | on, off         | Add some V&V EOS's to the   |
+|                             |                 | Singularity::Variant        |
++-----------------------------+-----------------+-----------------------------+
 
 Developing ``singularity-eos`` using Spack
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

doc/sphinx/src/models.rst

@@ -164,6 +164,64 @@ 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
+``````````````
+
+In high-energy density physics, the so-called three-temperature (or
+3T) model is often employed. In this model, a material is fully or
+partially ionized. Due to the separation in masses between electrons
+and atomic nuclei, electrons come into thermal equilibrium and ions
+come into thermal equilibrium, but the two populations are not in
+thermal equilibrium with each other. This introduces separate electron
+and ion temperatures. The third temperature is potentially a radiation
+temperature.
+
+By convention in 3T physics, density :math:`\rho` is always the mass
+density of the ions. The electron number density may then be computed
+as
+
+.. math::
+
+  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:`\overline{A}` is the mean
+atomic mass (in grams per mole) of a given material and :math:`m_p` is
+the proton mass.
+
+.. note::
+
+  Note that there is notational ambiguity between the average
+  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:`\overline{A}` and mean atomic number :math:`\overline{Z}` while we
+  use :math:`\left\langle Z\right\rangle` to denote mean ionizaiton
+  state.
+
+Also, since the electron mass is negligible compared to the ion mass,
+the specific internal energy carried by electrons
+:math:`\varepsilon_e` is specific with respect to the *ion* mass. In
+particular:
+
+.. math::
+
+  u_e = \varepsilon_e \rho
+
+where here :math:`u_e` is the internal energy per unit volume carried
+by electrons and, as discussed above, :math:`\rho` is ion mass
+density.
+
+``singularity-eos`` assumes that, when 3T physics is active, electrons
+and ions are each described by a separate equation of state
+object. Several models are specifically designed to represent, e.g.,
+the electron equation of state or ion equation of state. The tabulated
+models may also support loading tables specifically for electron or
+ion equations of state.
+
 Available EOS Information and Nomenclature
 ------------------------------------------
 
@@ -469,6 +527,90 @@ the atomic mass and number as a final optional parameter, e.g.,
    IdealGas(Real gm1, Real Cv, MeanAtomicProperties(Abar, Zbar));
    IdealGas(Real gm1, Real Cv, Real EntropyT0, Real EntropyRho0, MeanAtomicProperties(Abar, Zbar));
 
+Ideal Electron Gas
+```````````````````
+
+The ideal electron gas equation of state is designed for use with 3T
+physics. It is an ideal Boltzmann gas of electrons. As such, each
+electron is assumed to have three translational degrees of freedom
+:math:`f`, such that
+
+.. math::
+
+  \Gamma = \frac{2}{f} = \frac{2}{3}
+
+and
+
+.. math::
+
+  \gamma = \Gamma + 1 = \frac{5}{3}.
+
+The pressure is given by the number density of electrons times
+:math:`k_b T` for Boltzmann constant :math:`k_b` and temperature
+:math:`T`:
+
+.. math::
+
+  P = \frac{\rho}{m_p \overline{A}}\left\langle Z \right\rangle k_b T
+
+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 \overline{A}}
+
+so that
+
+.. math::
+
+  P = \Gamma \rho C_V T
+
+as expected. (Note that the total mass per nucleus isn't exactly
+: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.)
+
+The constructor takes only the ``MeanAtomicProperties`` struct, which
+is a required input:
+
+.. code-block:: cpp
+
+  IdealElectrons(const MeanAtomicProperties &AZbar);
+
+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.,
+
+.. code-block:: cpp
+
+  Real lambda[1] = {Z};
+  Real P = eos.PressureFromDensityTemperature(rho, T, lambda);
+
+.. note::
+
+  For now, the ideal electron gas is not in the default variant
+  provided by singularity-eos. If you would like to use it, you must
+  implement your own custom variant.
+
 Stiffened Gas
 `````````````