These directories contain links between the GAMS modeling system (http://www.gams.com) and some COIN-OR solvers.

For requirements and installation instruction see the file INSTALL.
For license information see the file LICENSE.

=== Introduction ===

Currently for the following solvers links are available:
* CoinGlpk: Gnu Linear Programming Kit
* CoinCbc:  Coin Branch and Cut code
* Ipopt: Interior Point Optimizer

There are known to work under Linux (32 and 64 bit), Windows (32 bit), and Darwin (only CoinGlpk and CoinCbc).

The GAMS/COIN-OR solvers implement a subset of all possible GAMS parameters.
Not all bells and whistles of regular GAMS solvers are part of the COIN/OSI interface.
Also, the solution passed back to GAMS can't be exactly qualified for MIP problems.
It is not clear if a model solved to optimality (model status 1) or if we are within the user supplied tolerance (model status 8).
The GAMS/COIN-OR solvers report for MIP problems model status 8 (INTEGER SOLUTION) whenever they find an integer solution.

=== Tests ===

The directory test contains a script that tests Cbc, Glpk, and Ipopt (if available) on the models
* trnsport (small LP)
* thai (small MIP)
* abel (small NLP)
from the GAMS model library.
The models are chosen such that they can also be run with a gams demo licence.
A test is passed when the optimal value found by Cbc or Glpk coincides with the one from CPLEX (within a gap tolerance of 1%).
For IPOPT a test is passed when the optimal value is within a tolerance of 1% of the known optimum.
Since there is no CPLEX on Darwin, these tests will not work on Darwin systems.

If you have installed Cbc, Glpk, or IPOPT in your GAMS system, then you can also use the GAMS test library to run a set of tests.
For that, follow the following steps:
1. Get the quality tests:
	testlib quality  (where the program testlib is located in your GAMS system directory)
2. Add the COIN-OR solvers to the set of "master solvers" by changing line 125 of quality.gms to
	SET solver 'master set of solvers' / system.solverNames , Glpk , Cbc /;
3. Let him skip the tests that check for the correct handling of SOS and semicontinuous variables
   (Glpk does not support both, the Cbc interface does not support semicontinuous variables yet) by adding around line 412:
	skip("cbc","semicon1")=yes;
	skip("cbc","sl4scon1")=yes;
	skip("glpk","sos1a")=yes;
	skip("glpk","sl4sos1a")=yes;
	skip("glpk","semicon1")=yes;
	skip("glpk","sl4scon1")=yes;
4. Run the tests (for the solvers you have installed):
	gams quality --suite lp --solver cbc
	gams quality --suite lp --solver glpk
	gams quality --suite mip --solver cbc
	gams quality --suite mip --solver glpk
	gams quality --suite nlp --solver ipopt
	At the end of output you should see something like "Congratulations!  All ... tests passed.".
	Otherwise it will report how many tests failed.	

=== Passing parameters to the Coin solvers ===

The following standard GAMS parameters are supported:
- iterlim: Maximum number of solver iterations
- reslim: Maximum time in seconds
- nodlim (only Cbc): Maximum number of nodes.
- optca (only Cbc): Absolute optimality criterion for a MIP.
    This is translated into the Cbc option CbcAllowableGap.
- optcr (only Glpk): Relative optimality criterion for a MIP.
    This is translated into the Glpk option TOLOBJ.
    
You can set these parameters either as an argument to your gams call on the command line,
or by writing model.parametername = ... in front of the solve statement in your gams model.

For more parameters that can be set, see src/Cbc/optcbc.gms, src/Glpk/optglpk.gms, and the IPOPT documentation.

= Writing an MPS file =

For debugging and reproducing bugs of the GAMS/OSI interface, the user can write out the model in MPS format.
You can do that by setting the parameter "writemps" to the name of the mpsfile that you want to write.
