1.1 Preview

1.2 Basics of Modeling

1.3 The GAMS Language

1.3.1 Lexical conventions

The GAMS examples that follow use comments of the standard kind (“*” in position 1), but in addition assume that text that starts with the sequence “#” to the end of the current line is regarded as a comment. Hence, the command

is assumed to be in effect in all examples. C++ and Java programmers might prefer to use the more familiar

1.3.2 Sets

The simplest set declarations have the form:

These lines declare the two sets Time and Bonds. The set Time contains the elements from 2002 through 2006 (the asterisk indicates filling out the intervening elements; one could have written this: SET Time /2002, 2003, 2004, 2005, 2006/;). Similarly, the Bonds set contains bonds named GOVT_1 through GOVT_4.

Indices and indexation

Most GAMS modeling elements (data, variables, etc.) can be indexed, with up to 10 indices. For instance, a two-dimensional parameter F can be defined over the sets declared above as (more on data declarations in Section 2.2.1):

These two declarations have identical meaning, given the ALIAS declarations of i and t, and specify that F takes two indices belonging to (aliased to) the sets Bonds and Time, respectively.

Indices are used, for instance in expressions, to pick out individual elements of indexed objects. If F(t,i) is a bond’s cashflows, then the following calculates each bond’s total cashflows:

and stores it into the declared one-dimensional parameter. Notice that this assignment is automatically performed for each value i in Bonds. There is more information on the summation operation in Section 1.3.3.

Constant set elements used as indices have to be specified in quotes:

The ORD and CARD set functions

The ORD function takes as an argument the name of a set (or an index aliased to a set) and returns the ordinate value of the index relative to the set. The CARD function takes a set name (or index) and returns the cardinality of the set, i.e., the number of elements in the set:

Subsets and multidimensional sets

A set can be declared as a subset of another set. For instance,

specifies a subset, Callable, of the Bonds set and declares bonds GOVT_1 and GOVT_3 as being callable bonds. Subsets can be multidimensional:

might specify the maturity years of the bonds as a subset of the cartesian product Bonds × Time. Note the dot-notation: GOVT_1.2003 specifies that the element (GOVT_1, 2003) belongs to Matur.

Dynamic sets

The sets seen so far were all static. Their elements were explicitly listed as part of their declaration. GAMS also allows dynamic sets, which are calculated during execution of the model allowing them to change dynamically depending on some model characteristics. Dynamic sets are always subsets of another set (or other sets) and do not have the / . . . / part in their declaration. Consider:

This fragment defines the set Sub as a dynamic subset of Time, and initializes it to contain all but the first element. The expression YES $ (tau(t) >= 1) means to include element t in Sub if the condition following the $-operator is satisfied (conditional expressions are covered in detail in Section 1.3.3).

1.3.3 Expressions, functions, and operators

Consider this simple example where some statistics of stock returns are calculated:

The $-operator and conditional expressions

First, evaluate the expression cond. If its value is non-zero, then the complete expression has the value of exp, otherwise it has the value 0 and exp is not evaluated. For example, the annual cashflows of a set of bonds given their coupon rates and maturity years can be calculated by:

where tau(t) maps elements of the time set to calendar years; a bond’s cashflow is composed of its price (negative at purchase), its principal payment (1, at maturity), and coupon payments; see Figures 2.1 and 2.2 for the complete model.

Notice also the use of an indexed set or parameter as a condition. Given the declarations

the expressions Matur(i,t) and F(t,i) are legal $-conditions, testing whether the pair (i,t) belongs to Matur, or whether F(t,i) is non-zero, respectively.

Special functions: SUM, PROD, SMIN, SMAX

The functions SUM, PROD, SMAX, and SMIN have two arguments where the first must be a set (or index) expression. They form the sum, product, element-wise maximum, and element-wise minimum over the second argument values:

Note the use of parentheses to sum over multiple indices.

The index set over which the operation is applied can be qualified using the $-operator, as in:

The operation will be performed only over indices that satisfy the condition. When the condition is simply an indexed set or parameter, as in Callable(i), the conditional summation can be abbreviated as shown in the second line above, which aids readability.

Applying one of these functions over an empty set results in the operations’s neutral element: 0 for SUM, 1 for PROD, -INF for SMAX, and INF for SMIN. Comparing index values directly is not possible:

It is necessary to use some function that converts from set elements to numerical values, such as ORD or some parameter indexed by the set (as tau in the example above). For the special case of testing for equality, however, GAMS has a function SAMEAS:

SAMEAS compares the names of the set elements referred to by the indices (not their ordinal values), and is legal even if the two indices belong to different sets.

Extended arithmetic: INF, EPS, NA, UNDF

1.3.4 Assignment statements

The assignment statement is used, as in any other language, to assign values to parameters (SCALARs, PARAMETERs, and TABLEs). The parameter on the left-hand side always has all indices specified, and GAMS automatically performs the assignment for each index value. Some examples:

The first line is a simple assignment of a single value. The second is performed for all indices i, the third only for those values of i that satisfy the condition. Note that in a conditional assignment that the condition is placed before the = sign.

As a complete example, consider the following calculation of a lower-triangular matrix to hold covariance information:

In this example we want to calculate variance-covariance information into a matrix efficiently, by only storing elements in the lower triangular half of the VarCov2 matrix, defined by the dynamically calculated subset SET Lower. The assignment to VarCov2(i,i)) calculates the diagonal, and the assignment to VarCov2(Lower(i,j)) is shorthand for:

so that only below-diagonal elements are assigned. Altogether, this calculation is almost twice as fast as calculating VarCov shown on page 7, yet used in a typical variance expression such as

it is equivalent (but again about twice as fast to evaluate).

1.3.5 Variable declarations

Variable attributes

After declaration of a variable it is always possible to change its bounds:

Table 1.5: The different kinds of variables and their declaration. The default bounds can be reset through the LO and UP (or FX) attributes.

Here, a two-dimensional array of variables is declared as non-negative (default bounds 0 and ∞), but then the bounds are reset to -4 and 10, by setting LO and UP attributes. Finally, y(“2”,”3”) is fixed at a specific value. Assigning a value to the FX attribute is equivalent to setting the variable’s lower and upper bounds to the same value. Fixing a variable does not remove it from the model; see the HOLDFIXED attribute on page 15 for how to do this. Variables also have two other attributes which are set by solvers: L is the “level” value (for instance the optimal value after the problem is solved), and M is the “marginal,” or reduced cost. These can both be initialized by the user, which is useful in nonlinear programming to provide a starting point for the solver.

1.3.6 Constraints: Equation declarations

Equations are used to declare and define model constraints:

Here, we declare a set of constraints constr(i), and an individual constraint, objective. They are then defined (indicated by the “..” symbol). Each of the constraints constr(i) is a less-or-equal inequality constraint, as indicated by =L=. The objective constraint is an equality indicated by =E=. Greater-or-equal constraints are specified using =G=. A fourth relation, =N=, indicates that the constraint is present but non-binding; no use has yet been found for it. The expressions used to define constraints are covered in Section 1.3.3.

Endogenous variables in constraints

A $-condition may be placed before the .. symbol in a constraint definition. The constraint is only then generated and included in the model if the condition is satisfied:

Equation attributes

Constraints have the attributes LO, UP, L and M. To understand these it is useful to consider, for instance, a less-equal constraint to be written as:

where lhs consists of all variable terms of the constraint and rhs consists of all constant terms. Then the level attribute .L is the value (after a solve) of the constraint’s left-hand side, and the bounds attributes LO, UP are the bounds on it; for a less-equal constraint the left-hand side has bounds -INF and rhs. The M attribute is the constraint’s dual price.

1.3.7 Model declarations

Between the slashes are listed the names (without indices) of any constraints that should be part of the model Dedication. If all the constraints defined in the source file up to this point are part of the model, one can write:

Model attributes

Others are set as a result of executing a SOLVE statement and they can be used to test the result of solving a model and hence decide on further actions to take:

Table 1.6: The most important OPTIONs. The argument N indicates a non-negative integer.

The most important values of MODELSTAT are 1: optimal, 2: locally optimal, 3: unbounded, and 4: infeasible;

Substituting fixed variables

The variable suffix FX will “fix” a variable, i.e., set its upper and lower bounds to the same value, but the variable is still present in the problem even though it has only a single feasible value. The MODEL attribute HOLDFIXED, when set to 1:

will cause the values of all fixed variables to be substituted for the value throughout in the model. This can greatly reduce the complexity of a model, for instance converting a nonlinear model to a linear one. The only piece of information lost is the variable’s dual information (marginal).

1.3.8 The SOLVE statement and model types

The SOLVE statement has the general form:

where model_name is the model to be solved, obj_var is the variable whose value should be minimized (one can also ask for MAXIMIZING the value), and model_type indicates the type of model to be solved; see Table 1.7. GAMS will select a default solver that is capable of solving the indicated model type, or a desired solver can be specified:

causes GAMS to use BDMLP to solve LP models.

Model types

1.3.9 Control structures

The IF statement

The IF statement has the following forms:

where condition is a conditional expression (1.3.3) and stat-seq is a semicolon-separated list of executable statements. Some examples follow:

The IF . . . ELSEIF . . . variant allows an arbitrary number of ELSEIF parts, and the ELSE part is optional.

Iterative control structures

These statements allow repeated execution of groups of statements until some condition is satisfied (WHILE), or under control of either a scalar parameter (FOR) or a set index (LOOP). Their syntax is:

where condition is a conditional expression (1.3.3) and stat-seq is a semicolon-separated list of executable statements. The FOR loop iterates a parameter parm through a range of values, as for instance:

As an example, Figure 1.1 shows how to solve a sequence of related models under control of a FOR statement. The model is the Klee-Minty model (see, e.g., Nash and Sofer [1996] for a discussion on the Klee-Minty problem), which is interesting because it may require 2^m iterations with a naive implementation of the simplex algorithm, where m, the number of variables and constraints, is a parameter:

(1.4)

(1.5)

(1.6)

Defeating parallel assignment

An assignment statement such as

is executed “in parallel”: GAMS performs the assignment for each value of the controlling index i “at once.” But sometimes the parallel assignment feature gets in the way. Consider calculating the Fibonacci numbers from 1 to 100. One might be tempted to do this:

The last assignment would not work because of the “parallel assignment” feature of GAMS: Most of the values referenced on the right-hand side are equal to zero (i.e., =Fibonacci(“3”) through Fibonacci(”100”)), and the values assigned to Fibonacci(“1”) through Fibonacci(”2”) use undefined indices, -1 and 0. The way to implement this kind of recurrence relation is to force GAMS to execute the assignment element-by-element in a specified order, rather than in parallel. The LOOP statement does this:

1.3.10 Conditional compilation

Some of the GAMS $-control commands (see Table 1.1) are particularly useful for conditional compilation, that is, including or excluding parts of the GAMS source code depending on some condition. We give here an example:

1.4 Getting Started

1.4.1 The Integrated Development Environment

Creating a new GAMS project

Opening an existing GAMS project

Executing GAMS models

1.4.2 Command line interaction

The simplest and most general way to use the GAMS system is from the command line through text files. An input file containing the model’s source code, and having a name with the extension .gms, is created using an ordinary text editor, such as vi, emacs, or Notepad (if using a word processor you should “save as type .TXT”). This file is then submitted to the GAMS system by issuing the command:

from the Unix prompt. GAMS will look for and compile the file dedicate.gms, and generate an output file, dedicate.lst, containing a listing of the input file and the solutions of any models solved. This file is then examined using a text editor. It is often convenient to have several open windows: one in which to edit the input file, one to call GAMS, and one to look at the output.

1.4.3 The model library

From the command line,

copies a file containing a list of the library models into the current directory; the commands

both copy model number 1, dedicate.gms, into the current directory.

Notes and References