Introduction

The option statement is used to set various global system parameters to control among other things output detail, the solution process and the layout of displays. GAMS provides default values for global system parameters that are adequate for the most purposes. However, there are always cases when the user would like to maintain control of some aspects of the run. In addition, the option statement provides an efficient and compact syntax to perform powerful operations on identifiers. Observe that option statements are processed at execution time unlike dollar control options that are processed at compile time.

The Syntax of the Option Statement

The keyword option or options indicates that this is an option statement. It is followed by key1, which is one of the options that are listed in this chapter. Consider the following simple example:

option reslim=800;

Here the keyword option is followed by the keyreslim. The option reslim specifies the maximum time in seconds that a solver may run before it terminates. Thus, in this example we give the solver 800 seconds to come up with a solution (which is slightly less than the default value of 1000).

Note

Option names are not reserved words and therefore they do not conflict with other uses of their names.

Observe that it depends on the respective option whether a value is expected and if so, what type of value. There are six different cases. An overview is given in Table 1.

Note that the last type is special: it does not involve a named option or key, but the keyword option is followed by identifiers and identifier operators. These special option statements are discussed in detail in section Special Options: Identifier Operations.

Observe that the value of an option may be reset as often as necessary, the new value will replace the previous value each time. Further, more than one option may be specified with one option statement and commas or end-of-line characters are both legal separators between options.

We will demonstrate with the following example how several options may be used. The code snippet may be added to the model [DICE].

Note that in the first option statement four options are specified: option measure has no associated value, option limcol expects an integer value, option optcr expects a real value and option MIP expects a text string as value. The second option statement specifies just one identifier option: clear, which has the variable comp as value.

Attention

Option statements are executed in sequence with other instructions. Therefore, if an option statement is located between two solve statements, the new values will be assigned between the solves and thus they will apply only to the second solve statement.

List of Options

The options available through the option statement are grouped into the following functional categories:

In the following subsections we will offer brief descriptions of the options in the first five categories. Note that each entry is linked to a detailed description of the respective option. Observe that detailed descriptions of all GAMS command line parameters, options and model attributes are given in section Detailed Descriptions of All Options. The options that belong to the last category are special, they are introduced and discussed in section Special Options that Involve Identifiers below.

Special Options that Involve Identifiers

Several options involve identifiers: they either take identifiers as values or have no key and value, but perform an operation on an identifier. In the following two subsections we will introduce and discuss these special options.

Special Options: Identifier Options

The value of identifier options is not a string or a number, but an identifier. In this subsection we will describe these options in detail.

clear

This option resets an identifier to its default value to free memory. The syntax is as follows:

option clear = identifier;

The following identifier types may be reset: sets, parameters, equations and variables. The option will free up memory to the GAMS heap manager, thus the memory may be used by GAMS but not by the operating system. To force the memory to be freed up to the operating system, the GAMS process needs to be terminated. One way to do this is to restart the execution system by solving a dummy model with the option SolveLink set to zero.

kill

This option is a synonym to option clear. Observe that the dollar control option $kill is not a synonym to $clear.

shuffle

This option rearranges the values of a parameter in a random order. The syntax is as follows:

option shuffle = itemname;

Here itemname is a one-dimensional parameter. One-dimensional parameters may be declared (and defined) in four different ways, depending on the domain and the data. The following table gives an overview of the effect of the option shuffle in the four cases.

No Data

Has Data

Universal set as domain

Use the universal set to initialize the data (case 1 in the example below).

Use the universal set to add zero values before shuffling the data (case 3 in the example below).

Specific set as domain

Use the domain to initialize the data (case 2 in the example below).

Use the domain to add zero values before shuffling the data (case 4 in the example below).

If the parameter was declared without data (the second column in the table above), the domain or the universal set will be used to assign the numbers 1 to N, where N is the number of elements in the domain or the universal set. If the parameter was declared with data (the third column in the table above), the domain or the universal set will be used to add zeroes for possibly missing entries. These zero values will participate in the random shuffle, but they will not be stored in the parameter. The following example serves as illustration:

Set i / i1*i5 /
j / j1*j5 /;
option decimals = 0;
*Case 1: universal set as domain and no data
Parameter A(*) "The universe is used to fill the parameter";
option shuffle = A;
display A;
*Case 2: set j as domain and no data
Parameter B(j) "The set j is used to fill the parameter";
option shuffle = B;
display B;
*Case 3: universal set as domain and has data
Parameter C(*) "The universe is used to add zeroes" / j2 2, j4 4 /;
option shuffle = C;
display C;
*Case 4: set i as domain and has data
Parameter D(i) "The set i is used to add zeroes" / i1 10, i3 30, i5 50 /;
option shuffle = D;
display D;

The code above will generate the output that follows. Observe that in this example, the universal set is the union of the sets i and j, which means that all elements of the sets i and j are members of the universal set. Note that we use random numbers, therefore the outcomes from a different run may vary.

Display Control

The display statement is introduced and discussed in chapter The Display Statement. While GAMS provides defaults for the displayed identifiers that suffice in most cases, the print format may be customized with the following option statement:

option ident:d;
option ident:d:r:c;

The keyword option is followed by the name of an identifier ident, a colon and an integer value d. Note that d may be between 0 and 8 and specifies the number of decimal places that will be displayed for the respective identifier. The specifications r and c are optional. They denote the number of index positions printed as row labels and the number of index positions printed as column labels respectively. Note that if r is zero, a list format will be used. For more information and examples, see sections Local Display Control and Display Statement to Generate Data in List Format.

Index Matching

The keyword option is followed by the name of the set, set_name, and two (or more) indices in parentheses that are linked with the matching operator ':'. Note that the set must have been declared earlier in the program. If the set has also been defined earlier in the program, it will be cleared first and then the matching operation will be processed. Note furthermore that the list of identifiers may be expanded to more than two and that besides the matching operator ':' also ',' may be used and will be interpreted as product operator. Consider the following example which also makes use of display control:

In its simplest form the matching operator is used to create the two dimensional set ij.

---- 9 SET ij
i1.j1
i2.j2

Note that each member of the index i has been matched with a member of the index j until one of the indices ran out of members.

The index matching operations to define the three-dimensional sets ijk and kij illustrate a more sophisticated usage of the index operator. The sets ijk and kij are built with the indices from left to right using the product operator when a ',' is encountered or the matching operator when a ':' is found.

For ijk the first operator is the ',' which is interpreted as product operator for the sets i and j and hence builds the Cartesian product of the two sets which has six 2-tuples as elements (i1.j1, i1.j2, i1.j3, i2.j1, i2.j2, i2.j3). The matching operator ':' is then applied to match those 2-tuples with the five set elements in k. The resulting sets are:

Note that sets hijk_1 and hijk_2 will be different even though hijk_1 uses set ijk and hijk_2 uses the same matching and product operation used at definition of ijk but spelled out. As already mentioned above, the matching operator builds up the sets with the indices from left to right. Hence, as set ijk is build first and then used on the right of the matching operator the two sets ar built up differently.

Projection and Aggregation of Sets and Parameters

In GAMS, projection and aggregation operations on sets may be performed in two different ways: with an assignment and the sum operator, and with an option statement.

Using an assignment and the sum operator is the slower but more intuitive way. Assignments and the sum operator are introduced and discussed in detail in chapter Data Manipulations with Parameters and section Indexed Operations respectively. Here we only show how they may be used in the context of sets to perform projections and aggregations. The following example serves as illustration.

Note that the set ijk is a three-dimensional set, its elements are 3-tuples and all permutations of the elements of the three sets i, j and k are in its domain. Thus the number of elements of the set ijk is 3 x 2 x 4 = 24. The sets ij1a and ij1b are two-dimensional sets that are declared in the set statement, but not defined. The first assignment statement defines the members of the set ij1a. This is a projection from the set ijk to the set ij1a where the three-tuples of the first set are mapped onto the pairs of the second set, such that the dimension k is eliminated. This means that the four elements "i1.j1.k1", "i1.j1.k2", "i1.j1.k3" and "i1.j1.k4" of the set ijk are all mapped to the element "i1.j1" of the set ij1a. Note that in this context, the result of the sum operation is not a number but a set. The second and third assignments are aggregations, where the number of elements of the two sets are computed. As already mentioned, the result of the first aggregation is 24 and the result of the second aggregation is 6 = 24 / 4.

The second way to perform projections and aggregations is faster and more compact, it uses an option statement. The general syntax of this option statement is as follows.

option ident1 < ident2 ;
option ident1 <= ident2 ;

The keyword option is followed by the identifiersident1 and ident2 which are linked by the symbol '<' or '<='. Observe that in most cases the two symbols have the same effect. The exeption is the special case when both identifiers are defined over domains that use at least one shared index set more than once, see the example below. Note that in general the dimension of the item on the left has to be equal or less than the dimension of the item on the right. Further, the index space of the two identifiers must be matchable. If the dimensions of the two identifiers are equal, then the same indices must appear in both, albeit the order may differ. If the dimension of the left item is less than the dimension of the right item, then the indices on the left must also appear on the right.

Observe that if both identifiers are sets, the operation will be a projection. However, if the identifier on the left-hand side is a scalar or a parameter and the identifier on the right-hand side is a set it will be an aggregation. The example that follows shows how the projection and the two aggregations above are accomplished with the option statement.

In the example above, the set on the left-hand side, ij1b, has fewer indices than the set on the right-hand side, ijk. Observe that if the two sets differ only in the order of the indices then a projection will have the effect of a permutation of the tuple.

Note

The option statement for projection and aggregation operations may also be applied to parameters.

Until now the indices in the domain of the sets were unique. A special case arises when sets are defined over a domain with the same indices, for example the set s(i,i,i). In this case, a projection always has the effect of a permutation. Users may choose whether they wish to perform the permutation from left to right or from right to left. The option statement

Option item1 < item2 ;

means a right-to-left permutation, while the option statement

Option item1 <= item2 ;

entails a left-to-right permutation. The following example clarifies the difference:

Note that in the right-to-left permuation, the element "i1.i2.i3" is projected to "i3.i2" and the element "i3.i3.i1" is projected to "i1.i3". In the left-to-right permutation however, the the element "i1.i2.i3" is projected to "i1.i2" and the element "i3.i3.i1" is projected to "i3.i3". Hence, the left-to-right permutation (<=) might be more intuitive.

Our examples so far involved only sets. As mentioned above, projections and aggregations may also be performed with parameters. However, there are some subtle differences. The first difference refers to the terminology: we aggregate sets, but we count parameters. The second difference is the result of the operation if the domain of the left symbol is just a permuted version of the domain of the right symbol. Consider the following example: