From 92106526413216e28ca779ce2da5046780839015 Mon Sep 17 00:00:00 2001 From: Jonah Miller Date: Mon, 22 Jul 2024 16:45:15 -0600 Subject: [PATCH 1/6] address JOSS review comments --- doc/sphinx/src/building.rst | 1 + doc/sphinx/src/examples.rst | 59 ++++++++++++++++++++++++++++++ doc/sphinx/src/getting-started.rst | 2 +- example/get_sound_speed_press.cpp | 29 --------------- joss-paper/paper.md | 4 +- 5 files changed, 62 insertions(+), 33 deletions(-) create mode 100644 doc/sphinx/src/examples.rst diff --git a/doc/sphinx/src/building.rst b/doc/sphinx/src/building.rst index 568d920a6d..89305c737e 100644 --- a/doc/sphinx/src/building.rst +++ b/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_PYTHON`` 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. diff --git a/doc/sphinx/src/examples.rst b/doc/sphinx/src/examples.rst new file mode 100644 index 0000000000..cfa94ea50d --- /dev/null +++ b/doc/sphinx/src/examples.rst @@ -0,0 +1,59 @@ +.. _examples: + +Examples +========= + +The ``examples`` 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. diff --git a/doc/sphinx/src/getting-started.rst b/doc/sphinx/src/getting-started.rst index 6ee6c94ed7..6da789e70c 100644 --- a/doc/sphinx/src/getting-started.rst +++ b/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 `. * To learn more about the design philosophy, look :ref:`here `. * To learn about how to build, look at :ref:`our build document `. * To learn more about the equation of state API, look :ref:`here `. diff --git a/example/get_sound_speed_press.cpp b/example/get_sound_speed_press.cpp index 9ecbf4a283..6c25221048 100644 --- a/example/get_sound_speed_press.cpp +++ b/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( - Cv); // base params is the parameters of the underlying eos - base_params["gm1"].emplace(gm1); - shifted_params["shift"].emplace( - shift); // these are the parameters for the modifiers - scaled_params["scale"].emplace(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; } diff --git a/joss-paper/paper.md b/joss-paper/paper.md index bb5ec1884b..5f781a524e 100644 --- a/joss-paper/paper.md +++ b/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 From 60ac994173c3d94681909a243ef80e2fecf342ba Mon Sep 17 00:00:00 2001 From: Jonah Miller Date: Mon, 22 Jul 2024 16:49:58 -0600 Subject: [PATCH 2/6] get examples building again --- CMakeLists.txt | 5 +++-- example/CMakeLists.txt | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 1a7ec465ba..f0daaab319 100644 --- a/CMakeLists.txt +++ b/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) diff --git a/example/CMakeLists.txt b/example/CMakeLists.txt index b56372595b..c367b8b51e 100644 --- a/example/CMakeLists.txt +++ b/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 From 6a61102ee9912a6ded2aa7e7b4919f49c4b81f36 Mon Sep 17 00:00:00 2001 From: Jonah Miller Date: Mon, 22 Jul 2024 16:53:36 -0600 Subject: [PATCH 3/6] customization not being slurped up --- doc/sphinx/src/{customization => customization.rst} | 0 doc/sphinx/src/examples.rst | 6 ++++++ 2 files changed, 6 insertions(+) rename doc/sphinx/src/{customization => customization.rst} (100%) diff --git a/doc/sphinx/src/customization b/doc/sphinx/src/customization.rst similarity index 100% rename from doc/sphinx/src/customization rename to doc/sphinx/src/customization.rst diff --git a/doc/sphinx/src/examples.rst b/doc/sphinx/src/examples.rst index cfa94ea50d..cd45646b09 100644 --- a/doc/sphinx/src/examples.rst +++ b/doc/sphinx/src/examples.rst @@ -57,3 +57,9 @@ 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 `. From cdeff3ac78fc2194f54ad4800fbb1ee77e889094 Mon Sep 17 00:00:00 2001 From: Jonah Miller Date: Mon, 22 Jul 2024 16:57:53 -0600 Subject: [PATCH 4/6] examples must be indexed --- doc/sphinx/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst index 16a8b2448e..ea170e3546 100644 --- a/doc/sphinx/index.rst +++ b/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 From f1a2684097308604282227d530dc83b23e44d76a Mon Sep 17 00:00:00 2001 From: Jonah Miller Date: Tue, 23 Jul 2024 08:50:50 -0600 Subject: [PATCH 5/6] Update doc/sphinx/src/examples.rst Co-authored-by: Parikshit Bajpai <45185043+parikshitbajpai@users.noreply.github.com> --- doc/sphinx/src/examples.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sphinx/src/examples.rst b/doc/sphinx/src/examples.rst index cd45646b09..51360cf832 100644 --- a/doc/sphinx/src/examples.rst +++ b/doc/sphinx/src/examples.rst @@ -3,7 +3,7 @@ Examples ========= -The ``examples`` directory of ``singularity-eos`` contains several +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: From fca9fdc7a692e86027df9c665be58e47cb65e43a Mon Sep 17 00:00:00 2001 From: Jonah Miller Date: Tue, 23 Jul 2024 08:52:08 -0600 Subject: [PATCH 6/6] typo in build matrix --- doc/sphinx/src/building.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sphinx/src/building.rst b/doc/sphinx/src/building.rst index 89305c737e..a25a60087a 100644 --- a/doc/sphinx/src/building.rst +++ b/doc/sphinx/src/building.rst @@ -108,7 +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_PYTHON`` OFF Build examples of ``singularity-eos`` in use. + ``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.