5.1 INTRODUCTION
One of the basic design paradigms of the GAMS language has been to use data in its most basic form, which may be scalar, list oriented, or tables of two or more dimensions. Based on this crite-rion, three data types are introduced in this chapter.
Scalar Single (scalar) data entry.
Parameter List oriented data.
Table Table oriented data. Must involve two or more dimensions.
Each of these data types will be explained in detail in the following sections.
Initialization of data can only be done once for parameters; thereafter data must be modified with assignment statements.
5.2 SCALARS
The scalar statement is used to declare and (optionally) initialize a GAMS parameter of di-mensionality zero. That means there are no associated sets, and that there is therefore exactly one number associated with the parameter.
5.2.1 THE SYNTAX
In general, the syntax in GAMS for a scalar declaration is:
scalar(s) scalar_name [text] [/signed_num/]
{ scalar_name [text] [/signed_num/]} ;
scalar_name is the internal name of the scalar (also called an identifier) in GAMS. The ac-companying text is used to describe the element immediately preceding it. Signed_num is a signed number and is assigned to be the value of scalar_name.
As with all identifiers, scalar_name has to start with a letter followed by more letters or dig-its. It can only contain alphanumeric characters, and can be up to 10 characters long. Explanatory text must not exceed 80 characters and must all be contained on the same line as the identifier or label it describes.
5.2.2 AN ILLUSTRATIVE EXAMPLE
An example of a scalar definition in GAMS is shown below.
DATA ENTRY: PARAMETERS, SCALARS & TABLES 46
Scalars rho "discount rate" / .15 / irr "internal rate of return"
life "financial lifetime of productive units" /20/;
The statement above initializes rho and life, but not irr. Later on another scalar state-ment can be used to initialize irr, or, (looking ahead to a notion that will be developed later), an assignment statement could be used to provide the value:
irr = 0.07;
5.3 PARAMETERS
While parameter is a data type that encompasses scalars and tables, the discussion in this chapter will focus on the use of parameters in data entry. List oriented data can be read into GAMS using the parameter statement.
5.3.1 THE SYNTAX
In general, the syntax in GAMS for a parameter declaration is:
parameter(s) param_name [text] [/ element [=] signed_num {,element [=] signed num} /]
{,param_name [text] [/ element [=] signed_num
{,element [=] signed num} /]} ;
param_name is the internal name of the parameter (also called an identifier) in GAMS. The ac-companying text is used to describe the parameter immediately preceding it. Signed_num is a signed number and is declared to be the value of the entry associated with the corresponding element.
As with all identifiers, param_name has to start with a letter followed by more letters or digits.
It can only contain alphanumeric characters, and can be up to 10 characters long. Explanatory text must not exceed 80 characters and must all be contained on the same line as the identifier or label it describes.
A parameter may be indexed over one or more sets (the maximum number being 10). The ele-ments in the data should belong to the set that the parameter is indexed over.
The default value of a parameter is 0.
Parameter initialization requires a list of data elements, each consisting of a label and a value.
Slashes must be used at the beginning and end of the list, and commas must separate data ele-ments entered more than one to a line. An equals sign or a blank may be used to separate the la-bel-tuple from its associated value. A parameter can be defined in a similar syntax to that used for a set.
5.3.2 AN ILLUSTRATIVE EXAMPLES
The fragment below is adapted from [MEXSS]. We also show the set definitions because they make the example clearer.
5.3 PARAMETERS 47
Set i "steel plants" / hylsa "monterrey"
hylsap "puebla" /
j "markets" / mexico-df, monterrey, guadalaja / ; parameter dd(j) distribution of demand
/ mexico-df 55, guadalaja 15 / ;
The domain checking specification for dd means that there will be a vector of data associated with it, one number corresponding to every member of the set j listed. The numbers are specified along with the declaration in a format very reminiscent of the way we specified sets: in this sim-ple case a label followed by a blank separator and then a value. Any of the legal number entry formats are allowable for the value. The default data value is zero. Since monterrey has been left out of the data list, then the value associated with dd('monterrey'), the market share in monterrey, would be zero.
We can also put several data elements on a line, separated by commas:
parameter a(i) / seattle = 350, san-diego = 600 / b(i) / seattle 2000, san-diego 4500 / ;
As with sets, commas are optional at end-of-line.
5.3.3 PARAMETER DATA FOR HIGHER DIMENSIONS
A parameter can have up to 10 dimensions. The list oriented data initialization through the pa-rameter statement can be easily extended to data of higher dimensionality. The label that appears on each line in the one-dimensional case is replaced by a label-tuple for higher dimensions. The elements in the n-tuple are separated by dots (.) just like in the case of multi-dimensional sets.
The following example illustrates the use of parameter data for higher dimensions:
parameter salaries(employee,manager,department) /anderson .murphy .toy = 6000 hendry .smith .toy = 9000 hoffman .morgan .cosmetics = 8000 / ;
All the mechanisms using asterisks and parenthesized lists that we introduced in our discussion of sets are available here as well. Below is an artificial example, in which a very small fraction of the total data points are initialized. GAMS will mark an error if the same label combination (or label-tuple) appears more than once in a data list.
Set row / row1*row10 / col / col1*col10 / ; parameter a(row, col)
/ (row1,row4) . cl2*col7 12 row10 . col10 17 row1*row7 . col10 33 / ;
In this example, the twelve elements row1.col2 to row1.col7 and row4.col2 to row4.col7 are all initialized at 12, the single element row10.col10 at 17, and the seven elements rows1.col10 to row7.col10 at 33. The other 80 elements (out of a total of 100) remain at their default value, which is 0. This example shows the ability of GAMS to provide a concise initialization, or definition, for a sparse data structure.
DATA ENTRY: PARAMETERS, SCALARS & TABLES 48
5.4 TABLES
Tabular data can be declared and initialized in GAMS using a table statement. For 2- and higher-dimensional parameters this provides a more concise and easier method of data entry than the list based approach, since each label appears only once (at least in small tables).
5.4.1 THE SYNTAX
In general, the syntax in GAMS for a table declaration is:
table table_name [text] EOL
element { element }
element signed_num { signed_num} EOL {element signed_num { signed_num} EOL} ;
table_name is the internal name of the table (also called an identifier) in GAMS. The accom-panying text is used to describe the parameter immediately preceding it. Signed_num is a signed number and is declared to be the value of the entry associated with the corresponding element.
The table statement is the only statement in the GAMS language that is not free format.
The following rules apply:
• The relative positions of all entries in a table are significant. This is the only statement where end of line (EOL) has meaning. The character positions of the numeric table entries must overlap the character positions of the column headings.
• The column section has to fit on one line.
• The sequence of signed numbers forming a row must be on the same line.
• The element definition of a row can span more than one line
• A specific column can appear only once in the entire table.
The rules for forming simple tables are straightforward. The components of the header line are the by now familiar keyword-identifier-domain_list-text sequence, the do-main-list and text being optional. Labels are used on the top and the left to map out a rectan-gular grid that contains the data values. The order of labels is unimportant, but if domain check-ing has been specified each label must match one in the associated set. Labels must not be re-peated, but can be left out if the corresponding numbers are all zero or not needed. At least one blank must separate all labels and data entries. Blank entries imply that the default value (zero) will be associated with that label combination.
Notice also that, in contrast to the set, scalar, and parameter state-ments, only one identifier can be declared and initialized in a table statement.
5.4.2 AN ILLUSTRATIVE EXAMPLE
The example below, adapted from [KORPET], is preceded by the appropriate set definitions,
5.4 TABLES 49
table ka(m,i) "initial cap. of productive units (100 tons per yr)"
inchon ulsan yosu atmos-dist 3702 12910 9875 steam-cr 517 1207 aromatics 181 148 hydrodeal 180 ;
In the example above, the row labels are drawn from the set m, and those on the column from the set i. Note that the data for each row is aligned under the corresponding column headings.
If there is any uncertainty about which data column a number goes with, GAMS will protest with an error message and mark the ambiguous entry.
5.4.3 CONTINUED TABLES
If a table has too many columns to fit nicely on a single line, then the columns that don’t fit can be continued on additional lines. We use the same example to illustrate:
table ka(m,i) initial cap. of productive units (100 tons per yr) inchon ulsan
The crucial item is the plus '+' sign above the row labels and to the left of the column labels in the continued part of the table. The row labels have been duplicated, except that hydroreal has been left out, not having associated data. Tables can be continued as many times as neces-sary.
5.4.4 TABLES WITH MORE THAN TWO DIMENSIONS
A table can have up to 10 dimensions. Dots are again used to separate adjacent labels, and can be used in the row or column position. The label on the left of the row corresponds to the first set in the domain list, and that on the right of each column header to the last. Obviously there must be the same number of labels associated with each number in the table, as there are sets in the do-main list.
The actual layout chosen will depend on the size of the controlling sets and the amount of data, and the ideal choice should be the one that provides the most intuitively satisfactory way of or-ganizing and inspecting the data. Most people can more easily look down a column of numbers than across a row, but to put extra labels on the row leads to a greater density of information.
The following example, adapted from [MARCO], illustrates the use of tables with more than two dimensions.
DATA ENTRY: PARAMETERS, SCALARS & TABLES 50
Sets ci "commodities : intermediate"
/ naphtha "naphtha"
table attrib(ci, cr, q) blending attributes density sulfur
The table attrib could also be laid out as shown below:
table attrib (ci,cr,q) blending attributes
w-tex.density mid-c.density w-tex.sulfur mid-c.sulfur naphtha 272 272 1.48 .283
dist 297 297 2.83 .526 gas-oil 303 303 5.05 .98 ;
5.4.5 CONDENSING TABLES
All the mechanisms using asterisks and parenthesized lists that were introduced in the discussion of sets are available here as well. The following example shows how repeated columns or rows can be condensed with asterisks and lists in parentheses follows. The set membership is not shown, but can easily be inferred.
table upgrade(strat,size,tech) table upgradex(strat,size,tech) alternative way of writing table tech1*tech2
strategy-1.(small,medium) .05 strategy-2*strategy-3.(small,medium) .2 trategy-4.medium .2;
display attrib, attribx;
Here we encounter the display statement again. It causes the data associated with upgrade and upgradex to be listed on the output file.
5.4.6 HANDLING LONG ROW LABELS
It is possible to continue the row labels in a table on a second, or even third, line in order to ac-commodate a reasonable number of columns. The break must come after a dot, and the rest of each line containing an incomplete row label-tuple must be blank.
The following example, adapted from [INDUS], is used to illustrate. As written, this table actu-ally has nine columns and many rows: we have just reproduced a small part to show continued row label-tuples.
5.5 ACRONYMS 51
table yield (c,t,s,w,z) crop yield (metric tons per acre) nwfp pmw wheat.(bullock, semi-mech).la-plant.
(heavy, january) .385 .338 wheat.(bullock, semi-mech).la-plant.light .506 .446 wheat.(bullock, semi-mech).la-plant. standard .592 .524 wheat.(bullock, semi-mech).(qk-harv, standard).
(heavy, january) .439 .387
5.5 ACRONYMS
An acronym is a special data type that allows the use of strings as values. It is useful in very spe-cial cases and is explained in Section 6.4.
5.5.1 THE SYNTAX
The declaration for an acronymis similar to a set or parameter declaration in that several of them can be declared in one statement.
Acronym(s) acronym_name {,acronym_name}
acronym_name is an identifier and follows the same naming convention as other identifiers like names of sets, parameters, or tables.
5.5.2 ILLUSTRATIVE EXAMPLE Consider the following example,
set machines /m-1*m5/ ;
acronyms monday, tuesday, wednesday, thursday, friday ; parameter shutdown(machines) /
m-1 tuesday m-2 wednesday m-3 friday m-4 monday m-5 thursday / ;
In the example above, data entries are in the form of strings like 'monday' and 'tuesday'. By declaring each of those character strings as acronyms, this kind of data entry can be used by GAMS. Sections 6.2.7 and 11.2.5 will explain the further use of acronyms once entered in this form.
5.6 SUMMARY
In this chapter, the declaration and initialization of parameters with the parameter, scalar and the table statement have been discussed. The next chapter will describe how this data can be changed with assignment statements.