Try our new documentation site (beta).
MATLAB API Overview
This section documents the Gurobi MATLAB® interface. 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. This manual begins with a quick overview of the methods provided by our MATLAB API. It then continues with a comprehensive presentation of all of the available methods, their arguments, and their return values.
If you are new to the Gurobi Optimizer, we suggest that you start with the Quick Start Guide or the Example Tour. These documents provide concrete examples of how to use the methods described here.
The MATLAB Optimization Toolbox provides its own interface for building optimization models (starting with version 2017b). Gurobi supports this interface as well. We'll discuss this aspect in the problem-based modeling section; consult also the linprog, intlinprog, opttoolbox_lp, and opttoolbox_mip1 examples in the Gurobi distribution for illustrations of how to pass models built using this interface to Gurobi.
A quick note for new users: the convention in math programming is that variables are non-negative unless specified otherwise. You'll need to explicitly set lower bounds if you want variables to be able to take negative values.
Our Gurobi MATLAB interface enables you to express problems of the following form:
| minimize |
 |
|
| subject to |  |
(linear constraints) |
 |
(bound constraints) | |
some  integral |
(integrality constraints) | |
 |
(quadratic constraints) | |
some  in SOS |
(special ordered set constraints) | |
| min, max, abs, or, ... | (general constraints) |
Models are stored as struct variables, each consisting of multiple fields. The fields capture the different model components listed above. Many of these model components are optional. For example, integrality constraints may be omitted.
An optimization model may be loaded from a file (using the gurobi_read function), or it can be built by populating the appropriate fields of a model variable (using standard MATLAB constructs). We will discuss the details of how models are represented in the model argument section.
We often refer to the class of an optimization model. A model with a linear objective function, linear constraints, and continuous variables is a Linear Program (LP). If the objective is quadratic, the model is a Quadratic Program (QP). If any of the constraints are quadratic, the model is a Quadratically-Constrained Program (QCP). We will sometimes refer to a few special cases of QCP: QCPs with convex constraints, QCPs with non-convex constraints, bilinear programs, and Second-Order Cone Programs (SOCP). If the model contains any integer variables, semi-continuous variables, semi-integer variables, Special Ordered Set (SOS) constraints, or general constraints, the model is a Mixed Integer Program (MIP). We'll also sometimes discuss special cases of MIP, including Mixed Integer Linear Programs (MILP), Mixed Integer Quadratic Programs (MIQP), Mixed Integer Quadratically-Constrained Programs (MIQCP), and Mixed Integer Second-Order Cone Programs (MISOCP). The Gurobi Optimizer handles all of these model classes.
Solving a Model
Once you have built a model, you can call gurobi to compute a solution. By default, gurobi will use the concurrent optimizer to solve LP models, the barrier algorithm to solve QP models and QCP models with convex constraints, and the branch-and-cut algorithm to solve mixed integer models. The solution is returned as a struct variable. We will discuss the details of how optimization results are represented when we discuss the gurobi function.
Here is a simple example of a likely sequence of commands
in the MATLAB API:
model = gurobi_read('examples/data/stein9.mps');
result = gurobi(model);
Multiple Solutions and Multiple Objectives
By default, the Gurobi Optimizer assumes that your goal is to find one proven optimal solution to a model with a single objective function. Gurobi provides features that allow you to relax either of these assumptions. You should refer to the section on Solution Pools for information on how to request more than one solution, or the section on Multiple Objectives for information on how to specify multiple objective functions and control the trade-off between them.
Infeasible Models
You have a few options if a model is found to be infeasible. You can try to diagnose the cause of the infeasibility, attempt to repair the infeasibility, or both. To obtain information that can be useful for diagnosing the cause of an infeasibility, call gurobi_iis to compute an Irreducible Inconsistent Subsystem (IIS). This method can be used for both continuous and MIP models, but you should be aware that the MIP version can be quite expensive. We will discuss the details of how IIS results are represented in the gurobi_iis function documentation.
To attempt to repair an infeasibility, call gurobi_feasrelax to compute a feasibility relaxation for the model. This relaxation allows you to find a solution that minimizes the magnitude of the constraint violation.
Managing Parameters
The Gurobi optimizer provides a set of parameters that allow you to control many of the details of the optimization process. Factors like feasibility and optimality tolerances, choices of algorithms, strategies for exploring the MIP search tree, etc., can be controlled by modifying Gurobi parameters before beginning the optimization.
Each Gurobi parameter has a default value. Desired parameter changes are passed in a struct variable. The name of each field within this struct must be the name of a Gurobi parameter, and the associated value should be the desired value of that parameter. You can find a complete list of the available Gurobi parameters here. We will provide additional details on changing parameter settings in the params argument section.
Monitoring Progress
Progress of the optimization can be monitored through Gurobi logging. By default, Gurobi will send output to the screen. A few simple controls are available for modifying the default logging behavior. If you would like to direct output to a file as well as to the screen, set the LogFile parameter to the name of your desired log file. The frequency of logging output can be controlled with the DisplayInterval parameter, and logging can be turned off entirely with the OutputFlag parameter. A detailed description of the Gurobi log file can be found in the Logging section.
Error Handling
If unsuccessful, the methods of the Gurobi MATLAB interface will return an error code and an error message. A list of possible error codes can be found in the Error Code section.
Environments
By default, the various Gurobi functions will look for a valid license file and create a local Gurobi environment. This environment exists for as long as the corresponding MATLAB API function is running, and is released upon completion.
Another option is to provide an optional env argument (also through a struct). This argument allows you to solve the given problem on a Gurobi Compute Server or using the Gurobi Instant Cloud. We will discuss this topic further in the env argument section.
Gurobi will check the current working directory for a file named gurobi.env, and it will attempt to read parameter settings from this file if it exists. The file should be in PRM format (briefly, each line should contain a parameter name, followed by the desired value for that parameter).
