Merge branch 'main' into jhp/robust_pte

CMakeLists.txt

@@ -238,8 +238,9 @@ if(SINGULARITY_SUBMODULE_MODE)
       CACHE BOOL "" FORCE)
 endif()
 
-# side-projects TODO: hdf5 again if(SINGULARITY_BUILD_EXAMPLES)
-# add_subdirectory(example) endif()
+if(SINGULARITY_BUILD_EXAMPLES)
+  add_subdirectory(example)
+endif()
 
 # add subdirs
 if(SINGULARITY_BUILD_PYTHON)

doc/sphinx/index.rst

@@ -15,6 +15,7 @@ Documentation approved for unlimited release. LA-UR-21-31131.
    :caption: Contents:
 
    src/getting-started
+   src/examples
    src/philosophy
    src/building
    src/integration

doc/sphinx/src/building.rst

@@ -108,6 +108,7 @@ The main CMake options to configure building are in the following table:
  ``SINGULARITY_BUILD_CLOSURE``           OFF      Build the mixed cell closure models
  ``SINGULARITY_BUILD_TESTS``             OFF      Build test infrastructure.
  ``SINGULARITY_BUILD_PYTHON``            OFF      Build Python bindings.
+ ``SINGULARITY_BUILD_EXAMPLES``          OFF      Build examples of ``singularity-eos`` in use.
  ``SINGULARITY_INVERT_AT_SETUP``         OFF      For tests, pre-invert eospac tables.
  ``SINGULARITY_BETTER_DEBUG_FLAGS``      ON       Enables nicer GPU debug flags. May interfere with in-tree builds as a submodule.
  ``SINGULARITY_HIDE_MORE_WARNINGS``      OFF      Makes warnings less verbose. May interfere with in-tree builds as a submodule.

doc/sphinx/src/examples.rst

@@ -0,0 +1,65 @@
+.. _examples:
+
+Examples
+=========
+
+The ``example`` directory of ``singularity-eos`` contains several
+examples of using the code. You can build the examples by setting
+``-DSINGULARITY_BUILD_EXAMPLES=ON`` at ``CMake`` configuration
+time. For example:
+
+.. code-block:: bash
+
+   # from singularity-eos repo
+   mkdir -p build && cd build
+   cmake .. -DSINGULARITY_BUILD_EXAMPLES=ON ..
+   make -j
+
+The available examples are listed below.
+
+Get Sound Speed and Pressure
+------------------------------
+
+The ``examples/get_sound_speed_press.cpp`` file implements a call go
+``singularity-eos`` that computes pressure and sound speed from
+density and energy for an ideal gas equation of state. It demonstrates
+how to make this call both through individual calls to pressure and
+bulk modulus, as well as by calling the in-one ``FillEos`` API. The
+former looks something like this:
+
+.. code-block:: cpp
+
+  // Loop through the cells and use the two function calls
+  for (int i = 0; i < Ncells; ++i) {
+    double sie = robust::ratio(uu[i], rho[i]); // convert to specific internal energy
+    P[i] = eos.PressureFromDensityInternalEnergy(rho[i], sie, lambda.data());
+    double bmod = eos.BulkModulusFromDensityInternalEnergy(rho[i], sie, lambda.data());
+    cs[i] = std::sqrt(robust::ratio(bmod, rho[i]));
+  }
+
+The exact same code is implemented via the python bindings in ``get_sound_speed_press.py``.
+
+Get SESAME State
+-------------------
+
+If you build with both ``SpinerEOS`` and ``EOSPAC`` backends for
+tabulated data, you can compare tabulated interpolations by calling
+the ``get_sesame_state`` executable built via the
+``get_sesame_state.cpp`` example file. You can call it as
+
+.. code-block:: bash
+
+   get_sesame_state matid sp5_file_name rho T sie
+
+for some ``SESAME`` material index ``matid`` and some tabulated spiner
+file ``sp5_file_name``, and a density, temperature and specific
+internal energy to evaluate at.
+
+The example demonstrates how to call the pressure, energy, and
+thermodynamic derivatives of a table at that point in phase space.
+
+Plugins
+----------
+
+The example directory also contains an example plugin that can be
+included via the plugin infrastructure, as described in :ref:`our customization section <customization>`.

doc/sphinx/src/getting-started.rst

@@ -78,7 +78,7 @@ And that's it!
 Going Deeper
 --------------
 
-* You can find code examples in the ``example`` source directory.
+* You can find code examples in the ``example`` source directory. We describe them :ref:`here <examples>`.
 * To learn more about the design philosophy, look :ref:`here <philosophy>`.
 * To learn about how to build, look at :ref:`our build document <building>`.
 * To learn more about the equation of state API, look :ref:`here <using-eos>`.

example/CMakeLists.txt

@@ -17,7 +17,7 @@ add_executable(get_sound_speed_press
 target_link_libraries(get_sound_speed_press PRIVATE
   singularity-eos::singularity-eos)
 
-if(SINGULARITY_USE_EOSPAC)
+if(SINGULARITY_USE_EOSPAC AND SINGULARITY_USE_SPINER_WITH_HDF5)
   add_executable(get_sesame_state
     get_sesame_state.cpp)
   target_link_libraries(get_sesame_state PRIVATE

example/get_sound_speed_press.cpp

@@ -91,37 +91,9 @@ int main() {
   constexpr double gm1 = 0.6;
   constexpr double Cv = 2;
 
-  // We initialize the eos two ways to show how it can be done
   // First initialize the EOS the "easy" way:
   EOS eos1 = IdealGas(gm1, Cv);
 
-  // The EOS Builder automates building an eos with modifiers, such as
-  // shift and scale by worrying about the combinatorics/switch
-  // statements, etc, for you. We'll initialize a shifted/scaled EOS
-  // with shift 0 and scale 1 to show you how it's done
-  constexpr double shift = 0;
-  constexpr double scale = 1;
-
-  // Eos builder requires a type specification,
-  // and then for each modifier, it requires a set of parameters,
-  // which are implemented as a variatic dictionary.
-  //
-  // This is equivalent to
-  // EOS eos2 = Shifted(Scaled(IdealGas(gm1, Cv), scale), shift);
-  EOSBuilder::EOSType type = EOSBuilder::EOSType::IdealGas;
-  EOSBuilder::modifiers_t modifiers;                               // this is a dictionary
-  EOSBuilder::params_t base_params, shifted_params, scaled_params; // so are these
-  base_params["Cv"].emplace<Real>(
-      Cv); // base params is the parameters of the underlying eos
-  base_params["gm1"].emplace<Real>(gm1);
-  shifted_params["shift"].emplace<Real>(
-      shift); // these are the parameters for the modifiers
-  scaled_params["scale"].emplace<Real>(scale); // you use strings for the variable names
-  // for each modifier put the relevant params in the modifiers object
-  modifiers[EOSBuilder::EOSModifier::Shifted] = shifted_params;
-  modifiers[EOSBuilder::EOSModifier::Scaled] = scaled_params;
-  EOS eos2 = EOSBuilder::buildEOS(type, base_params, modifiers); // build the builder
-
   // If you're on device, you need to call
   // eos1.GetOnDevice();
   // to call the EOS on device
@@ -155,7 +127,6 @@ int main() {
   // This usually only does anything if you're on device, but for GPU-data it
   // will call the appropriate destructor.
   eos1.Finalize();
-  eos2.Finalize();
 
   return 0;
 }

joss-paper/paper.md

@@ -96,7 +96,7 @@ specific internal energy. All capabilities are performance portable,
 meaning they compile and run on both CPU and GPU for a wide variety of
 architectures.
 
-# Statement of need
+# Statement of need and State of the Field
 
 When expressed mathematically for continuous materials, the laws of
 conservation of mass, energy, and momentum form the Navier-Stokes
@@ -141,8 +141,6 @@ material properties of the cell are as a whole. This is called a
 *pressure-temperature equilibrium* (PTE), where all materials
 in the cell are assumed to be at the same pressure and temperature.
 
-# State of the Field
-
 Typically fluid dynamics codes each develop an EOS package
 individually to meet a given problem's needs. Databases of tabulated
 equations of state, such as the Sesame [@sesame] and Stellar