# Gurobi Mex: A MATLAB interface for Gurobi

(Difference between revisions)
 Revision as of 13:56, 24 January 2010 (edit)m (→Example 2. Integer programming)← Previous diff Revision as of 14:06, 24 January 2010 (edit) (undo)m (→Three Examples)Next diff → Line 128: Line 128: Information for Gurobi callbacks can be found [http://www.gurobi.com/html/doc/refman/node80.html here] in Gurobi's help. An example can be found [http://www.gurobi.com/html/doc/exampletour/node8.html here]. Information for Gurobi callbacks can be found [http://www.gurobi.com/html/doc/refman/node80.html here] in Gurobi's help. An example can be found [http://www.gurobi.com/html/doc/exampletour/node8.html here]. - == Three Examples == + == Four Examples == === Example 1. Linear programming === === Example 1. Linear programming === Line 186: Line 186: 0 -1.5000 -0.5000 0 -1.5000 -0.5000 - Log file: ''gurobi_mex.log''. MPS file: ''test_gurobi_mex_LP.mps''. + Log file: ''test_gurobi_mex_LP.log''. MPS file: ''test_gurobi_mex_LP.mps''. === Example 2. Integer programming === === Example 2. Integer programming === Line 247: Line 247: ErrorMsg: [] ErrorMsg: [] - Log file: gurobi_mex.log. MPS file: test_gurobi_mex_MIP.mps. + Log file: ''test_gurobi_mex_MIP.log''. MPS file: ''test_gurobi_mex_MIP.mps''. - === Example 3. Compressive sensing === + === Example 3. Feasibility test === + Problem: +
+                                                                                   Find a solution or report infeasibility of
+
+                                                                                   5 x1 + 4 x2        + 5 x4 >= -21
+                                                                                   5 x1 + 3 x2 + 1 x3 + 4 x4  = -14
+                                                                                   3 x1 + 5 x2 + 2 x3 - 5 x4  =  11
+                                                                                   x1,x2,x3,x4 >= 0.
+
+ MATLAB code: +
+                                                                                   c = [];                    % use [] or 0 for null objective
+                                                                                   objtype = -1;              % 1 for minimize, -1 for maximize
+                                                                                   A =  sparse([5 4 0 5; 5 3 1 4; 3 5 2 -5]);
+                                                                                   b = [-21; -14; 11];        % stands for uniformly 0 lower bound
+                                                                                   lb = [];
+                                                                                   ub = [];                   % stands for uniformly inf upper bound
+                                                                                   contypes = '<>';
+                                                                                   vtypes = [];               % same as vtypes = 'CCCC'; empty means 'C...C'
+
+                                                                                   clear opts
+                                                                                   opts.FeasibilityTol = 1e-6;
+                                                                                   opts.Presolve = -1;        % -1 - auto, 0 - no, 1 - conserv, 2 - aggressive
+                                                                                   opts.Display = 1;
+                                                                                   opts.LogFile = 'test_gurobi_mex_Feasibility.log';
+                                                                                   opts.WriteToFile = 'test_gurobi_mex_Feasibility.mps';
+
+                                                                                   [x,val,exitflag,output] = gurobi_mex(c,objtype,A,b,contypes,lb,ub,vtypes,opts);
+
+ + Results: +
+                                                                                   disp('Solution:');disp(x')
+                                                                                   disp('Optimal obj value:');disp(val)
+                                                                                   disp('Exit flag:');disp(exitflag)
+
+                                                                                   Model is infeasible. No solution will be returned.
+
+                                                                                   Solution:
+                                                                                   Optimal obj value:
+                                                                                   Exit flag:
+                                                                                   3
+
+ Log file: ''test_gurobi_mex_Feasibility.log''. MPS file: ''test_gurobi_mex_Feasibility.mps''. + + === Example 4. Compressive sensing === See example m-file ''test_gurobi_mex_CS.m''. See example m-file ''test_gurobi_mex_CS.m''.

## Revision as of 14:06, 24 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/gurobi20.lib>"
```

For 64-bit MATLAB, please add option "-largeArrayDims".

#### Under Unix

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

For 64-bit MATLAB, please add option "-largeArrayDims".

#### 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 that the dynamic library of Gurobi 2.x is in system path and the license of Gurobi is valid.

## 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.
[] (empty array) means uniformly 0 coefficients, and scalar means all coefficients equal to scalar.
• objtype: 1 (minimization) or -1 (maximization).
• A: constraint coefficient matrix, double, sparse.
• b: constraint right-hand side vector, double.
If a sparse vector is specified, it is converted to full. This conversion takes time and memory space.
• contypes: constraint types. Char array of '>', '<', '='.
Warning: '>=' means two constraints instead of one an inequality constraint.
Example: '>><=' means the first two constraints have greater or equal to signs, the third has less than or equal to sign, and the last is an equality constraint.
If a single character is specified, all constraints are uniformly signed to the corresponding type.
• lb: variable lower bound vector, double.
[] (empty array) means 0 lower bound. -inf means no lower bound. scalar means a uniform lower bound equal to scalar.
• ub: variable upper bound vector, double.
[] (empty array) means no (or infinity) upper bound. scalar means a uniform upper bound equal to scalar.
• 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 array) 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.
If a single character is specified, all variables are uniformly signed to the corresponding type.
• 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.MIPGap: see Gurobi's parameter help.
• options.LPMethod: see Gurobi's parameter help.
• options.Presolve: see Gurobi's parameter help.
• options.TimeLimit: see Gurobi's parameter help.
• options.Threads: see Gurobi's parameter help.
• options.DisplayInterval: Gurobi's screen output interval. See Gurobi's parameter help. 0 means no Gurobi message.
• options.Display: Gurobi Mex's screen output level. 0 for no output; 1 for error only; 2 (default) for normal output.
• options.LogFile: char array of the name of log file. options.UseLogfile is no longer used.
• options.WriteToFile: char array of 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
• lambda: Lagrange multipliers. Because solving MIPs gives no such output, do not ask for this output for MIPs.

## Callbacks

Callback are useful to obtain the progress of Gurobi and to modify its behavior during runtime. Gurobi Mex uses a callback function mycallback to obtain Gurobi's progress messages and print them on the MATLAB screen. The print frequency is set by options.DisplayInterval (in seconds).

Information for Gurobi callbacks can be found here in Gurobi's help. An example can be found here.

## Four Examples

### Example 1. Linear programming

This example is borrowed from MATLAB's linprog help.

Problem:

``` 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'; [] 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.LogFile = 'test_gurobi_mex_LP.log';
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: test_gurobi_mex_LP.log. MPS file: test_gurobi_mex_LP.mps.

### Example 2. Integer programming

This example is borrowed from mip1_c.c of Gurobi 2.0.

Problem:

``` 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.LogFile = 'test_gurobi_mex_MIP.log';
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, unless model fix is called.

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: test_gurobi_mex_MIP.log. MPS file: test_gurobi_mex_MIP.mps.

### Example 3. Feasibility test

Problem:

```Find a solution or report infeasibility of

5 x1 + 4 x2        + 5 x4 >= -21
5 x1 + 3 x2 + 1 x3 + 4 x4  = -14
3 x1 + 5 x2 + 2 x3 - 5 x4  =  11
x1,x2,x3,x4 >= 0.
```

MATLAB code:

``` c = [];                    % use [] or 0 for null objective
objtype = -1;              % 1 for minimize, -1 for maximize
A =  sparse([5 4 0 5; 5 3 1 4; 3 5 2 -5]);
b = [-21; -14; 11];        % stands for uniformly 0 lower bound
lb = [];
ub = [];                   % stands for uniformly inf upper bound
contypes = '<>';
vtypes = [];               % same as vtypes = 'CCCC'; empty means 'C...C'

clear opts
opts.FeasibilityTol = 1e-6;
opts.Presolve = -1;        % -1 - auto, 0 - no, 1 - conserv, 2 - aggressive
opts.Display = 1;
opts.LogFile = 'test_gurobi_mex_Feasibility.log';
opts.WriteToFile = 'test_gurobi_mex_Feasibility.mps';

[x,val,exitflag,output] = gurobi_mex(c,objtype,A,b,contypes,lb,ub,vtypes,opts);
```

Results:

``` disp('Solution:');disp(x')
disp('Optimal obj value:');disp(val)
disp('Exit flag:');disp(exitflag)

Model is infeasible. No solution will be returned.

Solution:
Optimal obj value:
Exit flag:
3
```

Log file: test_gurobi_mex_Feasibility.log. MPS file: test_gurobi_mex_Feasibility.mps.

### Example 4. Compressive sensing

See example m-file test_gurobi_mex_CS.m.

## 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. Gurobi Mex: A MATLAB interface for Gurobi, URL: http://www.caam.rice.edu/~wy1/gurobi_mex, 2009-2010.