Pyomo expression trees are not composed of Python objects from a single class hierarchy. Consequently, Pyomo relies on duck typing to ensure that valid expression trees are created.
Most Pyomo expression trees have the following form
- Interior nodes are objects that inherit from the
ExpressionBaseclass. These objects typically have one or more child nodes. Linear expression nodes do not have child nodes, but they are treated as interior nodes in the expression tree because they references other leaf nodes.
- Leaf nodes are numeric values, parameter components and variable components, which represent the inputs to the expresion.
Expression classes typically represent unary and binary operations. The following table describes the standard operators in Python and their associated Pyomo expression class:
|Operation||Python Syntax||Pyomo Class|
Additionally, there are a variety of other Pyomo expression classes that capture more general logical relationships, which are summarized in the following table:
Expression objects are immutable. Specifically, the list of arguments to an expression object (a.k.a. the list of child nodes in the tree) cannot be changed after an expression class is constructed. To enforce this property, expression objects have a standard API for accessing expression arguments:
args- a class property that returns a generator that yields the expression arguments
arg(i)- a function that returns the
nargs()- a function that returns the number of expression arguments
Developers should never use the
_args_ property directly!
The semantics for the use of this data has changed since earlier
versions of Pyomo. For example, in some expression classes the
nargs() may not equal
Expression trees can be categorized in four different ways:
- constant expressions - expressions that do not contain numeric constants and immutable parameters.
- mutable expressions - expressions that contain mutable parameters but no variables.
- potentially variable expressions - expressions that contain variables, which may be fixed.
- fixed expressions - expressions that contain variables, all of which are fixed.
These three categories are illustrated with the following example:
m = ConcreteModel() m.p = Param(default=10, mutable=False) m.q = Param(default=10, mutable=True) m.x = Var() m.y = Var(initialize=1) m.y.fixed = True
The following table describes four different simple expressions that consist of a single model component, and it shows how they are categorized:
|not potentially variable||True||True||False||False|
Expressions classes contain methods to test whether an expression tree is in each of these categories. Additionally, Pyomo includes custom expression classes for expression trees that are not potentially variable. These custom classes will not normally be used by developers, but they provide an optimization of the checks for potentially variability.
Special Expression Classes
The following classes are exceptions to the design principles describe above.
Named expressions allow for changes to an expression after it has
been constructed. For example, consider the expression
M = ConcreteModel() M.v = Var() M.w = Var() M.e = Expression(expr=2*M.v) f = M.e + 3 # f == 2*v + 3 M.e += M.w # f == 2*v + 3 + w
f is an immutable expression, whose definition is
fixed, a sub-expressions is the named expression
expressions have a mutable value. In other words, the expression
that they point to can change. Thus, a change to the value of
M.e changes the expression tree for any expression that includes
the named expression.
The named expression classes are not implemented as sub-classes
This reflects design constraints related to the fact that these
are modeling components that belong to class hierarchies other
than the expression class hierarchy, and Pyomo’s design prohibits
the use of multiple inheritance for these classes.
Pyomo includes a special expression class for linear expressions.
LinearExpression provides a compact
description of linear polynomials. Specifically, it includes a
constant and two lists for coefficients and
This expression object does not have arguments, and thus it is treated as a leaf node by Pyomo visitor classes. Further, the expression API functions described above do not work with this class. Thus, developers need to treat this class differently when walking an expression tree (e.g. when developing a problem transformation).
Pyomo does not have a binary sum expression class. Instead,
it has an
n-ary summation class,
SumExpression. This expression class
treats sums as
n-ary sums for efficiency reasons; many large
optimization models contain large sums. But note tht this class
maintains the immutability property described above. This class
shares an underlying list of arguments with other
SumExpression objects. A particular
object owns the first
n arguments in the shared list, but
different objects may have different values of
This class acts like a normal immutable expression class, and the API described above works normally. But direct access to the shared list could have unexpected results.
Finally, Pyomo includes several mutable expression classes that are private. These are not intended to be used by users, but they might be useful for developers in contexts where the developer can appropriately control how the classes are used. Specifically, immutability eliminates side-effects where changes to a sub-expression unexpectedly create changes to the expression tree. But within the context of model transformations, developers may be able to limit the use of expressions to avoid these side-effects. The following mutable private classes are available in Pyomo:
Pyomo clear semantics regarding what is considered a valid leaf and interior node.
The following classes are valid interior nodes:
- Subclasses of
- Classes that that are duck typed to match the API of the
ExpressionBaseclass. For example, the named expression class
The following classes are valid leaf nodes:
- Members of
nonpyomo_leaf_types, which includes standard numeric data types like
long, as well as numeric data types defined by numpy and other commonly used packages. This set also includes
NonNumericValue, which is used to wrap non-numeric arguments to the
- Parameter component classes like
_ParamData, which arise in expression trees when the parameters are declared as mutable. (Immutable parameters are identified when generating expressions, and they are replaced with their associated numeric value.)
- Variable component classes like
_GeneralVarData, which often arise in expression trees. <pyomo.core.expr.current.pyomo5_variable_types>`.
In some contexts the
LinearExpression class can be treated
as an interior node, and sometimes it can be treated as a leaf.
This expression object does not have any child arguments, so
nargs() is zero. But this expression references variables
and parameters in a linear expression, so in that sense it does
not represent a leaf node in the tree.
Pyomo defines several context managers that can be used to declare the form of expressions, and to define a mutable expression object that efficiently manages sums.
object is a context manager that can be used to declare a linear sum. For
example, consider the following two loops:
M = ConcreteModel() M.x = Var(range(5)) s = 0 for i in range(5): s += M.x[i] with linear_expression() as e: for i in range(5): e += M.x[i]
The first apparent difference in these loops is that the value of
s is explicitly initialized while
e is initialized when the
context manager is entered. However, a more fundamental difference
is that the expression representation for
s differs from
Each term added to
s results in a new, immutable expression.
By contrast, the context manager creates a mutable expression
e. This difference allows for both (a) a
more efficient processing of each sum, and (b) a more compact
representation for the expression.
The difference between
is the underlying representation that each supports. Note that
both of these are instances of context manager classes. In
singled-threaded applications, these objects can be safely used to
construct different expressions with different context declarations.
Finally, note that these context managers can be passed into the
method for the
quicksum function. For example:
M = ConcreteModel() M.x = Var(range(5)) M.y = Var(range(5)) with linear_expression() as e: quicksum((M.x[i] for i in M.x), start=e) quicksum((M.y[i] for i in M.y), start=e)
This sum contains terms for
M.y[i]. The syntax
in this example is not intuitive because the sum is being stored
We do not generally expect users or developers to use these
context managers. They are used by the
sum_product functions to accelerate expression
generation, and there are few cases where the direct use of
these context managers would provide additional utility to users