Gurobi Mex: A MATLAB interface for Gurobi
From Wikimization
(→Callbacks) |
(Update for Gurobi Mex 1.20) |
||
Line 1: | Line 1: | ||
- | [[Image:Gurobi_matlab_logos.jpg|right]] Gurobi Mex is a MATLAB interface for Gurobi | + | [[Image:Gurobi_matlab_logos.jpg|right]] Gurobi Mex is a MATLAB interface for Gurobi 2 and 3 written by [http://www.caam.rice.edu/ Wotao Yin]. It calls [http://www.gurobi.com/ Gurobi] to solve linear/mixed-integer optimization problems. Gurobi is one of the leading linear and mixed integer programming solvers. Gurobi offers [http://www.gurobi.com/html/freetrial.html free trial], and its full version is [http://www.gurobi.com/html/academic.html free for academic usage]. |
The interface is open source and subject to [http://creativecommons.org/licenses/by-sa/3.0/us/ 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. | The interface is open source and subject to [http://creativecommons.org/licenses/by-sa/3.0/us/ 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. | + | Its current version is 1.20 published on April 25, 2010. It supports both Gurobi versions 2 and 3. |
---- | ---- | ||
Line 19: | Line 19: | ||
== Download, Installation, and Limitations == | == Download, Installation, and Limitations == | ||
- | [http://www.caam.rice.edu/~wy1/gurobi_mex/download_request.html Download C source code and MATLAB examples, the latest version] | + | [http://www.caam.rice.edu/~wy1/gurobi_mex/download_request.html Download C source code and MATLAB examples, the latest version 1.20] |
- | v1. | + | [http://www.caam.rice.edu/~wy1/gurobi_mex/download_request.html v1.20] New features: [http://www.caam.rice.edu/~wy1/links/mex_ctrl_c_trick/ Ctrl-C detection], Gurobi 3 support. Improved error and exception handling. Empty array [] is returned when an output argument is not available (due to optimization failures or errors). Fixed display interval. |
- | + | ||
- | + | ||
+ | === History === | ||
+ | [http://www.caam.rice.edu/~wy1/gurobi_mex/gurobi_mex_v1.10.zip v1.10] New features: callback, runtime progress output, flexible log file, flexible input types, more options. Part of the code was contributed by ''Tomáš Strnad''. | ||
Known bug: print an empty line even if options '''DisplayInterval''' and '''Display''' are both set to 0. Fix: remove Line 736 of ''gurobi_mex.c'': mexPrintf("\n"); | Known bug: print an empty line even if options '''DisplayInterval''' and '''Display''' are both set to 0. Fix: remove Line 736 of ''gurobi_mex.c'': mexPrintf("\n"); | ||
- | === History === | ||
[http://www.caam.rice.edu/~wy1/gurobi_mex/gurobi_mex_v1.05.zip v1.05] Major bug fix: char array of constraint sense has been fixed | [http://www.caam.rice.edu/~wy1/gurobi_mex/gurobi_mex_v1.05.zip v1.05] Major bug fix: char array of constraint sense has been fixed | ||
Line 41: | Line 40: | ||
=== Future Release === | === Future Release === | ||
- | + | Please send your suggested features to Wotao Yin (''wotao.yin AT rice.edu''). | |
- | === | + | === Install Gurobi Mex in MATLAB === |
- | + | ||
- | + | ||
- | + | ==== Preparation ==== | |
+ | Refer to [http://www.gurobi.com/doc/30/quickstart/node1.html Gurobi's installation guide]. Please make sure that proper environment variables are set, and your copy of Gurobi has a license and been successfully validated. | ||
- | + | ==== Special Update for Gurobi 2 ==== | |
+ | Uncomment Line 19 of gurobi_mex.c because GRB_SUBOPTIMAL is not part of Gurobi 2. It is introduced in Gurobi 3. | ||
- | + | ==== Compiling Gurobi Mex Under Windows ==== | |
+ | |||
+ | mex -O -I"<gurobi include path>" gurobi_mex.c "<gurobi C library file>" "<MATLAB libut.lib>" | ||
+ | |||
+ | For '''64-bit MATLAB''', please add option "-largeArrayDims". | ||
+ | |||
+ | Example for Gurobi 3.00, MSVC2008, MATLAB 2009B, and 32-bit Windows | ||
+ | |||
+ | mex -O -I"C:\Gurobi300\win32\include" gurobi_mex.c "C:\Gurobi300\win32\lib\gurobi30.lib" "C:\Program Files\MATLAB\R2009b\extern\lib\win32\microsoft\libut.lib" | ||
- | Example of path of gurobi20.lib: ''C:\Users\[Login Name]\Programs\Gurobi200\win32\lib\gurobi20.lib'' | ||
==== Under Unix ==== | ==== Under Unix ==== | ||
- | mex -O -I"<gurobi include path>" gurobi_mex.c -L"<gurobi lib path>" - | + | mex -O -I"<gurobi include path>" gurobi_mex.c -L"<gurobi lib path>" -l<gurobi C library file> -lut |
+ | |||
+ | For '''64-bit MATLAB''', please add option "-largeArrayDims". | ||
- | + | Example for Gurobi 3.00, GCC, MATLAB 2009B, and 64-bit Linux | |
- | + | mex -O -I"/opt/gurobi300/linux64/include" gurobi_mex.c -L"/opt/gurobi300/linux64/lib" -lgurobi30 -lut -largeArrayDims | |
- | Example of library path: ''/opt/gurobi200/linux64/lib'' | ||
==== Tested platforms ==== | ==== Tested platforms ==== | ||
Line 71: | Line 78: | ||
We found trouble with MATLAB's built-in ''lcc'' to link with Gurobi's library. | We found trouble with MATLAB's built-in ''lcc'' to link with Gurobi's library. | ||
- | |||
- | Please make sure that the dynamic library of Gurobi 2.x is in system path and the license of Gurobi is valid. | ||
== Syntax == | == Syntax == | ||
Line 134: | Line 139: | ||
** 11 for user interruption | ** 11 for user interruption | ||
** 12 for numerical difficulties | ** 12 for numerical difficulties | ||
+ | ** 13 for suboptimal solution (Gurobi 3 and later) | ||
* '''output''': structure contains the following fields | * '''output''': structure contains the following fields | ||
** '''output.IterCount''': number of Simplex iterations | ** '''output.IterCount''': number of Simplex iterations | ||
Line 143: | Line 149: | ||
Callbacks are useful to obtain the progress of Gurobi (e.g., by calling GRBcbget) and to modify its behavior during runtime (e.g., by calling GRBcbcut and GRBcbsolution). | Callbacks are useful to obtain the progress of Gurobi (e.g., by calling GRBcbget) and to modify its behavior during runtime (e.g., by calling GRBcbcut and GRBcbsolution). | ||
- | Gurobi Mex implements a callback function ''mycallback'' to obtain Gurobi's progress messages and print them on the MATLAB screen. The print frequency is set in options.DisplayInterval (in seconds). | + | Gurobi Mex implements a callback function ''mycallback'' to obtain Gurobi's progress messages and print them on the MATLAB screen. The print frequency is set in options.DisplayInterval (in seconds). The same function is also used to detect user input Ctrl-C. |
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]. |
Revision as of 02:34, 25 April 2010
Gurobi Mex is a MATLAB interface for Gurobi 2 and 3 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. Gurobi offers free trial, and its full version is free for academic usage.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.20 published on April 25, 2010. It supports both Gurobi versions 2 and 3.
Contents |
Model
min/max c'x subject to Ax [>= / <= / =] b, lb <= x <= ub, x(i) is [continuous / binary / integer / semi-continuous / semi-integer].
Download, Installation, and Limitations
Download C source code and MATLAB examples, the latest version 1.20
v1.20 New features: Ctrl-C detection, Gurobi 3 support. Improved error and exception handling. Empty array [] is returned when an output argument is not available (due to optimization failures or errors). Fixed display interval.
History
v1.10 New features: callback, runtime progress output, flexible log file, flexible input types, more options. Part of the code was contributed by Tomáš Strnad. Known bug: print an empty line even if options DisplayInterval and Display are both set to 0. Fix: remove Line 736 of gurobi_mex.c: mexPrintf("\n");
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.
Future Release
Please send your suggested features to Wotao Yin (wotao.yin AT rice.edu).
Install Gurobi Mex in MATLAB
Preparation
Refer to Gurobi's installation guide. Please make sure that proper environment variables are set, and your copy of Gurobi has a license and been successfully validated.
Special Update for Gurobi 2
Uncomment Line 19 of gurobi_mex.c because GRB_SUBOPTIMAL is not part of Gurobi 2. It is introduced in Gurobi 3.
Compiling Gurobi Mex Under Windows
mex -O -I"<gurobi include path>" gurobi_mex.c "<gurobi C library file>" "<MATLAB libut.lib>"
For 64-bit MATLAB, please add option "-largeArrayDims".
Example for Gurobi 3.00, MSVC2008, MATLAB 2009B, and 32-bit Windows
mex -O -I"C:\Gurobi300\win32\include" gurobi_mex.c "C:\Gurobi300\win32\lib\gurobi30.lib" "C:\Program Files\MATLAB\R2009b\extern\lib\win32\microsoft\libut.lib"
Under Unix
mex -O -I"<gurobi include path>" gurobi_mex.c -L"<gurobi lib path>" -l<gurobi C library file> -lut
For 64-bit MATLAB, please add option "-largeArrayDims".
Example for Gurobi 3.00, GCC, MATLAB 2009B, and 64-bit Linux
mex -O -I"/opt/gurobi300/linux64/include" gurobi_mex.c -L"/opt/gurobi300/linux64/lib" -lgurobi30 -lut -largeArrayDims
Tested platforms
- 64-bit Ubuntu Linux 9.10, 64-bit MATLAB, and gcc.
- 32-bit Windows, 32-bit MATLAB, and gcc (part of free Mingw/GnuMex).
- 32-bit Windows, 32-bit MATLAB, and MSVC 2008 SP1 (the express Edition is free).
- 64-bit Windows, 64-bit MATLAB, and MSVC 2008 SP1 (the express Edition is free). Courtesy of Imre Polik.
We found trouble with MATLAB's built-in lcc to link with Gurobi's library.
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.
- Gurobi takes a dense vector for this input. If a sparse vector is specified, it is converted to full by Gurobi Mex.
- 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 Callback 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. For complete silence, both DisplayInterval and Display need to be set to 0.
- 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
- 13 for suboptimal solution (Gurobi 3 and later)
- 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
Callbacks are useful to obtain the progress of Gurobi (e.g., by calling GRBcbget) and to modify its behavior during runtime (e.g., by calling GRBcbcut and GRBcbsolution).
Gurobi Mex implements a callback function mycallback to obtain Gurobi's progress messages and print them on the MATLAB screen. The print frequency is set in options.DisplayInterval (in seconds). The same function is also used to detect user input Ctrl-C.
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.
License
Creative Commons Attribution-Share Alike 3.0 United States License Allow commercial use of this work. Permit others to copy, distribute, display, and perform the work, including for commercial purposes. Allow modification, as long as others share alike. Permit others to distribute derivative works only under the same license or one compatible with the one that governs the licensor's work.