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 from common.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 is False.

  • 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). If flag is False, then a nonlinear term has been found, and list is None. Otherwise, list is a list of tuples: (coef, value). If value is None, then this represents a constant term with value coef. Otherwise, value is a variable object, and coef 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 is None. Default is True.

  • 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.

Parameters:
  • expr – The root node of an expression tree.

  • component_types (set or list) – A set of class types that will be matched during the search.

Yields:

Each node that is found.

pyomo.core.expr.identify_variables(expr, include_fixed=True)[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 to True.

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._GeneralVarData) – If specified, this function will return the derivative with respect to wrt. wrt is normally a _GeneralVarData, but could also be a _ParamData. wrt and wrt_list cannot both be specified.

  • wrt_list (list of pyomo.core.base.var._GeneralVarData) – 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.

byObject

maps (object id) to (string label)

Type:

dict

bySymbol

maps (string label) to (object)

Type:

dict

alias[source]

maps (string label) to (object)

Type:

dict

default_labeler

used to compute a string label from an object