MATLAB Reference Manual

The Gurobi MATLAB® interface allows you to build an optimization model, pass the model to Gurobi, and obtain the optimization result, all from within the MATLAB environment. For those of you who are not familiar with MATLAB, it is an environment for doing numerical computing. Please visit the MATLAB web site for more information.

The Gurobi MATLAB interface can be used to solve optimization problems of the following form:
minimize x'*Q*x + c'*x + alpha  
subject to Ax = b (linear constraints)
  l <= x <= u (bound constraints)
  some xj integral (integrality constraints)
  some xk lie within second order cones (cone constraints)
  x'*Qc*x + q'*x <= beta (quadratic constraints)
  some xi in SOS (special ordered set constraints)
Many of the model components listed here are optional. For example, integrality constraints may be omitted. We'll discuss the details of how models are represented shortly.

The Gurobi MATLAB API

The Gurobi MATLAB interface is quite concise. It consists of a single MATLAB function that takes a pair of arguments:

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 above). 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 ( b in the problem statement above). 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 (alpha in the problem statement above).
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: x'*Qc*x + q'*x <= beta. 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.
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.
If any of the mandatory fields 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 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 and the resultfile parameter to model.mps, you would do the following:

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, .lp, .rew, or .rlp, to indicate the desired file format (see the file formats section for details on Gurobi file formats).

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 attribute). This attribute indicates the magnitude of the violation of this aggregated constraint.
The 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 parameter infunbdinfo is set to 1, the field unbdray will be present. Finally, if the model is an infeasible linear program and the parameter infunbdinfo 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

Using the Gurobi MATLAB interface

In order to use our MATLAB interface, you'll need to use the MATLAB function gurobi_setup to tell MATLAB where to find the Gurobi mex file. This file is stored in the <installdir>/matlab directory of your Gurobi installation. For example, if you installed the 64-bit Windows version of Gurobi 5.0.0 in the default location, you should run

>> cd c:/Users/jones/gurobi500/win64/matlab
>> gurobi_setup
The gurobi_setup function adjusts your MATLAB path to include the <installdir>/matlab directory. If you want to avoid typing this command every time you start MATLAB, follow the instructions issued by gurobi_setup to permanently adjust your path.

The MATLAB examples provided with the Gurobi distribution are included in the <installdir>/examples/matlab directory. To run these examples you need to change to this directory. For example, if you are running the 64-bit Windows version of Gurobi, you would say:

>> cd c:/Users/jones/gurobi500/win64/examples/matlab
>> mip1

If the Gurobi package was successfully installed, you should see the following output:

         status: 'OPTIMAL'
    versioninfo: [1x1 struct]
         objval: 3
        runtime: 0.0386
              x: [3x1 double]
          slack: [2x1 double]

x 1
y 0
z 1
Obj: 3.000000e+00