diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a76569cbf..2b16f4c19f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -59,6 +59,7 @@ Date: 11/28/2023 - [[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 diff --git a/doc/sphinx/src/modifiers.rst b/doc/sphinx/src/modifiers.rst index 6fc6b1af15..552b16940b 100644 --- a/doc/sphinx/src/modifiers.rst +++ b/doc/sphinx/src/modifiers.rst @@ -195,6 +195,19 @@ Modifiers can be composed. For example: using namespace singularity; auto my_eos = ShiftedEOS>(ScaledEOS(IdealGas(gm1, Cv), scale), shift); +You can build modifiers up iteratively by, for example: + +.. code-block:: cpp + + using namespace singularity; + EOS eos = IdealGas(gm1, cv); + if (do_shift) { + eos = eos.template Modify(shift); + } + if (do_scale) { + eos = eos.template Modify(scale); + } + Undoing Modifiers ------------------ diff --git a/doc/sphinx/src/using-eos.rst b/doc/sphinx/src/using-eos.rst index 402f340e96..7f1d975863 100644 --- a/doc/sphinx/src/using-eos.rst +++ b/doc/sphinx/src/using-eos.rst @@ -388,6 +388,34 @@ modifiers. However, note that modifiers do not commute, and only one order is supported. The ordering, inside-out, is ``UnitSystem`` or ``RelativisticEOS``, then ``ScaledEOS``, then ``ShiftedEOS``. +A modified equation of state can be built up iteratively. To check if +the equation of state currently stored in the variant can modified, +you may call + +.. cpp:function:: bool ModifiedInVariant() const; + +where ``Mod`` is the type of the modifier you want to apply, for +example ``ShiftedEOS``. If this function returns true, then you can +apply a modifier with the function + +.. cpp:function:: Variant Modify(Args &&..args) const; + +where again ``Mod`` is the modifier you wish to apply, and ``args`` +are the arguments to the constructor for that modifier, e.g., the +shift. For example, one might build up a shifted or scaled eos with a +code block like this: + +.. code-block:: cpp + + using namespace singularity; + EOS eos = IdealGas(gm1, cv); + if (do_shift) { + eos = eos.template Modify(shift); + } + if (do_scale) { + eos = eos.template Modify(scale); + } + Relevant to the broad ``singularity-eos`` API, EOS models provide introspection. To check if an EOS is modified, call @@ -470,38 +498,34 @@ temperature or density and specific internal energy. 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. +The iterative construction of modifiers described above and in the +:ref:`modifiers` section is object oriented. For +convenience, we also provide a procedural, dispatch-based approach in +the ``EOSBuilder`` namespace and header. The key function is -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 `; 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