gurobipy.MQuadExpr#
- class MQuadExpr#
Gurobi quadratic matrix expression object. Quadratic matrix expressions are used to build quadratic objective functions and quadratic constraints. They are temporary objects that typically have short lifespans.
You generally build quadratic matrix expressions using overloaded operators. For example, if
x
is anMVar
object andA
is a 2-D matrix (dense or sparse), thenx @ A @ x
andx @ x
are bothMQuadExpr
objects. Arithmetic operations supported onMQuadExpr
objects are addition, subtraction (e.g.,expr = x @ A @ x - y @ B @ y
), and multiplication by a constant (e.g.expr = 2 * x @ A @ y
).An
MQuadExpr
object has ashape
representing its dimensions, asize
that counts the total number of elements, and anndim
that gives the number of dimensions. These properties lean on their counterparts in NumPy’s ndarray class.When working with
MQuadExpr
objects, you need to make sure that the operands’ shapes are compatible. The first step in building anMQuadExpr
is often to build anMLinExpr
(e.g., |expr = x @ A @ x|), so we refer you to the discussion ofMLinExpr
shape rules first. Rules for other operations onMQuadExpr
objects are generally similar to those forMLinExpr
objects, and both classes follow NumPy rules, so we refer you to the NumPy documentation for details.The full list of overloaded operators on
MQuadExpr
objects is as follows:+
,+=
,-
,-=
,*
, and*=
. In Python parlance, we’ve defined the followingQuadExpr
functions:__add__
,__radd__
,__iadd__
,__sub__
,__rsub__
,__isub__
,__neg__
,__mul__
,__rmul__
, and__imul__
.We’ve also overloaded the comparison operators (
==
,<=
, and>=
), to make it easier to build constraints from quadratic expressions.- clear()#
Reset this expression to all zeros.
- Example:
expr = 2 * model.addMVar(3)**2 + 1 expr.clear() # All three entries are reset to constant 0.0
- copy()#
Create a copy of a quadratic matrix expression.
- Returns:
Copy of expression object.
- Example:
orig = x @ Q @ x + p @ x copy = orig.copy() copy += 2.0 # Leaves 'orig' untouched
- getValue()#
Compute the value of a quadratic matrix expression using the current solution.
- Returns:
Value of expression as an ndarary.
- Example:
qexpr = x @ A @ x model.addConstr(qexpr == 0) model.optimize() val = qexpr.getValue()
- item()#
For an MQuadExpr that contains a single element, returns a copy of that element as a QuadExpr object. Calling this method on an MQuadExpr with more than one element will raise a ValueError.
- Returns:
A QuadExpr object
- Example:
mqe = 2 * model.addMVar((2, 2))** + 1 mqe_sub = mqe[0, 1] # A 0-D MQuadExpr encapsulating one QuadExpr object mqe_qe = mqe[0, 1].item() # A copy of the resident QuadExpr object
- property ndim#
The number of dimensions in this expression.
- Returns:
An int
- Example:
expr1 = 2 * model.addMVar((3,))**2 + 1 print(expr1.ndim) # "1" expr2 = 2 * model.addMVar((1, 3))**2 + 1 print(expr2.ndim) # "2"
- property shape#
The shape of this expression.
- Returns:
A tuple of int
- Example:
expr1 = 2 * model.addMVar((3,))**2 + 1 print(expr1.shape) # "(3,)" expr2 = 2 * model.addMVar((1, 3))**2 + 1 print(expr2.shape) # "(1, 3)"
- property size#
The total number of elements in this expression.
- Returns:
An int
- Example:
expr1 = 2 * model.addMVar((3,))**2 + 1 print(expr1.size) # "3" expr2 = 2 * model.addMVar((2, 3))**2 + 1 print(expr2.size) # "6"
- sum(axis=None)#
Sum the elements of this MQuadExpr; returns an
MQuadExpr
object.- Parameters:
axis – An int, or None. Sum along the specified axis. If set to None, summation takes place along all axes of this MQuadExpr.
- Returns:
An MQuadExpr representing the sum.
- Example:
expr = 2 * model.addMVar((2, 2))**2 - 1 sum_row = expr.sum(axis=0) # Sum along the rows sum_col = expr.sum(axis=1) # Sum along the columns sum_all = expr.sum() # Sum all elements, result is 0-D
- zeros(shape)#
Construct an all-zero MQuadExpr object of given shape.
- Parameters:
shape – An int, or tuple of int. The requested shape.
- Returns:
An MQuadExpr, initialized to zero.
- Example:
mle = gp.MQuadExpr.zeros(3) x = model.addMVar(3) mle += 2 * x**2
- __eq__()#
Overloads the
==
operator, creating aTempConstr
object that captures an equality constraint. The result is typically immediately passed toModel.addConstr
.- Returns:
A
TempConstr
object.- Example:
m.addConstr(x @ Q @ y == 1)
- __ge__(arg)#
Overloads the
>=
operator, creating aTempConstr
object that captures an inequality constraint. The result is typically immediately passed toModel.addConstr
.- Returns:
A
TempConstr
object.- Example:
m.addConstr(x @ Q @ y >= 1)
- __getitem__()#
Index or slice this MQuadExpr.
- Returns:
An
MQuadExpr
object.- Example:
mqe = 2 * m.addMVar((2,2))**2 col0 = mqe[:, 0] # The first column of mqe, 1-D result elmt = mqe[1, 0] # The element at position (1, 0), 0-D result
You can index and slice MQuadExpr objects like you would index NumPy’s ndarray, and indexing behavior is straightforward to understand if you only read from the returned object. When you write to the returned object, be aware some kinds of indexing return NumPy views on the indexed expression (e.g., slices), while others result in copies being returned (e.g., fancy indexing). Here is an example:
- Example:
mqe = 2 * m.addMVar(4)**2 leading_part_1 = mqe[:2] leading_part_2 = mqe[[0,1]] leading_part_1 += 99 # This modifies mqe, too leading_part_2 += 1 # This doesn't modify mqe
If you are unsure about any of these concepts and want to avoid any risk of accidentally writing back to the indexed object, you should always combine indexing with the
copy
method.- Example:
expr = 2 * model.addMVar((2,2))**2 + 1 first_col = expr[:, 0].copy() first_col =+ 1 # Leaves expr untouched
- __le__()#
Overloads the
<=
operator, creating aTempConstr
object that captures an inequality constraint. The result is typically immediately passed toModel.addConstr
.- Returns:
A
TempConstr
object.- Example:
m.addConstr(x @ Q @ y <= 1)
- __setitem__()#
Assign into this MQuadExpr.
- Example:
mqe = 2 * model.addMVar((2,2))**2 v = model.addVar() w = model.addVar() mqe[:] = v + 1 # Overwrite mqe with four independent copies of 'v+1' mqe[1, 1] = w*w # Overwrite the entry at position (1, 1) of mqe with 'w**2'
Note that assignment into an existing MQuadExpr always entails multiple data copies and is less efficient than building matrix expressions through operations with MVar objects.