# gurobi()

###

gurobi()

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:

**A**- The linear constraint matrix. This must be a sparse matrix.
**obj**- The linear objective vector (
`c`

in the problem statement). You must specify one value for each column of`A`

. This must be a dense vector. **sense**- The senses of the linear constraints. Allowed values are
`'='`

,`'<'`

, 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. **rhs**- The right-hand side vector for the linear constraints (
in the problem statement). You must
specify one value for each row of
`A`

. This must be a dense vector. **lb (optional)**- The lower bound vector. When present, you must
specify one value for each column of
`A`

. This must be a dense vector. When absent, each variable has a lower bound of 0. **ub (optional)**- The upper bound vector. When present, you must
specify one value for each column of
`A`

. This must be a dense vector. When absent, the variables have infinite upper bounds. **vtype (optional)**- The variable types. This char array is used to
capture variable integrality constraints. Allowed values are
`'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. **modelsense (optional)**- The optimization sense. Allowed values
are
`'min'`

(minimize) or`'max'`

(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
(
in the problem statement).
**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
array, 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`

. This must be a dense vector. **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 of`A`

. This must be a dense vector. **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 in`A`

.`Q`

must be a sparse matrix. **cones (optional)**- Second-order cone constraints. A struct
array. Each element in the array defines a single cone constraint:
`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. **quadcon (optional)**- The quadratic constraints. A struct
array. When present, each element in the array defines a single
quadratic constraint:
. The
`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`

. **sos (optional)**- The Special Ordered Set (SOS) constraints. A
struct array. When present, each element in the array defines a
single SOS constraint. A SOS constraint can be of type 1 or 2. This
is specified via
`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`

. **pwlobj (optional)**- The piecewise-linear objective functions. A
struct array. When present, each element in the array defines a
piecewise-linear objective function of a single variable. The
index of the variable whose objective function is being defined
is stored in
`model.pwlobj.var`

. The values for the points that define the piecewise-linear function are stored in

`model.pwlobj.x`

. The values in the vector must be in non-decreasing order. The values for the points that define the piecewise-linear function are stored in`model.pwlobj.y`

. **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. This must be a
dense vector. Note that you can leave the start value for a variable
undefined--the MIP solver will attempt to fill in values for the
undefined start values. This may be done by setting the start value
for that variable to
`nan`

. **varnames (optional)**- The variable names. A cell array of
strings. When present, each element of the array defines the name of
a variable. You must specify a name for each column of
`A`

. **constrnames (optional)**- The constraint names. A cell array of
strings. When present, each element of the array defines the name of
a constraint. You must specify a name for each row of
`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.

**status**- The status of the optimization, returned as a string.
The desired result is
`'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. **objval**- The objective value of the computed solution.
**runtime**- The elapsed wall-clock time (in seconds) for the
optimization.
**x**- The computed solution. This array contains one entry for
each column of
`A`

. **slack**- The constraint slack for the computed solution. This
array contains one entry for each row of
`A`

. **qcslack**- The quadratic constraint slack in the current
solution. This array contains one entry for second-order cone
constraint and one entry for each quadratic constraint. The slacks
for the second-order cone constraints appear before the slacks for
the quadratic constraints.
**pi**- Dual values for the computed solution (also known as
*shadow prices*). This array contains one entry for each row of`A`

. **qcpi**- The dual values associated with the quadratic
constraints. This array contains one entry for each second-order
cone constraint and one entry for each quadratic constraint. The
dual values for the second-order cone constraints appear before the
dual values for the quadratic constraints.
**rc**- Variable reduced costs for the computed solution. This
array contains one entry for each column of
`A`

. **vbasis**- Variable basis status values for the computed optimal
basis. You generally should not concern yourself with the contents
of this array. If you wish to use an advanced start later, you
would simply copy the
`vbasis`

and`cbasis`

arrays into the corresponding fields for the next model. This array contains one entry for each column of`A`

. **cbasis**- Constraint basis status values for the computed optimal
basis. This array contains one entry for each row of
`A`

. **unbdray**- Unbounded ray. Provides a vector that, when added to
any feasible solution, yields a new solution that is also feasible
but improves the objective.
**farkasdual**- Farkas infeasibility proof. This is a dual unbounded
vector. Adding this vector to any feasible solution of the dual
model yields a new solution that is also feasible but improves the
dual objective.
**farkasproof**- Magnitude of infeasibility violation in Farkas
infeasibility proof. A Farkas infeasibility proof identifies a new
constraint, obtained by taking a linear combination of the
constraints in the model, that can never be satisfied. (the linear
combination is available in the
`farkasdual`

field). This attribute indicates the magnitude of the violation of this aggregated constraint. **objbound**- Best available bound on solution (lower bound for
minimization, upper bound for maximization).
**itercount**- Number of simplex iterations performed.
**baritercount**- Number of barrier iterations performed.
**nodecount**- Number of branch-and-cut nodes explored.

`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