22.9.2 Major release (December 01, 2008)

Acknowledgements

We would like to thank all of our users who have reported problems and made suggestions for improving this release. In particular, we thank Stefan Boeters, Wolfgang Britz, Alexander Gocht, Josef Kallrath, Erwin Kalvelagen, Todd Munson, Yiqi Zhu.

Future Deprecation

We are planning to drop the following systems from our next GAMS Distribution 23.0. If you object please submit an email to support@gams.com!

CONOPT1 and CONOPT 2 (old versions of CONOPT)
DEA (capability will be offered by a more general scenario framework)
GAMSBAS
MPSWRITE
MILESOLD (old version of MILES)
MINOS5 (old version of MINOS)
OSL1 and OSL2 (old versions of OSL)
PATHOLD (old version of PATH)

GAMS System

GAMS

GAMS scratch file extension. Starting with distribution 22.9 the default file extension of intermediate files located in the 225? directories is .dat. The scratch extension is a parameter that can be changed with the GAMS option ScrExt, e.g gams trnsport scrext=tmp. Within GAMS code you get the scratch extension using %gams.scrext%.
GAMS Parameter ETlim (Elapsed Time limit). A GAMS job will terminate if the elapsed time in seconds exceeds the value of ETlim. The job elapsed time is checked before the execution of a $call, execute or solve statement. The system will terminate with a compilation or execution error if the limit (default INF) is reached.
GAMS Parameter AppendExpand (short form AE). Allows to control the file opening of the expand file. A value of 0 will open with rewrite, a value of 1, the default, will open with append.
New solveopt=clear option. A third option has been added to option solveopt=xxx. The related model attribute <model>.solveopt=n has been adjusted to match the new option values. If the model attribute is set to NA (default), the setting of the corresponding option statement will be used to determine the way solutions values are loaded back into the GAMS data space. The possible values are (the numeric value for the model attribute are given in parenthesis):
- replace (0) all equations appearing in the model list will be completely replaced by the new model results. Variables are only replaced if they appear in the final model.
- merge (1) the new model results are merged into the existing structures. This is the default.
- clear (2) similar to the replace option; in addition, variables appearing in the symbolic equations but squeezed out in the final model, are removed.
New solPrint=silent option. A third option has been added to option solPrint=xxx. The related model attribute <model>.solPrint=n and the GAMS parameter solPrint=n have been adjusted to match the new option values. If the model attribute is set to NA (default), the setting of the corresponding option statement will be used to control the printing of model generation and solution information. Note that the GAMS parameter initializes the corresponding option statement values. The possible values are (the numeric value for the model attribute are given in parenthesis):
- off (0) detailed solution output is suppressed.
- on (1) the most detailed solution output. This is the default.
- silent (2) all solve related output is suppressed.
New model attributes returning elapsed time information of the solution process:
- ETsolve total elapsed time to execute a solve statement
- ETsolver elapsed time that can be attributed to the solver only
- ETalg elapsed time that can be attributed to the core algorithm
New suffix for abort.noerror. When using the suffix .noerror with the $abort statement, the error count will NOT be increased. When a save file is written, all remaining unexecuted code will be flushed. This allows effective reuse of the save file.
Added a test and error message to see if a restart file has not been closed yet when we try to use the file.

The GAMS Macro Facility

The GAMS macro facility has been inspired by the GAMS-F preprocessor for function definition developed by Ferris, Rutherford and Starkweather, 1998, 2005. The GAMS macro facility incorporates the major features of the GAMS-F preprocessor into the standard GAMS release. The GAMS macros acts like a standard macro when defined, however, its recognition for expansion is GAMS syntax driven.

Macros are widely used in computer science to define and automate structured text replacements. The GAMS macro processors functions similar to the popular C/C++ macro preprocessor. The definition takes the form

$macro name  macro body
$macro name(arg1,arg3,arg2,..) macro body with tokens arg1,..

The name of the macro has to be unique, similar to other GAMS data types like sets and parameters. A ( following immediately the macro name starts the list of replacement arguments. The macro body is not further analyzed after removing leading and trailing spaces.

The recognition and following expansion is directed by GAMS syntax. The tokens in the macro body to be replaced by the actual macro arguments follow the standard GAMS identifier conventions. For example:

$macro diff(y) system.cosh(y) - cosh(y)
$macro cosh(x) (exp(x) + exp(-x))/2
scalar z; z = diff(2/3); display z;

will expand into:

scalar z; z = system.cosh(2/3) - (exp(2/3) + exp(-2/3))/2; display z;

This expansion takes place in two steps, first GAMS recognizes diff as a macro and changes the input text to:

scalar z; z = system.cosh(2/3) - cosh(2/3); display z;

Gams will continue to process the modified input text. The first occurrence of cosh is not recognized by gams as a macro, only the second reference to cosh(2/3) will result in a second and final expansion.

The recognition of macros and expansion of arguments can further be controlled by the use of ampersands (&) in the macro body. A single ampersand (&) is used as a concatenation or separation symbol to recognize tokens to be replaced. Two ampersands (&&) immediately preceding a token will drop the most outer matching single or double quotes of the replacement argument. For example:

$macro  f(i)  sum(j, x(i,j))
$macro equ(q)  equation equ_&q; equ_&q.. q =e= 0;
equ(f(i))

will expand into:

equation equ_f(i); equ_f(i).. sum(j, x(i,j)) =e= 0;

The first step of the above expansion is shown below. GAMS will then only recognize the third occurrence of f(i) as a macro which will be expanded to give the above result.:

equation equ_f(i); equ_f(i).. f(i) =e= 0;

The actual calling arguments of macros can contain complex expressions and other macro calls. Multiple arguments are separated by commas. Pairs of parenthesis and quotes can be used freely to protect the separating comma.

$macro many(a,b) scalar x; x=a/&&b); display x;
many((3/5),'(mod(3,2)')

Note that the second argument has unbalanced parenthesis and therefor needs to be enclosed in quotes to give the result below.

scalar x; x=(3/5)/(mod(3,2)); display x;

Some macro use can result in an expansion of infinite length. For example:

$macro a  b,a
display a;

will expand into:

display b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,...

GAMS will eventually refuse to do more substitutions and issue a compilation error.

The use of deeply nested macros may require the use of aliased sets in indexed operations like sum and prod. A minor syntax extension allows the implicit use of aliases. The suffix .local on a controlling set will use an implicit alias within the scope of the indexed operation. For example:

$macro qq(i) sum(i.local, b(i))
c(q) = qq(q);

will expand into:

c(q) = sum(q.local, b(q));

The use of the .local modifier is not limited to macros and can be used in any context.

Another feature motivated by the use of macros is the implicit use of the .l suffix in data manipulation statements. This allows using the same algebra in model definitions and assignment statements. The following code snippet illustrates this feature:

$macro D(s,h) INCOME(h)*alpha[s,h]*sum{s.local, alpha[s,h]*P[s]*
.  .  .
cmkt(s)..    Y(s) =g= sum(h, D(s,h));
. .  .
$onDotL

dl(s,h) = d(s,h); display dl;

where INCOME is another macro which calls a number of other nested macros. D(s,h) is now used to define the equation cmky and is also used in an assignment after the model has been solved. The $ondotl enables the implicit .l suffix for variables. This feature was introduced to make macros more useful and is not limited to be used in macro bodies. Since this a new feature it has to be enabled. The matching $offdotl will disable this feature.

Three more switches are relevant to macros. The $show will list any GAMS macros defined. The $onmacro/$offmacro will enable or disable the expansion of macros; the default is $onmacro. Finally, the $on/offexpand will change the processing of macros appearing in the arguments of a macro call. The default operation is not to expand macros in the arguments. The switch $onexpand enables the recognition and expansion of macros in the macro argument list. $offexpand will restore the default behavior.

Macro definitions are preserved in a save/restart file and are available again when performing a continued compilation.

Comparison of GAMS-F with GAMS macros

The GAMS-F preprocessor combines aspects of traditional macros with that of functions and objects. The example 7 from the GAMS-F documentation using macros can be found in the GAMS model library under the name two3mac. Some of the main differences between GAMS macros and the GAMS-F preprocessor are:

A macro is a new GAMS data type and shares the name space of GAMS symbols, like sets, parameters, variables,etc.
Instead of using <id> == <body>; to recognize a macro, we use $macro <id> <body> with the $ in position 1.
Surrounding parenthesis are not automatically added to the macro body when the macro is expanded.
A macro is recognized and expanded anywhere a proper GAMS identifier can be used. This can be suppressed by $onmacro/offmacro.
No automatic definition of new aliased sets and their use in controlled index positions. The .local feature has been added to ensure local use and eliminates the need for new alias definitions.
No automatic equation definitions for MCP models.
The body of the macro is only used during expansion. Hence, the macro definitions are not order dependent.
Variables in macro bodies will have an implicit .L when using in assignment statements. This is not a macro expansion feature, but a new GAMS feature that needs to be activated by $onDotL/$offDotL

GAMSIDE

The model library open file no longer converts the file name to lowercase
The ViewClose command for IDECmds now allows closing for any file
Added option to execute command scripts (.cmd files) from the IDE
Pressing F3 (search again) after a search/replace will restart the replace dialog
Output of the put_utility 'title' option will be shown in the process window

GAMS Data Utilities

CHOLESKY
- Compute the Cholesky factors of a symmetric positive-definite matrix
EIGENVALUE
- Compute the eigenvalues of a symmetric matrix
EIGENVECTOR
- Compute the eigenvalues and eigenvectors of a symmetric matrix
GDXCOPY
- When we convert a gdx file using the -Replace option, and the file is open in the IDE, the IDE will be signaled to close the file and reopen the file after the conversion is complete.
GDXDUMP
- Updated documentation.
GDXVIEWER
- Allow resizing of the column width
GDXDCLIB
- Reading an aliased set could return too many elements
GDXMERGE
- Fixed a problem when we specify a list of identifiers

SCENRED2

Scenred2 is an updated and expanded version of the scenred utility for scenario reduction. Scenred2 is intended to be a replacement for the existing scenred, but we have made the newer version available as scenred2 due to some differences in the options used to control scenred's behavior. Having both available also facilitates comparisons between the two.

New features in scenred2 include:

Tree construction. Scenred could only reduce existing scenario trees, while scenred2 can create trees from collections of independent scenarios (i.e. from scenario "fans").
Visualization. Scenred2 contains new options to create input files for GNUPLOT.
Improved metrics. Tree reduction can now be carried out w.r.t. the Fortet-Mourier metric, instead of the upper bounds given by the Monge-Kantorovich metric.

Documentation

Updated McCarl GAMS User's Guide

Other

Semidefinite Programming Solver CSDP available for Windows, Linux and Macintosh on Intel distributions. Some examples are included in the GAMS Model Library:
- trnssdp (340)
- gqapsdp (339)
- maxcut (338)
Additional Lahey Fortan version of all API files does not depend on a C compiler

Model Libraries

GAMS Model Library

two3mac (341): Simple 2 x 2 x 2 General Equilibrium Model Using Macros
trnssdp (340): Solving the Transportation LP Problem using SDP
gqapsdp (339): SDP Convexifications of the Generalized Quadratic Assignment Problem
maxcut (338): Goemans/Williamson Randomized Approximation Algorithm for MaxCut

GAMS Test Library

load4 (414): Tests various file opening options for GDX files
eigvec02 (413): Test Eigenvector/Eigenvalue utilities
choles02 (412): Test 2 Cholesky utility
choles01 (411): Test 1 Cholesky utility
eigvec01 (410): Test Eigenvector utility
eigval01 (409): Test Eigenvalue utility
scnred01 (408): Basic Scenred2 test - tree construction
scensol1 (407): Basic Scenario Solver Test
gdxmerg2 (406): Bad acronym merge in gdxmerge
gdx8 (405): Bad acronym mapping
gdx7 (404): Bad acronym loading
macro01 (403): Several macro tests
assign2 (402): Test for bad assignment with .fx
mcp08 (401): Test MCP that turfs up PATH preprocessing error
convert6 (400): CONVERT test suite - hessian.gdx

Solvers

Coin-OR

New libraries
- Bonmin 0.100
- Cbc 2.2
- Glpk 4.32
- Ipopt 3.5
Scip 1.1
Mumps 4.8.3 (used by Ipopt and Bonmin)
CoinCbc can now use multiple threads (see new option "threads"). This option is available for all platforms other than Windows.
Scip supports special ordered set of type 1 and 2 (SOS1 and SOS2). Further, a new heuristic and a new cutting plane separator has been added, the preprocessing has been improved, the Clp interface revised, and bugs were fixed.

Cplex

New libraries 11.2

CPLEX 11.2 offers finer control for solution polishing. In previous versions, the only stopping criterion for solution polishing was set by the parameter PolishTime to limit time spent polishing a solution. General stopping criteria, such as the time limit, absolute MIP gap, relative MIP gap, MIP node limit or MIP integer solution limit did not apply to solution polishing.

Now, however, CPLEX 11.2 allows the user to control more finely when solution polishing terminates. In other words, the usual tolerances (EpAGap and EpGapinitialized with GAMS parameters OptCA and OptCr) and limits (IntSolLim, NodeLim and TiLim initialized with GAMS paramter NodLim and ResLim) now apply to solution polishing.

In addition to those existing parameters that now control the termination of solution polishing, there are also new parameters specific to the starting conditions for solution polishing.

With these new parameters, a user can tell CPLEX when to switch from branch & cut to solution polishing. CPLEX is able to switch after it has found a feasible solution and put into place the MIP structures needed for solution polishing. When these two conditions are met (feasible solution and structures in place), CPLEX stops branch & cut and switches to solution polishing whenever the first of these starting conditions is met:
- when CPLEX achieves a specified absolute MIP gap (PolishAfterEpAGap)
- when CPLEX achieves a specified relative MIP gap (PolishAfterEpGap)
- when CPLEX finds a specified number of integer solutions (PolishAfterIntSol)
- when CPLEX processes a specified number of nodes (PolishAfterNode)
- when CPLEX reaches a specified time limit on time spent in optimization (PolishAfterTime)
The new parameters are incompatible with the deprecated option PolishTime. If you use them together in an option file you will see an error like this:
```
  Reading parameter(s) from "C:\tmp\cplex.opt"
  
  >>  polishtime 5
      Warning line 1: deprecated option "polishtime"; Use option polishafter... for finer solution polishing control.
  >>  polishafterintsol 1
  Finished reading from "cplex.opt"
  CPLEX Error  1807: Incompatible parameters.
  polishafterintsol: current = 2100000000, default = 2100000000, minimum = 1, maximum = 2100000000
```
A few examples with the corresponding GAMS/CPLEX option file:
- As an example of how to manage time spent polishing a feasible solution, suppose the user wants to solve a problem by spending 100 seconds in branch & cut and an additional 200 seconds in polishing:
```
  TiLim 300
  PolishAfterTime 100
```
- Switch to polishing after first feasible solution:
```
  PolishAfterIntSol 1
```
- For example, the following procedure applies branch & cut until it reaches a 10% gap. Then it starts solution polishing until it narrows the gap to 2%.
```
  PolishAfterEpGap 0.1
  EpGap 0.02
```

Lindoglobal

New libraries 5.0.1.292 now also for Sun Sparc Solaris

PATH

New libraries 4.7.01 fix preprocessing bug for both MCP and NLP front ends

BDMLPD, CPLEXD and CONOPTD

Enhancements and bug fixes for the three experimental in-core communication solver links BDMLPD, CPLEXD and CONOPTD.

Solver/Platform Availability Matrix

Solver/Platform availability - 22.9 December 1, 2008
	x86 MS Windows	x86_64 MS Windows	x86 Linux	x86_64 Linux	Sun Sparc SOLARIS	Sun Sparc64 SOLARIS	Sun Intel SOLARIS	HP 9000 HP-UX 11¹	DEC Alpha Digital Unix 4.0³	IBM RS-6000 AIX 4.3	Mac PowerPC Darwin	Mac Intel32 Darwin	SGI IRIX²
ALPHAECP
BARON 8.1		32bit		32bit
BDMLP
COIN
CONOPT 3
CPLEX 11.2								10.0	8.1				9.1
DECIS						32bit
DICOPT
KNITRO 5.1		32bit				32bit
LINDOGLOBAL 5.0
LGO
MILES
MINOS
MOSEK 5								3.2
MPSGE
MSNLP						32bit
NLPEC
OQNLP		32bit		32bit
OSL V3		32bit		32bit		32bit		V2					V2
OSLSE		32bit		32bit		32bit
PATH
SBB
SNOPT
XA		32bit				32bit
XPRESS 18.00		32bit		32bit		32bit		16.10
¹⁾GAMS distribution for HP 9000/HP-UX is 22.1.
²⁾GAMS distribution for SGI IRIX is 22.3.
³⁾GAMS distribution for DEC Alpha is 22.7.

Table of Contents

22.9.2 Major release (December 01, 2008)

Acknowledgements

Future Deprecation

GAMS System

GAMS

The GAMS Macro Facility

GAMSIDE

GAMS Data Utilities

SCENRED2

Documentation

Other

Model Libraries

GAMS Model Library

GAMS Test Library

Solvers

Coin-OR

Cplex

Lindoglobal

PATH

BDMLPD, CPLEXD and CONOPTD

Solver/Platform Availability Matrix