Tutorial: Getting Started with the Gurobi MATLAB API

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.

The most fundamental fields of the MATLAB struct model are:

• The constraint matrix (A),
• the objective vector (obj),
• the right-hand side vector (rhs),
• and the constraint sense vector (sense).

Among these, only the constraint matrix is mandatory, and default values are substituted for all other model fields in case they are missing.

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.

In addition to the fields discussed above, this example sets two more 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 field 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.

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, an LP format file that contains the optimization model). The Gurobi MATLAB interface allows you to set as many Gurobi parameters as you 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 values. Please consult the Parameters section of the Gurobi Reference Manual for a complete list of all Gurobi parameters.

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.

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 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. For a list of all possible fields and details about when you will find them populated, refer to the documentation for the gurobi function in the reference manual.

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

The Gurobi MATLAB examples can be found in the <installdir>/examples/matlab/ directory of your Gurobi installation (the default <installdir> for Gurobi 10.0.2 is /opt/gurobi1002/linux64 for Linux). 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/gurobi1002/linux64/examples/matlab
>> mip1

If Gurobi was successfully set up for use in MATLAB, you should see the following output in the command window:

          status: 'OPTIMAL'
     versioninfo: [1x1 struct]
         runtime: 3.2401e-04
          objval: 3
               x: [3x1 double]
           slack: [2x1 double]
    poolobjbound: 3
            pool: [1x2 struct]
          mipgap: 0
        objbound: 3
       objboundc: 3
       itercount: 0
    baritercount: 0
       nodecount: 0

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

From all this data we only use the fields objval and x in our example. Please refer to the Gurobi Reference Manual for a complete description of all the other output fields.

In order to get more familiar with the Gurobi MATLAB interface, we encourage you to browse through the files in the MATLAB example directory. Often these examples can be used as starting points for your own optimization projects.