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

# gurobipy.MVar

class MVar

  Gurobi matrix variable object. An `MVar` is a NumPy ndarray of Gurobi variables. Variables are always associated with a particular model. You typically create these objects using `Model.addMVar`.

  Many concepts, properties and methods of the MVar class lean on equivalents in NumPy’s ndarray class. For explanations of concepts like shape, dimensions, or broadcasting, we refer you to the NumPy documentation.

  You generally use `MVar` objects to build matrix expressions, typically using overloaded operators. You can build `linear matrix expressions` or `quadratic matrix expressions`:

      expr1 = A @ x
      expr2 = A @ x + B @ y + z
      expr3 = x @ A @ x + y @ B @ y

  The first two expressions are linear, while the third is quadratic.

  In the examples above (and in general), \(A\) and \(B\) can be NumPy ndarray objects or any of the sparse matrix classes defined in SciPy.sparse. Dimensions of the operands must compatible, in the usual sense of Python’s matrix multiplication operator. For example, in the expression \(A @ x\), both \(A\) and \(x\) must have at least one dimension, and their inner-most dimensions must agree. For a complete description of shape compatibility rules, we refer you to Python’s documentation

  An expression is typically then passed to `setObjective` (to set the optimization objective) or `addConstr` (to add a constraint).

  MVar objects support standard NumPy indexing and slicing. An MVar of size \(1\) can be passed in all places where gurobipy accepts a Var object.

  Variable objects have a number of attributes. Some variable attributes can only be queried, while others can also be set. Recall that the Gurobi Optimizer employs a lazy update approach, so changes to attributes don’t take effect until the next call to `Model.update`, `Model.optimize`, or `Model.write` on the associated model.

  We should point out a few things about variable attributes. Consider the `lb` attribute. Its value can be queried using `mvar.lb`. The Gurobi library ignores letter case in attribute names, so it can also be queried as `var.LB`. Attribute values are returned as a NumPy `ndarray` that has the same shape as `mvar`, where each element contains the attribute value for the corresponding element of the `MVar` object. An attribute can be set, using a standard assignment statement (e.g., `var.lb = l`), with `l` being either an `ndarray` with the appropriate shape, or a scalar which is then applied to all of the associated variables. However, as mentioned earlier, attribute modification is done in a lazy fashion, so you won’t see the effect of the change immediately. And some attributes can not be set (e.g., the `x` attribute), so attempts to assign new values to them will raise an exception.

  You can also use `MVar.getAttr`/ `MVar.setAttr` to access attributes. The attribute name can be passed to these routines as a string, or you can use the constants defined in the `GRB.Attr` class (e.g., `GRB.Attr.LB`).

  The full list of attributes can be found in the Attributes section of this document. Examples of how to query and set attributes can also be found in this section.

  copy()

    Create a copy of this MVar.

    Returns:

      The new object.

    Example:

          orig = model.addMVar(3)
          copy = orig.copy()

  diagonal(offset=0, axis1=0, axis2=1)

    Create an MVar corresponding to the variables on the specified diagonal of this MVar.

    Parameters:

      - offset – (optional) Offset of the diagonal w.r.t. the main diagonal. Values >0 mean above it, and values <0 below it

      - axis1 – (optional) Axis to be used as the first axis of the 2-D sub-MVar from which the diagonal should be taken. Defaults to 0. You need to consider this argument only for MVar objects with more than 2 dimensions.

      - axis2 – (optional) Axis to be used as the second axis of the 2-D sub-MVar from which the diagonal should be taken. Defaults to 1. You need to consider this argument only for MVar objects with more than 2 dimensions.

    Returns:

      An MVar representing the requested diagonal of this MVar.

    Example:

          x = model.addMVar((8, 8))
          diag_main = x.diagonal()  # The main diagonal of x
          diag_sup = x.diagonal(1)  # The first superdiagonal of x
          diag_sup = x.diagonal(-2)  # The second subdiagonal of x
          adiag_main = x[:, ::-1].diagonal()  # The main anti-diagonal of x

  fromlist(varlist)

    Convert a list of variables into an MVar object. The shape is inferred from the contents of the list - a list of Var objects produces a 1-D MVar object, a list of lists of Var objects produces a 2-D MVar, etc.

    Parameters:

      varlist – A list of Var objects to populate the returned MVar.

    Returns:

      MVar object corresponding to the input variables.

    Example:

          x0 = model.addVar()
          x1 = model.addVar()
          x2 = model.addVar()
          x3 = model.addVar()
          x_1d = MVar.fromlist([x0, x1, x2, x3])  # 1-D MVar
          x_2d = MVar.fromlist([[x0, x1], [x2, x3]])  # 2-D MVar

  fromvar(var)

    Convert a Var object into a 0-dimensional MVar object.

    Parameters:

      var – The variable object to populate the returned MVar.

    Returns:

      MVar object corresponding to the input variable.

    Example:

          x = model.addVar()
          x_as_mvar = MVar.fromvar(x)

  getAttr(attrname)

    Query the value of an attribute for a matrix variable.

    Raises an `AttributeError` if the requested attribute doesn’t exist or can’t be queried. Raises a `GurobiError` if there is a problem with the `MVar` object (e.g., it was removed from the model).

    The result is returned in a NumPy ndarray with the same shape as the `MVar` object.

    Parameters:

      attrname – The attribute being queried.

    Returns:

      Current values for the requested attribute.

    Example:

          print(var.getAttr(GRB.Attr.X))
          print(var.getAttr("x"))

  item()

    For an MVar that contains a single element, returns a copy of that element as a Var object. Calling this method on an MVar with more than one element will raise a ValueError.

    Returns:

      A Var object

    Example:

          x = model.addMVar((2, 2))
          x_sub = x[0, 1]  # A 0-D MVar encapsulating one Var object
          x_var = x[0, 1].item()  # The resident Var object itself

  property ndim

    The number of dimensions in this matrix variable.

    Returns:

      An int

    Example:

          x1 = model.addMVar((3,))
          print(x1.ndim)  #  "1"
          x2 = model.addMVar((1, 3))
          print(x2.ndim)  #  "2"

  reshape(shape, order='C')

    Return a copy of this MVar with the same variables, but with a new shape.

    Parameters:

      - shape – An int, or a tuple of int. The new shape should be compatible with this MVar’s shape. The special value of -1 can be passed in at one position, which then infers the length of that dimension from the overall number of Var objects in the MVar and the provided lengths of the other dimensions.

      - order – (optional) A string ‘C’ or ‘F’. Read the elements of this MVar using C-like (‘C’) or Fortran-like (‘F’) order, and write the elements into the reshaped array in this order.

    Returns:

      An MVar of requested shape

    Example:

          x = model.addMVar((2, 2))
          x_vec = x.reshape(-1, order='C')  # 1-D result, rows of x stacked
          x_vec = x.reshape(-1, order='F')  # 1-D result, columns of x stacked

  setAttr(attrname, newvalue)

    Set the value of a matrix variable attribute.

    Note that, due to our lazy update approach, the change won’t actually take effect until you update the model (using `Model.update`), optimize the model (using `Model.optimize`), or write the model to disk (using `Model.write`).

    Raises an `AttributeError` if the specified attribute doesn’t exist or can’t be set. Raises a `GurobiError` if there is a problem with the `MVar` object (e.g., it was removed from the model).

    Parameters:

      - attrname – The attribute being modified.

      - newvalue – The desired new value of the attribute. The shape must be the same as the `MVar` object. Alternatively, you can pass a scalar argument, which will automatically be promoted to have the right shape.

    Example:

          var.setAttr("ub", np.full((5,), 0)
          var.setAttr(GRB.Attr.UB, 0.0)
          var.setAttr("ub", 0.0)

  property shape

    The shape of this MVar.

    Returns:

      A tuple of int

    Example:

          x1 = model.addMVar((3,))
          print(x1.shape)  #  "(3,)"
          x2 = model.addMVar((1, 3))
          print(x2.shape)  #  "(1, 3)"

  property size

    The total number of elements in this matrix variable.

    Returns:

      An int

    Example:

          x1 = model.addMVar((3,))
          print(x1.size)  #  "3"
          x2 = model.addMVar((2, 3))
          print(x2.size)  #  "6"

  sum(axis=None)

    Sum the elements of the MVar; returns an `MLinExpr` object.

    Parameters:

      axis – An int, or None. Sum along the specified axis. If set to None, summation takes place along all axes of this MVar.

    Returns:

      An MLinExpr representing the sum.

    Example:

          x = model.addMVar((2, 2))
          sum_row = x.sum(axis=0)  # Sum along the rows of X
          sum_col = x.sum(axis=1)  # Sum along the columns of X
          sum_all = x.sum()  # Sum all variables in this MVar

  property T

    Synonymous property for transpose.

    Example:

          x = model.addMVar((4, 1))  # Resembles a "column vector"
          x_t = x.T  # Same variables, but as a "row vector"
          y = model.addMVar((3, 2))
          y_t = x.T  # Has shape (2, 3)

  tolist()

    Return the variables associated with this matrix variable as a list of individual `Var` objects.

    Returns:

      List of `Var` objects.

    Example:

          mvar = model.addMVar(5)
          varlist = mvar.tolist()
          # Do something with the Var corresponding to mvar[3]
          print(varlist[3])

  transpose()

    Transpose this MVar; create a new MVar object by reversing the order of the original MVar’s axes. For 1-D MVar objects, this routine simply returns a copy of the original MVar.

    Returns:

      An MVar object representing the transpose.

    Example:

          x = model.addMVar((4, 1))  # Resembles a "column vector"
          x_t = x.transpose()  # Same variables, but as a "row vector"
          y = model.addMVar((3, 2))
          y_t = x.transpose()  # Has shape (2, 3)

  property nl

    Returns an `MNLExpr` representing this matrix variable. Using this property is as advanced technique and is not required in the vast majority of cases. See More control over expression creation for further details.

Help and Feedback

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