Table of Contents
Introduction
The display statement in GAMS is a quick way to write data into the listing file. It does not provide a publication quality reporting function, but is instead aimed at functionality that is easy to use and provides graceful defaults. These defaults may be modified by the user to control the layout and appearance of the output. Both defaults and customization options are presented in this chapter. For information on the listing file, see chapter GAMS Output. In addition to the display statement, GAMS offers the put writing facility, a more sophisticated way to generate reports, where the user has much more flexibility and control over the output of individual items.
The Syntax
In general, the syntax for the display statement in GAMS is as follows:
display ident | quoted text {, ident | quoted text};
The keyword display indicates that this is a display statement. It is followed by an identifier. If the identifier is a set or a parameter, only the name of the set or parameter itself is specified. If the identifier is a variable, an equation or a model, it must be followed by a suffix, i.e. a variable attribute, equation attribute or model attribute respectively. As usual, quoted text must be surrounded by single or double quotes. The identifiers and the text may be mixed and matched in any order, and the whole statement may be continued over several lines. For conditional displays a dollar condition may follow the keyword display.
The output produced by a display statement consists of labels and data. For multi-dimensional sets the keyword yes (indicating membership) is used instead of values.
- Note
- Only the non-default values are displayed for all data types.
The default value is generally zero. Exceptions are some upper and lower bounds of variables and equations (the attributes .lo and .up). Their default values are listed in sections Variable Attributes and Equation Attributes respectively.
The syntax of the display statement is illustrated by the following example:
Sets s / s1*s4 /
t / t5*t7 /
st(s,t) / s1.t5, s1.t7, s2.t6, s3.t7, s4.t5 / ;
Parameters p(s) / s1 0.33, s3 0.67 /
q(t) / t5 0.33, t7 0.67 / ;
Variable v(s,t) ;
v.l(s,t) = p(s)*q(t);
display 'first a simple set', s, 'then a two-dimensional set', st, 'then a parameter', p,
'then the activity level of a variable', v.l;
The display statement will generate the following lines in the listing file:
---- 8 first a simple set
---- 8 SET s
s1, s2, s3, s4
---- 8 then a two-dimensional set
---- 8 SET st
t5 t6 t7
s1 YES YES
s2 YES
s3 YES
s4 YES
---- 8 then a parameter
---- 8 PARAMETER p
s1 0.330, s3 0.670
---- 8 then the activity level of a variable
---- 8 VARIABLE v.L
t5 t7
s1 0.109 0.221
s3 0.221 0.449
In the case of multi-dimensional identifiers like the set st and the level values of the variable v, the data is by default reported in a tabular form that is easy to read. Note that only the non-default values are displayed. To display zero values, the special value EPS can be used. In the example above, all values of the parameter p can be displayed by adding the following lines.
display 'display all values';
p(s)$(not p(s)) = EPS;
display p;
The following lines will be displayed in the listing file.
---- 11 display all values ---- 13 PARAMETER p s1 0.330, s2 EPS, s3 0.670, s4 EPS
An alternative to displaying EPS is to use acronym but computations cannot be done with the resulting parameters.
Displaying Multi-Dimensional Identifiers: Label Order
We have seen that two-dimensional identifiers are displayed in table format. The default layout for displaying multi-dimensional identifiers is summarized in Table 1. Note that the default format may be modified with the local display control. The figures in the table refer to the index position in the domain list of the identifier. For example, if we display x, where x has been declared as x(i,j,k,l), then the i labels (the first index) will by default be associated with the individual subtables, the j and k with the row labels and the l (the fourth and last index) with the column headings.
| Number of Indices | Subtable | Index Position(s) on the Row | Column |
|---|---|---|---|
| 1 | list format | ||
| 2 | - | 1 | 2 |
| 3 | - | 1,2 | 3 |
| 4 | 1 | 2,3 | 4 |
| 5 | 1,2 | 3,4 | 5 |
| 6 | 1,2,3 | 4,5 | 6 |
Table 1: Default Layout for Displaying Multi-Dimensional Identifiers
For 7 to the maximum number of indices the natural progression is followed. For the current maximum number of indices, see Dimensions. The labels vary slowest for the first index position and quickest for the highest. Within each index position the order of the label is the GAMS entry order of the labels. Some users may need to manipulate the order of the labels.
- Note
- The only way to change the order in which the labels for each index position appear in the display output is to change the order of appearance of the labels in the GAMS program.
This is most easily done by declaring a set whose only purpose is to list all the labels in the order that is needed. Make this set the very first declaration in the GAMS program.
Note that the order of the indices in an identifier is always as the order in the declaration statement. One can declare them in the order that is found appealing, or make an assignment to a new identifier with a different order, as illustrated in the example below.
Example for Multi-Dimensional Displays
Consider the following example. The parameter x has four dimensions or index positions. It is initialized using parameter format and then displayed as shown below.
Set i first index / first, second /
j second index / one, two, three /
k third index / a, b /
l fourth index / i, ii / ;
Parameter
x(i,j,k,l) a four dimensional structure /
second.one.a.i 0.00013, first .three.b.i -6.3161
first .one.b.i 5.63559, second.two .b.i 20000.00
second.one.b.ii -17.29948, first .two .b.ii 10.3457
first .two.a.ii 0.02873, second.one .a.ii 1.0037
second.two.a.ii +inf, first .two .a.i -2.9393
first .one.a.ii 0.00000 /
y(k,l,i,j) a four dimensional structure with changed index order;
y(k,l,i,j) = x(i,j,k,l);
display x, y;
For variable x the code fragment produces the following output:
---- 16 PARAMETER x a four dimensional structure
INDEX 1 = first
i ii
one .b 5.636
two .a -2.939 0.029
two .b 10.346
three.b -6.316
INDEX 1 = second
i ii
one.a 1.300000E-4 1.004
one.b -17.299
two.a +INF
two.b 20000.000
Notice that there are two subtables, one for each label in the first index position. Note further that the order of the labels is not the same as in the input data list of the parameter x, but is according to the label order in the driving sets. Observe that the numbers closer in magnitude to one are displayed in fixed format, rounded to three digits (the default). This default may be modified with display controls, the topic of the next section. In contrast, the especially small value appears in E-format: it would display as all zeros in fixed format. Note also that the zero in the list for x('first','one','a','ii') has vanished, since default values are not shown. Similarly, rows and columns containing only zero values are suppressed in each subtable separately.
Notice furthermore how parameter y can be used to display the same data with a different index order.
Display Controls
GAMS allows the user to modify the number of row and column labels in the display listing as well as the accuracy of the data being displayed. There are global and local display controls. Global display controls allow the user to affect more than one display statement. The local display control may be used to override the global controls if specific data need to be listed in a particular format. Both controls are expressed with option statements.
Global Display Controls
The first option for global display controls specifies the number of digits shown after the decimal point. It affects the numbers appearing in all display output following the option statement, unless it is changed for a specific identifier as shown below. The general form of this option statement is:
option decimals = value;
The keyword option indicates that this is an option statement, decimals is the specific option and value is an integer between 0 and 8. The value 0 supresses decimals as well as the decimal point. Note that the default is decimals=3, and that setting this option does not change the field width, just the number of decimals. Increasing decimals results in more digits being displayed; this may in turn cause numbers to appear in E-format if the longer fixed-format result would exceed the field width.
A word about rounding for display purposes is in order. In the event of ties, the display routines use the round-to-even tie-breaking rule. So for example, with decimals=0, both 1.5 and 2.5 will display as 2. Similarly, with decimals=1, 2.25 displays as 2.2 while 2.75 displays as 2.8.
Consider the following extension to the example discussed in the previous section.
option decimals = 1; display x;
GAMS will display numbers using E-format where necessary to avoid exceeding the display width or showing all zeros. The output is as follows:
---- 14 PARAMETER x a four dimensional structure
INDEX 1 = first
i ii
one .b 5.6
two .a -2.9 2.873000E-2
two .b 10.3
three.b -6.3
INDEX 1 = second
i ii
one.a 1.300000E-4 1.0
one.b -17.3
two.a +INF
two.b 20000.0
Note that GAMS overrode the decimal choice for x('first','two','a','ii') to ensure that small numbers are not displayed as zeroes.
Another option for global display control modifies the width of the display. This is particularly important for longer label names. Label names that are headers of columns are cut off after 9 characters when data is displayed in table format. The following option may be used to display longer names in full:
option dispwidth = value;
The name of the option is dispwidth and value is a positive integer smaller or equal to 31. An illustrative example follows.
Set i 'South African cities' / Johannesburg, Cape_Town /
j 'other African cities' / Maputo, Dar_es_Salaam /
f(i,j) 'direct flight connections' / Johannesburg.Maputo, Johannesburg.Dar_es_Salaam, Cape_Town.Maputo /;
display f ;
The display statement generates the following output:
---- 4 SET f direct flight connections
Maputo Dar_es_Sa~
Johannesburg YES YES
Cape_Town YES
Note that only the label 'Dar_es_Salaam' is cut off since it is heading a column. The label 'Johannesburg' is not cut off as it is the label for a row. Now we add the following line to change the width of the display statement:
option dispwidth = 15; display f;
As expected, the output changes and the label 'Dar_es_Salaam' is no longer cut off:
---- 5 SET f direct flight connections
Maputo Dar_es_Salaam
Johannesburg YES YES
Cape_Town YES
Local Display Control
It is often useful to control the number of decimals for specific identifiers separately. The following option statement accomplishes this:
option ident:d-value;
Ident denotes the name of the identifier and d-value is an integer in the range 0 to 8. The number of decimal places shown on all displays of ident that follow will be d-value.
This option statement can be extended to control the layout of the data in addition to the decimal places. The general form is as follows:
option ident:d-value:r-value:c-value ;
Here r-value denotes the number of index positions that are combined to form the row label and c-value means the number of indices on the column headers.
The example discussed in the previous section is further extended in order to illustrate the local display control.
option x:5:3:1; display x;
These two statements generate the following output:
---- 17 PARAMETER x a four dimensional structure
i ii
first .one .b 5.63559
first .two .a -2.93930 0.02873
first .two .b 10.34570
first .three.b -6.31610
second.one .a 0.00013 1.00370
second.one .b -17.29948
second.two .a +INF
second.two .b 20000.00000
Note that five decimal places are shown, three labels are used to mark the rows and one label acts as head of the column. Since this is a four-dimensional structure, all indices are accounted for.
The next example places two indices on each of the row and and column labels and retains five decimal places:
option x:5:2:2; display x;
The output is:
---- 18 PARAMETER x a four dimensional structure
a.i a.ii b.i b.ii
first .one 5.63559
first .two -2.93930 0.02873 10.34570
first .three -6.31610
second.one 0.00013 1.00370 -17.29948
second.two +INF 20000.00000
If in the option statement less dimensions are specified than the number of indices in the domain, then subtables will be generated for the labels of the beginning indices. Observe how the display layout will change if we use the following statement:
option x:0:1:1; display x;
The output follows.
---- 19 PARAMETER x a four dimensional structure
INDEX 1 = first INDEX 2 = one
i
b 6
INDEX 1 = first INDEX 2 = two
i ii
a -3 2.873000E-2
b 10
INDEX 1 = first INDEX 2 = three
i
b -6
INDEX 1 = second INDEX 2 = one
i ii
a 1.300000E-4 1
b -17
INDEX 1 = second INDEX 2 = two
i ii
a +INF
b 20000
The option statement is checked for consistency against the dimensionality of the identifier and error messages will be issued if the number of the dimensions specified in the option statement is larger than the number of indices in the domain of the identifier.
Display Statement to Generate Data in List Format
The option statement for local display controls may be used to generate data in list format by setting the r-value to zero:
option ident:d-value:0:c-value;
In this case the c-value specifies the maximum number of items displayed on a line. The actual number will depend on the page width and the number and length of the labels.
Using the same example as in the previous sections, we change the r-value to zero in the option statement:
option x:5:0:1; display x;
option x:5:0:2; display x;
Note that we specified one and two columns to illustrate the impact of different c-value settings. These statements will generate the following output:
---- 20 PARAMETER x a four dimensional structure first .one .b.i 5.63559 first .two .a.i -2.93930 first .two .a.ii 0.02873 first .two .b.ii 10.34570 first .three.b.i -6.31610 second.one .a.i 0.00013 second.one .a.ii 1.00370 second.one .b.ii -17.29948 second.two .a.ii +INF second.two .b.i 20000.00000 ---- 21 PARAMETER x a four dimensional structure first .one .b.i 5.63559, first .two .a.i -2.93930 first .two .a.ii 0.02873, first .two .b.ii 10.34570 first .three.b.i -6.31610, second.one .a.i 0.00013 second.one .a.ii 1.00370, second.one .b.ii -17.29948 second.two .a.ii +INF, second.two .b.i 20000.00000
This output nicely illustrates the label order used. The first index varies the slowest, the last the fastest, and each one runs from beginning to end before the next one to the left advances. This ordering scheme is also used in equation and column lists and in the solution report which are all generated by the solve statement.
Conditional Displays
This section assumes familiarity with the if statement and the dollar condition.
The display statement may be controlled by conditional expressions. Conditionals have the effect that the items are displayed only if a logical condition is satisfied. There are two ways to express conditional displays in GAMS: with dollar conditions and using if statements. The syntax using a dollar condition is as follows:
display$logical_condition ident | quoted text {, ident | quoted text};
Note that the dollar condition is inserted after the keyword display. For details on the various forms of conditional expressions in GAMS, see sections Logical Conditions and Filtering Sets. Consider the following simple example:
Scalars x, y;
x = 7;
y = 3;
display$(x-y < 0) "display if x minus y is less than 0", x, y;
The logical condition (x-y < 0) controls the display statement. In this case it is not satisfied, hence there will be no display output. If the value of y is changed to, say 10, then the logical condition will be satisfied and the display statement will generate the following output:
---- 4 display if x minus y is less than 0
PARAMETER x = 7.000
PARAMETER y = 10.000
The syntax for conditional displays using an if statement is as follows:
if( logical_condition, display statement );
The simple example above may be reformulated as follows:
Scalars x, y;
x = 7;
y = 3;
if( x-y < 0,
display "display if x minus y is less than 0", x, y;
);