EOSBuilder rewrite

CHANGELOG.md

@@ -40,6 +40,7 @@
 - [[PR177]](https://github.com/lanl/singularity-eos/pull/177) added EOSPAC vector functions
 
 ### Changed (changing behavior/API/variables/...)
+- [[PR311]](https://github.com/lanl/singularity-eos/pull/311) Refactor EOSBuilder for flexibility and extensibility
 - [[PR310]](https://github.com/lanl/singularity-eos/pull/310) Speed up and clean up tests
 - [[PR295]](https://github.com/lanl/singularity-eos/pull/295) Add fast logs to singularity-eos
 - [[PR246]](https://github.com/lanl/singularity-eos/pull/246) Update CMake with upstream changes

CMakeLists.txt

@@ -390,6 +390,8 @@ if(SINGULARITY_USE_FORTRAN)
   target_include_directories(
     singularity-eos INTERFACE $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>
                               $<INSTALL_INTERFACE:include/singularity-eos/eos>)
+else() # Needed because cmake improperly infers linker for header-only
+  set_target_properties(singularity-eos PROPERTIES LINKER_LANGUAGE CXX)
 endif() # SINGULARITY_USE_FORTRAN
 
 target_include_directories(

doc/sphinx/src/using-eos.rst

@@ -473,35 +473,43 @@ EOS Builder
 The inclusion of modifiers can make building a desired equation of
 state somewhat cumbersome. To handle this, we have implemented the
 ``EOSBuilder`` machinery. ``EOSBuilder`` is a set of functions that
-provides a declarative interface for building an equation of state
-object.
+provides a way to iteratively build up an equation of state object.
 
 The EOS Builder functions and types are defined in the
 ``singularity::EOSBuilder`` namespace. The key function is
 
-.. cpp:function:: EOS EOSBuilder::buildEOS(EOSBuilder::EOSType t, EOSBuilder::params_t base_params, EOSBuilder::modifiers_t modifiers)
+.. code-block:: cpp
 
-* ``EOSBuilder::EOSType`` is an enum class with names that match the various EOS classes defined in :ref:`the models section <models>`; for example, ``EOSBuilder::EOSType::IdealGas``.
-* ``EOSBuilder::params_t`` is a dictionary object with some type erasure, which maps strings to the types ``std::string``, ``int``, or ``Real``. It is used to map parameter names to their values for class constructors.
-* ``EOSBuilder::modifiers_t`` is a dictionary from the ``EOSModifier`` enum class, which works identically to the ``EOSType`` enum but for modifiers, to ``params_t`` objects, specifying the constructor values for each modifier.
+  template <template <class...> typename Mod, typename... Ts, typename... Args>
+  singularity::Variant<Ts...> Modify(const Variant<Ts...> &eos, Args &&...args);
 
-Putting it all together, initializing an ``IdealGas`` with
-``EOSBuilder`` looks something like this:
+where ``Mod`` is an EOS modifier, ``Variant`` is either your
+user-defined custom EOS variant type, or the pre-defined ``EOS`` type,
+the ``eos`` object is an EOS you'd like to modify (stored as a
+variant), and ``args`` are the additional arguments to the constructor
+of ``Mod`` beyond the object to modify. For esample, initializing an
+``IdealGas`` equation of state that is optionally shifted and scaled
+might look something like this:
 
 .. code-block:: cpp
 
   using namespace singularity;
-  EOSBuilder::EOSType type = EOSBuilder::EOSType::IdealGas;
-  EOSBuilder::modifiers_t modifiers;
-  EOSBuilder::params_t base_params, shifted_params, scaled_params;
-  base_params["Cv"].emplace<Real>(Cv);
-  base_params["gm1"].emplace<Real>(gm1);
-  shifted_params["shift"].emplace<Real>(shift);
-  scaled_params["scale"].emplace<Real>(scale);
-  modifiers[EOSBuilder::EOSModifier::Shifted] = shifted_params;
-  modifiers[EOSBuilder::EOSModifier::Scaled] = scaled_params;
-  EOS eos = EOSBuilder::buildEOS(type, base_params, modifiers);
+  EOS eos = IdealGas(gm1, cv);
+  if (do_shift) {
+    eos = EOSBuilder::Modify<ShiftedEOS>(eos, shift);
+  }
+  if (do_scale) {
+    eos = EOSBuilder::Modify<ScaledEOS>(eos, scale);
+  }
+
+The advantage of this approach is the EOS can be built up
+iteratively.
+
+.. warning::
 
+  Note that order of modifiers matters, and if you want follow this
+  approach, you must ensure that all combinations of types that you may
+  want to iteratively build up are present in the variant.
 
 .. _eos methods reference section:
 

singularity-eos/CMakeLists.txt

@@ -45,9 +45,7 @@ set(EOS_HEADERS
     eos/eos_stiff.hpp
 )
 
-set(EOS_SRCS
-    eos/eos_builder.cpp
-)
+set(EOS_SRCS eos/eos.cpp)
 
 if (SINGULARITY_BUILD_CLOSURE)
   list(APPEND EOS_HEADERS

singularity-eos/base/variadic_utils.hpp

@@ -18,7 +18,35 @@
 #include <type_traits>
 
 namespace singularity {
-namespace detail {
+namespace variadic_utils {
+
+// Some generic variatic utilities
+// ======================================================================
+
+// Backport of C++17 bool_constant.
+// With C++17, can be replaced with
+// using std::bool_constant
+template <bool B>
+using bool_constant = std::integral_constant<bool, B>;
+
+// Implementation of std::conjunction/std::disjunction without C++17
+// With C++17, can be replaced with
+// using std::disjunction
+template <bool...>
+struct bool_pack {};
+template <bool... Bs>
+using conjunction = std::is_same<bool_pack<true, Bs...>, bool_pack<Bs..., true>>;
+template <bool... Bs>
+struct disjunction : bool_constant<!conjunction<!Bs...>::value> {};
+
+// Checks if T is contained in the pack Ts
+template <typename T, typename... Ts>
+using contains = disjunction<std::is_same<T, Ts>::value...>;
+
+template <typename T, typename... Ts>
+constexpr bool contains_v() {
+  return contains<T, Ts...>::value;
+}
 
 // variadic list
 template <typename... Ts>
@@ -156,7 +184,7 @@ constexpr auto pack_size(type_list<Ts...>) {
   return sizeof...(Ts);
 }
 
-} // namespace detail
+} // namespace variadic_utils
 } // namespace singularity
 
 #endif // SINGULARITY_EOS_BASE_VARIADIC_UTILS_HPP_

singularity-eos/eos/eos.cpp

@@ -0,0 +1,45 @@
+//------------------------------------------------------------------------------
+// © 2021-2023. Triad National Security, LLC. All rights reserved.  This
+// program was produced under U.S. Government contract 89233218CNA000001
+// for Los Alamos National Laboratory (LANL), which is operated by Triad
+// National Security, LLC for the U.S.  Department of Energy/National
+// Nuclear Security Administration. All rights in the program are
+// reserved by Triad National Security, LLC, and the U.S. Department of
+// Energy/National Nuclear Security Administration. The Government is
+// granted for itself and others acting on its behalf a nonexclusive,
+// paid-up, irrevocable worldwide license in this material to reproduce,
+// prepare derivative works, distribute copies to the public, perform
+// publicly and display publicly, and to permit others to do so.
+//------------------------------------------------------------------------------
+
+// JMM: This is a dummy file to provide a source file for cmake to
+// compile when built without fortran.
+//
+// The main reason to do this is that when we build without fortran
+// bindings, the library is completely header only. However WITH
+// fortran bindings, it is not.
+//
+// cmake supports a build mode for header only libraries by marking
+// those libraries INTERFACE. Without this flag, a few things will go
+// wrong:
+// 1. CMake will be unable to infer a proper linker
+//    so one must be specified by hand.
+// 2. no dynamic library file (e.g., "*.a") will be generated,
+//    but dependencies that link against it, such as another library,
+//    or in our case, tests, will look for it. This will lead to
+//    a failure of the downstream library at link time.
+//
+// On the other hand, a library with implementation files
+// CANNOT be marked INTERFACE, as otherwise source files will
+// not be compiled.
+//
+// Unfortunately, switching the INTERFACE tag on and off in cmake
+// is very cumbersome, as if a library is marked INTERFACE
+// all its dependencies must ALSO be slurped in with an INTERFACE
+// flag. This introduces significant branching in the cmake code
+// and a lot of builer plate. For now, then, I simply include this
+// empty source file.
+//
+// In the future, we could include centralized code here that we
+// always want compiled, such as template instantiations or
+// convenience functions.

singularity-eos/eos/eos.hpp

@@ -57,13 +57,13 @@ namespace singularity {
 
 // recreate variadic list
 template <typename... Ts>
-using tl = singularity::detail::type_list<Ts...>;
+using tl = singularity::variadic_utils::type_list<Ts...>;
 
 template <template <typename> class... Ts>
-using al = singularity::detail::adapt_list<Ts...>;
+using al = singularity::variadic_utils::adapt_list<Ts...>;
 
 // transform variadic list: applies modifiers to eos's
-using singularity::detail::transform_variadic_list;
+using singularity::variadic_utils::transform_variadic_list;
 
 // all eos's
 static constexpr const auto full_eos_list =
@@ -117,31 +117,31 @@ static constexpr const auto scaled_1 =
     transform_variadic_list(full_eos_list, al<ScaledEOS>{});
 // relativistic and unit system modifiers
 static constexpr const auto unit_or_rel =
-    singularity::detail::concat(unit_system, relativistic);
+    singularity::variadic_utils::concat(unit_system, relativistic);
 // variadic list of eos with shifted, relativistic or unit system modifiers
 static constexpr const auto shifted_of_unit_or_rel =
     transform_variadic_list(unit_or_rel, al<ShiftedEOS>{});
 // combined list of all shifted EOS
 static constexpr const auto shifted =
-    singularity::detail::concat(shifted_1, shifted_of_unit_or_rel);
+    singularity::variadic_utils::concat(shifted_1, shifted_of_unit_or_rel);
 // variadic list of eos with scaled, relativistic or unit system modifiers
 static constexpr const auto scaled_of_unit_or_rel =
     transform_variadic_list(unit_or_rel, al<ScaledEOS>{});
 // variadic list of Scaled<Shifted<T>>'s
 static constexpr const auto scaled_of_shifted =
     transform_variadic_list(shifted, al<ScaledEOS>{});
 // combined list of all scaled EOS
-static constexpr const auto scaled =
-    singularity::detail::concat(scaled_1, scaled_of_unit_or_rel, scaled_of_shifted);
+static constexpr const auto scaled = singularity::variadic_utils::concat(
+    scaled_1, scaled_of_unit_or_rel, scaled_of_shifted);
 // create combined list
 static constexpr const auto combined_list_1 =
-    singularity::detail::concat(full_eos_list, shifted, scaled, unit_or_rel);
+    singularity::variadic_utils::concat(full_eos_list, shifted, scaled, unit_or_rel);
 // make a ramped eos of everything
 static constexpr const auto ramped_all =
     transform_variadic_list(combined_list_1, al<BilinearRampEOS>{});
 // final combined list
 static constexpr const auto combined_list =
-    singularity::detail::concat(combined_list_1, ramped_all);
+    singularity::variadic_utils::concat(combined_list_1, ramped_all);
 // a function that returns a Variant from a typelist
 template <typename... Ts>
 struct tl_to_Variant_struct {