Building Expressions Faster
Expression Generation
Pyomo expressions can be constructed using native binary operators in Python. For example, a sum can be created in a simple loop:
M = ConcreteModel()
M.x = Var(range(5))
s = 0
for i in range(5):
s = s + M.x[i]
Additionally, Pyomo expressions can be constructed using functions
that iteratively apply Python binary operators. For example, the
Python sum()
function can be used to replace the previous
loop:
s = sum(M.x[i] for i in range(5))
The sum()
function is both more compact and more efficient.
Using sum()
avoids the creation of temporary variables, and
the summation logic is executed in the Python interpreter while the
loop is interpreted.
Linear, Quadratic and General Nonlinear Expressions
Pyomo can express a very wide range of algebraic expressions, and there are three general classes of expressions that are recognized by Pyomo:
linear polynomials
quadratic polynomials
nonlinear expressions, including higher-order polynomials and expressions with intrinsic functions
These classes of expressions are leveraged to efficiently generate compact representations of expressions, and to transform expression trees into standard forms used to interface with solvers. Note that There not all quadratic polynomials are recognized by Pyomo; in other words, some quadratic expressions are treated as nonlinear expressions.
For example, consider the following quadratic polynomial:
s = sum(M.x[i] for i in range(5)) ** 2
This quadratic polynomial is treated as a nonlinear expression unless the expression is explicitly processed to identify quadratic terms. This lazy identification of of quadratic terms allows Pyomo to tailor the search for quadratic terms only when they are explicitly needed.
Pyomo Utility Functions
Pyomo includes several similar functions that can be used to create expressions:
prod
A function to compute a product of Pyomo expressions.
quicksum
A function to efficiently compute a sum of Pyomo expressions.
sum_product
A function that computes a generalized dot product.
prod
The prod
function is analogous to the builtin
sum()
function. Its main argument is a variable length
argument list, args
, which represents expressions that are multiplied
together. For example:
M = ConcreteModel()
M.x = Var(range(5))
M.z = Var()
# The product M.x[0] * M.x[1] * ... * M.x[4]
e1 = prod(M.x[i] for i in M.x)
# The product M.x[0]*M.z
e2 = prod([M.x[0], M.z])
# The product M.z*(M.x[0] + ... + M.x[4])
e3 = prod([sum(M.x[i] for i in M.x), M.z])
quicksum
The behavior of the quicksum
function is
similar to the builtin sum()
function, but this function often
generates a more compact Pyomo expression. Its main argument is a
variable length argument list, args
, which represents
expressions that are summed together. For example:
M = ConcreteModel()
M.x = Var(range(5))
# Summation using the Python sum() function
e1 = sum(M.x[i] ** 2 for i in M.x)
# Summation using the Pyomo quicksum function
e2 = quicksum(M.x[i] ** 2 for i in M.x)
The summation is customized based on the start
and
linear
arguments. The start
defines the initial
value for summation, which defaults to zero. If start
is
a numeric value, then the linear
argument determines how
the sum is processed:
If
linear
isFalse
, then the terms inargs
are assumed to be nonlinear.If
linear
isTrue
, then the terms inargs
are assumed to be linear.If
linear
isNone
, the first term inargs
is analyze to determine whether the terms are linear or nonlinear.
This argument allows the quicksum
function to customize the expression representation used, and
specifically a more compact representation is used for linear
polynomials. The quicksum
function can be slower than the builtin sum()
function,
but this compact representation can generate problem representations
more quickly.
Consider the following example:
M = ConcreteModel()
M.A = RangeSet(100000)
M.p = Param(M.A, mutable=True, initialize=1)
M.x = Var(M.A)
start = time.time()
e = sum((M.x[i] - 1) ** M.p[i] for i in M.A)
print("sum: %f" % (time.time() - start))
start = time.time()
generate_standard_repn(e)
print("repn: %f" % (time.time() - start))
start = time.time()
e = quicksum((M.x[i] - 1) ** M.p[i] for i in M.A)
print("quicksum: %f" % (time.time() - start))
start = time.time()
generate_standard_repn(e)
print("repn: %f" % (time.time() - start))
The sum consists of linear terms because the exponents are one. The following output illustrates that quicksum can identify this linear structure to generate expressions more quickly:
sum: 1.447861
repn: 0.870225
quicksum: 1.388344
repn: 0.864316
If start
is not a numeric value, then the quicksum
sets the initial value to start
and executes a simple loop to sum the terms. This allows the sum
to be stored in an object that is passed into the function (e.g. the linear context manager
linear_expression
).
Warning
By default, linear
is None
. While this allows
for efficient expression generation in normal cases, there are
circumstances where the inspection of the first
term in args
is misleading. Consider the following
example:
M = ConcreteModel()
M.x = Var(range(5))
e = quicksum(M.x[i] ** 2 if i > 0 else M.x[i] for i in range(5))
The first term created by the generator is linear, but the
subsequent terms are nonlinear. Pyomo gracefully transitions
to a nonlinear sum, but in this case quicksum
is doing additional work that is not useful.
sum_product
The sum_product
function supports
a generalized dot product. The args
argument contains one
or more components that are used to create terms in the summation.
If the args
argument contains a single components, then its
sequence of terms are summed together; the sum is equivalent to
calling quicksum
. If two or more components are
provided, then the result is the summation of their terms multiplied
together. For example:
M = ConcreteModel()
M.z = RangeSet(5)
M.x = Var(range(10))
M.y = Var(range(10))
# Sum the elements of x
e1 = sum_product(M.x)
# Sum the product of elements in x and y
e2 = sum_product(M.x, M.y)
# Sum the product of elements in x and y, over the index set z
e3 = sum_product(M.x, M.y, index=M.z)
The denom
argument specifies components whose terms are in
the denominator. For example:
# Sum the product of x_i/y_i
e1 = sum_product(M.x, denom=M.y)
# Sum the product of 1/(x_i*y_i)
e2 = sum_product(denom=(M.x, M.y))
The terms summed by this function are explicitly specified, so
sum_product
can identify
whether the resulting expression is linear, quadratic or nonlinear.
Consequently, this function is typically faster than simple loops,
and it generates compact representations of expressions..
Finally, note that the dot_product
function is an alias for sum_product
.