tboudreaux/MeanField_SERiF
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(eos): added doxygen comments throughout

Browse Source
This commit is contained in:
Emily Boudreaux
2026-10-05 14:23:58 -04:00
parent 3c4d1614d4
commit 1348f32312
12 changed files with 689 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
src/include/serif/eos/evaluation.hpp
View File

@@ -1,4 +1,12 @@
#pragma once
/**
* @file evaluation.hpp
* @author Emily M. Boudreaux
*
* @brief File containing the evaluate and partial_derivative functions. These functions are used to evaluate relations and partial derivatives for a given EOS model.
*/
#include "serif/eos/models/concepts.hpp"
namespace serif::eos {
@@ -15,6 +23,17 @@ namespace serif::eos {
* to determine if the expression inside it is noexcept. That is to say if eos.evaluate(...) is noexcept for the particular
* templates EOS argument then this function will be noexcept. If eos.evaluate(...) is not noexcept then this function will not be noexcept.
*/
/**
* @brief Evaluates a relation for a given EOS model. This function is used to evaluate relations for a given EOS model.
* @tparam OutputQ The output quantity type to evaluate.
* @tparam InputValues The input values to use for evaluation.
* @param eos The EOS model instance to use for evaluation.
* @param inputValues The input values to use for evaluation.
* @return The result of the evaluation.
*
* @note this is generally the function you want to call to evaluate a model as it will automatically dispatch to the correct relation.
*/
template <dimensions::ThermodynamicQuantityType OutputQ, models::EOSModel EOS, dimensions::QuantityValueType... InputValues>
requires models::EOSSupportingRelation<EOS, relations::Relation<OutputQ, dimensions::QuantityOfT<InputValues>...>>
[[nodiscard]] constexpr dimensions::QuantityValue<OutputQ> evaluate(const EOS& eos, const InputValues... inputValues)
@@ -22,10 +41,21 @@ namespace serif::eos {
return eos.evaluate(relations::Relation<OutputQ, dimensions::QuantityOfT<InputValues>...>{}, inputValues...);
};
/**
* @brief Evaluates a partial derivative of a relation for a given EOS model. This function is used to evaluate partial derivatives of relations for a given EOS model.
* @tparam OutputQ The output quantity type to evaluate.
* @tparam InputQ The input quantity type to take the partial derivative with respect to.
* @tparam InputValues The input values to use for evaluation.
* @param eos The EOS model instance to use for evaluation.
* @param inputValues The input values to use for evaluation.
* @return The result of the evaluation.
*
* @note this is generally the function you want to call to evaluate a model's partial derivative as it will automatically dispatch to the correct relation and partial derivative.
*/
template <dimensions::ThermodynamicQuantityType OutputQ, dimensions::ThermodynamicQuantityType InputQ, models::EOSModel EOS, dimensions::QuantityValueType... InputValues>
requires models::EOSSupportingPartialDerivative<EOS, relations::Relation<OutputQ, dimensions::QuantityOfT<InputValues>...>, InputQ>
[[nodiscard]] constexpr dimensions::PartialDerivative<OutputQ, InputQ> partial_derivative(const EOS& eos, const InputValues... inputValues)
noexcept(noexcept(eos.partialDerivative(relations::Relation<OutputQ, dimensions::QuantityOfT<InputValues>...>{}, dimensions::WithRespectTo<InputQ>{}, inputValues...))) {
noexcept(noexcept(eos.partial_derivative(relations::Relation<OutputQ, dimensions::QuantityOfT<InputValues>...>{}, dimensions::WithRespectTo<InputQ>{}, inputValues...))) {
return eos.partial_derivative(relations::Relation<OutputQ, dimensions::QuantityOfT<InputValues>...>{}, dimensions::WithRespectTo<InputQ>{}, inputValues...);
}

14
src/include/serif/eos/exceptions.hpp
View File

@@ -1,9 +1,23 @@
#pragma once
/**
* @file exceptions.hpp
* @author Emily M. Boudreaux
*
* @brief File containing the EOSEvaluationError exception class. This class is used to represent errors that occur during the evaluation of an EOS model.
*/
#include <cstdint>
#include <stdexcept>
#include <string>
namespace serif::eos {
/**
* @brief An exception class to represent errors that occur during the evaluation of an EOS model. This class inherits from std::domain_error and is used to provide a more specific exception type for EOS evaluation errors.
*
* @todo We have moved away from custom error types, this may warrant removal.
*/
class EOSEvaluationError final : public std::domain_error {
public:
explicit EOSEvaluationError(std::string message):

31
src/include/serif/eos/models/concepts.hpp
View File

@@ -1,26 +1,57 @@
#pragma once
/**
* @file concepts.hpp
* @author Emily M. Boudreaux
*
* @brief File containing concepts for the eos module. These concepts are used to constrain template parameters in the eos module.
*/
#include "serif/eos/models/traits.hpp"
#include "serif/eos/relations/relations.hpp"
namespace serif::eos::models {
/**
* @brief A concept to determine if a type is an equation of state model. A type is a valid EOSModel if it satisfies the is_equation_of_state_model_v trait.
*/
template <typename EOSCandidate>
concept EOSModel = is_equation_of_state_model_v<EOSCandidate>;
/**
* @brief A concept to determine if a type is an equation of state model that supports a given relation. A type is a valid EOSSupportingRelation if it satisfies the supports_relation_v trait.
*/
template <typename EOS, typename RelationT>
concept EOSSupportingRelation = supports_relation_v<EOS, RelationT>;
/**
* @brief A concept to determine if a type is an equation of state model that supports a given relation and a given input quantity. A type is a valid EOSSupportingPartialDerivative if it satisfies the supports_partial_derivative_v trait.
*/
template <typename EOS, typename RelationT, typename InputQuantity>
concept EOSSupportingPartialDerivative = supports_partial_derivative_v<EOS, RelationT, InputQuantity>;
/**
* @brief A concept to determine if a type is an equation of state model that can be used in the current SERiF seed initialization system. This is satisfied for types that are both valid EOSModels and
* which also support the relation for computing specific enthalpy from density.
*
* @todo A future more general version of this code will need a more general seeding system.
*/
template <typename EOSCandidate>
concept StructureSeedEOS = EOSModel<EOSCandidate> &&
EOSSupportingRelation<EOSCandidate, relations::SpecificEnthalpyFromDensity>;
/**
* @brief A concept to determine if an EOS type can be used as a barotropic closure in the current SERiF system. This is satisfied for types that are
* valid EOS models, support the relation for computing density from specific enthalpy, and support the partial derivative of that relation with respect to specific enthalpy.
*/
template <typename EOSCandidate>
concept BarotropicClosureEOS = EOSModel<EOSCandidate> &&
EOSSupportingRelation<EOSCandidate, relations::DensityFromSpecificEnthalpy> &&
EOSSupportingPartialDerivative<EOSCandidate, relations::DensityFromSpecificEnthalpy, dimensions::SpecificEnthalpy>;
/**
* @brief A concept to determine if an EOS type can be used to compute pressure forces in the current SERiF system. This is satisfied for types that are valid EOS models, support
* the relation for computing pressure from specific enthalpy, and support the partial derivative of that relation with respect to specific enthalpy.
*/
template <typename EOSCandidate>
concept PressureForceEOS = EOSModel<EOSCandidate> &&
EOSSupportingRelation<EOSCandidate, relations::PressureFromSpecificEnthalpy> &&

147
src/include/serif/eos/models/polytropic.hpp
View File

@@ -1,22 +1,50 @@
#pragma once
/**
* @file polytropic.hpp
* @author Emily M. Boudreaux
*
* @brief File containing the Polytropic equation of state.
*/
#include "serif/eos/relations/relations.hpp"
#include "serif/dimensions/type_alias.hpp"
#include "serif/dimensions/partial.hpp"
namespace serif::eos::models {
/**
* @brief A struct to hold the parameters for a polytropic equation of state.
*/
struct PolytropeParameters final {
double n;
double K;
double n; ///< Polytropic index
double K; ///< Polytropic constant
};
/*
* *
* @brief A class representing a polytropic equation of state.
*
* @note The polytropic equation of state is defined by the relation P = K * rho^(1 + 1/n), where P is the pressure, rho is the density, K is the polytropic constant, and n is the polytropic index.
*
* @note The idea here (and with all EOS) is that we force the developer / implementer to enumerate all the thermodynamic relations that the EOS supports explicitly.
* This is a small amount of boilerplate; however, it enables effectively a fully automatic, compile time resolution, of which EOS are valid for particular parts
* of the code and which are not. Much of the EOS system these classes depend on (relations, models, the system in evaluation) are all there to allow for the
* compile-time checking of the EOS model and its relations and to allow the developer cross-section of that to be limited to defining this relation catalog. Every
* EOS implemented should start (at the very top of the class with a Relations alias in the public section of the class. Any EOS that does not have this
* will not compile.
*/
class Polytrope final {
public:
/* The idea here (and with all EOS) is that we force the developer / implementer to enumerate all the thermodynamic relations
* that the EOS supports explicitly. This is a small amount of boilerplate; however, it enables effectively a fully automatic
* EOS compiler down the line. Much of the EOS system these classes depend on (relations, models, the system in evaluation) are all
* there to allow for the compile-time checking of the EOS model and its relations and to allow the developer cross-section
* of that to be limited to defining this relation catalog. Every EOS implemented should start (at the very top of the class
* with a Relations alias in the public section of the class. Any EOS that does not have this will not compile.
/**
* @brief A type alias for the relation catalog that this EOS supports. This is used to determine which relations are valid for this EOS.
*
* A polytropic EOS supports the following relations:
* - PressureFromDensity
* - PressureFromSpecificEnthalpy
* - SpecificEnthalpyFromDensity
* - SpecificEnthalpyFromPressure
* - DensityFromSpecificEnthalpy
*/
using Relations = relations::RelationCatalog<
relations::PressureFromDensity,
@@ -26,40 +54,115 @@ namespace serif::eos::models {
relations::DensityFromSpecificEnthalpy
>;
/**
* @brief Constructs a Polytrope with the given parameters.
* @param parameters The parameters for the polytropic equation of state.
*/
explicit Polytrope(const PolytropeParameters& parameters);
/**
* @brief Constructs a Polytrope with the given polytropic index and constant.
* @param n The polytropic index.
* @param K The polytropic constant.
*/
explicit Polytrope(double n, double K);
/**
* @brief Returns the polytropic index of the equation of state.
* @return The polytropic index.
*/
[[nodiscard]] double polytropic_index() const noexcept;
/**
* @brief Returns the polytropic constant of the equation of state.
* @return The polytropic constant.
*/
[[nodiscard]] double polytropic_constant() const noexcept;
/**
* @brief Returns the enthalpy scale of the equation of state. Note that this is calculated at construction time from the polytropic index and constant as
* h = (n + 1) * K
* @return The enthalpy scale.
*/
[[nodiscard]] double enthalpy_scale() const noexcept;
[[nodiscard]] dimensions::PressureValue evaluate(relations::PressureFromDensity, dimensions::DensityValue density) const;
[[nodiscard]] dimensions::PressureValue evaluate(relations::PressureFromSpecificEnthalpy, dimensions::SpecificEnthalpyValue specific_enthalpy) const;
[[nodiscard]] dimensions::SpecificEnthalpyValue evaluate(relations::SpecificEnthalpyFromDensity, dimensions::DensityValue density) const;
[[nodiscard]] dimensions::SpecificEnthalpyValue evaluate(relations::SpecificEnthalpyFromPressure, dimensions::PressureValue pressure) const;
[[nodiscard]] dimensions::DensityValue evaluate(relations::DensityFromSpecificEnthalpy, dimensions::SpecificEnthalpyValue specific_enthalpy) const;
// Note how we need an evaluate for each relation that the EOS supports.
/**
* @brief Evaluate the pressure from the density.
* @param relation The relation to evaluate (note that this is not used in the function but is used to constrain the overload being called).
* @param density The density value to evaluate the pressure from.
*/
[[nodiscard]] dimensions::PressureValue evaluate(relations::PressureFromDensity /*relation*/, dimensions::DensityValue density) const;
/**
* @brief Evaluate the pressure from the specific enthalpy.
* @param relation The relation to evaluate (note that this is not used in the function but is used to constrain the overload being called).
* @param specific_enthalpy The specific enthalpy value to evaluate the pressure from.
*/
[[nodiscard]] dimensions::PressureValue evaluate(relations::PressureFromSpecificEnthalpy /*relation*/, dimensions::SpecificEnthalpyValue specific_enthalpy) const;
/**
* @brief Evaluate the specific enthalpy from the density.
* @param relation The relation to evaluate (note that this is not used in the function but is used to constrain the overload being called).
* @param density The density value to evaluate the specific enthalpy from.
*/
[[nodiscard]] dimensions::SpecificEnthalpyValue evaluate(relations::SpecificEnthalpyFromDensity /*relation*/, dimensions::DensityValue density) const;
/**
* @brief Evaluate the specific enthalpy from the pressure.
* @param relation The relation to evaluate (note that this is not used in the function but is used to constrain the overload being called).
* @param pressure The pressure value to evaluate the specific enthalpy from.
*/
[[nodiscard]] dimensions::SpecificEnthalpyValue evaluate(relations::SpecificEnthalpyFromPressure /*relation*/, dimensions::PressureValue pressure) const;
/**
* @brief Evaluate the density from the specific enthalpy.
* @param relation The relation to evaluate (note that this is not used in the function but is used to constrain the overload being called).
* @param specific_enthalpy The specific enthalpy value to evaluate the density from.
*/
[[nodiscard]] dimensions::DensityValue evaluate(relations::DensityFromSpecificEnthalpy /*relation*/, dimensions::SpecificEnthalpyValue specific_enthalpy) const;
/**
* @brief Evaluate the partial derivative of the density with respect to the specific enthalpy.
* @param relation The relation to evaluate (note that this is not used in the function but is used to constrain the overload being called).
* @param with_respect_to The quantity to take the partial derivative with respect to (note that this is not used in the function but is used to constrain the overload being called).
* @param specific_enthalpy The specific enthalpy value to evaluate the partial derivative from.
*/
[[nodiscard]] dimensions::PartialDerivative<dimensions::MassDensity, dimensions::SpecificEnthalpy> partial_derivative(
relations::DensityFromSpecificEnthalpy,
dimensions::WithRespectTo<dimensions::SpecificEnthalpy>,
relations::DensityFromSpecificEnthalpy /*relation*/,
dimensions::WithRespectTo<dimensions::SpecificEnthalpy> /*with_respect_to*/,
dimensions::SpecificEnthalpyValue specific_enthalpy
) const;
/**
* @brief Evaluate the partial derivative of the pressure with respect to the specific enthalpy.
* @param relation The relation to evaluate (note that this is not used in the function but is used to constrain the overload being called).
* @param with_respect_to The quantity to take the partial derivative with respect to (note that this is not used in the function but is used to constrain the overload being called).
* @param specific_enthalpy The specific enthalpy value to evaluate the partial derivative from.
*/
[[nodiscard]] dimensions::PartialDerivative<dimensions::Pressure, dimensions::SpecificEnthalpy> partial_derivative(
relations::PressureFromSpecificEnthalpy,
dimensions::WithRespectTo<dimensions::SpecificEnthalpy>,
relations::PressureFromSpecificEnthalpy /*relation*/,
dimensions::WithRespectTo<dimensions::SpecificEnthalpy> /*with_respect_to*/,
dimensions::SpecificEnthalpyValue specific_enthalpy
) const;
/**
* @brief Evaluate the partial derivative of the pressure with respect to the mass density.
* @param relation The relation to evaluate (note that this is not used in the function but is used to constrain the overload being called).
* @param with_respect_to The quantity to take the partial derivative with respect to (note that this is not used in the function but is used to constrain the overload being called).
* @param density The density value to evaluate the partial derivative from.
*/
[[nodiscard]] dimensions::PartialDerivative<dimensions::Pressure, dimensions::MassDensity> partial_derivative(
relations::PressureFromDensity,
dimensions::WithRespectTo<dimensions::MassDensity>,
relations::PressureFromDensity /*relation*/,
dimensions::WithRespectTo<dimensions::MassDensity> /*with_respect_to*/,
dimensions::DensityValue density
) const;
private:
double m_polytropic_index;
double m_polytropic_constant;
double m_enthalpy_scale;
double m_polytropic_index; ///< The polytropic index of the equation of state.
double m_polytropic_constant; ///< The polytropic constant of the equation of state.
double m_enthalpy_scale; ///< The enthalpy scale of the equation of state, calculated as (n + 1) * K.
};
}

67
src/include/serif/eos/models/traits.hpp
View File

@@ -1,12 +1,30 @@
#pragma once
/**
* @file traits.hpp
* @author Emily M. Boudreaux
*
* @brief File containing the traits for the eos module. These traits are used to determine if a type is an equation of state model and if it supports a given relation or partial derivative.
*/
#include "serif/dimensions/quantities.hpp"
#include "serif/dimensions/partial.hpp"
#include "serif/eos/relations/concepts.hpp"
namespace serif::eos::models {
/**
* @brief A trait to determine if a type is an equation of state model. This is the default false specialization.
* @tparam EOSCandidate The type to check.
*/
template <typename EOS, typename RelationT>
struct ImplementsRelation_t : std::false_type{};
/**
* @brief A specialization of the ImplementsRelation_t trait for a relation. This is used to determine if an EOS type implements a given relation.
* @tparam EOS The EOS type to check.
* @tparam Output The output quantity of the relation.
* @tparam Inputs The input quantities of the relation.
*/
template <typename EOS, typename Output, typename... Inputs>\
struct ImplementsRelation_t<EOS, relations::Relation<Output, Inputs...>> :
std::bool_constant<
@@ -15,17 +33,36 @@ namespace serif::eos::models {
eos.evaluate(relations::Relation<Output, Inputs...>{}, inputValues...)
} -> std::same_as<dimensions::QuantityValue<Output>>;}>{}; // Read this as a requirement that when evaluating the templates EOS with the given relation and inputs the returned value is of the correct output type.
/**
* @brief A trait to determine if a type implements all relations in a relation catalog. This is the default false specialization.
* @tparam EOS The EOS type to check.
* @tparam Catalog The relation catalog to check.
*/
template <typename EOS, typename Catalog>
struct ImplementsRelationCatalog_t : std::false_type {};
/**
* @brief A specialization of the ImplementsRelationCatalog_t trait for a relation catalog. This is used to determine if an EOS type implements all relations in a given relation catalog.
* @tparam EOS The EOS type to check.
* @tparam Relations The relations in the relation catalog.
*/
template <typename EOS, typename... Relations>
struct ImplementsRelationCatalog_t<EOS, relations::RelationCatalog<Relations...>> :
std::bool_constant<
(ImplementsRelation_t<EOS, Relations>::value && ...)>{}; // Fold over all relations in a catalog and ensure the EOS implements all of them.
/**
* @brief A trait to determine if a type is an equation of state model. This is the default false specialization.
* @tparam EOSCandidate The type to check.
*/
template <typename EOSCandidate, typename = void>
struct IsEquationOfStateModel_t : std::false_type {};
/**
* @brief A specialization of the IsEquationOfStateModel_t trait for a type that has a Relations type alias. A candidate is an equation of state model
* if it has a valid relation catalog and implements all relations in that catalog.
* @tparam EOSCandidate The type to check.
*/
template <typename EOSCandidate>
struct IsEquationOfStateModel_t<EOSCandidate, std::void_t<typename std::remove_cvref_t<EOSCandidate>::Relations>> :
std::bool_constant<
@@ -34,23 +71,51 @@ namespace serif::eos::models {
std::remove_cvref_t<EOSCandidate>,
typename std::remove_cvref_t<EOSCandidate>::Relations>::value>{ };
/**
* @brief A trait to determine if a type implements a partial derivative for a given relation and input quantity. This is the default false specialization.
* @tparam EOS The EOS type to check.
* @tparam RelationT The relation to check.
* @tparam InputQuantity The input quantity to check.
*/
template <typename EOS, typename RelationT, typename InputQuantity>
struct ImplementsPartialDerivative_t : std::false_type {};
/**
* @brief A specialization of the ImplementsPartialDerivative_t trait for a relation and input quantity. This is used to determine if an EOS type implements a partial derivative for a given relation and input quantity.
* @tparam EOS The EOS type to check.
* @tparam Output The output quantity of the relation.
* @tparam Inputs The input quantities of the relation.
* @tparam InputQuantity The input quantity to check.
*/
template <typename EOS, typename Output, typename... Inputs, typename InputQuantity>
struct ImplementsPartialDerivative_t<EOS, relations::Relation<Output, Inputs...>, InputQuantity> :
std::bool_constant<
(std::same_as<InputQuantity, Inputs> || ...) &&
requires (const std::remove_cvref_t<EOS> &eos, dimensions::QuantityValue<Inputs>... inputValues) {
{eos.partialDerivative(relations::Relation<Output, Inputs...>{}, dimensions::WithRespectTo<InputQuantity>{}, inputValues...)} -> std::same_as<dimensions::PartialDerivative<Output, Inputs...>>;
{eos.partial_derivative(relations::Relation<Output, Inputs...>{}, dimensions::WithRespectTo<InputQuantity>{}, inputValues...)} -> std::same_as<dimensions::PartialDerivative<Output, InputQuantity>>;
}>{};
/**
* @brief A variable template to determine if a type is an equation of state model.
* @tparam EOSCandidate The type to check.
*/
template <typename EOSCandidate>
inline constexpr bool is_equation_of_state_model_v = IsEquationOfStateModel_t<std::remove_cvref_t<EOSCandidate>>::value;
/**
* @brief A variable template to determine if an EOS type supports a given relation.
* @tparam EOS The EOS type to check.
* @tparam RelationT The relation to check.
*/
template <typename EOS, typename RelationT>
inline constexpr bool supports_relation_v = is_equation_of_state_model_v<EOS> && ImplementsRelation_t<std::remove_cvref_t<EOS>, std::remove_cvref_t<RelationT>>::value;
/**
* @brief A variable template to determine if an EOS type supports a partial derivative for a given relation and input quantity.
* @tparam EOS The EOS type to check.
* @tparam RelationT The relation to check.
* @tparam InputQuantity The input quantity to check.
*/
template <typename EOS, typename RelationT, typename InputQuantity>
inline constexpr bool supports_partial_derivative_v = is_equation_of_state_model_v<EOS> && ImplementsPartialDerivative_t<std::remove_cvref_t<EOS>, std::remove_cvref_t<RelationT>, InputQuantity>::value;
}

24
src/include/serif/eos/relations/catalog.hpp
View File

@@ -1,5 +1,12 @@
#pragma once
/**
* @file catalog.hpp
* @author Emily M. Boudreaux
*
* @brief File containing the Relation and RelationCatalog structs. These structs are used to represent relations between physical quantities and to group them into catalogs for use in EOS models.
*/
#include "serif/utils/misc/concepts/type_uniqueness.hpp"
#include "serif/utils/misc/std_helper/variadic_cleaning.hpp"
#include "serif/dimensions/quantities.hpp"
@@ -8,16 +15,25 @@ namespace serif::eos::relations {
using utils::misc::std_helper::CountVariadicArguments;
using utils::misc::concepts::AllTypesAreUnique;
/**
* @brief A struct to represent a relation between physical quantities. This is used to define the relations that an EOS model supports.
* @tparam Output The output quantity of the relation.
* @tparam Inputs The input quantities of the relation.
*/
template <typename Output, typename... Inputs>
struct Relation final {
using OutputQuantity = Output;
using InputQuantities = dimensions::QuantityList<Inputs...>;
using OutputQuantity = Output; ///< The output quantity of the relation.
using InputQuantities = dimensions::QuantityList<Inputs...>; ///< The input quantities of the relation.
static constexpr std::size_t inputCount = CountVariadicArguments<Inputs...>();
static constexpr std::size_t inputCount = CountVariadicArguments<Inputs...>(); ///< The number of input quantities in the relation.
};
/**
* @brief A struct to represent a catalog of relations between physical quantities. This is used to group relations for use in EOS models.
* @tparam Relations The relations to include in the catalog.
*/
template <typename... Relations>
struct RelationCatalog final {
static constexpr std::size_t size = CountVariadicArguments<Relations...>();
static constexpr std::size_t size = CountVariadicArguments<Relations...>(); ///< The number of relations in the catalog.
};
}

20
src/include/serif/eos/relations/concepts.hpp
View File

@@ -1,17 +1,37 @@
#pragma once
/**
* @file concepts.hpp
* @author Emily M. Boudreaux
*
* @brief File containing concepts for the eos relations module. These concepts are used to constrain template parameters in the eos relations module.
*/
#include "serif/eos/relations/traits.hpp"
namespace serif::eos::relations {
/**
* @brief A concept used to constrain a type to a catalog that contains a given relation.
*/
template <typename Catalog, typename RelationT>
concept CatalogContainingRelation = relation_catalog_contains_relation_v<Catalog, RelationT>;
/**
* @brief A concept used to constrain a type to a relation that contains a given input quantity.
*/
template <typename RelationT, typename Quantity>
concept RelationContainingInput = relation_contains_input_v<RelationT, Quantity>;
/**
* @brief A concept used to constrain a type to a valid thermodynamic relation. A type is a valid thermodynamic relation if it satisfies the is_thermodynamic_relation_v trait.
*/
template <typename RelationCandidate>
concept ValidThermodynamicRelation = is_thermodynamic_relation_v<RelationCandidate>;
/**
* @brief A concept used to constrain a type to a valid relation catalog. A type is a valid relation catalog if it satisfies the is_valid_relation_catalog_v trait.
*/
template <typename CandidateCatalog>
concept ValidRelationCatalog = is_valid_relation_catalog_v<CandidateCatalog>;
}

31
src/include/serif/eos/relations/relations.hpp
View File

@@ -1,26 +1,19 @@
#pragma once
/**
* @file relations.hpp
* @author Emily M. Boudreaux
*
* @brief File containing the thermodynamic relations used in the eos module. These relations are used to compute various thermodynamic quantities from other quantities.
*/
#include "serif/eos/relations/catalog.hpp"
#include "serif/dimensions/dimensions.hpp"
namespace serif::eos::relations {
using PressureFromDensity = Relation<
dimensions::Pressure,
dimensions::MassDensity>;
using PressureFromSpecificEnthalpy = Relation<
dimensions::Pressure,
dimensions::SpecificEnthalpy>;
using SpecificEnthalpyFromDensity = Relation<
dimensions::SpecificEnthalpy,
dimensions::MassDensity>;
using SpecificEnthalpyFromPressure = Relation<
dimensions::SpecificEnthalpy,
dimensions::Pressure>;
using DensityFromSpecificEnthalpy = Relation<
dimensions::MassDensity,
dimensions::SpecificEnthalpy>;
using PressureFromDensity = Relation<dimensions::Pressure, dimensions::MassDensity>; ///< A relation to compute pressure from density.
using PressureFromSpecificEnthalpy = Relation<dimensions::Pressure, dimensions::SpecificEnthalpy>; ///< A relation to compute pressure from specific enthalpy.
using SpecificEnthalpyFromDensity = Relation<dimensions::SpecificEnthalpy, dimensions::MassDensity>; ///< A relation to compute specific enthalpy from density.
using SpecificEnthalpyFromPressure = Relation<dimensions::SpecificEnthalpy, dimensions::Pressure>; ///< A relation to compute specific enthalpy from pressure.
using DensityFromSpecificEnthalpy = Relation<dimensions::MassDensity, dimensions::SpecificEnthalpy>; ///< A relation to compute density from specific enthalpy.
}

68
src/include/serif/eos/relations/traits.hpp
View File

@@ -1,25 +1,66 @@
#pragma once
/**
* @file traits.hpp
* @author Emily M. Boudreaux
*
* @brief File containing traits for the eos relations module. These traits are used to determine if a type is a valid thermodynamic relation or a valid relation catalog.
*/
#include "serif/eos/relations/catalog.hpp"
namespace serif::eos::relations {
/**
* @brief A trait to determine if a catalog contains a given relation. This is the default false specialization.
* @tparam Catalog The catalog type to check.
* @tparam RelationT The relation type to check for.
*/
template <typename Catalog, typename RelationT>
struct CatalogContainsRelation : std::false_type {};
/**
* @brief A specialization of the CatalogContainsRelation trait for a RelationCatalog. This trait is used to determine if a RelationCatalog contains a given relation.
* This is true so long as any of the relations in the catalog match the relation type being checked for.
* @tparam Relations The relation types that make up the catalog.
* @tparam RelationT The relation type to check for.
*/
template <typename... Relations, typename RelationT>
struct CatalogContainsRelation<RelationCatalog<Relations...>, RelationT> :
std::bool_constant<(std::same_as<RelationT, Relations> || ...)> {}; // Fold over all Relations and return true type if any of them match RelationT
/**
* @brief A trait to determine if a relation contains a given input quantity. This is the default false specialization.
* @tparam RelationT The relation type to check.
* @tparam Quantity The quantity type to check for.
*/
template <typename RelationT, typename Quantity>
struct RelationContainsInput : std::false_type {};
/**
* @brief A specialization of the RelationContainsInput trait for a Relation. This trait is used to determine if a Relation contains a given input quantity.
* This is true so long as any of the input quantities in the relation match the quantity type being checked for.
* @tparam Output The output quantity of the relation.
* @tparam Inputs The input quantities of the relation.
* @tparam Quantity The quantity type to check for.
*/
template <typename Output, typename... Inputs, typename Quantity>
struct RelationContainsInput<Relation<Output, Inputs...>, Quantity> :
std::bool_constant<(std::same_as<Quantity, Inputs> || ...)> {};
/**
* @brief A trait to determine if a type is a valid thermodynamic relation. This is the default false specialization.
* @tparam RelationCandidate The type to check.
*/
template <typename RelationCandidate>
struct IsThermodynamicRelation : std::false_type {};
/**
* @brief A specialization of the IsThermodynamicRelation trait for a Relation. This trait is used to determine if a Relation is a valid thermodynamic relation.
* A relation is considered valid if its output quantity and all of its input quantities are valid thermodynamic quantities, and if all of its input quantities are unique types.
* @tparam Output The output quantity of the relation.
* @tparam Inputs The input quantities of the relation.
*/
template <typename Output, typename... Inputs>
struct IsThermodynamicRelation<Relation<Output, Inputs...>> :
std::bool_constant<
@@ -27,9 +68,18 @@ namespace serif::eos::relations {
(dimensions::ThermodynamicQuantityType<Inputs> && ...) && // Fold over all InputQuantities to ensure they are valid thermodynamic quantities
AllTypesAreUnique<Inputs...>> {}; // Ensure all InputQuantities are unique types
/**
* @brief A trait to determine if a type is a valid relation catalog. This is the default false specialization.
* @tparam CandidateCatalog The type to check.
*/
template <typename CandidateCatalog>
struct IsValidRelationCatalog : std::false_type {};
/**
* @brief A specialization of the IsValidRelationCatalog trait for a RelationCatalog. This trait is used to determine if a RelationCatalog is a valid relation catalog.
* A relation catalog is considered valid if it contains at least one relation, if all of its relations are valid thermodynamic relations, and if all of its relations are unique types.
* @tparam Relations The relation types that make up the catalog.
*/
template <typename... Relations>
struct IsValidRelationCatalog<RelationCatalog<Relations...>> :
std::bool_constant<
@@ -37,15 +87,33 @@ namespace serif::eos::relations {
(IsThermodynamicRelation<Relations>::value && ...) && // Fold over all Relations and ensure they are all valid
AllTypesAreUnique<Relations...>> {}; // Ensure all Relations are unique types (e.g. no duplicate relations)
/**
* @brief A trait to determine if a catalog contains a given relation. This is a helper variable template that simplifies the usage of the CatalogContainsRelation trait.
* @tparam Catalog The catalog type to check.
* @tparam RelationT The relation type to check for.
*/
template <typename Catalog, typename RelationT>
inline constexpr bool relation_catalog_contains_relation_v = CatalogContainsRelation<std::remove_cv_t<Catalog>, std::remove_cv_t<RelationT>>::value;
/**
* @brief A trait to determine if a relation contains a given input quantity. This is a helper variable template that simplifies the usage of the RelationContainsInput trait.
* @tparam RelationT The relation type to check.
* @tparam Quantity The quantity type to check for.
*/
template <typename RelationT, typename Quantity>
inline constexpr bool relation_contains_input_v = RelationContainsInput<std::remove_cv_t<RelationT>, std::remove_cv_t<Quantity>>::value;
/**
* @brief A trait to determine if a relation is a valid thermodynamic relation. This is a helper variable template that simplifies the usage of the IsThermodynamicRelation trait.
* @tparam RelationCandidate The relation type to check.
*/
template <typename RelationCandidate>
constexpr bool is_thermodynamic_relation_v = IsThermodynamicRelation<RelationCandidate>::value;
/**
* @brief A trait to determine if a catalog is a valid relation catalog. This is a helper variable template that simplifies the usage of the IsValidRelationCatalog trait.
* @tparam CatalogCandidate The catalog type to check.
*/
template <typename CatalogCandidate>
constexpr bool is_valid_relation_catalog_v = IsValidRelationCatalog<CatalogCandidate>::value;

20
src/include/serif/eos/runtime/concepts.hpp
View File

@@ -1,16 +1,36 @@
#pragma once
/**
* @file concepts.hpp
* @author Emily M. Boudreaux
*
* @brief File containing concepts for the eos runtime module. These concepts are used to constrain template parameters in the eos runtime module.
*/
#include "serif/eos/models/concepts.hpp"
#include "serif/eos/runtime/details.hpp"
namespace serif::eos::runtime {
/**
* @brief A concept to determine if a type is a valid runtime EOS model. A type is a valid RuntimeEOSModel if it satisfies the EOSModel concept and if its Relations catalog is supported by the runtime system.
* @tparam Candidate The type to check.
*/
template <typename Candidate>
concept RuntimeEOSModel = eos::models::EOSModel<Candidate> &&
RuntimeCatalogIsSupported<typename std::remove_cvref_t<Candidate>::Relations>::value;
/**
* @brief A helper alias to adapt a runtime EOS model to the runtime catalog dispatch system. This is used to simplify the usage of runtime EOS models in the runtime system.
* @tparam EOSCandidate The runtime EOS model type to adapt.
*/
template <RuntimeEOSModel EOSCandidate>
using RuntimeEOSAdapter = RuntimeCatalogDispatch<EOSCandidate, typename EOSCandidate::Relations>;
/**
* @brief A helper function to get the runtime relation descriptors for a runtime EOS model. This is used to simplify the usage of runtime EOS models in the runtime system.
* @tparam EOSCandidate The runtime EOS model type to get the descriptors for.
* @return A span of runtime relation descriptors.
*/
template <RuntimeEOSModel EOSCandidate>
[[nodiscard]] constexpr std::span<const dimensions::runtime::RuntimeRelationDescriptor> runtimeRelationDescriptors() noexcept {
return RuntimeCatalogStorage<EOSCandidate, typename EOSCandidate::Relations>::descriptors;

186
src/include/serif/eos/runtime/details.hpp
View File

@@ -1,4 +1,12 @@
#pragma once
/**
* @file details.hpp
* @author Emily M. Boudreaux
*
* @brief File containing implementation details for the eos runtime module. These details are used internally by the runtime system and are not intended to be used directly by users.
*/
#include <array>
#include <type_traits>
#include <tuple>
@@ -6,30 +14,59 @@
#include "serif/dimensions/runtime/concepts.hpp"
#include "serif/eos/exceptions.hpp"
#include "serif/eos/evaluation.hpp"
#include "serif/eos/relations/catalog.hpp"
#include "serif/utils/error/codes.hpp"
namespace serif::eos::runtime {
/**
* @brief A helper trait to determine if a relation has runtime quantity identifiers. This is used to ensure that all relations in a catalog have unique runtime quantity identifiers.
* @tparam RelationT The relation type to check.
*/
template <typename RelationT>
struct HasRuntimeQuantityIdentifiers : std::false_type {};
/**
* @brief A specialization of the HasRuntimeQuantityIdentifiers trait for a relation. This specialization checks if the output and input quantities of the relation have runtime quantity identifiers.
* @tparam OutputT The output quantity type of the relation.
* @tparam InputTs The input quantity types of the relation.
*/
template <typename OutputT, typename... InputTs>
struct HasRuntimeQuantityIdentifiers<relations::Relation<OutputT, InputTs...>>
: std::bool_constant<
dimensions::runtime::RuntimeIdentifiedThermodynamicQuantity<OutputT> &&
(dimensions::runtime::RuntimeIdentifiedThermodynamicQuantity<InputTs> && ...)> {};
/**
* @brief A helper trait to extract the output and input quantity types from a relation. This is used to simplify the usage of relations in the runtime system.
* @tparam RelationT The relation type to extract the quantity types from.
*/
template <typename RelationT>
struct RuntimeRelationQuantities;
/**
* @brief A specialization of the RuntimeRelationQuantities trait for a relation. This specialization extracts the output and input quantity types from the relation and stores them in a tuple.
* @tparam OutputT The output quantity type of the relation.
* @tparam InputTs The input quantity types of the relation.
*/
template <typename OutputT, typename... InputTs>
struct RuntimeRelationQuantities<relations::Relation<OutputT, InputTs...>> {
using Type = std::tuple<OutputT, InputTs...>;
};
/**
* @brief A helper alias to extract the quantity types from a catalog of relations. This is used to simplify the usage of catalogs in the runtime system.
* @tparam RelationTs The relation types in the catalog.
*/
template <typename... RelationTs>
using RuntimeCatalogQuantityTuple = decltype(std::tuple_cat(std::declval<typename RuntimeRelationQuantities<RelationTs>::Type>()...));
/**
* @brief A helper function to determine if two runtime quantity identifiers are compatible. This is used to ensure that all relations in a catalog have unique runtime quantity identifiers.
* @tparam FirstQuantityT The first quantity type to check.
* @tparam SecondQuantityT The second quantity type to check.
* @return True if the quantity identifiers are compatible, false otherwise.
*/
template <typename FirstQuantityT, typename SecondQuantityT>
[[nodiscard]] consteval bool runtimeQuantityIdentifiersAreCompatible() {
if constexpr (std::same_as<FirstQuantityT, SecondQuantityT>) {
@@ -40,6 +77,13 @@ namespace serif::eos::runtime {
}
}
/**
* @brief A helper function to determine if the runtime quantity identifiers in a tuple of quantity types are unambiguous. This is used to ensure that all relations in a catalog have unique runtime quantity identifiers.
* @tparam QuantityTupleT The tuple of quantity types to check.
* @tparam First The index of the first quantity type to check.
* @tparam Offsets The indices of the remaining quantity types to check.
* @return True if the quantity identifiers are unambiguous, false otherwise.
*/
template <typename QuantityTupleT, std::size_t First, std::size_t... Offsets>
[[nodiscard]] consteval bool runtimeQuantityIdentifierIsUnambiguous(std::index_sequence<Offsets...>) {
return (
@@ -49,6 +93,12 @@ namespace serif::eos::runtime {
);
}
/**
* @brief A helper function to determine if the runtime quantity identifiers in a tuple of quantity types are unambiguous. This is used to ensure that all relations in a catalog have unique runtime quantity identifiers.
* @tparam QuantityTupleT The tuple of quantity types to check.
* @tparam Indices The indices of the quantity types to check.
* @return True if the quantity identifiers are unambiguous, false otherwise.
*/
template <typename QuantityTupleT, std::size_t... Indices>
[[nodiscard]] consteval bool runtimeQuantityIdentifiersAreUnambiguous(std::index_sequence<Indices...>) {
return (
@@ -56,35 +106,69 @@ namespace serif::eos::runtime {
);
}
/**
* @brief A helper trait to determine if the runtime quantity identifiers in a catalog of relations are unambiguous. This is used to ensure that all relations in a catalog have unique runtime quantity identifiers.
* @tparam RelationTs The relation types in the catalog.
*/
template <bool QuantitiesAreIdentified, typename... RelationTs>
struct RuntimeRelationsAreSupported : std::false_type {};
/**
* @brief A specialization of the RuntimeRelationsAreSupported trait for a catalog of relations. This specialization checks if the runtime quantity identifiers in the catalog are unambiguous.
* @tparam RelationTs The relation types in the catalog.
*/
template <typename... RelationTs>
struct RuntimeRelationsAreSupported<true, RelationTs...> :
std::bool_constant<runtimeQuantityIdentifiersAreUnambiguous<RuntimeCatalogQuantityTuple<RelationTs...>>(
std::make_index_sequence<std::tuple_size_v<RuntimeCatalogQuantityTuple<RelationTs...>>>{}
)> {};
/**
* @brief A helper trait to determine if a catalog of relations is supported by the runtime system. This is used to ensure that all relations in a catalog have unique runtime quantity identifiers.
* @tparam CatalogT The catalog type to check.
*/
template <typename CatalogT>
struct RuntimeCatalogIsSupported : std::false_type {};
/**
* @brief A specialization of the RuntimeCatalogIsSupported trait for a catalog of relations. This specialization checks if the relations in the catalog have runtime quantity identifiers and if the runtime quantity identifiers are unambiguous.
* @tparam RelationTs The relation types in the catalog.
*/
template <typename... RelationTs>
struct RuntimeCatalogIsSupported<relations::RelationCatalog<RelationTs...>> :
RuntimeRelationsAreSupported<(HasRuntimeQuantityIdentifiers<RelationTs>::value && ...), RelationTs...> {};
/**
* @brief A helper trait to determine if a catalog of relations is supported by the runtime system. This is used to ensure that all relations in a catalog have unique runtime quantity identifiers.
* @tparam CatalogT The catalog type to check.
*/
template <typename EOS, typename RelationT>
struct RuntimeRelationStorage;
/**
* @brief A specialization of the RuntimeRelationStorage trait for a relation. This specialization extracts the output and input quantity types from the relation and stores them in a tuple.
* @tparam EOS The EOS model type that supports the relation.
* @tparam OutputT The output quantity type of the relation.
* @tparam InputTs The input quantity types of the relation.
*/
template <typename EOS, typename OutputT, typename... InputTs>
struct RuntimeRelationStorage<EOS, relations::Relation<OutputT, InputTs...>> {
using RelationType = relations::Relation<OutputT, InputTs...>;
using RelationType = relations::Relation<OutputT, InputTs...>; ///< The relation type that this storage is for.
static_assert(sizeof...(InputTs) <= 64, "Runtime EOS relation descriptors support at most 64 inputs. If you need more than this you will need to implement your own custom RuntimeRelationStorage specialization");
inline static constexpr std::array<dimensions::runtime::ThermodynamicQuantityID, sizeof...(InputTs)> inputQuantityIDs {
/**
* @brief A static array of the runtime quantity identifiers for the input quantities of the relation. This is used to ensure that all relations in a catalog have unique runtime quantity identifiers.
*/
static constexpr std::array<dimensions::runtime::ThermodynamicQuantityID, sizeof...(InputTs)> inputQuantityIDs {
dimensions::runtime::thermodynamicQuantityID<InputTs>...
};
/**
* @brief A helper function to create a bitmask of the partial derivatives that are supported by the EOS model for the relation. This is used to ensure that all relations in a catalog have unique runtime quantity identifiers.
* @tparam Indices The indices of the input quantities to check.
* @return A bitmask of the partial derivatives that are supported by the EOS model for the relation.
*/
template <std::size_t... Indices>
[[nodiscard]] static consteval std::uint64_t makePartialDerivativeMask(std::index_sequence<Indices...>) {
using InputTuple = std::tuple<InputTs...>;
@@ -116,31 +200,58 @@ namespace serif::eos::runtime {
return (std::uint64_t{0} | ... | (models::EOSSupportingPartialDerivative<EOS, RelationType, std::tuple_element_t<Indices, InputTuple>> ? (std::uint64_t{1} << Indices) : std::uint64_t{0}));
}
inline static constexpr std::uint64_t partialDerivativeMask = makePartialDerivativeMask(std::index_sequence_for<InputTs...>{});
static constexpr std::uint64_t partialDerivativeMask = makePartialDerivativeMask(std::index_sequence_for<InputTs...>{}); ///< A bitmask of the partial derivatives that are supported by the EOS model for the relation. Each bit corresponds to an input quantity, with the least significant bit corresponding to the first input quantity and the most significant bit corresponding to the last input quantity.
inline static constexpr dimensions::runtime::RuntimeRelationDescriptor descriptor {
/**
* @brief A runtime relation descriptor for the relation. This is used to ensure that all relations in a catalog have unique runtime quantity identifiers.
*/
static constexpr dimensions::runtime::RuntimeRelationDescriptor descriptor {
.outputQuantity = dimensions::runtime::thermodynamicQuantityID<OutputT>,
.inputQuantities = std::span<const dimensions::runtime::ThermodynamicQuantityID>{inputQuantityIDs},
.partialDerivativeMask = partialDerivativeMask
};
};
/**
* @brief A helper struct to store the runtime relation descriptors for a catalog of relations. This is used to ensure that all relations in a catalog have unique runtime quantity identifiers.
* @tparam EOS The EOS model type that supports the relations in the catalog.
* @tparam CatalogT The catalog type to store the descriptors for.
*/
template <typename EOS, typename CatalogT>
struct RuntimeCatalogStorage;
/**
* @brief A specialization of the RuntimeCatalogStorage struct for a catalog of relations. This specialization stores the runtime relation descriptors for each relation in the catalog.
* @tparam EOS The EOS model type that supports the relations in the catalog.
* @tparam RelationTs The relation types in the catalog.
*/
template <typename EOS, typename... RelationTs>
struct RuntimeCatalogStorage<EOS, relations::RelationCatalog<RelationTs...>> {
inline static constexpr std::array descriptors {
RuntimeRelationStorage<EOS, RelationTs>::descriptor...
};
static constexpr std::array descriptors {RuntimeRelationStorage<EOS, RelationTs>::descriptor...};
};
/**
* @brief A helper function to create a std::unexpected with a SERiFErrorCode. This is used to simplify the usage of std::expected in the runtime system.
* @param code The SERiFErrorCode to wrap in a std::unexpected.
* @return A std::unexpected containing the given SERiFErrorCode.
*/
[[nodiscard]] inline std::expected<double, utils::errors::SERiFErrorCode> runtimeEvaluationFailure(
const utils::errors::SERiFErrorCode code
) {
return std::unexpected{code};
}
/**
* @brief A helper function to evaluate a relation at runtime. This is used to simplify the usage of std::expected in the runtime system.
* @tparam EOS The EOS model type that supports the relation.
* @tparam OutputT The output quantity type of the relation.
* @tparam InputTs The input quantity types of the relation.
*
* @param eos The EOS model instance to use for evaluation.
* @param relation The relation to evaluate.
* @param inputValues The input values to use for evaluation.
* @return A std::expected containing the result of the evaluation or a SERiFErrorCode if the evaluation failed.
*/
template <typename EOS, typename OutputT, typename... InputTs>
[[nodiscard]] std::expected<double, utils::errors::SERiFErrorCode> evaluateRuntimeRelation(
const EOS& eos,
@@ -163,6 +274,19 @@ namespace serif::eos::runtime {
}
}
/**
* @brief A helper function to evaluate a partial derivative of a relation at runtime. This is used to simplify the usage of std::expected in the runtime system.
* @tparam InputQuantityT The input quantity type to take the partial derivative with respect to.
* @tparam EOS The EOS model type that supports the relation.
* @tparam OutputT The output quantity type of the relation.
* @tparam InputTs The input quantity types of the relation.
*
* @param eos The EOS model instance to use for evaluation.
* @param relation The relation to evaluate.
* @param withRespectTo The input quantity type to take the partial derivative with respect to.
* @param inputValues The input values to use for evaluation.
* @return A std::expected containing the result of the evaluation or a SERiFErrorCode if the evaluation failed.
*/
template <typename InputQuantityT, typename EOS, typename OutputT, typename... InputTs>
[[nodiscard]] bool tryRuntimePartialDerivative(
const EOS& eos,
@@ -183,7 +307,7 @@ namespace serif::eos::runtime {
try {
result = invoke_evaluate_partial_derivative(std::index_sequence_for<InputTs...>{});
} catch (const EOSEvaluationError& /*e*/) {
result = std::unexpected{utils::errors::SERiFErrorCode::EOS_UNSUPPORTED_DERIVATIVE};
result = std::unexpected{utils::errors::SERiFErrorCode::EOS_ERROR};
}
} else {
result = runtimeEvaluationFailure(utils::errors::SERiFErrorCode::EOS_UNSUPPORTED_DERIVATIVE);
@@ -192,6 +316,18 @@ namespace serif::eos::runtime {
return true;
}
/**
* @brief A helper function to evaluate a partial derivative of a relation at runtime. This is used to simplify the usage of std::expected in the runtime system.
* @tparam EOS The EOS model type that supports the relation.
* @tparam OutputT The output quantity type of the relation.
* @tparam InputTs The input quantity types of the relation.
*
* @param eos The EOS model instance to use for evaluation.
* @param relation The relation to evaluate.
* @param withRespectTo The input quantity type to take the partial derivative with respect to.
* @param inputValues The input values to use for evaluation.
* @return A std::expected containing the result of the evaluation or a SERiFErrorCode if the evaluation failed.
*/
template <typename EOS, typename OutputT, typename... InputTs>
[[nodiscard]] std::expected<double, utils::errors::SERiFErrorCode> evaluateRuntimePartialDerivative (
const EOS& eos,
@@ -207,6 +343,15 @@ namespace serif::eos::runtime {
return result;
}
/**
* @brief A helper function to determine if a relation matches the given output quantity and input quantities at runtime. This is used to simplify the usage of std::expected in the runtime system.
* @tparam EOS The EOS model type that supports the relation.
* @tparam RelationT The relation type to check.
*
* @param outputQuantityID The output quantity type to check.
* @param inputValues The input values to check.
* @return True if the relation matches the given output quantity and input quantities, false otherwise.
*/
template <typename EOS, typename RelationT>
[[nodiscard]] bool runtimeRelationMatches(
const dimensions::runtime::ThermodynamicQuantityID outputQuantityID,
@@ -227,11 +372,28 @@ namespace serif::eos::runtime {
return true;
}
/**
* @brief A helper struct to dispatch runtime evaluation of relations in a catalog. This is used to simplify the usage of std::expected in the runtime system.
* @tparam EOS The EOS model type that supports the relations in the catalog.
* @tparam CatalogT The catalog type to dispatch.
*/
template <typename EOS, typename CatalogT>
struct RuntimeCatalogDispatch;
/**
* @brief A specialization of the RuntimeCatalogDispatch struct for a catalog of relations. This specialization dispatches runtime evaluation of relations in the catalog.
* @tparam EOS The EOS model type that supports the relations in the catalog.
* @tparam RelationTs The relation types in the catalog.
*/
template <typename EOS, typename...RelationTs>
struct RuntimeCatalogDispatch<EOS, relations::RelationCatalog<RelationTs...>> {
/**
* @brief A helper function to evaluate a relation in the catalog at runtime. This is used to simplify the usage of std::expected in the runtime system.
* @param object A pointer to the EOS model instance to use for evaluation.
* @param outputQuantity The output quantity type to evaluate.
* @param inputValues The input values to use for evaluation.
* @return A std::expected containing the result of the evaluation or a SERiFErrorCode if the evaluation failed.
*/
[[nodiscard]] static std::expected<double, utils::errors::SERiFErrorCode> evaluate(
const void *object,
const dimensions::runtime::ThermodynamicQuantityID& outputQuantity,
@@ -252,6 +414,14 @@ namespace serif::eos::runtime {
return result;
}
/**
* @brief A helper function to evaluate a partial derivative of a relation in the catalog at runtime. This is used to simplify the usage of std::expected in the runtime system.
* @param object A pointer to the EOS model instance to use for evaluation.
* @param outputQuantity The output quantity type to evaluate.
* @param withRespectTo The input quantity type to take the partial derivative with respect to.
* @param inputValues The input values to use for evaluation.
* @return A std::expected containing the result of the evaluation or a SERiFErrorCode if the evaluation failed.
*/
[[nodiscard]] static std::expected<double, utils::errors::SERiFErrorCode> partial_derivative(
const void *object,
const dimensions::runtime::ThermodynamicQuantityID& outputQuantity,

114
src/include/serif/eos/runtime/views.hpp
View File

@@ -1,12 +1,29 @@
#pragma once
/**
* @file views.hpp
* @author Emily M. Boudreaux
*
* @brief File containing the EOSView class. This class is used to provide a runtime view of an EOS model and its relations.
*/
#include <span>
#include "serif/eos/runtime/concepts.hpp"
namespace serif::eos::runtime {
/**
* @brief A class to provide a runtime view of an EOS model and its relations. This class is used to provide a uniform interface for evaluating relations and partial derivatives at runtime.
*/
class EOSView final {
public:
/**
* @brief Constructs an EOSView from a runtime EOS model. This constructor is used to create a view of the EOS model and its relations at runtime.
* @tparam EOS The type of the EOS model to view.
* @param eos The EOS model instance to view.
*/
template <typename EOS>
requires RuntimeEOSModel<std::remove_cvref_t<EOS>>
explicit EOSView(const EOS& eos) noexcept :
@@ -15,12 +32,31 @@ namespace serif::eos::runtime {
m_evaluate(&RuntimeEOSAdapter<std::remove_cvref_t<EOS>>::evaluate),
m_partialDerivative(&RuntimeEOSAdapter<std::remove_cvref_t<EOS>>::partial_derivative) {}
// TODO: This function can be moved to an implantation file, it may need to be to prevent ODR violations
/**
* @brief Deleted constructor to prevent constructing an EOSView from an rvalue EOS model. This is to prevent dangling references and ensure that the EOS model instance outlives the EOSView.
* @tparam EOS The type of the EOS model to view.
* @param eos The EOS model instance to view.
*/
template <typename EOS>
requires RuntimeEOSModel<std::remove_cvref_t<EOS>>
explicit EOSView(const EOS&&) = delete;
/**
* @brief Returns a span of the runtime relation descriptors for the EOS model.
* @return A span of the runtime relation descriptors.
*
* @todo Move this to the implementation file to clean things up a bit.
*/
[[nodiscard]] std::span<const dimensions::runtime::RuntimeRelationDescriptor> relations() const noexcept {
return m_relations;
}
// TODO: This function can be moved to an implantation file, it may need to be to prevent ODR violations
/**
* @brief Determines if the EOS model supports a relation with the given output quantity and input quantities at runtime. This is used to check if a relation can be evaluated at runtime.
* @param outputQuantity The output quantity to check.
* @param inputQuantities The input quantities to check.
* @return True if the relation is supported, false otherwise.
*/
[[nodiscard]] bool supports(
const dimensions::runtime::ThermodynamicQuantityID outputQuantity,
const std::span<const dimensions::runtime::ThermodynamicQuantityID> inputQuantities
@@ -28,6 +64,12 @@ namespace serif::eos::runtime {
return find_relation(outputQuantity, inputQuantities) != nullptr;
}
/**
* @brief Evaluates a relation with the given output quantity and input quantities at runtime. This is used to evaluate relations at runtime.
* @param outputQuantity The output quantity to evaluate.
* @param inputQuantities The input quantities to evaluate.
* @return A std::expected containing the result of the evaluation or a SERiFErrorCode if the evaluation failed.
*/
[[nodiscard]] std::expected<dimensions::runtime::RuntimeQuantityValue, utils::errors::SERiFErrorCode> try_evaluate(
const dimensions::runtime::ThermodynamicQuantityID outputQuantity,
const std::span<const dimensions::runtime::RuntimeQuantityValue> inputQuantities
@@ -46,6 +88,12 @@ namespace serif::eos::runtime {
return dimensions::runtime::RuntimeQuantityValue{outputQuantity, *result};
}
/**
* @brief Evaluates a relation with the given output quantity and input quantities at runtime. This is used to evaluate relations at runtime.
* @tparam OutputQuantity The output quantity to evaluate.
* @tparam InputValues The input values to evaluate.
* @return A std::expected containing the result of the evaluation or a SERiFErrorCode if the evaluation failed.
*/
template <dimensions::runtime::RuntimeIdentifiedThermodynamicQuantity OutputQuantity, dimensions::ThermodynamicQuantityValueType... InputValues>
[[nodiscard]] std::expected<dimensions::QuantityValue<OutputQuantity>, utils::errors::SERiFErrorCode> try_evaluate(
const InputValues... inputValues
@@ -71,6 +119,13 @@ namespace serif::eos::runtime {
return dimensions::QuantityValue<OutputQuantity>{result->value};
}
/**
* @brief Evaluates a partial derivative of a relation with the given output quantity and input quantities at runtime. This is used to evaluate partial derivatives at runtime.
* @param outputQuantity The output quantity to evaluate.
* @param withRespectTo The input quantity with respect to which the partial derivative is taken.
* @param inputValues The input values to evaluate.
* @return A std::expected containing the result of the evaluation or a SERiFErrorCode if the evaluation failed.
*/
[[nodiscard]] std::expected<double, utils::errors::SERiFErrorCode> try_partial_derivative(
const dimensions::runtime::ThermodynamicQuantityID outputQuantity,
const dimensions::runtime::ThermodynamicQuantityID withRespectTo,
@@ -100,8 +155,16 @@ namespace serif::eos::runtime {
return m_partialDerivative(m_object, outputQuantity, withRespectTo, inputValues);
}
/**
* @brief Evaluates a partial derivative of a relation with the given output quantity and input quantities at runtime. This is used to evaluate partial derivatives at runtime.
* @tparam OutputQuantity The output quantity to evaluate.
* @tparam InputQuantity The input quantity with respect to which the partial derivative is taken.
* @tparam InputValues The types of the input values.
* @param inputValues The input values to evaluate.
* @return A std::expected containing the result of the evaluation or a SERiFErrorCode if the evaluation failed.
*/
template <dimensions::runtime::RuntimeIdentifiedThermodynamicQuantity OutputQuantity, dimensions::runtime::RuntimeIdentifiedThermodynamicQuantity InputQuantity, dimensions::QuantityValueType... InputValues>
[[nodiscard]] std::expected<dimensions::PartialDerivative<OutputQuantity, InputQuantity>, EOSEvaluationError> try_partial_derivative(
[[nodiscard]] std::expected<dimensions::PartialDerivative<OutputQuantity, InputQuantity>, utils::errors::SERiFErrorCode> try_partial_derivative(
const InputValues... inputValues
) const {
constexpr bool inputHaveRuntimeIdentifiers = (dimensions::runtime::RuntimeIdentifiedThermodynamicQuantity<dimensions::QuantityOfT<InputValues>> && ...);
@@ -118,19 +181,26 @@ namespace serif::eos::runtime {
);
if (!result.has_value()) {
return std::unexpected<EOSEvaluationError>{result.error()};
return std::unexpected<utils::errors::SERiFErrorCode>{result.error()};
}
return dimensions::PartialDerivative<OutputQuantity, InputQuantity>{*result};
}
private: // Type aliases
/**
* @brief A type alias for a function pointer to a runtime evaluation function. This is used to store the evaluation function for the EOS model.
*/
using RuntimeEvaluateFunction = std::expected<double, utils::errors::SERiFErrorCode> (*)(
const void*,
const dimensions::runtime::ThermodynamicQuantityID&,
std::span<const dimensions::runtime::RuntimeQuantityValue>
);
/**
* @brief A type alias for a function pointer to a runtime partial derivative evaluation function. This is used to store the partial derivative evaluation function for the EOS model.
*/
using RuntimePartialDerivativeFunction = std::expected<double, utils::errors::SERiFErrorCode> (*)(
const void*,
const dimensions::runtime::ThermodynamicQuantityID&,
@@ -138,7 +208,15 @@ namespace serif::eos::runtime {
std::span<const dimensions::runtime::RuntimeQuantityValue>
);
private: // Private methods
// TODO: this can be moved to the implementation file, It may need to be to prevent ODR violations
/**
* @brief Finds a relation with the given output quantity and input quantities at runtime. This is used to find relations at runtime.
* @param outputQuantity The output quantity to find the relation for.
* @param inputQuantities The input quantities to find the relation for.
* @return A pointer to the runtime relation descriptor if found, nullptr otherwise.
*
* @todo move to implementation file to clean things up a bit.
*/
[[nodiscard]] const dimensions::runtime::RuntimeRelationDescriptor *find_relation(
const dimensions::runtime::ThermodynamicQuantityID outputQuantity,
const std::span<const dimensions::runtime::ThermodynamicQuantityID> inputQuantities
@@ -163,6 +241,12 @@ namespace serif::eos::runtime {
return nullptr;
}
/**
* @brief Validates a relation request with the given output quantity and input quantities at runtime. This is used to validate relations at runtime.
* @param outputQuantity The output quantity to validate.
* @param inputValues The input values to validate.
* @return A std::expected containing a pointer to the runtime relation descriptor if valid, or a SERiFErrorCode if invalid.
*/
[[nodiscard]] std::expected<const dimensions::runtime::RuntimeRelationDescriptor *, utils::errors::SERiFErrorCode> validate_relation_request(
const dimensions::runtime::ThermodynamicQuantityID outputQuantity,
const std::span<const dimensions::runtime::RuntimeQuantityValue> inputValues
@@ -171,11 +255,15 @@ namespace serif::eos::runtime {
bool inputCountAvailable = false;
for (const auto& descriptor : m_relations) {
if (descriptor.outputQuantity != outputQuantity || descriptor.inputQuantities.size() != inputValues.size()) {
if (descriptor.outputQuantity != outputQuantity) {
continue;
}
outputAvailable = true;
if (descriptor.inputQuantities.size() != inputValues.size()) {
continue;
}
inputCountAvailable = true;
bool matches = true;
@@ -208,6 +296,12 @@ namespace serif::eos::runtime {
);
}
/**
* @brief A helper function to handle runtime failures. This is used to simplify the usage of std::expected in the runtime system.
* @tparam Value The type of the value to return.
* @param code The SERiFErrorCode to return.
* @return A std::unexpected containing the SERiFErrorCode.
*/
template <typename Value>
[[nodiscard]] static std::expected<Value, utils::errors::SERiFErrorCode> runtime_failure(
const utils::errors::SERiFErrorCode code
@@ -216,9 +310,9 @@ namespace serif::eos::runtime {
}
private: // Private members
const void *m_object;
std::span<const dimensions::runtime::RuntimeRelationDescriptor> m_relations;
RuntimeEvaluateFunction m_evaluate;
RuntimePartialDerivativeFunction m_partialDerivative;
const void *m_object; ///< Type erased pointer to the EOS model instance.
std::span<const dimensions::runtime::RuntimeRelationDescriptor> m_relations; ///< A span of the runtime relation descriptors for the EOS model.
RuntimeEvaluateFunction m_evaluate; ///< A function pointer to the runtime evaluation function for the EOS model.
RuntimePartialDerivativeFunction m_partialDerivative; ///< A function pointer to the runtime partial derivative evaluation function for the EOS model.
};
}