MaterialPropertyLib::Function Class Reference

Detailed Description

A function property defined by mathematical expression. For the evaluation of the expressions the exprtk library is used. In the expressions all variables defined in MaterialPropertyLib::Variable enum, t for time, x,y,z for the spatial position are supported, and curves from the <curves> section can be called using their names. A curve is a single argument function and can be used in an expression like curveA(sin(t)).

The evaluation is thread-safe for OpenMP by using per-thread storage.

Definition at line 34 of file Function.h.

#include <Function.h>

Inheritance diagram for MaterialPropertyLib::Function:

Collaboration diagram for MaterialPropertyLib::Function:

Classes
struct	Implementation

Public Member Functions
	Function (std::string name, std::vector< std::string > const &value_string_expressions, std::vector< std::pair< std::string, std::vector< std::string > > > const &dvalue_string_expressions, std::vector< D2ValueConfig > const &d2value_string_expressions, std::map< std::string, std::unique_ptr< MathLib::PiecewiseLinearInterpolation > > const &curves)
PropertyDataType	value (VariableArray const &variable_array, ParameterLib::SpatialPosition const &pos, double const t, double const dt) const override
PropertyDataType	dValue (VariableArray const &variable_array, Variable const variable, ParameterLib::SpatialPosition const &pos, double const t, double const dt) const override
PropertyDataType	d2Value (VariableArray const &variable_array, Variable const variable1, Variable const variable2, ParameterLib::SpatialPosition const &pos, double const t, double const dt) const override
	Default implementation: 2nd derivative of any constant property is zero.
	~Function ()
Public Member Functions inherited from MaterialPropertyLib::Property
virtual	~Property ()
virtual PropertyDataType	initialValue (ParameterLib::SpatialPosition const &pos, double const t) const
virtual PropertyDataType	value () const
virtual PropertyDataType	value (VariableArray const &variable_array, VariableArray const &variable_array_prev, ParameterLib::SpatialPosition const &pos, double const t, double const dt) const
virtual PropertyDataType	dValue (VariableArray const &variable_array, VariableArray const &variable_array_prev, Variable const variable, ParameterLib::SpatialPosition const &pos, double const t, double const dt) const
virtual void	setProperties (std::vector< std::unique_ptr< Phase > > const &phases)
	Default implementation:
void	setScale (std::variant< Medium *, Phase *, Component * > scale)
template<typename T>
T	initialValue (ParameterLib::SpatialPosition const &pos, double const t) const
template<typename T>
T	value () const
template<typename T>
T	value (VariableArray const &variable_array, VariableArray const &variable_array_prev, ParameterLib::SpatialPosition const &pos, double const t, double const dt) const
template<typename T>
T	value (VariableArray const &variable_array, ParameterLib::SpatialPosition const &pos, double const t, double const dt) const
template<typename T>
T	dValue (VariableArray const &variable_array, VariableArray const &variable_array_prev, Variable const variable, ParameterLib::SpatialPosition const &pos, double const t, double const dt) const
template<typename T>
T	dValue (VariableArray const &variable_array, Variable const variable, ParameterLib::SpatialPosition const &pos, double const t, double const dt) const
template<typename T>
T	d2Value (VariableArray const &variable_array, Variable const &variable1, Variable const &variable2, ParameterLib::SpatialPosition const &pos, double const t, double const dt) const

Private Member Functions
std::variant< Function::Implementation< 2 > *, Function::Implementation< 3 > * >	getImplementationForDimensionOfVariableArray (VariableArray const &variable_array) const

Private Attributes
std::unique_ptr< Implementation< 2 > >	impl2_
std::unique_ptr< Implementation< 3 > >	impl3_
std::vector< Variable >	required_variables_enum_
	Variables used in the exprtk expressions.

Additional Inherited Members
Protected Attributes inherited from MaterialPropertyLib::Property
std::string	name_
PropertyDataType	value_
	The single value of a property.
PropertyDataType	dvalue_
std::variant< Medium *, Phase *, Component * >	scale_

Constructor & Destructor Documentation

Function()

MaterialPropertyLib::Function::Function	(	std::string	name,
		std::vector< std::string > const &	value_string_expressions,
		std::vector< std::pair< std::string, std::vector< std::string > > > const &	dvalue_string_expressions,
		std::vector< D2ValueConfig > const &	d2value_string_expressions,
		std::map< std::string, std::unique_ptr< MathLib::PiecewiseLinearInterpolation > > const &	curves )

Definition at line 560 of file Function.cpp.

{
    name_ = std::move(name);
 
    // Validate the d2value blocks once, before the per-thread/per-dimension
    // Implementations are built: each unordered {v1,v2} pair may appear at
    // most once, and each block must carry one expression per value component.
    {
        std::vector<VariablePair> seen_pairs;
        for (auto const& [vname1, vname2, exprs] : d2value_string_expressions)
        {
            VariablePair const pair{convertStringToVariable(vname1),
                                    convertStringToVariable(vname2)};
            if (ranges::contains(seen_pairs, pair))
            {
                OGS_FATAL(
                    "Function property '{}': duplicate d2value block for "
                    "variable pair '{}'/'{}'. Each unordered pair may "
                    "appear at most once.",
                    name_, vname1, vname2);
            }
            seen_pairs.push_back(pair);
 
            if (exprs.size() != value_string_expressions.size())
            {
                OGS_FATAL(
                    "Function property '{}': the number of d2Value expressions "
                    "({:d}) for variables '{:s}'/'{:s}' does not match the "
                    "number of value expressions ({:d}).",
                    name_, exprs.size(), vname1, vname2,
                    value_string_expressions.size());
            }
        }
    }
 
    // Collect variables from all expressions (value, dvalue, and d2value) so
    // the symbol table is complete even when a variable appears only in a
    // derivative.
    auto all_exprs = value_string_expressions;
    for (auto const& [_, exprs] : dvalue_string_expressions)
    {
        all_exprs.insert(all_exprs.end(), exprs.begin(), exprs.end());
    }
    for (auto const& [_1, _2, exprs] : d2value_string_expressions)
    {
        all_exprs.insert(all_exprs.end(), exprs.begin(), exprs.end());
    }
    auto const expression_symbol_names =
        ParameterLib::collectVariables(all_exprs);
 
    required_variables_enum_ =
        expression_symbol_names |
        ranges::views::filter(
            [&curves](std::string const& s)
            {
                return !ParameterLib::isBuiltinSymbol(s) && !curves.contains(s);
            }) |
        ranges::views::transform([](std::string const& s)
                                 { return convertStringToVariable(s); }) |
        ranges::to<std::vector>;
 
    int const num_threads = BaseLib::getNumberOfThreads();
 
    impl2_ = std::make_unique<Implementation<2>>(
        num_threads, expression_symbol_names, required_variables_enum_,
        value_string_expressions, dvalue_string_expressions,
        d2value_string_expressions, curves);
    impl3_ = std::make_unique<Implementation<3>>(
        num_threads, expression_symbol_names, required_variables_enum_,
        value_string_expressions, dvalue_string_expressions,
        d2value_string_expressions, curves);
}

References ParameterLib::collectVariables(), MaterialPropertyLib::convertStringToVariable(), BaseLib::getNumberOfThreads(), impl2_, impl3_, ParameterLib::isBuiltinSymbol(), MaterialPropertyLib::name, MaterialPropertyLib::Property::name_, OGS_FATAL, and required_variables_enum_.

~Function()

MaterialPropertyLib::Function::~Function ( )

default

Member Function Documentation

d2Value()

PropertyDataType MaterialPropertyLib::Function::d2Value ( VariableArray const & variable_array, Variable const variable1, Variable const variable2, ParameterLib::SpatialPosition const & pos, double const t, double const dt ) const

overridevirtual

Default implementation: 2nd derivative of any constant property is zero.

This virtual method will compute the second derivative of a property with respect to the given variables pv1 and pv2.

Reimplemented from MaterialPropertyLib::Property.

Definition at line 723 of file Function.cpp.

{
    return std::visit(
        [&](auto&& impl_ptr)
        {
            auto& thread_data = impl_ptr->per_thread_data[currentThreadId(
                name_, impl_ptr->per_thread_data.size())];
            auto const it = ranges::find(thread_data.d2value_expressions,
                                         VariablePair{variable1, variable2},
                                         &D2ValueExpression::variables);
 
            if (it == thread_data.d2value_expressions.end())
            {
                OGS_FATAL(
                    "Requested second derivative with respect to variables "
                    "'{:s}'/'{:s}' not provided for Function-type property "
                    "'{:s}'.",
                    variable_enum_to_string[static_cast<int>(variable1)],
                    variable_enum_to_string[static_cast<int>(variable2)],
                    name_);
            }
 
            return thread_data.evaluate(impl_ptr->non_scalar_variables,
                                        variable_array, pos, t,
                                        it->expressions);
        },
        getImplementationForDimensionOfVariableArray(variable_array));
}

References MaterialPropertyLib::currentThreadId(), getImplementationForDimensionOfVariableArray(), MaterialPropertyLib::Property::name_, OGS_FATAL, MaterialPropertyLib::variable_enum_to_string, and MaterialPropertyLib::D2ValueExpression::variables.

dValue()

PropertyDataType MaterialPropertyLib::Function::dValue ( VariableArray const & variable_array, Variable const variable, ParameterLib::SpatialPosition const & pos, double const t, double const dt ) const

overridevirtual

This virtual method will compute the property derivative value based on the variables that are passed as arguments with the default implementation using empty variables array for the previous time step.

The default implementation of this method only returns the property value derivative without altering it.

Reimplemented from MaterialPropertyLib::Property.

Definition at line 695 of file Function.cpp.

{
    return std::visit(
        [&](auto&& impl_ptr)
        {
            auto& thread_data = impl_ptr->per_thread_data[currentThreadId(
                name_, impl_ptr->per_thread_data.size())];
            auto const it = ranges::find_if(thread_data.dvalue_expressions,
                                            [&variable](auto const& v)
                                            { return v.first == variable; });
 
            if (it == end(thread_data.dvalue_expressions))
            {
                OGS_FATAL(
                    "Requested derivative with respect to the variable {:s} "
                    "not provided for Function-type property {:s}.",
                    variable_enum_to_string[static_cast<int>(variable)], name_);
            }
 
            return thread_data.evaluate(impl_ptr->non_scalar_variables,
                                        variable_array, pos, t, it->second);
        },
        getImplementationForDimensionOfVariableArray(variable_array));
}

References MaterialPropertyLib::currentThreadId(), getImplementationForDimensionOfVariableArray(), MaterialPropertyLib::Property::name_, OGS_FATAL, and MaterialPropertyLib::variable_enum_to_string.

getImplementationForDimensionOfVariableArray()

std::variant< Function::Implementation< 2 > *, Function::Implementation< 3 > * > MaterialPropertyLib::Function::getImplementationForDimensionOfVariableArray ( VariableArray const & variable_array ) const

private

Definition at line 642 of file Function.cpp.

{
    if (variable_array.is2D())
    {
        return impl2_.get();
    }
    if (variable_array.is3D())
    {
        return impl3_.get();
    }
 
    OGS_FATAL(
        "Variable array has vectors for 2 and 3 dimensions simultaneously. "
        "Mixed dimensions cannot be dealt within Function evaluation.");
}

References impl2_, impl3_, MaterialPropertyLib::VariableArray::is2D(), MaterialPropertyLib::VariableArray::is3D(), and OGS_FATAL.

Referenced by d2Value(), dValue(), and value().

value()

PropertyDataType MaterialPropertyLib::Function::value ( VariableArray const & variable_array, ParameterLib::SpatialPosition const & pos, double const t, double const dt ) const

overridevirtual

This virtual method will compute the property value based on the variables that are passed as arguments with the default implementation using empty variables array for the previous time step.

Reimplemented from MaterialPropertyLib::Property.

Definition at line 679 of file Function.cpp.

{
    return std::visit(
        [&](auto&& impl_ptr)
        {
            auto& thread_data = impl_ptr->per_thread_data[currentThreadId(
                name_, impl_ptr->per_thread_data.size())];
            return thread_data.evaluate(impl_ptr->non_scalar_variables,
                                        variable_array, pos, t,
                                        thread_data.value_expressions);
        },
        getImplementationForDimensionOfVariableArray(variable_array));
}

References MaterialPropertyLib::currentThreadId(), getImplementationForDimensionOfVariableArray(), and MaterialPropertyLib::Property::name_.

Member Data Documentation

impl2_

std::unique_ptr<Implementation<2> > MaterialPropertyLib::Function::impl2_

private

Definition at line 71 of file Function.h.

Referenced by Function(), and getImplementationForDimensionOfVariableArray().

impl3_

std::unique_ptr<Implementation<3> > MaterialPropertyLib::Function::impl3_

private

Definition at line 72 of file Function.h.

Referenced by Function(), and getImplementationForDimensionOfVariableArray().

required_variables_enum_

std::vector<Variable> MaterialPropertyLib::Function::required_variables_enum_

private

Variables used in the exprtk expressions.

Definition at line 79 of file Function.h.

Referenced by Function().

---

The documentation for this class was generated from the following files:

• Function.h
• Function.cpp