gurobipy.MNLExpr#

classMNLExpr#

Gurobi matrix-friendly nonlinear expression object. AnMNLExpr stores adense array ofNLExpr objects, and makes it possible to formulatea set of nonlinear constraints in Python using a single mathematicalexpression.

You will generally build anMNLExpr by starting fromMVarobjects and applying Python operators,nonlinear functions, or a combination of both. AnMNLExpr will only becreated for matrix expressions that cannot be captured by anMLinExpr orMQuadExpr. Specifically, formulating amatrix expression whereany element of the matrix is not a polynomial ofdegree at most 2 will result in anMNLExpr.

AnMNLExpr 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 ontheir counterparts in NumPy’sndarray class.

When working withMLinExpr objects, you need to make sure that theoperands’ shapes are compatible. For matrix multiplication, we follow therules of Python’s matrix multiplication operator: both operands need to haveat least one dimension, and their inner dimensions must agree. For moreinformation we refer you to Python’s documentation. Other binary operationssuch as addition and multiplication are straightforward to understand if bothoperands have the same shape: the operation is applied point wise on thematching indices. For operands that have different shapes, the arithmeticfollows NumPy’s broadcasting rules. We refer you to the NumPy documentationfor more information.

The following example lists the object types and shapes of variousexpressions constructed fromMVar objects:

fromgurobipyimportnlfunc...x=model.addMVar((3,),name="x")# MVar, shape (3,)y=model.addMVar((3,3),name="y")# MVar, shape (3,3)z=model.addMVar((3,3),name="z")# MVar, shape (3,3)expr1=2.0*x# MLinExpr, shape (3,)expr2=2.0*x*y# MQuadExpr, shape (3,3)expr3=2.0*x*y*z# MNLExpr, shape (3,3)expr4=x/y# MNLExpr, shape (3,3)expr5=nlfunc.sin(x)# MNLExpr, shape (3,)

Nonlinear matrix expressions are used to build nonlinear matrix generalconstraints. They are typically temporary objects which are passedimmediately to eitherModel.addConstr orModel.addGenConstrNL to add a group of constraints to the model.Such constraints are always equality constraints with aresultant variableon the left side of the expression. In Python code these constraints can beadded using either method. Using theMVar objects from theprevious example:

# Add the constraint z_ij = sqrt(x_j + y_ij) for each (i, j)model.addConstr(z==nlfunc.sqrt(x+y))# Add the constraint z_ij = x_j / y_ij for each (i, j)model.addGenConstrNL(z,x/y)

Nonlinear Inequality Constraints

It is not possible to use<= or>= operators to specify nonlinearinequality constraints usingNLExpr objects. However, you can formulatean equivalent constraint by creating a bounded resultant variable. Forexample, the following code constrains that\(log(x_i) \le 1\) for\(i \in {0, 1, 2, 3}\):

x=model.addMVar((4,))res=model.addMVar(x.shape,lb=-GRB.INFINITY,ub=1.0)model.addGenConstrNL(res,nlfunc.log(x))

More control over expression creation

If you want more control over the expression trees generated, you canexplicitly opt in to the nonlinear world using thenlproperty ofMVar objects. This is considered advanced usage. Inthe vast majority of cases, you do not need to consider how a nonlinearexpression is represented internally.

MVar.nl returns anMNLExpr object holding a matrix ofexpression trees, each of which represent a single variable. Any arithmeticoperations involving that object will also result in anMNLExpr:

x=model.addMVar((2,2))# MVar, shape (2,2)expr1=x+1.0# MLinExpr, shape (2,2)expr2=x.nl# MNLExpr, shape (2,2)expr3=x.nl+1.0# MNLExpr, shape (2,2)

The implications are subtle, but can have an impact on how a constraint ishandled by the solver. For example, the following two constraints representthe same set of expressions\((x_i + y_i)^2\) but have a differentinternal representation in the solver:

x=model.addMVar((5,))y=model.addMVar((5,))z=model.addMVar((5,))c1=model.addGenConstrNL(z,(x-y)**2)c2=model.addGenConstrNL(z,(x.nl-y.nl)**2)

Specifically, the first case captures quadratic expressions in expanded form\(x_i^2 - 2 x_i y_i + y_i^2\). The second case captures a nonlinearexpression with\(x_i - y_i\) as a node in the expression tree which isexplicitly squared.

Domain restrictions of operators

Some subtleties arise from certain arithmetic operators not being applicableto the whole domain that an operand may have (e.g., division by zero). Referto the additional information for thedivide operator and thepower operator for allthe details.

propertyshape#

The shape of this expression.

Returns:

A tuple of int

propertysize#

The total number of elements in this expression.

Returns:

An int

propertyndim#

The number of dimensions in this expression.

Returns:

An int

sum(axis=None)#

Sum the elements of thisMNLExpr; returns anMNLExprobject.

Parameters:

axis – An int, orNone. Sum along the specified axis. Ifset toNone, summation takes place along all axes of thisMNLExpr.

Returns:

AnMNLExpr representing the sum.

item()#

For anMNLExpr that contains a single element, returns a copyof that element as anNLExpr object. Calling thismethod on anMNLExpr with more than one element will raise aValueError.

Returns:

AnNLExpr object