MATLAB API Overview#

Models#

Our Gurobi MATLAB interface enables you to express problems of the following form:

minimize

\(x^TQ x+ c^Tx + \mathrm{alpha}\)

subject to

\(Ax = b\)

(linear constraints)

\(\ell \le x \le u\)

(bound constraints)

some \(x_j\) integral

(integrality constraints)

\(x^TQc\, x + q^Tx \le \mathrm{beta}\)

(quadratic constraints)

some \(x_i\) 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. At the highest level, a model can be continuous or discrete, depending on whether the modeling elements present in the model require discrete decisions to be made. Among continuous models…

  • 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 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 any of the constraints are non-linear (chosen from among the available general constraints), the model is a Non-Linear Program (NLP).

A model that contains any integer variables, semi-continuous variables, semi-integer variables, Special Ordered Set (SOS) constraints, or general constraints, is discrete, and is referred to as a Mixed Integer Program (MIP). The special cases of MIP, which are the discrete versions of the continuous models types we’ve already described, are…

  • Mixed Integer Linear Programs (MILP)

  • Mixed Integer Quadratic Programs (MIQP)

  • Mixed Integer Quadratically-Constrained Programs (MIQCP)

  • Mixed Integer Second-Order Cone Programs (MISOCP)

  • Mixed Integer Non-Linear Programs (MINLP)

The Gurobi Optimizer handles all of these model classes. Note that the boundaries between them aren’t as clear as one might like, because we are often able to transform a model from one class to a simpler class.

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. These two features are also addressed in the examples poolsearch.m and multiobj.m, respectively.

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. You will find more information about this feature in section Relaxing for feasibility.

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 in the reference manual. We will provide additional details on changing parameter settings in the params argument section.

Refer to params.m for an example.

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 of the reference manual.

Error Handling#

If unsuccessful, the methods of the Gurobi MATLAB interface will display an error code and an error message. A list of possible error codes can be found in the Error Code table in the reference manual.

Environments and license parameters#

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 licensing parameters through an optional params argument (also through a struct). This argument allows you to solve the given problem on a Gurobi Compute Server, on Gurobi Instant Cloud, or using a Gurobi Cluster Manager. We will discuss this topic further in the params 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).