Mathematical Utility Methods#
There are a number of useful mathematical operations that either exhibit singularities or non-smooth behavior that can cause issues when used in equation-oriented models. This library contains smooth formulations for some of these operations which can be used to approximate these operations in models.
Users should note that these formulations involve smoothing parameters which should be tuned for their particular system. Larger values generally result in smoother behavior but greater error.
This module contains utility functions for mathematical operators of use in equation oriented models.
- idaes.core.util.math.safe_log(a, eps=0.0001)[source]#
Returns the log of max(a, eps) using the smooth_max expression. This can be used to avoid transient evaluation errors when changing a model from one state to another. This can be used when at the solution, a >> eps.
- Parameters:
a – Pyomo expression
eps – epsilon parameter for smooth max
- Returns:
approximately log(max(a, eps))
- idaes.core.util.math.safe_sqrt(a, eps=0.0001)[source]#
Returns the square root of max(a, 0) using the smooth_max expression. This can be used to avoid transient evaluation errors when changing a model from one state to another. This can be used when a at the solution is not expected to be near 0.
- Parameters:
a – Pyomo expression
eps – epsilon parameter for smooth max
- Returns:
approximately sqrt(max(a, 0))
- idaes.core.util.math.smooth_abs(a, eps=0.0001)[source]#
General function for creating an expression for a smooth minimum or maximum.
\[|a| = sqrt(a^2 + eps^2)\]- Parameters:
a – term to get absolute value from (Pyomo component, float or int)
eps – smoothing parameter (Param, float or int) (default=1e-4)
- Returns:
An expression for the smoothed absolute value operation.
- idaes.core.util.math.smooth_bound(val, lb, ub, eps=0.0001, eps_lb=None, eps_ub=None)[source]#
Returns a smooth expression that returns approximately the value of val between lb and ub, the value of ub if val > ub and the value of lb if val < lb. The expression returned is
..math:: smooth_min(smooth_max(val, lb, eps_lb), ub, eps_ub)
Example Usage This function is useful when calculating the value of a quantity with physical limitations that may not be otherwise captured. A good example of this is using a controller to manipulate a valve to maintain, for example, a set flow rate. Under some process conditions the controller may indicate the valve should be more than fully opened or closed. In this example, the smooth_bound expression can be applied to the unbounded controller output to get a bounded controller output, ensuring the valve opening stays in the feasible region, while maintaining smoothness.
- Parameters:
val – an expression for a bounded version of this value is returned
lb – lower bound
ub – lower bound
eps – smoothing parameter
eps_lb – (optional) lower bound smoothing parameter if not provided use eps
eps_ub – (optional) upper bound smoothing parameter if not provided use eps
- Returns:
smooth bounded version of val.
- Return type:
expression
- idaes.core.util.math.smooth_max(a, b, eps=0.0001)[source]#
Smooth maximum operator, using smooth_abs operator.
\[max(a, b) = 0.5*(a+b + |a-b|)\]- Parameters:
a – first term in max function
b – second term in max function
eps – smoothing parameter (Param or float, default = 1e-4)
- Returns:
An expression for the smoothed maximum operation.
- idaes.core.util.math.smooth_min(a, b, eps=0.0001)[source]#
Smooth minimum operator, using smooth_abs operator.
\[max(a, b) = 0.5*(a+b - |a-b|)\]- Parameters:
a – first term in min function
b – second term in min function
eps – smoothing parameter (Param or float, default = 1e-4)
- Returns:
An expression for the smoothed minimum operation.
- idaes.core.util.math.smooth_minmax(a, b, eps=0.0001, sense='max')[source]#
General function for creating an expression for a smooth minimum or maximum. Uses the smooth_abs operator.
\[minmax(a, b) = 0.5*(a+b +- |a-b|)\]- Parameters:
a – first term in mix or max function (Pyomo component, float or int)
b – second term in min or max function (Pyomo component, float or int)
eps – smoothing parameter (Param, float or int) (default=1e-4)
sense – ‘mim’ or ‘max’ (default = ‘max’)
- Returns:
An expression for the smoothed minimum or maximum operation.