Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# gurobipy.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()

Help and Feedback

Press `/` or click to search this documentation | Gurobi website | Gurobi community forum
Go to other Gurobi documentation | Gurobi download | Contact support