Utilities to Manage and Analyze Expressions
Functions
- pyomo.core.expr.expression_to_string(expr, verbose=None, labeler=None, smap=None, compute_values=False)[source]
Return a string representation of an expression.
- Parameters:
expr (ExpressionBase) – The root node of an expression tree.
verbose (bool) – If
True
, then the output is a nested functional form. Otherwise, the output is an algebraic expression. Default is retrieved fromcommon.TO_STRING_VERBOSE
labeler (Callable) – If specified, this labeler is used to generate the string representation for leaves (Var / Param objects) in the expression.
smap (SymbolMap) – If specified, this
SymbolMap
is used to cache labels.compute_values (bool) – If
True
, then parameters and fixed variables are evaluated before the expression string is generated. Default isFalse
.Returns – A string representation for the expression.
- pyomo.core.expr.decompose_term(expr)[source]
A function that returns a tuple consisting of (1) a flag indicating whether the expression is linear, and (2) a list of tuples that represents the terms in the linear expression.
- Parameters:
expr (expression) – The root node of an expression tree
- Returns:
A tuple with the form
(flag, list)
. Ifflag
isFalse
, then a nonlinear term has been found, andlist
isNone
. Otherwise,list
is a list of tuples:(coef, value)
. Ifvalue
isNone
, then this represents a constant term with valuecoef
. Otherwise,value
is a variable object, andcoef
is the numeric coefficient.
- pyomo.core.expr.clone_expression(expr, substitute=None)[source]
A function that is used to clone an expression.
Cloning is equivalent to calling
copy.deepcopy
with no Block scope. That is, the expression tree is duplicated, but no Pyomo components (leaf nodes or named Expressions) are duplicated.- Parameters:
expr – The expression that will be cloned.
substitute (dict) – A dictionary mapping object ids to objects. This dictionary has the same semantics as the memo object used with
copy.deepcopy
. Defaults to None, which indicates that no user-defined dictionary is used.
- Returns:
The cloned expression.
- pyomo.core.expr.evaluate_expression(exp, exception=True, constant=False)[source]
Evaluate the value of the expression.
- Parameters:
expr – The root node of an expression tree.
exception (bool) – A flag that indicates whether exceptions are raised. If this flag is
False
, then an exception that occurs while evaluating the expression is caught and the return value isNone
. Default isTrue
.constant (bool) – If True, constant expressions are evaluated and returned but nonconstant expressions raise either FixedExpressionError or NonconstantExpressionError (default=False).
- Returns:
A floating point value if the expression evaluates normally, or
None
if an exception occurs and is caught.
- pyomo.core.expr.identify_components(expr, component_types)[source]
A generator that yields a sequence of nodes in an expression tree that belong to a specified set.
- pyomo.core.expr.identify_variables(expr, include_fixed=True, named_expression_cache=None)[source]
A generator that yields a sequence of variables in an expression tree.
- Parameters:
expr – The root node of an expression tree.
include_fixed (bool) – If
True
, then this generator will yield variables whose value is fixed. Defaults toTrue
.
- Yields:
Each variable that is found.
- pyomo.core.expr.differentiate(expr, wrt=None, wrt_list=None, mode=Modes.reverse_numeric)[source]
Return derivative of expression.
This function returns the derivative of expr with respect to one or more variables. The type of the return value depends on the arguments wrt, wrt_list, and mode. See below for details.
- Parameters:
expr (pyomo.core.expr.numeric_expr.NumericExpression) – The expression to differentiate
wrt (pyomo.core.base.var.VarData) – If specified, this function will return the derivative with respect to wrt. wrt is normally a VarData, but could also be a ParamData. wrt and wrt_list cannot both be specified.
wrt_list (list of pyomo.core.base.var.VarData) – If specified, this function will return the derivative with respect to each element in wrt_list. A list will be returned where the values are the derivatives with respect to the corresponding entry in wrt_list.
mode (pyomo.core.expr.calculus.derivatives.Modes) –
Specifies the method to use for differentiation. Should be one of the members of the Modes enum:
- Modes.sympy:
The pyomo expression will be converted to a sympy expression. Differentiation will then be done with sympy, and the result will be converted back to a pyomo expression. The sympy mode only does symbolic differentiation. The sympy mode requires exactly one of wrt and wrt_list to be specified.
- Modes.reverse_symbolic:
Symbolic differentiation will be performed directly with the pyomo expression in reverse mode. If neither wrt nor wrt_list are specified, then a ComponentMap is returned where there will be a key for each node in the expression tree, and the values will be the symbolic derivatives.
- Modes.reverse_numeric:
Numeric differentiation will be performed directly with the pyomo expression in reverse mode. If neither wrt nor wrt_list are specified, then a ComponentMap is returned where there will be a key for each node in the expression tree, and the values will be the floating point values of the derivatives at the current values of the variables.
- Returns:
res – The value or expression of the derivative(s)
- Return type:
float,
NumericExpression
,ComponentMap
, or list
Classes
- class pyomo.core.expr.symbol_map.SymbolMap(labeler=None)[source]
A class for tracking assigned labels for modeling components.
Symbol maps are used, for example, when writing problem files for input to an optimizer.
Warning
A symbol map should never be pickled. This class is typically constructed by solvers and writers, and it may be owned by models.
Note
We should change the API to not use camelcase.
- default_labeler
used to compute a string label from an object