MATLAB Interface

This section describes the Gurobi MATLAB interface. We begin with information on how to set up Gurobi for use within MATLAB. An example of how to use the MATLAB interface follows.

Setting up Gurobi for MATLAB

To begin, you'll need to tell MATLAB where to find the Gurobi routines. We've provided a script to assist you with this. The Gurobi MATLAB setup script, gurobi_setup.m, can be found in the <installdir>/matlab directory of your Gurobi installation (e.g., /opt/gurobi500/linux64/matlab for the 64-bit Linux version of Gurobi 5.0). To get started, type the following commands within MATLAB to change to the matlab directory and call gurobi_setup:

>> cd /opt/gurobi500/linux64/matlab
>> gurobi_setup

You will need to be careful that the MATLAB binary and the Gurobi package you install both use the same instruction set. For example, if you are using the 64-bit Windows version of MATLAB, you'll need to install the 64-bit version of Gurobi, and you'll need to use the 64-bit Gurobi MATLAB libraries (i.e., the ones included with the 64-bit version of Gurobi). The error messages that result from Windows instruction set mismatches can be quite cryptic, so please check this point carefully if our MATLAB interface refuses to launch.

Note that the Gurobi MATLAB interface is not supported on 32-bit Linux.

Example

Let us now turn our attention to an example of using Gurobi to solve a simple MIP model. Our example optimizes the following model:

maximize x + y + 2 z    
subject to x + 2 y + 3 z $\leq$ 4
  x + y     $\geq$ 1
  x, y, z binary  
Note that this is the same model that was modeled and optimized in the C Interface section.

This is the complete source code for our example (also available in <installdir>/examples/matlab/mip1.m)...

names = {'x'; 'y'; 'z'};

try
    clear model;
    model.A = sparse([1 2 3; 1 1 0]);
    model.obj = [1 1 2];
    model.rhs = [4; 1];
    model.sense = '<>';
    model.vtype = 'B';
    model.modelsense = 'max';

    clear params;
    params.outputflag = 0;
    params.resultfile = 'mip1.lp';

    result = gurobi(model, params);

    disp(result)

    for v=1:length(names)
        fprintf('%s %d\n', names{v}, result.x(v));
    end

    fprintf('Obj: %e\n', result.objval);

catch gurobiError
    fprintf('Error reported\n');
end

Example details

Let us now walk through the example, line by line, to understand how it achieves the desired result of optimizing the indicated model.

Building the model

The example begins by building an optimization model. The data associated with an optimization model must be stored in a MATLAB struct. Fields in this struct contain the different parts of the model. A few fields are mandatory: the constraint matrix (A), the objective vector (obj), the right-hand side vector (rhs), and the constraint sense vector (sense). A model can also include optional fields (e.g., the objective sense modelsense).

The example uses the built-in sparse function to build the constraint matrix A. The Gurobi MATLAB interface only accepts sparse matrices as input. If you have a dense matrix, use sparse to convert it to a sparse matrix before passing it to our interface.

Subsequent statements populate other fields of the model variable, including the objective vector, the right-hand-side vector, and the constraint sense vector.

In addition to the mandatory fields, this example also sets two optional fields: modelsense and vtype. The former is used to indicate the sense of the objective function. The default is minimization, so we've set the fields equal to 'max' to indicate that we would like to maximize the specified objective. The vtype field is used to indicate the types of the variables in the model. In our example, all variables are binary ('B'). Note that our interface allows you to specify a scalar value for the sense and vtype arguments. The Gurobi interface will expand that scalar to a constant array of the appropriate length. In this example, the scalar value 'B' will be expanded to an array of length 3, containing one 'B' value for each column of A.

Modifying Gurobi parameters

The next statements create a struct variable that will be used to modify two Gurobi parameters:

params.outputflag = 0;
params.resultfile = 'mip1.lp';
In this example, we set the Gurobi OutputFlag parameter to 0 in order to shut off Gurobi output. We also set the ResultFile parameter to request that Gurobi produce a file as output (in this case, a LP format file that contains the optimization model). The Gurobi MATLAB interface allows you to set as many Gurobi parameters as you would like. The field names in the parameter structure simply need to match Gurobi parameter names, and the values of the fields should be set to the desired parameter value. Please consult the Parameters section of the Gurobi Reference Manual for a complete list of all Gurobi parameters.

Solving the model

The next statement is where the actual optimization occurs:

result = gurobi(model, params);
We pass the model and the optional list of parameter changes to the gurobi() function. It computes an optimal solution to the specified model and returns the computed result.

Printing the solution

The gurobi() function returns a struct as its result. This struct contains a number of fields, where each field contains information about the computed solution. The available fields depend on the result of the optimization, the type of model that was solved (LP, QP, QCP, SOCP, or MIP), and the algorithm used to solve the model. The returned struct will always contain a status field, which indicates whether Gurobi was able to compute an optimal solution to the model. You should consult the Status Codes section of the Gurobi Reference Manual for a complete list of all possible status codes. If Gurobi was able to find a solution to the model, the return value will also include objval and x fields. The former gives the objective value for the computed solution, and the latter is the computed solution vector (one entry per column of the constraint matrix). For continuous models, we will also return dual information (reduced costs and dual multipliers), and possibly an optimal basis.

In our example, we simply print the optimal objective value (result.objval) and the optimal solution vector (result.x).

Running the example

The Gurobi MATLAB examples can be found in the <installdir>/examples/matlab/ directory of your Gurobi installation (e.g., /opt/gurobi500/linux64/examples/matlab for the 64-bit Linux version of Gurobi 5.0). To run one of the examples, first change to this directory in MATLAB, then type its name into the MATLAB prompt. For example, to run example mip1, you would say:

>> cd /opt/gurobi500/linux64/examples/matlab
>> mip1

If Gurobi was successfully set up for use in MATLAB, 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

The MATLAB example directory contains a number of examples. We encourage you to browse and modify them in order to become more familiar with the Gurobi MATLAB interface.