MATLAB API - Common Arguments#
Most common arguments in the Gurobi MATLAB interface are
MATLAB struct
variables, each having multiple fields.
Several of these fields are optional. Note that you refer to a field of
a struct variable by adding a period to the end of the variable name,
followed by the name of the field. For example, model.A
refers to field A
of variable model
.
The model argument#
Model variables store optimization problems (as described in the problem statement).
Models can be built in a number of ways. You can populate the
appropriate fields of the model
struct using standard
MATLAB routines. You can also read a model from a file, using
gurobi_read
. A few API functions
(gurobi_feasrelax
and gurobi_relax
) also
return models.
Note that all vector fields within the model
variable must be dense
vectors except for the linear part of the quadratic constraints and
INDICATOR general constraints, all matrix fields must be sparse
matrices, and all strings, names, etc. must be char
arrays.
The following is an enumeration of all of the fields of the model
argument that Gurobi will take into account when optimizing the model:
Commonly used fields#
- A
The linear constraint matrix.
- obj (optional)
The linear objective vector (the
c
vector in the problem statement). When present, you must specify one value for each column ofA
. When absent, each variable has a default objective coefficient of 0.- sense (optional)
The senses of the linear constraints. Allowed values are
=
,<
, or>
. You must specify one value for each row ofA
, or a single value to specify that all constraints have the same sense. When absent, all senses default to<
.- rhs (optional)
The right-hand side vector for the linear constraints (\(b\) in the problem statement). You must specify one value for each row of
A
. When absent, the right-hand side vector defaults to the zero vector.- lb (optional)
The lower bound vector. When present, you must specify one value for each column of
A
. When absent, each variable has a default lower bound of 0.- ub (optional)
The upper bound vector. When present, you must specify one value for each column of
A
. When absent, the variables have infinite upper bounds.- vtype (optional)
The variable types. This vector is used to capture variable integrality constraints. Allowed values are
C
(continuous),B
(binary),I
(integer),S
(semi-continuous), orN
(semi-integer). Binary variables must be either 0 or 1. Integer variables can take any integer value between the specified lower and upper bounds. Semi-continuous variables can take any value between the specified lower and upper bounds, or a value of zero. Semi-integer variables can take any integer value between the specified lower and upper bounds, or a value of zero. When present, you must specify one value for each column ofA
, or a single value to specify that all variables have the same type. When absent, each variable is treated as being continuous. Refer to the variable section of the reference manual for more information on variable types.- modelsense (optional)
The optimization sense. Allowed values are
min
(minimize) ormax
(maximize). When absent, the default optimization sense is minimization.- modelname (optional)
The name of the model. The name appears in the Gurobi log, and when writing a model to a file.
- objcon (optional)
The constant offset in the objective function (\(\mathrm{alpha}\) in the problem statement).
- varnames (optional)
The variable names vector. A cell array. When present, each element of this vector defines the name of a variable. You must specify a name for each column of
A
.- constrnames (optional)
The constraint names vector. A cell array. When present, each element of the vector defines the name of a constraint. You must specify a name for each row of
A
.
Quadratic objective and constraint fields#
- Q (optional)
The quadratic objective matrix. When present,
Q
must be a square matrix whose row and column counts are equal to the number of columns inA
.- quadcon (optional)
The quadratic constraints. A struct array. When present, each element in
quadcon
defines a single quadratic constraint: \(x^TQc\, x + q^Tx \le \mathrm{beta}\).The
Qc
matrix must be a square matrix whose row and column counts are equal to the number of columns ofA
. There are two options to store the matrix: (i) inmodel.quadcon(i).Qc
as a sparse matrix; (ii) through three dense vectorsmodel.quadcon(i).Qrow
,model.quadcon(i).Qcol
, andmodel.quadcon(i).Qval
specifying the matrix in triple format, with row indices, column indices, and values, respectively.The optional
q
vector defines the linear terms in the constraint. It can be a dense vector specifying a value for each column ofA
or a sparse vector (sparse n-by-1 matrix). It is stored inmodel.quadcon(i).q
.The scalar
beta
is stored inmodel.quadcon(i).rhs
. It defines the right-hand side value for the constraint.The optional
sense
string defines the sense of the quadratic constraint. Allowed values are<
,=
or>
. If not present, the default sense is<
. It is stored inmodel.quadcon(i).sense
.The optional
name
string defines the name of the quadratic constraint. It is stored inmodel.quadcon(i).name
.
SOS constraint fields#
- sos (optional)
The Special Ordered Set (SOS) constraints. A struct array. When present, each entry in
sos
defines a single SOS constraint. A SOS constraint can be of type 1 or 2. The type of SOS constraint \(i\) is specified viamodel.sos(i).type
. A type 1 SOS constraint is a set of variables where at most one variable in the set may take a value other than zero. A type 2 SOS constraint is an ordered set of variables where at most two variables in the set may take non-zero values. If two take non-zeros values, they must be contiguous in the ordered set. The members of an SOS constraint are specified by placing their indices in vectormodel.sos(i).index
. Weights associated with SOS members are provided in vectormodel.sos(i).weight
. Please refer to SOS Constraints section in the reference manual for details on SOS constraints.
Multi-objective fields#
- multiobj (optional)
Multi-objective specification for the model. A struct array. When present, each entry in
multiobj
defines a single objective of a multi-objective problem. Please refer to the Multiple Objectives section in the reference manual for more details on multi-objective optimization. Each objective \(i\) may have the following fields:- objn
Specified via
model.multiobj(i).objn
. This is the i-th objective vector.- objcon (optional)
Specified via
model.multiobj(i).objcon
. If provided, this is the i-th objective constant. The default value is 0.- priority (optional)
Specified via
model.multiobj(i).priority
. If provided, this value is the hierarchical priority for this objective. The default value is 0.- weight (optional)
Specified via
model.multiobj(i).weight
. If provided, this value is the multiplier used when aggregating objectives. The default value is 1.0.- reltol (optional)
Specified via
model.multiobj(i).reltol
. If provided, this value specifies the relative objective degradation when doing hierarchical multi-objective optimization. The default value is 0.- abstol (optional)
Specified via
model.multiobj(i).abstol
. If provided, this value specifies the absolute objective degradation when doing hierarchical multi-objective optimization. The default value is 0.- name (optional)
Specified via
model.multiobj(i).name
. If provided, this string specifies the name of the i-th objective function.
Note that when multiple objectives are present, the
result.objval
field that is returned in the result of an optimization call will be a vector of the same length asmodel.multiobj
.A multi-objective model can’t have other objectives. Thus, combining
model.multiobj
with any ofmodel.obj
,model.objcon
,model.pwlobj
, ormodel.Q
is an error.
Computing an IIS#
When computing an Irreducible Inconsistent Subsystem (IIS) for an infeasible model, additional model attributes for variable bounds, linear constraints, quadratic constraints and general constraints may be set in order to indicate whether the corresponding entity should be explicitly included or excluded from the IIS:
- iislbforce (optional)
array of length equal to the number of variables. The value of
model.iislbforce(i)
specifies the IIS force attribute for the lower bound of the \(i\)-th variable.- iisubforce (optional)
array of length equal to the number of variables. The value of
model.iisubforce(i)
specifies the IIS force attribute for the upper bound of the \(i\)-th variable.- iisconstrforce (optional)
array of length equal to the number of constraints. The value of
model.iisconstrforce(i)
specifies the IIS force attribute for the \(i\)-th constraint.- iisqconstrforce (optional)
array of length equal to the number of quadratic constraints. The value of
model.iisqconstrforce(i)
specifies the IIS force attribute for the \(i\)-th quadratic constraint.- iisgenconstrforce (optional)
array of length equal to the number of general constraints. The value of
model.iisgenconstrforce(i)
specifies the IIS force attribute for the \(i\)-th general constraint.
Possible values for all five attribute arraysfrom above are: \(-1\) to let the algorithm decide, \(0\) to exclude the corresponding entity from the IIS, and \(1\) to always include the corresponding entity in the IIS.
Note that setting this attribute to 0 may make the resulting subsystem feasible (or consistent), which would then make it impossible to construct an IIS. Trying anyway will result in a IIS_NOT_INFEASIBLE error. Similarly, setting this attribute to 1 may result in an IIS that is not irreducible. More precisely, the system would only be irreducible with respect to the model elements that have force values of -1 or 0.
General constraint fields#
The struct arrays described below are used to add general constraints to a model. Please refer to the General Constraints section in the reference manual for additional details on general constraints.
- genconmax (optional)
A struct array. When present, each entry in
genconmax
defines a MAX general constraint of the form\[x[\mathrm{resvar}] = \max\left\{\mathrm{con},x[j]:j\in\mathrm{vars}\right\}\]Each entry may have the following fields:
- resvar
Specified via
model.genconmax(i).resvar
. Index of the variable in the left-hand side of the constraint.- vars
Specified via
model.genconmax(i).vars
, it is a vector of indices of variables in the right-hand side of the constraint.- con (optional)
Specified via
model.genconmax(i).con
. When present, specifies the constant on the left-hand side. Default value is \(-\infty\).- name (optional)
Specified via
model.genconmax(i).name
. When present, specifies the name of the \(i\)-th MAX general constraint.
- genconmin (optional)
A struct array. When present, each entry in
genconmax
defines a MIN general constraint of the form\[x[\mathrm{resvar}] = \min\left\{\mathrm{con},x[j]:j\in\mathrm{vars}\right\}\]Each entry may have the following fields:
- resvar
Specified via
model.genconmin(i).resvar
. Index of the variable in the left-hand side of the constraint.- vars
Specified via
model.genconmin(i).vars
, it is a vector of indices of variables in the right-hand side of the constraint.- con (optional)
Specified via
model.genconmin(i).con
. When present, specifies the constant on the left-hand side. Default value is \(\infty\).- name (optional)
Specified via
model.genconmin(i).name
. When present, specifies the name of the \(i\)-th MIN general constraint.
- genconabs (optional)
A struct array. When present, each entry in
genconmax
defines an ABS general constraint of the form\[x[\mathrm{resvar}] = \vert x[\mathrm{argvar}]\vert\]Each entry may have the following fields:
- resvar
Specified via
model.genconabs(i).resvar
. Index of the variable in the left-hand side of the constraint.- argvar
Specified via
model.genconabs(i).argvar
. Index of the variable in the right-hand side of the constraint.- name (optional)
Specified via
model.genconabs(i).name
. When present, specifies the name of the \(i\)-th ABS general constraint.
- genconand (optional)
A struct array. When present, each entry in
genconand
defines an AND general constraint of the form\[x[\mathrm{resvar}] = \mathrm{and}\{x[i]:i\in\mathrm{vars}\}\]Each entry may have the following fields:
- resvar
Specified via
model.genconand(i).resvar
. Index of the variable in the left-hand side of the constraint.- vars
Specified via
model.genconand(i).vars
, it is a vector of indices of variables in the right-hand side of the constraint.- name (optional)
Specified via
model.genconand(i).name
. When present, specifies the name of the \(i\)-th AND general constraint.
- genconor (optional)
A struct array. When present, each entry in
genconor
defines an OR general constraint of the form\[x[\mathrm{resvar}] = \mathrm{or}\{x[i]:i\in\mathrm{vars}\}\]Each entry may have the following fields:
- resvar
Specified via
model.genconor(i).resvar
. Index of the variable in the left-hand side of the constraint.- vars
Specified via
model.genconor(i).vars
, it is a vector of indices of variables in the right-hand side of the constraint.- name (optional)
Specified via
model.genconor(i).name
. When present, specifies the name of the \(i\)-th OR general constraint.
- genconnorm (optional)
A struct array. When present, each entry in
genconnorm
defines a NORM general constraint of the form\[x[\mathrm{resvar}] = \mathrm{norm}(x[i]:i\in\mathrm{vars}, \mathrm{which})\]Each entry may have the following fields:
- resvar
Specified via
model.genconnorm(i).resvar
. Index of the variable in the left-hand side of the constraint.- vars
Specified via
model.genconnorm(i).vars
, it is a vector of indices of variables in the right-hand side of the constraint.- which
Specified via
model.genconnorm(i).which
. Specifies which p-norm to use. Possible values are 0, 1, 2 and \(\infty\).- name (optional)
Specified via
model.genconnorm(i).name
. When present, specifies the name of the \(i\)-th NORM general constraint.
- genconind (optional)
A struct array. When present, each entry in
genconind
defines an INDICATOR general constraint of the form\[x[\mathrm{binvar}] = \mathrm{binval}\Rightarrow\sum\left( x[j]\cdot\mathrm{a}[j]\right) \ \mathrm{sense} \ \mathrm{rhs}\]This constraint states that when the binary variable \(x[\mathrm{binvar}]\) takes the value
binval
then the linear constraint \(\sum\left(x[\mathrm{vars}[j]]\cdot\mathrm{val}[j]\right) \ \mathrm{sense} \ \mathrm{rhs}\) must hold. Note thatsense
is one of=
,<
, or>
for equality (\(=\)), less than or equal (\(\leq\)) or greater than or equal (\(\geq\)) constraints. Each entry may have the following fields:- binvar
Specified via
model.genconind(i).binvar
. Index of the implicating binary variable.- binval
Specified via
model.genconind(i).binval
. Value for the binary variable that forces the following linear constraint to be satisfied. It can be either 0 or 1.- a
Specified via
model.genconind(i).a
. Vector of coefficients of variables participating in the implied linear constraint. You can specify a value fora
for each column ofA
(dense vector) or pass a sparse vector (sparse n-by-1 matrix).- sense
Specified via
model.genconind(i).sense
. Sense of the implied linear constraint. Must be one of=
,<
, or>
.- rhs
Specified via
model.genconind(i).rhs
. Right-hand side value of the implied linear constraint.- name (optional)
Specified via
model.genconind(i).name
. When present, specifies the name of the \(i\)-th INDICATOR general constraint.
- genconpwl (optional)
A struct array. When present, each entry in
genconpwl
defines a piecewise-linear constraint of the form\[x[\mathrm{yvar}] = f(x[\mathrm{xvar}])\]The breakpoints for \(f\) are provided as arguments. Refer to the description of piecewise-linear objectives for details of how piecewise-linear functions are defined
Each entry may have the following fields:
- xvar
Specified via
model.genconpwl(i).xvar
. Index of the variable in the right-hand side of the constraint.- yvar
Specified via
model.genconpwl(i).yvar
. Index of the variable in the left-hand side of the constraint.- xpts
Specified via
model.genconpwl(i).xpts
. Specifies the \(x\) values for the points that define the piecewise-linear function. Must be in non-decreasing order.- ypts
Specified via
model.genconpwl(i).ypts
. Specifies the \(y\) values for the points that define the piecewise-linear function.- name (optional)
Specified via
model.genconpwl(i).name
. When present, specifies the name of the \(i\)-th piecewise-linear general constraint.
- genconpoly (optional)
A struct array. When present, each entry in
genconpoly
defines a polynomial function constraint of the form\[x[\mathrm{yvar}] = p_0 x[\mathrm{xvar}]^d + p_1 x[\mathrm{xvar}]^{d-1} + ... + p_{d-1} x[\mathrm{xvar}] + p_{d}\]A piecewise-linear approximation of the function is added to the model. The details of the approximation are controlled using the following four attributes (or using the parameters with the same names): FuncPieces, FuncPieceError, FuncPieceLength, and FuncPieceRatio. Alternatively, the function can be treated as a nonlinear constraint by setting the attribute FuncNonlinear. For details, consult the General Constraint discussion.
Each entry may have the following fields:
- xvar
Specified via
model.genconpoly(i).xvar
. Index of the variable in the right-hand side of the constraint.- yvar
Specified via
model.genconpoly(i).yvar
. Index of the variable in the left-hand side of the constraint.- p
Specified via
model.genconpoly(i).p
. Specifies the coefficients for the polynomial function (starting with the coefficient for the highest power). If \(x^d\) is the highest power term, a dense vector of length \(d+1\) is returned.- name (optional)
Specified via
model.genconpoly(i).name
. When present, specifies the name of the \(i\)-th polynomial function constraint.- funcpieces (optional)
Specified via
model.genconpoly(i).funcpieces
. When present, specifies the FuncPieces attribute of the \(i\)-th polynomial function constraint.- funcpiecelength (optional)
Specified via
model.genconpoly(i).funcpiecelength
. When present, specifies the FuncPieceLength attribute of the \(i\)-th polynomial function constraint.- funcpieceerror (optional)
Specified via
model.genconpoly(i).funcpieceerror
. When present, specifies the FuncPieceError attribute of the \(i\)-th polynomial function constraint.- funcpieceratio (optional)
Specified via
model.genconpoly(i).funcpieceratio
. When present, specifies the FuncPieceRatio attribute of the \(i\)-th polynomial function constraint.- funcnonlinear (optional)
Specified via
model.genconpoly(i).funcnonlinear
. When present, specifies the FuncNonlinear attribute of the \(i\)-th polynomial function constraint.
- genconexp (optional)
A struct array. When present, each entry in
genconexp
defines the natural exponential function constraint of the form\[x[\mathrm{yvar}] = \mathrm{exp}(x[\mathrm{xvar}])\]A piecewise-linear approximation of the function is added to the model. The details of the approximation are controlled using the following four attributes (or using the parameters with the same names): FuncPieces, FuncPieceError, FuncPieceLength, and FuncPieceRatio. Alternatively, the function can be treated as a nonlinear constraint by setting the attribute FuncNonlinear. For details, consult the General Constraint discussion.
Each entry may have the following fields:
- xvar
Specified via
model.genconexp(i).xvar
. Index of the variable in the right-hand side of the constraint.- yvar
Specified via
model.genconexp(i).yvar
. Index of the variable in the left-hand side of the constraint.- name (optional)
Specified via
model.genconexp(i).name
. When present, specifies the name of the \(i\)-th natural exponential function constraint.- funcpieces (optional)
Specified via
model.genconexp(i).funcpieces
. When present, specifies the FuncPieces attribute of the \(i\)-th natural exponential function constraint.- funcpiecelength (optional)
Specified via
model.genconexp(i).funcpiecelength
. When present, specifies the FuncPieceLength attribute of the \(i\)-th natural exponential function constraint.- funcpieceerror (optional)
Specified via
model.genconexp(i).funcpieceerror
. When present, specifies the FuncPieceError attribute of the \(i\)-th natural exponential function constraint.- funcpieceratio (optional)
Specified via
model.genconexp(i).funcpieceratio
. When present, specifies the FuncPieceRatio attribute of the \(i\)-th natural exponential function constraint.- funcnonlinear (optional)
Specified via
model.genconexp(i).funcnonlinear
. When present, specifies the FuncNonlinear attribute of the \(i\)-th natural exponential function constraint.
- genconexpa (optional)
A struct array. When present, each entry in
genconexpa
defines an exponential function constraint of the form\[x[\mathrm{yvar}] = \mathrm{a}^{x[\mathrm{xvar}]}\]A piecewise-linear approximation of the function is added to the model. The details of the approximation are controlled using the following four attributes (or using the parameters with the same names): FuncPieces, FuncPieceError, FuncPieceLength, and FuncPieceRatio. Alternatively, the function can be treated as a nonlinear constraint by setting the attribute FuncNonlinear. For details, consult the General Constraint discussion.
Each entry may have the following fields:
- xvar
Specified via
model.genconexpa(i).xvar
. Index of the variable in the right-hand side of the constraint.- yvar
Specified via
model.genconexpa(i).yvar
. Index of the variable in the left-hand side of the constraint.- a
Specified via
model.genconexpa(i).a
. Specifies the base of the exponential function \(a > 0\).- name (optional)
Specified via
model.genconexpa(i).name
. When present, specifies the name of the \(i\)-th exponential function constraint.- funcpieces (optional)
Specified via
model.genconexpa(i).funcpieces
. When present, specifies the FuncPieces attribute of the \(i\)-th exponential function constraint.- funcpiecelength (optional)
Specified via
model.genconexpa(i).funcpiecelength
. When present, specifies the FuncPieceLength attribute of the \(i\)-th exponential function constraint.- funcpieceerror (optional)
Specified via
model.genconexpa(i).funcpieceerror
. When present, specifies the FuncPieceError attribute of the \(i\)-th exponential function constraint.- funcpieceratio (optional)
Specified via
model.genconexpa(i).funcpieceratio
. When present, specifies the FuncPieceRatio attribute of the \(i\)-th exponential function constraint.- funcnonlinear (optional)
Specified via
model.genconexpa(i).funcnonlinear
. When present, specifies the FuncNonlinear attribute of the \(i\)-th exponential function constraint.
- genconlog (optional)
A struct array. When present, each entry in
genconlog
defines the natural logarithmic function constraint of the form\[x[\mathrm{yvar}] = \mathrm{log}(x[\mathrm{xvar}])\]A piecewise-linear approximation of the function is added to the model. The details of the approximation are controlled using the following four attributes (or using the parameters with the same names): FuncPieces, FuncPieceError, FuncPieceLength, and FuncPieceRatio. Alternatively, the function can be treated as a nonlinear constraint by setting the attribute FuncNonlinear. For details, consult the General Constraint discussion.
Each entry may have the following fields:
- xvar
Specified via
model.genconlog(i).xvar
. Index of the variable in the right-hand side of the constraint.- yvar
Specified via
model.genconlog(i).yvar
. Index of the variable in the left-hand side of the constraint.- name (optional)
Specified via
model.genconlog(i).name
. When present, specifies the name of the \(i\)-th natural logarithmic function constraint.- funcpieces (optional)
Specified via
model.genconlog(i).funcpieces
. When present, specifies the FuncPieces attribute of the \(i\)-th natural logarithmic function constraint.- funcpiecelength (optional)
Specified via
model.genconlog(i).funcpiecelength
. When present, specifies the FuncPieceLength attribute of the \(i\)-th natural logarithmic function constraint.- funcpieceerror (optional)
Specified via
model.genconlog(i).funcpieceerror
. When present, specifies the FuncPieceError attribute of the \(i\)-th natural logarithmic function constraint.- funcpieceratio (optional)
Specified via
model.genconlog(i).funcpieceratio
. When present, specifies the FuncPieceRatio attribute of the \(i\)-th natural logarithmic function constraint.- funcnonlinear (optional)
Specified via
model.genconlog(i).funcnonlinear
. When present, specifies the FuncNonlinear attribute of the \(i\)-th natural logarithmic function constraint.
- genconloga (optional)
A struct array. When present, each entry in
genconloga
defines a logarithmic function constraint of the form\[x[\mathrm{yvar}] = \mathrm{log}(x[\mathrm{xvar}])\setminus\mathrm{log}(a)\]A piecewise-linear approximation of the function is added to the model. The details of the approximation are controlled using the following four attributes (or using the parameters with the same names): FuncPieces, FuncPieceError, FuncPieceLength, and FuncPieceRatio. Alternatively, the function can be treated as a nonlinear constraint by setting the attribute FuncNonlinear. For details, consult the General Constraint discussion.
Each entry may have the following fields:
- xvar
Specified via
model.genconloga(i).xvar
. Index of the variable in the right-hand side of the constraint.- yvar
Specified via
model.genconloga(i).yvar
. Index of the variable in the left-hand side of the constraint.- a
Specified via
model.genconloga(i).a
. Specifies the base of the logarithmic function \(a > 0\).- name (optional)
Specified via
model.genconloga(i).name
. When present, specifies the name of the \(i\)-th logarithmic function constraint.- funcpieces (optional)
Specified via
model.genconloga(i).funcpieces
. When present, specifies the FuncPieces attribute of the \(i\)-th logarithmic function constraint.- funcpiecelength (optional)
Specified via
model.genconloga(i).funcpiecelength
. When present, specifies the FuncPieceLength attribute of the \(i\)-th logarithmic function constraint.- funcpieceerror (optional)
Specified via
model.genconloga(i).funcpieceerror
. When present, specifies the FuncPieceError attribute of the \(i\)-th logarithmic function constraint.- funcpieceratio (optional)
Specified via
model.genconloga(i).funcpieceratio
. When present, specifies the FuncPieceRatio attribute of the \(i\)-th logarithmic function constraint.- funcnonlinear (optional)
Specified via
model.genconloga(i).funcnonlinear
. When present, specifies the FuncNonlinear attribute of the \(i\)-th logarithmic function constraint.
- genconlogistic (optional)
A struct array. When present, each entry in
genconlog
defines the logistic function constraint of the form\[x[\mathrm{yvar}] = 1 / (1 + \mathrm{exp}(-x[\mathrm{xvar}]))\]A piecewise-linear approximation of the function is added to the model. The details of the approximation are controlled using the following four attributes (or using the parameters with the same names): FuncPieces, FuncPieceError, FuncPieceLength, and FuncPieceRatio. Alternatively, the function can be treated as a nonlinear constraint by setting the attribute FuncNonlinear. For details, consult the General Constraint discussion.
Each entry may have the following fields:
- xvar
Specified via
model.genconlogistic(i).xvar
. Index of the variable in the right-hand side of the constraint.- yvar
Specified via
model.genconlogistic(i).yvar
. Index of the variable in the left-hand side of the constraint.- name (optional)
Specified via
model.genconlogistic(i).name
. When present, specifies the name of the \(i\)-th logistic function constraint.- funcpieces (optional)
Specified via
model.genconlogistic(i).funcpieces
. When present, specifies the FuncPieces attribute of the \(i\)-th logistic function constraint.- funcpiecelength (optional)
Specified via
model.genconlogistic(i).funcpiecelength
. When present, specifies the FuncPieceLength attribute of the \(i\)-th logistic function constraint.- funcpieceerror (optional)
Specified via
model.genconlogistic(i).funcpieceerror
. When present, specifies the FuncPieceError attribute of the \(i\)-th logistic function constraint.- funcpieceratio (optional)
Specified via
model.genconlogistic(i).funcpieceratio
. When present, specifies the FuncPieceRatio attribute of the \(i\)-th logistic function constraint.- funcnonlinear (optional)
Specified via
model.genconlogistic(i).funcnonlinear
. When present, specifies the FuncNonlinear attribute of the \(i\)-th logistic function constraint.
- genconpow (optional)
A struct array. When present, each entry in
genconpow
defines a power function constraint of the form\[x[\mathrm{yvar}] = x[\mathrm{xvar}]^\mathrm{a}\]A piecewise-linear approximation of the function is added to the model. The details of the approximation are controlled using the following four attributes (or using the parameters with the same names): FuncPieces, FuncPieceError, FuncPieceLength, and FuncPieceRatio. Alternatively, the function can be treated as a nonlinear constraint by setting the attribute FuncNonlinear. For details, consult the General Constraint discussion.
Each entry may have the following fields:
- xvar
Specified via
model.genconpow(i).xvar
. Index of the variable in the right-hand side of the constraint.- yvar
Specified via
model.genconpow(i).yvar
. Index of the variable in the left-hand side of the constraint.- a
Specified via
model.genconpow(i).a
. Specifies the exponent of the power function.- name (optional)
Specified via
model.genconpow(i).name
. When present, specifies the name of the \(i\)-th power function constraint.- funcpieces (optional)
Specified via
model.genconpow(i).funcpieces
. When present, specifies the FuncPieces attribute of the \(i\)-th power function constraint.- funcpiecelength (optional)
Specified via
model.genconpow(i).funcpiecelength
. When present, specifies the FuncPieceLength attribute of the \(i\)-th power function constraint.- funcpieceerror (optional)
Specified via
model.genconpow(i).funcpieceerror
. When present, specifies the FuncPieceError attribute of the \(i\)-th power function constraint.- funcpieceratio (optional)
Specified via
model.genconpow(i).funcpieceratio
. When present, specifies the FuncPieceRatio attribute of the \(i\)-th power function constraint.- funcnonlinear (optional)
Specified via
model.genconpow(i).funcnonlinear
. When present, specifies the FuncNonlinear attribute of the \(i\)-th power function constraint.
- genconsin (optional)
A struct array. When present, each entry in
genconsin
defines the sine function constraint of the form\[x[\mathrm{yvar}] = \mathrm{sin}(x[\mathrm{xvar}])\]A piecewise-linear approximation of the function is added to the model. The details of the approximation are controlled using the following four attributes (or using the parameters with the same names): FuncPieces, FuncPieceError, FuncPieceLength, and FuncPieceRatio. Alternatively, the function can be treated as a nonlinear constraint by setting the attribute FuncNonlinear. For details, consult the General Constraint discussion.
Each entry may have the following fields:
- xvar
Specified via
model.genconsin(i).xvar
. Index of the variable in the right-hand side of the constraint.- yvar
Specified via
model.genconsin(i).yvar
. Index of the variable in the left-hand side of the constraint.- name (optional)
Specified via
model.genconsin(i).name
. When present, specifies the name of the \(i\)-th sine function constraint.- funcpieces (optional)
Specified via
model.genconsin(i).funcpieces
. When present, specifies the FuncPieces attribute of the \(i\)-th sine function constraint.- funcpiecelength (optional)
Specified via
model.genconsin(i).funcpiecelength
. When present, specifies the FuncPieceLength attribute of the \(i\)-th sine function constraint.- funcpieceerror (optional)
Specified via
model.genconsin(i).funcpieceerror
. When present, specifies the FuncPieceError attribute of the \(i\)-th sine function constraint.- funcpieceratio (optional)
Specified via
model.genconsin(i).funcpieceratio
. When present, specifies the FuncPieceRatio attribute of the \(i\)-th sine function constraint.- funcnonlinear (optional)
Specified via
model.genconsin(i).funcnonlinear
. When present, specifies the FuncNonlinear attribute of the \(i\)-th sine function constraint.
- genconcos (optional)
A struct array. When present, each entry in
genconcos
defines the cosine function constraint of the form\[x[\mathrm{yvar}] = \mathrm{cos}(x[\mathrm{xvar}])\]A piecewise-linear approximation of the function is added to the model. The details of the approximation are controlled using the following four attributes (or using the parameters with the same names): FuncPieces, FuncPieceError, FuncPieceLength, and FuncPieceRatio. Alternatively, the function can be treated as a nonlinear constraint by setting the attribute FuncNonlinear. For details, consult the General Constraint discussion.
Each entry may have the following fields:
- xvar
Specified via
model.genconcos(i).xvar
. Index of the variable in the right-hand side of the constraint.- yvar
Specified via
model.genconcos(i).yvar
. Index of the variable in the left-hand side of the constraint.- name (optional)
Specified via
model.genconcos(i).name
. When present, specifies the name of the \(i\)-th cosine function constraint.- funcpieces (optional)
Specified via
model.genconcos(i).funcpieces
. When present, specifies the FuncPieces attribute of the \(i\)-th cosine function constraint.- funcpiecelength (optional)
Specified via
model.genconcos(i).funcpiecelength
. When present, specifies the FuncPieceLength attribute of the \(i\)-th cosine function constraint.- funcpieceerror (optional)
Specified via
model.genconcos(i).funcpieceerror
. When present, specifies the FuncPieceError attribute of the \(i\)-th cosine function constraint.- funcpieceratio (optional)
Specified via
model.genconcos(i).funcpieceratio
. When present, specifies the FuncPieceRatio attribute of the \(i\)-th cosine function constraint.- funcnonlinear (optional)
Specified via
model.genconcos(i).funcnonlinear
. When present, specifies the FuncNonlinear attribute of the \(i\)-th cosine function constraint.
- gencontan (optional)
A struct array. When present, each entry in
gencontan
defines the tangent function constraint of the form\[x[\mathrm{yvar}] = \mathrm{tan}(x[\mathrm{xvar}])\]A piecewise-linear approximation of the function is added to the model. The details of the approximation are controlled using the following four attributes (or using the parameters with the same names): FuncPieces, FuncPieceError, FuncPieceLength, and FuncPieceRatio. Alternatively, the function can be treated as a nonlinear constraint by setting the attribute FuncNonlinear. For details, consult the General Constraint discussion.
Each entry may have the following fields:
- xvar
Specified via
model.gencontan(i).xvar
. Index of the variable in the right-hand side of the constraint.- yvar
Specified via
model.gencontan(i).yvar
. Index of the variable in the left-hand side of the constraint.- name (optional)
Specified via
model.gencontan(i).name
. When present, specifies the name of the \(i\)-th tangent function constraint.- funcpieces (optional)
Specified via
model.gencontan(i).funcpieces
. When present, specifies the FuncPieces attribute of the \(i\)-th tangent function constraint.- funcpiecelength (optional)
Specified via
model.gencontan(i).funcpiecelength
. When present, specifies the FuncPieceLength attribute of the \(i\)-th tangent function constraint.- funcpieceerror (optional)
Specified via
model.gencontan(i).funcpieceerror
. When present, specifies the FuncPieceError attribute of the \(i\)-th tangent function constraint.- funcpieceratio (optional)
Specified via
model.gencontan(i).funcpieceratio
. When present, specifies the FuncPieceRatio attribute of the \(i\)-th tangent function constraint.- funcnonlinear (optional)
Specified via
model.gencontan(i).funcnonlinear
. When present, specifies the FuncNonlinear attribute of the \(i\)-th tangent function constraint.
Advanced fields#
- pwlobj (optional)
The piecewise-linear objective functions. A struct array. When present, each entry in
pwlobj
defines a piecewise-linear objective function for a single variable. The index of the variable whose objective function is being defined is stored inmodel.pwlobj(i).var
. The \(x\) values for the points that define the piecewise-linear function are stored inmodel.pwlobj(i).x
. The values in the \(x\) vector must be in non-decreasing order. The \(y\) values for the points that define the piecewise-linear function are stored inmodel.pwlobj(i).y
.- vbasis (optional)
The variable basis status vector. Used to provide an advanced starting point for the simplex algorithm. You would generally never concern yourself with the contents of this vector, but would instead simply pass it from the result of a previous optimization run to the input of a subsequent run. When present, you must specify one value for each column of
A
.- cbasis (optional)
The constraint basis status vector. Used to provide an advanced starting point for the simplex algorithm. Consult the
vbasis
description for details. When present, you must specify one value for each row ofA
.- varhintval (optional)
A set of user hints. If you know that a variable is likely to take a particular value in high quality solutions of a MIP model, you can provide that value as a hint. You can also (optionally) provide information about your level of confidence in a hint with the
varhintpri
field. If present, you must specify one value for each column ofA
. Use a value ofnan
for variables where no such hint is known. For more details, please refer to the Attribute section in the reference manual.- varhintpri (optional)
Priorities on user hints. After providing variable hints through the
varhintval
struct, you can optionally also provide hint priorities to give an indication of your level of confidence in your hints. If present, you must specify a value for each column ofA
. For more details, please refer to the Attribute section in the reference manual.- branchpriority (optional)
Variable branching priority. If present, the value of this attribute is used as the primary criteria for selecting a fractional variable for branching during the MIP search. Variables with larger values always take priority over those with smaller values. Ties are broken using the standard branch variable selection criteria. If present, you must specify one value for each column of
A
.- pstart (optional)
The current simplex start vector. If you set
pstart
values for every variable in the model anddstart
values for every constraint, then simplex will use those values to compute a warm start basis. For more details, please refer to the Attribute section in the reference manual.- dstart (optional)
The current simplex start vector. If you set
dstart
values for every linear constraint in the model andpstart
values for every variable, then simplex will use those values to compute a warm start basis. For more details, please refer to the Attribute section in the reference manual.- lazy (optional)
Determines whether a linear constraint is treated as a lazy constraint. If present, you must specify one value for each row of
A
. For more details, please refer to the Attribute section in the reference manual.- start (optional)
The MIP start vector. The MIP solver will attempt to build an initial solution from this vector. When present, you must specify a start value for each variable. Note that you can set the start value for a variable to
nan
, which instructs the MIP solver to try to fill in a value for that variable.- partition (optional)
The MIP variable partition number, which is used by the MIP solution improvement heuristic. If present, you must specify one value for each variable of
A
. For more details, please refer to the Attribute section in the reference manual.
If any of the mandatory components listed above are missing, the
gurobi()
function will return an error.
Below is an example that demonstrates the construction of a simple optimization model:
model.A = sparse([1 2 3; 1 1 0]);
model.obj = [1 1 1];
model.modelsense = 'max';
model.rhs = [4; 1];
model.sense = '<>'
The params argument#
As mentioned previously, the Gurobi Optimizer provides a set of parameters that allow you to control many of the details of the optimization process. Factors like feasibility and optimality tolerances, choices of algorithms, strategies for exploring the MIP search tree, etc., can be controlled by modifying Gurobi parameters before beginning the optimization.
Parameter changes are specified using a struct
variable having
multiple fields
, which is passed as an argument to the appropriate
Gurobi function (e.g., gurobi
). The name of each
field must be the name of a Gurobi parameter, and the associated value
should be the desired value of that parameter. You can find a complete
list of the available Gurobi parameters in the
reference manual.
To create a struct that would set the Gurobi
Method parameter to 2 and the
ResultFile parameter to model.mps
,
you would do the following:
params params.Method = 2;
params.ResultFile = 'model.mps';
We should say a bit more about the ResultFile parameter.
If this parameter is set, the optimization model that is eventually
passed to Gurobi will also be output to the specified file. The filename
suffix should be one of .mps
, .rew
, .lp
, .rlp
,
.dua
, .dlp
, .ilp
, or .opb
, to indicate the desired file
format (see the file format section in the
reference manual for details on Gurobi file formats).
The params struct can also be used to set license specific parameters, that define the computational environment to be used. We will discuss the two most common use cases next, and refer again to the collection of all available parameters in the reference manual.
Using a Compute Server License#
Gurobi Compute Server allows you to offload optimization jobs to a remote server. Servers are organized into clusters. By providing the name of any node within the cluster, your job will automatically be sent to the least heavily loaded node in the cluster. If all nodes are at capacity, your job will be placed in a queue, and will proceed once capacity becomes available. You can find additional information about Gurobi Compute Server in the Gurobi Remote Services Reference Manual. The most commonly used parameters are the following.
- ComputeServer
A Compute Server. You can refer to the server using its name or its IP address. If you are using a non-default port, the server name should be followed by the port number (e.g.,
server1:61000
).- ServerPassword (optional)
User password on the Compute Server cluster. Obtain this from your Compute Server administrator.
- CSPriority (optional)
The priority of the job. Priorities must be between -100 and 100, with a default value of 0 (by convention). Higher priority jobs are chosen from the server job queue before lower priority jobs. A job with priority 100 runs immediately, bypassing the job queue and ignoring the job limit on the server. You should exercise caution with priority 100 jobs, since they can severely overload a server, which can cause jobs to fail, and in extreme cases can cause the server to crash.
- CSRouter (optional)
The router for the Compute Server cluster. A router can be used to improve the robustness of a Compute Server deployment. You can refer to the router using either its name or its IP address. A typical Remote Services deployment won’t use a router, so you typically won’t need to set this.
- CSTLSinsecure (optional)
Indicates whether to use insecure mode in the TLS (Transport Layer Security). Leave this at its default value of 0 unless your server administrator tells you otherwise.
Here is an example of how to use a params
argument to connect to a
Compute Server:
params params.ComputeServer = 'server1.mycompany.com:61000';
params.CSPriority = 5;
Using a Gurobi Instant Cloud License#
Gurobi Instant Cloud allows you to offload optimization jobs to a Gurobi Compute Server on the cloud. If an appropriate machine is already running, the job will run on that machine. It will automatically launch a new machine otherwise. Note that launching a new machine can take a few minutes. You can find additional information about the Gurobi Instant Cloud service in the reference manual. The most commonly used parameters are the following.
- CloudAccessID
The access ID for your Gurobi Instant Cloud license. This can be retrieved from the Gurobi Instant Cloud website. When used in combination with your CloudSecretKey, this allows you to launch Instant Cloud instances and submit jobs to them.
- CloudSecretKey
The secret key for your Gurobi Instant Cloud license. This can be retrieved from the Gurobi Instant Cloud website. When used in combination with your CloudAccessID, this allows you to launch Instant Cloud instances and submit jobs to them. Note that you should keep your secret key private.
- CloudPool (optional)
The machine pool. Machine pools allow you to create fixed configurations on the Instant Cloud website (capturing things like type of machine, geographic region, etc.), and then launch and share machines from client programs without having to restate configuration information each time you launch a machine. If not provided, your job will be launched in the default pool associated with your cloud license.
- CSPriority (optional)
The priority of the job. Priorities must be between -100 and 100, with a default value of 0 (by convention). Higher priority jobs are chosen from the server job queue before lower priority jobs. A job with priority 100 runs immediately, bypassing the job queue and ignoring the job limit on the server. You should exercise caution with priority 100 jobs, since they can severely overload a server, which can cause jobs to fail, and in extreme cases can cause the server to crash.
Here is an example of how to use a params
argument to launch a
Gurobi Instant Cloud instance:
params params.CloudAccessID = '3d1ecef9-dfad-eff4-b3fa';
params.CloudSecretKey = 'ae6L23alJe3+fas';