This section will work through a simple example in order to illustrate the use of the Gurobi MATLAB API. The example builds a simple Mixed Integer Programming model, solves it, and prints the optimal solution.
We have special instructions on how to set up Gurobi for use within MATLAB. See How do I install Gurobi for Matlab? for more information.
The example
Our example optimizes the following model:
| maximize | x | + | y | + | 2 z | ||
| subject to | x | + | 2 y | + | 3 z | ≤ | 4 |
| x | + | y | ≥ | 1 | |||
| x, y, z binary | |||||||
The complete source code for our example can be found in:
- Online: Example mip1.m
- Distribution: <installdir>/examples/matlab/mip1.m
In the following sections, we will walk through the example, line by line, to understand how it achieves the desired result of optimizing the above 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.
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.
Modifying the 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, 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.
Optimizing 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.
Reporting the results
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).
Running the example
The Gurobi MATLAB examples can be found in the <installdir>/examples/matlab/ directory of your Gurobi installation (the default <installdir> for Gurobi 12.0.2 is /opt/gurobi1202/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/gurobi1202/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.