The tupledict class
The final important preliminary we would like to discuss is the
tupledict class. This is a custom sub-class of the Python
dict class that allows you to efficiently work with subsets of
Gurobi variable objects. To be more specific, you can use the
sum and prod methods on a tupledict object to
easily and concisely build linear expressions. The keys for a
tupledict are stored as a tuplelist, so the same
select syntax can be used to choose subsets of entries.
Specifically, by associating a tuple with each Gurobi variable, you
can efficiently create expressions that contain a subset of matching
variables. For example, using the sum method on a
tupledict object, you could easily build an expression that
captures the sum over all Gurobi variables for which the first field
of the corresponding tuple is equal to 3 (using x.sum(3, '*')).
While you can directly build your own tupledict, the Gurobi
interface provides an addVars method that adds one Gurobi
decision variable to the model for each tuple in the input
argument(s) and returns the result as a tupledict.
Let us give a simple example. We'll begin by
constructing a list of tuples, and then we'll create a set of Gurobi
variables that are indexed using this list:
gurobi> l = list([(1, 2), (1, 3), (2, 3), (2, 4)]) gurobi> d = model.addVars(l, name="d") gurobi> model.update()The
addVars method will create variables d(1,2),
d(1,3), d(2,3), and d(2,4). Note that the
name argument is used to name the resulting variables, but it
only gives the prefix for the name - the names are subscripted by the
tuple keys (so the variables would be named d[1,2],
d[1,3], etc.). The final call to update synchronizes
certain internal data structures; this detail can be safely ignored
for now.
You can then use this tupledict to build linear expressions.
For example, you could do:
gurobi> sum(d.select(1, '*'))The
select method returns a list of Gurobi variables where the
first field of the associated tuple is 1. The Python sum
statement then creates a linear expression that captures the sum of
these variables. In this case, that expression would be
d(1,2) + d(1,3). Similarly, sum(d.select('*', 3)) would
give d(1,3) + d(2,3). As with a tuplelist, you use a
'*' string to indicate that any value is acceptable in that
position in the tuple.
The tupledict class includes a method that simplifies the
above. Rather than sum(d.select('*', 3)), you can use
d.sum('*', 3) instead.
The tupledict class also includes a prod method, for
cases where you need to build a linear expression with coefficients that aren't all
1.0. Coefficients are provided through a dict argument.
They are indexed using the same tuples as the tupledict. For
example, given a dict named coeff with two entries:
coeff(1,2) = 5 and coeff(2,3) = 7, a call to
d.prod(coeff) would give the expression
5 d(1,2) + 7 d(2,3). You can also include a filter, so
d.prod(coeff, 2, '*') would give just 7 d(2,3).
Note that tupledict is a sub-class of dict, so you can
use the standard dict methods to access or modify a
tupledict:
gurobi> print(d[1,3]) <gurobi.Var d[1,3]> gurobi> d[3, 4] = 0.3 gurobi> print(d[3, 4]) 0.3 gurobi> print(d.values()) dict_values([<gurobi.Var d[1,2]>, 0.3, <gurobi.Var d[1,3]>, <gurobi.Var d[2,3]>, <gurobi.Var d[2,4]>])In our upcoming network flow example, once we've built a
tupledict that contains a variable for each valid
commodity-source-destination combination on the network (we'll call it
flows), we can create a linear expression that captures the
total flow on all arcs that empty into a specific destination city as
follows:
gurobi> inbound = flows.sum('*', '*', 'New York')
We now present an example that illustrates the use of all of the concepts discussed so far.
