4.1 INTRODUCTION
Sets are fundamental building blocks in any GAMS model. They allow the model to be suc-cinctly stated and easily read. In this chapter we will discuss how sets are declared and initial-ized. There are some more advanced set concepts, such as assignments to sets as well as lag and lead operations, but these are not introduced until much later in the book. However the topics covered in this chapter will be enough to provide a good start on most models.
4.2 SIMPLE SETS
A set S that contains the elements a, b and c is written, using normal mathematical notation, as:
S = {a,b,c}
In GAMS notation, because of character set limitations, the same set must be written as
set S /a, b, c/
The set statement begins with the keyword set (or sets). S is the name of the set, and its members are a, b, and c. They are labels, but are often referred to as elements or members.
4.2.1 THE SYNTAX
In general, the syntax in GAMS for simple sets is as follows:
set set_name ["text"] [/element ["text"] {,element ["text"]} /]
{,set_name ["text"] [/element ["text"] {,element ["text"]} /] ;
set_name is the internal name of the set (also called an identifier) in GAMS. The accompany-ing text is used to describe the set or element immediately precedaccompany-ing it.
4.2.2 SET NAMES
The name of the set is an identifier. An identifier has to start with a letter followed by more let-ters or digits. It can only contain alphanumeric characlet-ters, and can be up to 10 characlet-ters long.
This is enough to construct meaningful names, and explanatory text can be used to provide more details.
Examples of legal identifiers are
i i15 countries s0051
whereas the following identifiers are incorrect:
25 $currency countriesinafrica food&drink
SET DEFINITIONS 38
4.2.3 SET ELEMENTS
The name of each set element can be up to 10 characters long, and can be used in quoted or un-quoted form. The unun-quoted form is simpler to use but places restrictions on characters used, in that any unquoted label must start with a letter or digit and can only be followed by letters, digits, or the sign characters + and -. Examples of legal unquoted labels are:
Phos-Acid 1986 1952-53 A September H2S04 Line-1
In quoted labels, quotes are used to delimit the label, which may begin with and/or include any legal character. Either single or double quotes can be used but the closing quote has to match the opening one. A label quoted with double quotes can contain a single quote (and vice versa). Most experienced users avoid quoted labels because they can be tedious to enter and confusing to read.
There are a couple of special circumstances. If one wants to make a label stand out, then to put asterisks in it and indent it, as below, is common. A more subtle example is that it is possible to use GAMS keywords as labels if they are quoted. If one need to use labels like no, ne or sum then they will have to be quoted.
Examples of quoted labels are:
'*TOTAL*' 'Match' '10%incr' '12”/foot' 'Line 1'
Labels do not have a value. The label '1986' does not have the numerical value 1986 and the label '01' is different from the label '1'.
Each element in a set must be separated from other elements by a comma or by an end-of-line. In contrast, each element is separated from any associated text by a blank.
Consider the following example from the Egyptian fertilizer model [FERTS], where the set of fertilizer nutrients could be written as
set cq "nutrients" / N, P2O5 / ;
or as
set cq "nutrients" / N
P2O5 / ;
The order in which the set members are listed is normally not important. However, if the mem-bers represent, for example, time periods, then it may be useful to refer to 'next' or 'previous' member. There are special operations to do this, and they will be discussed in Chapter 13. For now, it is enough to remember that the order in which set elements are specified is not relevant, unless and until some operation implying order is used. At that time, the rules change, and the set becomes what we will later call an ordered set.
4.2.4 ASSOCIATED TEXT
It is also possible to associate text with each set member or element. Explanatory text must not exceed 80 characters and must all be contained on the same line as the identifier or label it de-scribes.
For example, label text for the set of final products in [SHALE] contains details of the units of measurement.
4.2 SIMPLE SETS 39
Set f "final products"
/yncrude "refined crude (million barrels)"
lpg "liquified petroleum gas(million barrels)"
ammonia "ammonia (million tons)"
coke "coke (million tons)"
sulfur "sulfur (million tons)"
/;
Notice that text may have embedded blanks, and may include special characters such as paren-theses. There are, however, restrictions on special characters in text. Include slashes, commas or semicolons only if the text is enclosed in quotes. A set definition like
set prices prices of commodities in dollars/ounce / gold-price, sil-price / ;
will cause errors since the slash between dollars and ounce will signal the beginning of the set declaration, and the GAMS compiler will treat ounce as the name of the first element. Further, the slash before gold-price will be treated as the end of the set definition, and gold-price will be treated as a new set. However, by enclosing the explanatory text in quotes, this problem is avoided. The following text is valid:
set prices "prices of commodities in dollars/ounce"
4.2.5 SEQUENCES AS SET ELEMENTS
The asterisk '*' plays a special role in set definitions. It is used to relieve the tedium of typing a sequence of elements for a set, and to make intent clearer. For example in a simulation model there might be ten annual time periods from 1991 to 2000. Instead of typing ten years, the ele-ments of this set can be written as
set t "time" /1991 * 2000 /;
which means that the set includes the ten elements 1991, 1992,…,2000. GAMS builds up these label lists by looking at the differences between the two labels. If the only characters that differ are digits, and if the number (say L) formed by these digits in the left one is less than that from the right one (R), then a label is constructed for every integer in the sequence L to R . Any non-numeric differences or other inconsistencies cause errors.
The following example illustrates the most general form of the 'asterisked' definition:
set g / a1bc * a20bc /;
Note that this is not the same as
set g / a01bc * a20bc /;
although the sets, which have 20 members each, have 11 members in common. As a last example, the following are all illegal because they are not consistent with the rule given above for making lists:
set illegal1 / a20bc * a10bc / illegal2 / a1x1 * a9x9 / illegal3 / a1 * b9 /;
Note one last time that set elements (often referred to as labels) can contain the sign characters '-' and '+' as well as letters and numbers.
SET DEFINITIONS 40
4.2.6 DECLARATIONS FOR MULTIPLE SETS
The keyword set (if you prefer, say sets instead: the two are equivalent) does not need to be used for each set, rather only at the beginning of a group of sets. It is often convenient to put a group of set declarations together at the beginning of the program. When this is done the set keyword need only be used once. If you prefer to intermingle set declarations with other state-ments, you will have to use a new set statement for each additional group of sets.
The following example below shows how two sets can be declared together. Note that the semi-colon is used only after the last set is declared.
sets
s "Sector" / manuf agri services government / r "regions" / north
eastcoast midwest
sunbelt / ;
4.3 THE ALIAS STATEMENT: MULTIPLE NAMES FOR A SET
It is sometimes necessary to have more than one name for the same set. In input-output models, for example, each commodity may be used in the production of all other commodities and it is necessary to have two names for the set of commodities to specify the problem without ambigu-ity. In the general equilibrium model [ORANI], the set of commodities is written
set c "commodities" / food, clothing / ;
and a second name for the set c is established with either of the following statements
alias (c, cp) ; alias (cp, c) ;
where cp is the new set that can be used instead of the original set c.
The newly introduced set can be used as an alternative name for the original set, and will always contain only the same elements as the original set.
The alias statement can be used to introduce more than one new name for the original set.
alias (c,cp, cpp, cppp);
where the new sets cp, cpp, cppp are all new names for the original set c.
The order of the sets in the alias statement does not matter. The only restric-tion set by GAMS is that exactly one of the sets in the statement be defined earlier. All the other sets are introduced by the alias statement.
We will not demonstrate the use of set aliases until later. Just remember they are used for cases when a set has to be referred to by more than one name.
4.4 SUBSETS AND DOMAIN CHECKING 41
4.4 SUBSETS AND DOMAIN CHECKING
It is often necessary to define sets whose members must all be members of some larger set. The syntax is:
set set_ident1 (set_ident2) ;
where set_ident1 is a subset of the larger set set_ident2.
For instance, we may wish to define the sectors in an economic model following the style in [CHENERY]
set
i "all sectors" / light-ind, food+agr, heavy-ind, services / t(i) "traded sectors" / light-ind, food+agr, heavy-ind /
nt "non-traded sectors" / services / ;
Some types of economic activity, for example exporting and importing, may be logically re-stricted to a subset of all sectors. In order to model the trade balance, for example, we need to know which sectors are traded, and one obvious way is to list them explicitly, as in the definition of the set t above. The specification t(i) means that each member of the set t must also be a member of the set i. GAMS will enforce this relationship, which is called domain checking. Ob-viously the order of declaration is important: the membership of i must be known before t is de-clared for checking to be done. There will be much more on this topic in succeeding chapters.
For now it is important to note that domain checking will find any spelling errors that might be made in establishing the members of the set t. These would cause errors in the model if they went undetected.
It is legal but unwise to define a subset without reference to the larger set, as is done above for the set nt. If services were misspelled no error would be marked, but the model would give in-correct results. So we urge you to use domain checking whenever possible. It catches errors and allows you to write models that are conceptually cleaner because logical relationships are made explicit.
This completes the discussion of sets in which the elements are simple. This is sufficient for most GAMS applications; however, there are a variety of problems for which it is useful to have sets that are defined in terms of two or more other sets.
4.5 MULTI-DIMENSIONAL SETS
It is often necessary to provide mappings between elements of different sets. For this purpose, GAMS allows the use of multi-dimensional sets.
GAMS allows sets with up to 10 dimensions.
The next two sub-sections explain how to express one-to-one and many-to-many mappings be-tween sets.
4.5.1 ONE-TO-ONE MAPPING Consider a set whose elements are pairs:
A = { (b,d), (a,c), (c,e) }
SET DEFINITIONS 42
In this set there are three elements and each element consists of a pair of letters. This kind of set is useful in many types of modeling. As an illustrative example, consider the world aluminum model [ALUM], where it is necessary to associate, with each bauxite-supplying country, a port that is near to the bauxite mines. The set of countries is
set c "countries"
/ jamaica haiti guyana brazil / ;
and the set of ports is
set p "ports"
/ kingston s-domingo georgetown belem / ;
Then a set can be created to associate each port with its country, viz.,
set ptoc(p, c) "port to country relationship"
/ kingston .jamaica s-domingo .haiti georgetown .guyana belem .brazil /;
The dot between kingston and jamaica is used to create one such pair. Blanks may be used freely around the dot for readability. The set ptoc has four elements, and each element consists of a port-country pair. The notation (p,c) after the set name ptoc indicates that the first mem-ber of each pair must be a memmem-ber of the set p of ports, and that the second must be in the set c of countries. This is a second example of domain checking. GAMS will check the set elements to ensure that all members belong to the appropriate sets.
4.5.2 MANY-TO-MANY MAPPING
A many-to-many mapping is needed in certain cases. Consider the following set
set i / a, b / j / c, d, e / ij1(i,j) /a.c, a.d/
ij2(i,j) /a.c, b.c/
ij3(i,j) /a.c, b.c, a.d, b.d/ ;
• ij1 represents a one-to-many mapping where one element of i maps onto many elements of j.
• ij2 represents a many-to-one mapping where many elements of i map onto one element of j.
• ij3is the most general case where many elements of i map on to many elements of j. These sets can be written compactly as
set i / a, b / j / c, d, e / ij1(i,j) /a.(c,d)/
ij2(i,j) /(a,b).c/
ij3(I,j) /(a,b).(c,d)/ ;
The parenthesis provides a list of elements that can be expanded when creating pairs.
4.6 SUMMARY 43 When complex sets like this are created, it is important to check that the
de-sired set has been obtained. The checking can be done by using a display statement.
The concepts may be generalized to set with more than two labels per set element. Mathemati-cally these are called 3-tuples, 4-tuples, or more generally, n-tuples.
This section ends with some examples to illustrate definitions of multi-label set elements. Some examples of the compact representation of sets of n-tuples using combinations of dots, parenthe-ses and commas are:
Construct Result
(a,b).c.d a.c.d., b.c.d
(a,b).(c,d) .e a.c.e., b.c.e., a.d.e, b.d.e (a.1*3).c (a.1, a.2, a.3).c
or a.1.c,a.2.c,a.3.c
1*3. 1*3. 1*3 1.1.1, 1.1.2, 1.1.3, . . . ., 3.3.3
Note that the asterisk can also be used in conjunction with the dot. Recall that the elements of the list 1*4 are {1,2,3,4} when examining the above examples.
4.6 SUMMARY
In GAMS, a simple set consists of a set name and the elements of the set. Both the name and the elements may have associated text that explains the name or the elements in more detail.
More complex sets have elements that are pairs or even tuples. These sets with pairs and n-tuples are ideal for establishing relationships between the elements in different sets. GAMS also uses a domain checking capability to help catch labeling inconsistencies and typographical errors made during the definition of related sets.
The discussion here has been limited to sets whose members are all specified as the set is being declared. For many models this is all you need to know about sets. Later we will discuss more complicated concepts, such as sets whose membership changes in different parts of the model (assignment to sets) and other set operations such as unions, complements and intersections.