gurobi | ( model, params ) |
The two arguments are MATLAB struct
variables, each consisting
of multiple fields. The first argument contains the
optimization model to be solved. The second contains an optional set
of Gurobi parameters to be modified during the solution process. The
return value of this function is a struct
, also consisting of
multiple fields. It contains the result of performing the
optimization on the specified model. We'll now discuss the details of
each of these data structures.
The optimization model
As we've mentioned, the model
argument to the gurobi
function is a struct
variable, containing multiple fields
that
represent the various parts of the optimization model. Several of
these fields are optional. Note that you refer to a field of a MATLAB
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 following is an enumeration of all of the fields of the
model
argument that Gurobi will take into account when
optimizing the model:
c
in the
problem statement). You must
specify one value for each column of A
. This must be a dense
vector.
'='
, '<'
, or '>'
. You must specify one value for each row of
A
, or a single value to specify that all constraints have the
same sense. This must be a char array.
A
. This must be a dense
vector.
A
. This must be a
dense vector. When absent, each variable has a lower bound of 0.
A
. This must be a
dense vector. When absent, the variables have infinite upper
bounds.
'C'
(continuous), 'B'
(binary), 'I'
(integer),
'S'
(semi-continuous), or 'N'
(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 of A
, or a single value to specify that
all variables have the same type. When absent, each variable is
treated as being continuous.
'min'
(minimize) or 'max'
(maximize). When
absent, the default optimization sense is minimization.
A
.
This must be a dense vector.
vbasis
description for details. When present,
you must specify one value for each row of A
. This must be
a dense vector.
Q
must be a square matrix whose row and column counts are equal
to the number of columns in A
. Q
must be a sparse
matrix.
x(k)^2 >= sum(x(idx).^2)
, x(k) >= 0
. The constraint
is defined via model.cones.index = [k idx]
, with the first
entry in index
corresponding to the index of the variable on
the left-hand side of the constraint, and the remaining entries
corresponding to the indices of the variables on the right-hand side
of the constraint. model.cones.index
must be a dense
vector.
Qc
matrix must be a square matrix whose row and column counts
are equal to the number of columns of A
. Qc
must be
a sparse matrix. It is stored in model.quadcon.Qc
. The
q
vector defines the linear terms in the constraint. You must
specify a value for q
for each column of A
. This
must be a dense vector. It is stored in model.quadcon.q
.
The scalar beta defines the right-hand side of the constraint. It is
stored in model.quadcon.rhs
.
model.sos.type
. A type 1 SOS constraint is
a set of variables for which 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
model.sos.index
. Optional weights associated with SOS members
may be defined in model.sos.weight
.
nan
.
A
.
A
.
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 2]; model.modelsense = 'max'; model.rhs = [4; 1]; model.sense = '<>'
Parameters
The optional params
argument to the gurobi
function is
also a struct
, potentially containing multiple fields. 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.
Gurobi parameters allow users to modify the default behavior of the
Gurobi optimization algorithms. You can find a complete list of the
available Gurobi parameters here.
To create a struct that would set the Gurobi method parameter to 2 you would do the following:
params.method = 2;
The optimization result
The gurobi
function returns a struct
, with the various results
of the optimization stored in its fields. The specific
results that are available depend on the type of model that was
solved, and the status of the optimization.
The following is a list of fields that might be available
in the returned result. We'll discuss the circumstances under which
each will be available after presenting the list.
'OPTIMAL'
, which indicates that an
optimal solution to the model was found. Other status are possible,
for example if the model has no feasible solution or if you set a
Gurobi parameter that leads to early solver termination. See the
Status Code section for further
information on the Gurobi status codes.
A
.
A
.
A
.
A
.
vbasis
and cbasis
arrays into
the corresponding fields for the next model. This array contains
one entry for each column of A
.
A
.
farkasdual
field). This
attribute indicates the magnitude of the violation of this
aggregated constraint.
Status
field will be present in all cases. It indicates
whether Gurobi was able to find a proven optimal solution to the
model. In cases where a solution to the model was found, optimal or
otherwise, the objval
and x
fields will be present.
For linear and quadratic programs, if a solution is available, then
the pi
and rc
fields will also be present. For models
with quadratic constraints, if the parameter qcpdual
is set to
1, the field qcpi
will be present. If the final solution is a
basic solution (computed by simplex), then vbasis
and
cbasis
will be present. If the model is an unbounded linear
program and the
infunbdinfo
parameter is set to 1, the field
unbdray
will be present. Finally, if the model is an infeasible
linear program and the infunbdinfo parameter is set to 1, the
fields farkasdual
and farkasproof
will be set.
The following is an example of how the results of the gurobi
call might be extracted and output:
result = gurobi(model, params) if strcmp(result.status, 'OPTIMAL') fprintf('Optimal objective: %e\n', result.objval); disp(result.x) else fprintf('Optimization returned status: %s\n', result.status); end