MaterialPropertyLib::Sigmoid Class Reference

Detailed Description

Sigmoid property with configurable independent variable

The sigmoid function is a smooth step function with a configurable range defined by the following formula

\[ (X_\mathrm{u} - X_\mathrm{l}) \left[1 + \exp(-k(X - X_\mathrm{c})) \right]^{-1} + X_\mathrm{l} \]

where

• \(X_\mathrm{l}\) is the lower bound (value as X -> -inf)
• \(X_\mathrm{u}\) is the upper bound (value as X -> +inf)
• \(X\) is the independent material variable (temperature, pressure, etc.)
• \(X_\mathrm{c}\) is the midpoint (a.k.a. inflection point) of the transition
• \(k\) controls the steepness of the transition; a positive \(k\) gives a monotonically increasing curve, a negative \(k\) a decreasing one.

Definition at line 31 of file Sigmoid.h.

#include <Sigmoid.h>

Inheritance diagram for MaterialPropertyLib::Sigmoid:

Collaboration diagram for MaterialPropertyLib::Sigmoid:

Public Member Functions
	Sigmoid (std::string name, double const steepness, double const midpoint, double const lower_bound, double const upper_bound, Variable const independent_variable)
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.
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
bool	derivativeVanishes (Variable const variable) const

Private Attributes
double	steepness_
double	midpoint_
double	lower_bound_
	X_l parameter (lower bound)
double	upper_bound_
	X_u parameter (upper bound)
Variable	independent_variable_

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

Sigmoid()

MaterialPropertyLib::Sigmoid::Sigmoid	(	std::string	name,
		double const	steepness,
		double const	midpoint,
		double const	lower_bound,
		double const	upper_bound,
		Variable const	independent_variable )

Definition at line 40 of file Sigmoid.cpp.

    : steepness_(steepness),
      midpoint_(midpoint),
      lower_bound_(lower_bound),
      upper_bound_(upper_bound),
      independent_variable_(independent_variable)
{
    if (lower_bound_ >= upper_bound_)
    {
        OGS_FATAL(
            "In the sigmoid property '{:s}', the lower_bound value {} must be "
            "smaller than the upper_bound value {}.",
            name, lower_bound_, upper_bound_);
    }
 
    name_ = std::move(name);
}

References independent_variable_, lower_bound_, midpoint_, MaterialPropertyLib::name, MaterialPropertyLib::Property::name_, OGS_FATAL, steepness_, and upper_bound_.

Member Function Documentation

d2Value()

PropertyDataType MaterialPropertyLib::Sigmoid::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 119 of file Sigmoid.cpp.

{
    // Only compute second derivative if both variables are the independent
    // variable.
    if (derivativeVanishes(variable1) || derivativeVanishes(variable2))
    {
        return 0.0;
    }
 
    // Compute second derivative using a numerically stable formula.
    // From f'(X) = k * f_norm * (range - f_norm) / range, we get:
    // f''(X) = k^2 * f_norm * (range - f_norm) * (range - 2*f_norm) / range^2
    // This avoids overflow/underflow issues.
    double const f = std::get<double>(value(variable_array, pos, t, unused_dt));
    auto const state = normalizedState(f, lower_bound_, upper_bound_);
    if (!state)
    {
        return 0.0;
    }
    auto const [f_normalized, range] = *state;
 
    return steepness_ * steepness_ * f_normalized * (range - f_normalized) *
           (range - 2.0 * f_normalized) / (range * range);
}

References derivativeVanishes(), lower_bound_, MaterialPropertyLib::normalizedState(), steepness_, MaterialPropertyLib::unused_dt, upper_bound_, and MaterialPropertyLib::Property::value().

derivativeVanishes()

bool MaterialPropertyLib::Sigmoid::derivativeVanishes ( Variable const variable ) const

private

True when the derivative w.r.t. variable is identically zero, i.e. variable is not the independent variable.

Definition at line 86 of file Sigmoid.cpp.

{
    // Non-zero only for the derivative w.r.t. the independent variable.
    return variable != independent_variable_;
}

References independent_variable_.

Referenced by d2Value(), and dValue().

dValue()

PropertyDataType MaterialPropertyLib::Sigmoid::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 92 of file Sigmoid.cpp.

{
    if (derivativeVanishes(variable))
    {
        return 0.0;
    }
 
    // Compute derivative using a numerically stable formula.
    // From dz/dX = k * z * (1-z) where z = 1 / (1 + exp(-k*(X-Xc))),
    // and f_norm = (upper - lower) * z, we get:
    // f'(X) = k * f_norm / (upper - lower) * ((upper - lower) - f_norm)
    // This avoids computing huge (1 + exp(-k*(X-Xc)))^2
    double const f = std::get<double>(value(variable_array, pos, t, unused_dt));
    auto const state = normalizedState(f, lower_bound_, upper_bound_);
    if (!state)
    {
        return 0.0;
    }
    auto const [f_normalized, range] = *state;
 
    return steepness_ * f_normalized * (range - f_normalized) / range;
}

References derivativeVanishes(), lower_bound_, MaterialPropertyLib::normalizedState(), steepness_, MaterialPropertyLib::unused_dt, upper_bound_, and MaterialPropertyLib::Property::value().

value()

PropertyDataType MaterialPropertyLib::Sigmoid::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 63 of file Sigmoid.cpp.

{
    double const X = std::get<double>(variable_array[independent_variable_]);
 
    // Compute sigmoid: (X_u - X_l) / (1 + exp(-k * (X - X_c))) + X_l
    double const exponent = -steepness_ * (X - midpoint_);
 
    // Exponent large positive -> sigmoid -> lower_bound; avoid exp overflow.
    if (exponent > max_exp_argument)
    {
        return lower_bound_;
    }
 
    double const sigmoid_value =
        (upper_bound_ - lower_bound_) / (1.0 + std::exp(exponent)) +
        lower_bound_;
 
    return sigmoid_value;
}

References independent_variable_, lower_bound_, MaterialPropertyLib::max_exp_argument, midpoint_, steepness_, and upper_bound_.

Member Data Documentation

independent_variable_

Variable MaterialPropertyLib::Sigmoid::independent_variable_

private

Independent material variable (temperature, pressure, etc.)

Definition at line 72 of file Sigmoid.h.

Referenced by Sigmoid(), derivativeVanishes(), and value().

lower_bound_

double MaterialPropertyLib::Sigmoid::lower_bound_

private

X_l parameter (lower bound)

Definition at line 70 of file Sigmoid.h.

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

midpoint_

double MaterialPropertyLib::Sigmoid::midpoint_

private

X_c parameter, the midpoint (a.k.a. inflection point) of the transition

Definition at line 68 of file Sigmoid.h.

Referenced by Sigmoid(), and value().

steepness_

double MaterialPropertyLib::Sigmoid::steepness_

private

\(k\) parameter (controls steepness); positive k gives an increasing curve, negative k a decreasing one. Has units of \(1/[X]\), i.e. the inverse of the independent variable's unit.

Definition at line 64 of file Sigmoid.h.

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

upper_bound_

double MaterialPropertyLib::Sigmoid::upper_bound_

private

X_u parameter (upper bound)

Definition at line 71 of file Sigmoid.h.

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

---

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

• Sigmoid.h
• Sigmoid.cpp