Free Windows student version available for download

Notes on GAMS for Optimization
by Ronald L. Rardin
May 21, 1999

GAMS has an enormous number of features and options which allow it to support the most sophisticated mathematical programming and econometric applications. Fortunately, what a beginner needs to know to use the language in solving standard mathematical programs is much less.

These Notes are Professor Ron Rardin's overview of the features most often needed in coding and solving optimization models.

• Part I presents the basics needed for all GAMS models
• Part II introduces the real power of GAMS -- subscripts and symbolic parameters
• Part III deals with some refinements on subscripting required in many models
• Part IV discusses special input/output and option statements, and
• Part V briefly introduces available loop and if/elseif/else capabilities

In the interest of simplicity and good style, many features of the language are presented in a much more limited and rigid form than actually allowed by the full GAMS. Users with more complicated questions should download the manual (about 250 pages) GAMS: A User's Guide which is available online in .pdf format.

Professor Rardin retains all copyrights to these Notes. Reproduction of any part of them for sale is prohibited without his expressed written consent, but noncommercial use or reproduction is authorized as long as the original source and author are acknowledged. (Accessed 3586 times from 1714 different hosts since 18-Jan-98)

Part I: Basics Input (.gms) and Output (.lst) Files GAMS from a Command Line GAMS in the Integrated Development (Windows) Environment Examples of Elementary GAMS Input Files GAMS Statement Formats Option Statements Defining Decision Variables Defining Equations (Objectives and Constraints) Model Statements Solve Statements Decision Variable Bounds, Levels and Duals Error Messages and Debugging Part II: Indexing and Symbolic Parameters Example of GAMS Input with Parameters and Subscripts Defining Subscripts and Indexes with Sets Subscripted Systems of Variables Subscripted (For Every) Systems of Constraints Indexed Summations and Products Symbolic Parameters Parameter Tables (Two of More Subscripts)

Part III: Advanced Index/Subscripting $-Restrictions on Subscript Ranges and ord() Functions Index Lag/Lead Offsets Domains and Aliases Subsets of Index Sets (Dynamic Sets) Part IV: Specialized Input/Output and Options Supplemental Print Diagnostic Print Included Files and Spreadsheet Input Output to a File Option Choices Part V: Loops and Conditional Statements Indexed Loops While Loops For Loops If/Elseif/Else Statements Model Outcome Status Conditions

Input (.gms) and Output (.lst) Files

filename.gms

When the input file is ready, the system is invoked to solve one or more versions of the model, with output (including any error messages) sent to corresponding file

filename.lst

Default output begins with an echo of the input like the following. If syntax errors were detected, GAMS includes numbered messages within the echo output and provides a key at the end of the listing.

   1  * Echo print example with an error
   2  positive variable x1 "product 1", x2 "product 2";
   3  free variable p "profit";
   4  equations objective, capacity;
   5  objective.. z =e= 10*x1 + 20*x2;
****              $140
   6  capacity.. x1 + x2 =l= 100;
   7  model tiny /all/;
   8  solve tiny using lp maximizing z;
****                                 $257

Error Messages
140  Unknown symbol
257  Solve statement not checked because of previous errors

Once all errors are corrected, the SOLVE SUMMARY part of the .lst file details results of the optimization.

               S O L V E      S U M M A R Y

     MODEL   TINY                OBJECTIVE  Z         
     TYPE    LP                  DIRECTION  MAXIMIZE
     SOLVER  CPLEX               FROM LINE  8

**** SOLVER STATUS     1 NORMAL COMPLETION         
**** MODEL STATUS      1 OPTIMAL                   
**** OBJECTIVE VALUE             2000.0000

                       LOWER     LEVEL     UPPER    MARGINAL  

---- EQU OBJECTIVE       .         .         .        1.000      
---- EQU CAPACITY       -INF    100.000   100.000    20.000      

                       LOWER     LEVEL     UPPER    MARGINAL  

---- VAR X1              .         .        +INF    -10.000      
---- VAR X2              .      100.000     +INF       .         
---- VAR Z              -INF   2000.000     +INF       .         

  X1          product 1
  X2          product 2
  Z           profit

The first main part of each SOLVE SUMMARY reviews results for model equations. Values are given for each objective and constraint, with the LEVEL of each constraint providing the amount of the associated resource used in the final solution and MARGINAL showing the corresponding dual variable (Lagrange multiplier) value. Any value having only a decimal point is = 0.

The second part of each SOLVE SUMMARY details results for all decision variables. These reports show the final LEVEL for each variable along with any upper and lower bounds and a MARGINAL value corresponding to the variable's reduced cost. Again, values having only a decimal point = 0.

Errors may also be reported during solving. Such execution errors usually result from an infeasible or unbounded model, program limits being exceeded, or improper computations such as taking the logarithm of a nonpositive number.

GAMS from a Command Line

gams filename

When running in command-line mode, it is recommended that each .gms file begin with the commands

$offsymxref offsymlist
option limrow=0, limcol=0;

GAMS in the Integrated Development (Windows) Environment

To run the IDE version of GAMS, users must first launch the system by selecting Gams and gamside on the Programs menu (accessible from Start).

The result should be a screen similar to many other Windows applications, with a menu bar along the top and a main Edit Window for GAMS applications. As with most such systems, input and output operations are controlled by the File pulldown menu, with other menu items used in edit operations, and in running the GAMS system.

Users should begin each session by selecting a "project". A project is a system file you save but never have to touch. Still, its location is important because the folder (directory) of the current project file is where .gms input and .lst output files are saved by default. This allows you to easily keep all the input and output files for any task together in the same directory, and use different directories for different projects. The starting project file (if any) shows at the top of the main GAMS window. To select another, or create a new one, use the Project item on the File menu.

The IDE version provides for standard, mouse-driven editing of .gms files in the main GAMS Edit Window. If the appropriate file is not already displayed, use the New or Open commands on the File menu to activate one. Then create or correct the file with the mouse and tools provided on the Edit and Search menus. The Matching Parenthesis button helps with the many parentheses in GAMS by skipping the cursor to the parenthesis that corresponds to the one it is now positioned in front of.

Once a .gms file is ready to run, the Run item on the main menu bar invokes GAMS. In addition, it automatically causes a .lst output to be stored in the current project directory (but not displayed).

The .lst output file can be activated using the Open command on the File menu. However, it is usually easier to first survey an IDE run by examining the separate Process Window, which is automatically displayed. A brief log of the run appears there, and clicking on any of the boldface lines (including run error messages) will activate the entire .lst output file and position you on that message. In particular, clicking on Reading solution for model will open the .lst and position the window at the SOLVE SUMMARY.

Syntax errors in GAMS input show in red in the Process Window. Clicking on any such red error message brings up the corresponding .gms file in the main GAMS window and positions the cursor at the point where the error was detected.

Examples of Elementary GAMS Input Files

Formulation

GAMS Input

LP Example 5.1: Top Brass Trophy max 12x1+9x2 (profit) s.t. x1 <= 1000 (footballs) x2 <= 1500 (soccer balls) x1+x2 <= 1750 (plaques) 4x1+2x2 <= 4800 (wood) x1, x2 >= 0

* Rardin Example 5.1 file topbrass.gms free variable profit "profit"; positive variables x1 "football trophies", x2 "soccer trophies"; equations obj "max profit", foot "footballs", socc "soccer balls", plaq "plaques", wood "wood"; obj.. 12*x1 + 9*x2 =e= profit; foot.. x1 =l= 1000; socc.. x2 =l= 1500; plaq.. x1 + x2 =l= 1750; wood.. 4*x1 + 2*x2 =l= 4800; model topbrass /all/; solve topbrass using lp maximizing profit;

Formulation	GAMS Input
ILP Example 12.2: River Power min 7x1+12x2+5x3+11x4 (total cost) s.t. 300x1+600x2+500x3+1600x4 >= 700 (demand) x1, x2, x3, x4 = 0 or 1	* Rardin Example 12.2 file rivpower.gms option optcr=0.0; free variable cost "total cost"; binary variables x1 "use 1", x2 "use 2", x3 "use 3", x4 "use 4"; equations obj "min total cost", dem "demand"; obj.. 7*x1 + 12*x2 + 5*x3 + 14*x4 =e= cost; dem.. 300*x1 + 600*x2 + 500*x3 + 1600*x4 =g= 700; model rivpower /all/; solve rivpower using mip minimizing cost;

Formulation

GAMS Input

NLP Example 14.7: Service Desk Design max 2x1+2x2+2 (outer perimeter) s.t. (x1)2/25+(x2)2/16 <= 1 (10m limit) x1 >= 3.5 (outside) x2 >= 2.75 (2m inside)

* Rardin Example 14.7 file servdesk.gms free variable outer "outer perimeter"; positive variables x1 "inner half width", x2 "inner depth"; equations obj "max outer perimeter", dist "10m distance limit", out "outside conveyers", in "2m inside"; obj.. 2*x1 + 2*x2 + 2 =e= outer; dist.. sqr(x1)/25 + sqr(x2)/16 =l= 1; out.. x1 =g= 3.5; in.. x2 =g= 2.75; model servdesk /all/; solve servdesk using nlp maximizing outer;

GAMS Statement Formats

• Lines with an * (asterisk) in the very first character are comments. For example, an initial comment identifies each of the above example files.
• Lines with a dollar sign in the very first character are GAMS input/output options. For example, $include 'filename' copies in the content of filename as if it had been typed at this point. Such $-option lines have no end punctuation.
• All other GAMS statements are coded over one or more lines and end in a semicolon, with component items separated by commas.
• Line breaks, extra spaces and blank lines may be added for readability without effect.
• GAMS is not case sensitive. That is, XX, xx and Xx are the same entity.
• Declaration statements such as free variable(s) and equations(s) may contain a few words of double-quoted "explanatory text" elaborating on the meaning of each defined item immediately after its name is specified. This explanatory text will accompany the item on outputs to make results easier to decipher.
• Names in GAMS consist of up to 9 letters and digits, beginning with a letter. Internal commas, spaces and other special characters should not be used, but underlines (_) are allowed.
• All GAMS command words (e.g. variable, table, equation, model) and function names (e.g. sum, log, sin) are reserved, and should not be used for declared names. Naming entities with some standard computer words such as for, if, elseif, else, while, file, and system also causes errors.
• Subscripts on variables and constraints are enclosed in parentheses, with explicit (non-varying) subscripts enclosed in quotes.
• Numerical constants in statements may have a decimal point, but they may not contain commas (i.e. use 20000 not 20,000).

Option Statements

• All of models run in command line (as opposed to IDE) mode should have the extra commands

  $offsymxref offsymlist
  option limrow=0, limcol=0;

  at the top. This eliminates lengthy debug print that is usually not needed.
• ILP/MIP models need to set the optcr option, which specifies how much suboptimality is allowed when solution terminates. The default is 10% or optcr=0.1. This is appropriate if run times are long, but for classroom models, it is usually better to set optcr=0.0 as in the ILP example above.

Defining Decision Variables

Allowed types and corresponding GAMS keywords are as follows:

Any type can also be indexed over one or more subscript sets (see Part II).

In addition to the usual decision variables of the model, there must always be free variable(s) defined to represent the objective function value(s). For example, free variable profit plays this role in the Top Brass Trophy illustration above.

Defining Equations (Objectives and Constraints)

equation dem "annual demand";

The second part of defining an equation is to add detail on each declared equation name in a separate statement beginning

equationname..

For example, the annual demand equation declared above might be detailed as

dem .. x1 + x2 + x3 =g= 120 - x0;

One such equation always sets the objective function equal to the (free) objective value variable. Any equation can be indexed over one or more subscript sets to define a whole system of similar constraints (see Part II).

The syntax of equation detail statements follows the pattern of C and similar languages with + for addition, - for subtraction, * for multiplication, / for division, and ** for exponentiation. Terms need not be collected, and they may appear on either side of the relational operator. Parentheses may be added to group quantities or aid readability.

A variety of standard functions may also be included:

Model Statements

For simple cases this is accomplished with the statement

model modelname /all/;

model small /obj,demand/;
model big /obj,demand,detail/;

Solve Statements

solve modelname using solvertype maximizing objectivevaluevariable;

solve modelname using solvertype minimizing objectivevaluevariable;

There is a default solver for each of these model types. The defaults are detailed in online documentation, and, for the IDE version, under Options on the File menu. Default solvers can also be changed with an option command. For example,

option nlp=minos5;

Input files often contain more than one solve statement, each optimizing a different case. For example, the following sequence solves a nonlinear programming model three times from different starting values of the decision variable x:

x.l=2.0;
solve nlmodel using nlp minimizing z;
x.l=20.0;
solve nlmodel using nlp minimizing z;
x.l=200.0;
solve nlmodel using nlp minimizing z;

Decision Variable Bounds, Levels and Duals

Upper and lower bounds may be assigned values to impose constraints. For example the statements

x.lo=1e-5;
x.up=92.0;

10^-5 <= x <= 92.0

It is sometimes also necessary to set the current level of a variable. This is particularly true in nonlinear programming where it is advisable to pick starting solutions because results may depend on initial variable values. For example, the statement

x.l=56.2;

Note that the statement x=56.2; would not be allowed for a GAMS decision variable x because the variable name itself cannot be assigned a value. Add an appropriate suffix (usually .l) to correct the resulting error.

Error Messages and Debugging

If a review of the errors is not enough to find the problems in a GAMS model, consider the extensive debug print options outlined in Part IV.

Example of GAMS Input with Parameters and Subscripts

Consider a facilities location problem in the form (SUM denotes the usual sigma for summations):

min  SUMi SUMj djci,jxi,j + s SUMi fiyi
s.t. SUMi xi,j = 1 
     SUMj xi,j <= 5yi
     yLA + yATL <= 1
     xi,j >= 0
     yi = 0 or 1

for all j
for all i

for all i,j
for all i

where x_i,j and y_i are the decision variables for i=LA,CHI,ATL and j=1,...,5. The rest of the symbols in the model are constant parameters with s=100, and c_i,j, d_j and f_i as shown in the following table:

The corresponding GAMS input would be

* Facilities location example with subscripts and symbolic constants

option optcr=0.0;

sets
i "facilities" /LA, CHI, ATL/,
j "customers" /1 * 5/;

scalar s "scaling constant" /100/;
parameter d(j) "demand at j"
/1 11, 3 15, 4 12, 5 19/;
parameter f(i) "fixed cost at i";
f(i) = 3.1;
table c(i,j) "i to j transportation cost"
     1   2   3   4   5
LA   2   4   9   3   8
CHI  6           1   2
ATL  1   4   2   0   3 ;

free variable cost "total cost";
positive variable x(i,j) "fraction of j serviced by i";
binary variable y(i) "whether i is opened";

equations
obj "min total cost",
switch(i) "switching at i",
sumone(j) "do customer all of j",
laoratl "LA or ATL";

obj..
sum((i,j), d(j)*c(i,j)*x(i,j)) + s*sum(i, f(i)*y(i)) =e= cost;
switch(i)..
sum(j, x(i,j)) =l= card(j)*y(i);
sumone(j)..
sum(i, x(i,j)) =e= 1;
laoratl..
y('LA') + y('ATL') =l= 1;

model facloc /all/;
solve facloc using mip minimizing cost;

Defining Subscripts and Indexes with Sets

If the set is a sequence of consecutive integers, the shorthand

/ lowerlimit * upperlimit /     gives     lowerlimit,...,upperlimit

A handy function card( setname ) returns the number of elements in the specified set. Notice that switch(i) constraints in the above example use the value of this function as a model constant.

Subscripted Systems of Variables

Once a set name has been associated with some a variable, that same index name must normally be used whenever the variable is referenced. Cases where more than one subscript name is needed are handled with aliases (see Domains and Aliases.)

The fact that elements of sets are taken as strings means they must be enclosed in quotes when called out explicitly. For example in the above model, a single side constraint

xLA,3 <= yLA  would be expressed x('LA','3') =l= y('LA');

Subscripted (For Every) Systems of Constraints

Sometimes indexing is desired over only part of the elements of an index set. For example an equation may exist for all i and all j> i. The $-restriction feature of GAMS, which handles such cases, is outlined in Part III below.

Indexed Summations and Products

sum( subscript range, expression )

The objective function of the above example illustrates:

obj .. sum((i,j), d(j)*c(i,j)*x(i,j)) + s*sum(i, f(i)*y(i)) =e= cost;

A similar approach can be used to express indexed products. The operator

prod( subscript range, expression )

Sometimes indexing is desired over only part of the elements of an index set. For example we may want to sum over all i and all j> i. The $-restriction feature of GAMS, which handles such cases, is outlined in Part III below.

Symbolic Parameters

When the parameter has no subscripts, the scalar statement is used. For example, the statement

scalar s "scaling constant" /100/;

Subscripted symbolic parameters may be defined in a similar way with parameter statements. For example the above statement

parameter d(j) "demand for j" /1 11, 3 15, 4 12, 5 19/;

When a parameter has more than one subscript, its nonzero elements can be defined in a similar way with subscript combinations concatinated with periods. For example the statement

parameter c(i,j) "i to j transportation cost" /LA.1 2, CHI.1 6, ATL.5 3/;

The /-delimited value lists may be omitted in all these examples. Values must then be assigned after the declaration by placing parameter names on the left side of an = sign. Some examples include

Notice that, in contrast to decision variables, no suffix is required on parameters.

Parameter Tables (Two or More Subscripts)

Subscript set elements are arranged around the borders and nonzero values aligned with them in a matrix. The above example model illustrates for two subscripts:

table c(i,j) "i to j transportation cost"
     1   2   3   4   5
LA   2   4   9   3   8
CHI  6           1   2
ATL  1   4   2   0   3 ;

If a symbolic parameter has more than two subscripts, some must me concatenated by periods to reduce to a two-dimensional table. For example, the sixteen components of a table yield_i,j,k,l over sets

sets i /A,B/, j /1,2/, k /90,95/, l /Y,Z/;

table yield(i,j,k,l) "process yield"
        90.Y   90.Z    95.Y    95.Z
A.1                    1.23
A.2
B.1
B.2                            45   ;

$-Restrictions on Subscript Ranges and ord() Functions

GAMS accommodates such situations with a $-operator read to mean "such that". Appending a $-restriction to any subscript(s) makes the operation apply only to subscript combinations satisfying the specified condition. For example,

The condition used in a $-restriction can be any sort of logical expression using relational operators over model quantities

For example the statement

parameter c(i,j)$( a(i) gt 0 and b(j) gt 0 );

Because set elements are treated as strings in GAMS, it is often necessary to convert them to numbers in order to express $-conditions. An ord( ) function is provided for this purpose which returns the ordinal position (beginning with 1) of an element of a set. For example if c_i,j are to be summed over all i and all j > i the natural coding sum( (i,j)$( j gt i ), c(i,j) ) produces errors because j and i are not numeric quantities. However, they can be converted with the ord() function (assuming elements of the sets were originally defined in sequence) to obtain correct form

sum( (i,j)$( ord(j) gt ord(i) ), c(i,j) );

Index Lag/Lead Offsets

i_t = i_t-1 + x_t - d_t

Even though it stretches the principle that elements of sets are treated as strings rather than numbers, GAMS allows such equations to be coded

balance(t).. i(t) =e= i(t-1) + x(t) - d(t);

Subscripted quantities outside the set in such + and - constructions are taken = 0. For example, in the above balance(t), i('1'-1) is assumed =0.

An alternative is to wraparound indexing from one end of a set to another. Double operators ++ and -- are used. Changing the above example in this way to

balance(t).. i(t) =e= i(t--1) + x(t) - d(t);

Domains and Aliases

GAMS provides an alias option to escape this limitation when, for example, a variable is defined as x(j) but later referred to as x(k). The statement

alias (j,k);

Subsets of Index Sets (Dynamic Sets)

For example, consider a model posed on a network or graph, and let

set i /1 * 4/;
alias (i,j);

Declaration

set arc(i,j) / 1.2, 1.3, 2.4, 3.2, 3.4 /;

sum( (i,j)$arc(i,j), x(i,j) );

Unlike underlying sets, which must remain "static" through all modeling and computation, subsets are "dynamic", i.e. their membership can be changed as processing evolves. The syntax is simply to assign the values yes or no to particular indices of the set. For example arc(i,j)=yes makes the arc set in the above example complete; all arcs belong to the subset. A later statement arc('3','2')=no would delete arc (3,2).

Dynamic (sub)sets can also be defined by classic set operations on other subsets.

Supplemental Print

One case is where the user wants to print values not part of the standard output. The display statement is used for this purpose. For example the sequence

parameter dist(i,j); dist(i,j) = abs( h(i)-h(j) ) + abs( k(i) - k(j) ); display dist;

Another common use of display statements is to replace for a voluminous default output. First, statement

option solprint = off;

display x.l, budget.m;

Diagnostic Print

option limrow = integer;

option limcol = integer;

Included Files and Spreadsheet Input

$include 'includefile.gms'

This include feature provides a convenient way to import parameter values from spreadsheet software. For example, the main file

sets i /1*2/, t /95*98/;
table sales(i,t)
$include 'sales.gms'
;

        95    96    97   98
1      1.3   2.0   2.7  3.6
2      4.9   4.6   4.3  4.5

Output to a File

file soln /training.out/;
put soln;
put "final x and y =";
put x.l, y.l;
put /;

Option Choices

All these parameters have default values that are usually satisfactory, but explicit option statements may be used to make a different choice. For example

option lp = cplex;

Indexed Loops

model dsgn /all/;
option solprint = off;
set t /1*20/;
loop( t,
   x.l(j) = uniform( x.lo(j), x.up(j) );
   solve dsgn using nlp minimizing cost;
   display x.l, cost.l;
);

While Loops

model dsgn /all/;
option solprint = off;
scalar t /1/;
while( (t le 20),
   x.l(j) = uniform( x.lo(j), x.up(j) );
   solve dsgn using nlp minimizing cost;
   display x.l, cost.l;
   t = t + 1;
);

For Loops

model dsgn /all/;
option solprint = off;
scalar t;
for( t = 1 to 20,
   x.l(j) = uniform( x.lo(j), x.up(j) );
   solve dsgn using nlp minimizing cost;
   display x.l, cost.l;
);

If/Elseif/Else Statements

if( x.l gt 0 ),
   s = 1;
elseif( x.l lt 0 ),
   s = -1;
else
   s = 0;
);

Model Outcome Status Conditions

Thus, for example, if some statements are to be executed only if the last solve terminated optimal, the following sequence would be appropriate:

model plan /all/;
solve plan using lp minimizing cost;
if( (plan.modelstat eq 1),
   statements
);