# Gurobi Mex: A MATLAB interface for Gurobi

(Difference between revisions)
 Revision as of 21:17, 19 January 2010 (edit) (Initial creation)← Previous diff Revision as of 21:25, 19 January 2010 (edit) (undo) (→Input Description - Better styling)Next diff → Line 65: Line 65: == Input Description == == Input Description == - '''c''': objective coefficient vector, double. + * '''c''': objective coefficient vector, double. - + * '''objtype''': 1 (minimization) or -1 (maximization). - '''objtype''': 1 (minimization) or -1 (maximization). + * '''A''': constraint coefficient matrix, double, sparse. - + * '''b''': constraint right-hand side vector, double. - '''A''': constraint coefficient matrix, double, sparse. + * '''contypes''': constraint types. Char array of '>', '<', '='. Example: '>><=' means the first two constraints have ">= "signs, the third has "<=" sign, and the last is an equality constraint. Warning: '>=' means two constraints instead of one an inequality constraint. - + * '''lb''': variable lower bound vector, double. Empty means 0 lower bound. - '''b''': constraint right-hand side vector, double. + * '''ub''': variable upper bound vector, double. Empty means no (or inf) upper bound. - + * '''vartypes''': variable types. Char array of chars 'C', 'B', 'I', 'S', 'N'. C for continuous; B for binary; I for integer; S for semi-continuous; N for semi-integer. Empty means all variables are continuous. Example: 'CCCCC' stands for five continuous variables. Note that semi-continuous variables are variables that must take a value between their minimum and maximum or zero. Semi-integer variables are similarly defined. - '''contypes''': constraint types. Char array of '>', '<', '='. Example: '>><=' means the first two constraints have ">= "signs, the third has "<=" sign, and the last is an equality constraint. Warning: '>=' means two constraints instead of one an inequality constraint. + * '''options''': ''optional'' structure that may contain one or more of the following fields: (see [http://www.gurobi.com/html/doc/refman/node378.html Gurobi's parameter help] for their allowed values. Also, see [[Gurobi_Mex:_A_MATLAB_interface_for_Gurobi#Three_Examples|examples]] below.) - + ** '''options.IterationLimit''': see Gurobi's parameter help - '''lb''': variable lower bound vector, double. Empty means 0 lower bound. + ** '''options.FeasibilityTol''': see Gurobi's parameter help - + ** '''options.IntFeasTol''': see Gurobi's parameter help - '''ub''': variable upper bound vector, double. Empty means no (or inf) upper bound. + ** '''options.OptimalityTol''': see Gurobi's parameter help - + ** '''options.LPMethod''': see Gurobi's parameter help - '''vartypes''': variable types. Char array of chars 'C', 'B', 'I', 'S', 'N'. C for continuous; B for binary; I for integer; S for semi-continuous; N for semi-integer. Empty means all variables are continuous. Example: 'CCCCC' stands for five continuous variables. Note that semi-continuous variables are variables that must take a value between their minimum and maximum or zero. Semi-integer variables are similarly defined. + ** '''options.Presolve''': see Gurobi's parameter help - + ** '''options.Display''': controls the level of screen output. 0 for no output; 1 for no output unless error; 2 (default) for normal output. - '''options''': (optional) structure that may contain one or more of the following fields: (see [http://www.gurobi.com/html/doc/refman/node378.html Gurobi's parameter help] for their allowed values. Also, see [[Gurobi_Mex:_A_MATLAB_interface_for_Gurobi#Three_Examples|examples]] below.) + ** '''options.UseLogfile''': this field (no matter what value is assigned to it) lets Gurobi generate a log file. The file name is "gurobi_mex.log" by default. To change the name, modify field LOGFILENAME in the source file. - + ** '''options.WriteToFile''': char array; contains the name of the file to which optimization data is written. See Gurobi C-Reference entry [http://www.gurobi.com/html/doc/refman/node35.html GRBwrite] for supported formats. This option helps one verify whether the model is correctly passed to Gurobi. - options.IterationLimit: see Gurobi help + - options.FeasibilityTol: see Gurobi help + - options.IntFeasTol: see Gurobi help + - options.OptimalityTol: see Gurobi help + - options.LPMethod: see Gurobi help + - options.Presolve: see Gurobi help + - options.Display: controls the level of screen output. 0 for no output; 1 for no output unless error; 2 (default) for normal output. + - options.UseLogfile: this field (no matter what value is assigned to it) lets Gurobi generate a log file. The file name is "gurobi_mex.log" by default. To change the name, modify field LOGFILENAME in the source file. + - options.WriteToFile: char array; contains the name of the file to which optimization data is written. See Gurobi C-Reference entry [http://www.gurobi.com/html/doc/refman/node35.html GRBwrite] for supported formats. This option helps one verify whether the model is correctly passed to Gurobi. + == Output Description == == Output Description ==

## Revision as of 21:25, 19 January 2010

Gurobi Mex is a MATLAB interface for Gurobi 2 written by Wotao Yin. It calls Gurobi to solve linear/mixed-integer optimization problems. Gurobi is one of the leading linear and mixed integer programming solvers.

The interface is open source and subject to Creative Commons Attribution-Share Alike 3.0 United States License. It is a tool for MATLAB users to quickly call Gurobi, and its source code serves as a start point for those who want to develop a customized MATLAB interface for Gurobi.

Its current version is 1.05 published on Jan 2, 2010.

## Model

```min/max  c'x
subject to
Ax  [>= / <= / =]  b,
lb <= x <= ub,
x(i) is [continuous / binary / integer / semi-continuous / semi-integer].
```

### History

v1.05 Major bug fix: char array of constraint sense has been fixed

v1.04 support writing model to files in various formats such as MPS, REW, LP, ...

v1.03 support log file

v1.02 fixed a memory leak issue

v1.01 update: support output dual solution lambda; allow vartypes to be empty (for all continuous variables).

v1.00 initial version.

### Building Gurobi Mex in MATLAB

#### Under Windows

```mex -O -I"<gurobi include path>" gurobi_mex.c "<absolute path and filename of gurobi20.lib>"
```

#### Under Unix

```mex -O -I"<gurobi include path>" gurobi_mex.c -L"<gurobi lib path>" -lgurobi20
```

#### Tested platforms

Windows 32-bit and gcc (included in free Mingw/GnuMex); Ubuntu Linux 9.10 64-bit and gcc.

MATLAB's built-in lcc cannot link with Gurobi.

Please make sure the dynamic library of Gurobi 2.x is in system path.

## Syntax

``` x = gurobi_mex(c, objtype, A, b, contypes, lb, ub, vartypes);
x = gurobi_mex(c, objtype, A, b, contypes, lb, ub, vartypes, options);
[x,val] = gurobi_mex(...);
[x,val,flag] = gurobi_mex(...);
[x,val,flag,output] = gurobi_mex(...);
[x,val,flag,output,lambda] = gurobi_mex(...);
```

## Input Description

• c: objective coefficient vector, double.
• objtype: 1 (minimization) or -1 (maximization).
• A: constraint coefficient matrix, double, sparse.
• b: constraint right-hand side vector, double.
• contypes: constraint types. Char array of '>', '<', '='. Example: '>><=' means the first two constraints have ">= "signs, the third has "<=" sign, and the last is an equality constraint. Warning: '>=' means two constraints instead of one an inequality constraint.
• lb: variable lower bound vector, double. Empty means 0 lower bound.
• ub: variable upper bound vector, double. Empty means no (or inf) upper bound.
• vartypes: variable types. Char array of chars 'C', 'B', 'I', 'S', 'N'. C for continuous; B for binary; I for integer; S for semi-continuous; N for semi-integer. Empty means all variables are continuous. Example: 'CCCCC' stands for five continuous variables. Note that semi-continuous variables are variables that must take a value between their minimum and maximum or zero. Semi-integer variables are similarly defined.
• options: optional structure that may contain one or more of the following fields: (see Gurobi's parameter help for their allowed values. Also, see examples below.)
• options.IterationLimit: see Gurobi's parameter help
• options.FeasibilityTol: see Gurobi's parameter help
• options.IntFeasTol: see Gurobi's parameter help
• options.OptimalityTol: see Gurobi's parameter help
• options.LPMethod: see Gurobi's parameter help
• options.Presolve: see Gurobi's parameter help
• options.Display: controls the level of screen output. 0 for no output; 1 for no output unless error; 2 (default) for normal output.
• options.UseLogfile: this field (no matter what value is assigned to it) lets Gurobi generate a log file. The file name is "gurobi_mex.log" by default. To change the name, modify field LOGFILENAME in the source file.
• options.WriteToFile: char array; contains the name of the file to which optimization data is written. See Gurobi C-Reference entry GRBwrite for supported formats. This option helps one verify whether the model is correctly passed to Gurobi.

## Output Description

x: primal solution vector; empty if Gurobi encounters errors or stops early (in this case, check output flag).

val: optimal objective value; empty if Gurobi encounters errors or stops early.

flag: value meanings:

```1 for not started
2 for optimal
3 for infeasible
4 for infeasible or unbounded
5 for unbounded
6 for objective worse than user-specified cutoff
7 for reaching iteration limit
8 for reaching node limit
9 for reaching time limit
10 for reaching solution limit
11 for user interruption
12 for numerical difficulties
```

output: structure contains the following fields

```output.IterCount: number of Simplex iterations
output.Runtime: running time in seconds
output.ErrorMsg: contains Gurobi error message, if any
output.lambda: Lagrange multipliers; DO NOT ask for this output for MIPs.
```

## Three Examples

### Example 1

#### A linear program (borrowed from MATLAB's linprog help)

```min –5 x1 – 4 x2 –6 x3,
subject to
x1 – x2 + x3 ≤ 20
3 x1 + 2 x2 + 4 x3 ≤ 42
3 x1 + 2 x2 ≤ 30
0 ≤ x1, 0 ≤ x2, 0 ≤ x3.
```

MATLAB code:

```c = [-5; -4; -6];
objtype = 1;
A =  sparse([1 -1  1; 3  2  4; 3  2  0]);
b = [20; 42; 30];
lb = zeros(3,1); % same as lb = [];
ub = [];
contypes = '<<<';
vtypes = []; % same as vtypes = 'CCC'; empty means 'C...C'
```
```clear opts
opts.IterationLimit = 20;
opts.FeasibilityTol = 1e-6;
opts.IntFeasTol = 1e-5;
opts.OptimalityTol = 1e-6;
opts.LPMethod = 1; % 0 - primal, 1 - dual
opts.Presolve = -1; % -1 - auto, 0 - no, 1 - conserv, 2 - aggressive
opts.Display = 1;
opts.UseLogfile = []; % as long as opts.UseLogfile exists, a log file is created
opts.WriteToFile = 'test_gurobi_mex_LP.mps';
```
```[x,val,exitflag,output,lambda] = gurobi_mex(c,objtype,A,b,contypes,lb,ub,vtypes,opts);
```

Results:

```x' =
0 15 3
val =
-78
exitflag =
2
output =
IterCount: 2
Runtime: 0
ErrorMsg: []
lambda' =
0   -1.5000   -0.5000
Log file: gurobi_mex.log.
MPS file: test_gurobi_mex_LP.mps.
```

### Example 2

#### Integer program (borrowed from mip1_c.c of Gurobi 2.0)

```max  x + y + 2z,
subject to
x + 2 y + 3 z <= 4
x +   y       >= 1
x, y, z binary.
```

MATLAB code:

```c = [1; 1; 2];
objtype = -1; % 1 for minimize, -1 for maximize
A =  sparse([1 2 3; 1 1 0]);
b = [4; 1];
lb = [];
ub = [];
contypes = '<>';
vtypes = 'BBB';
```
```clear opts
opts.IterationLimit = 20;
opts.FeasibilityTol = 1e-6;
opts.IntFeasTol = 1e-5;
opts.OptimalityTol = 1e-6;
opts.LPMethod = 1; % 0 - primal, 1 - dual
opts.Presolve = -1; % -1 - auto, 0 - no, 1 - conserv, 2 - aggressive
opts.Display = 1;
opts.UseLogfile = []; % as long as opts.UseLogfile exists, a log file is created
opts.WriteToFile = 'test_gurobi_mex_MIP.mps';
```
```[x,val,exitflag,output] = gurobi_mex(c,objtype,A,b,contypes,lb,ub,vtypes,opts);
```

Gurobi does not give lambda (Pi, or Lagrange multipliers) for MIPs, without calling modelfix().

Results:

```disp('Solution:');disp(x')
disp('Optimal obj value:');disp(val)
disp('Exit flag:');disp(exitflag)
disp('Optimization info:');disp(output)
```
```Solution:
1     0     1
Optimal obj value:
3
Exit flag:
2
Optimization info:
IterCount: 0
Runtime: 0
ErrorMsg: []
Log file: gurobi_mex.log.
MPS file: test_gurobi_mex_MIP.mps.
```

### Example 3

A compressive sensing example. See example m-file test_gurobi_mex_CS.m in the package.

## Feedback

I would be delighted to hear from you if you find Gurobi Mex useful, or if you have any suggestions, contributions, or bug reports. Please send these to Wotao Yin (wotao.yin AT rice.edu)

## How to cite

Wotao Yin. Software: Gurobi Mex, URL: www.caam.rice.edu/~wy1/gurobi_mex, 2009-2010.