Python API - tupledict#

class tupledict#

Gurobi tuple dict. This is a sub-class of the Python dict class that is designed to efficiently support a usage pattern that is quite common when building optimization models. In particular, a tupledict is a Python dict where the keys represent variable indices, and the values are typically Gurobi Var objects. Objects of this class make it easier to build linear expressions on sets of Gurobi variables, using tuplelist.select() syntax and semantics.

You typically build a tupledict by calling Model.addVars. Once you’ve created a tupledict d, you can use d.sum() to create a linear expression that captures the sum of the variables in the tupledict. You can also use a command like d.sum(1, '*', 5) to create a sum over a subset of the variables in d. Assuming the keys for the tupledict are tuples containing three fields, this statement would create a linear expression that captures the sum over all variables in d whose keys contain a 1 in the first field of the tuple and a 5 in the third field (the '*' character is a wildcard that indicates that any value is acceptable in that field). You can also use d.prod(coeff) to create a linear expression where the coefficients are pulled from the dictionary coeff. For example, if d(1,2,5) contains variable x and coeff(1,2,5) is 2.0, then the resulting expression would include term \(2.0*x\).

To access the members of a tupledict, you can use standard dict indexing. For example, d[1,2] returns the value associated with tuple (1,2).

Note that a tupledict key must be a tuple of scalar values (int, float, string, …). Thus, you can use (1, 2.0, 'abc') as a key, but you can’t use ((1, 2.0), 'abc').

Note that tupledict objects build and maintain a set of internal data structures to support efficient select operations. If you wish to reclaim the storage associated with these data structures, you can call the clean function.

tupledict(args, kwargs)#

tupledict constructor. Arguments are identical to those of a Python dict constructor.

Note that you will typically use Model.addVars to build a tupledict.

Parameters:

  • args – Positional arguments.

  • kwargs – Named arguments.

Returns:

A tupledict object.

Example:
d = gp.tupledict([((1,2), 'onetwo'), ((1,3), 'onethree'), ((2,3), 'twothree')])
print(d[1,2]) # prints 'onetwo'
select(pattern)#

Returns a list containing the values associated with keys that match the specified tuple pattern. The pattern should provide one value for each field in the key tuple. A '*' value indicates that any value is accepted in that field.

Without arguments, this method returns a list of all values in the tupledict.

Parameters:

pattern – Pattern to match for a key tuple.

Example:
d = gp.tupledict([((1,2), 'onetwo'), ((1,3), 'onethree'), ((2,3), 'twothree')])
print(d.select())       # prints ['onetwo', 'onethree', 'twothree']
print(d.select(1, '*')) # prints ['onetwo', 'onethree']
print(d.select('*', 3)) # prints ['onethree', 'twothree']
print(d.select(1, 3))   # prints ['onethree']
sum(pattern)#

Returns the sum of the values associated with keys that match the specified pattern. If the values are Gurobi Var objects, the result is a LinExpr. The pattern should provide one value for each field in the key tuple. A '*' value indicates that any value is accepted in that field.

Without arguments, this method returns the sum of all values in the tupledict.

Parameters:

pattern – Pattern to match for a key tuple.

Example:
x = m.addVars([(1,2), (1,3), (2,3)])
expr = x.sum()       # LinExpr: x[1,2] + x[1,3] + x[2,3]
expr = x.sum(1, '*') # LinExpr: x[1,2] + x[1,3]
expr = x.sum('*', 3) # LinExpr: x[1,3] + x[2,3]
expr = x.sum(1, 3)   # LinExpr: x[1,3]
prod(coeff, pattern)#

Returns a linear expression that contains one term for each tuple that is present in both the tupledict and the coeff argument; coeff should be a Python dict object that maps tuples to coefficient values. For example, x.prod(coeff) would contain term 2.0*var if x[1,2] = var and coeff[1,2] = 2.0.

Parameters:

  • coeff – Python dict that maps tuples to coefficients.

  • pattern – Pattern to match for a key tuple.

Example:
x = m.addVars([(1,2), (1,3), (2,3)])
coeff = dict([((1,2), 2.0), ((1,3), 2.1), ((2,3), 3.3)])
expr = x.prod(coeff) # LinExpr: 2.0 x[1,2] + 2.1 x[1,3] + 3.3 x[2,3]
expr = x.prod(coeff, '*', 3) # LinExpr: 2.1 x[1,3] + 3.3 x[2,3]
clean()#

Discards internal data structure associated with a tupledict object. Note that calling this routine won’t affect the contents of the tupledict. It only affects the memory used and the performance of later calls to select.

Example:
d.clean()