### Table of Contents

# Introduction

The output from GAMS contains many components in support for checking and comprehending a model. This chapter discusses the components of the GAMS output file generated from a GAMS run as well as ways to control the amount of diagnostic output produced. A GAMS run also generates a log which serves as a useful first step in analysing a GAMS run. The details regarding the log can be found in the GAMS log chapter.

The output file generated from a GAMS run is called *listing* *file*. The listing file has the file extension `.lst`

and can be read using any text editor. By default the listing file has the same file name as the input file, but this can be changed using the command line parameter Output. See chapter The GAMS Call and Command Line Parameters for more information. The main components in the listing file are:

- Compilation. The compilation output contains an echo print of the input file, possibly error messages, along with lists of GAMS objects and cross reference maps.
- Execution. The execution output contains the results of display statements and possibly execution error messages.
- Model Generation. The output generated during model generation contains listings of equations and variable listings as well as model statistics and possibly generation execution error messages.
- Solution. The output generated when an external solver program processes the model is the solution report including the solve summary, the solver report, the solution listing and the report summary.
- Post-Solution. The final components added to the listing file are the final execution summary and the file summary.

A small nonlinear program [ALAN] will be used to illustrate every component of the listing file. The possibilities for extension to large models with voluminous output (which is when the diagnostics are really useful) should be apparent. After covering all the components of the listing file we will discuss error reporting and conclude the chapter with a compiled list of how to customize the output file.

This chapter does not cover the output that can be generated by the user through display statements and put statements. This output is covered in the chapters The Display Statement and The Put Writing Facility respectively.

# An Illustrative Model

[ALAN] is a portfolio selection model whose objective is to choose a portfolio of investments whose expected return meets a target while minimizing the variance. We will discuss a simplified version of this model. The input file is listed for reference.

```
$Title A Quadratic Programming Model for Portfolio Analysis (ALAN,SEQ=124a)
$onsymlist onsymxref onuellist onuelxref
$Ontext
This is a mini mean-variance portfolio selection problem described in
'GAMS/MINOS:Three examples' by Alan S. Manne, Department of Operations
Research, Stanford University, May 1986.
$Offtext
* This model has been modified for use in the documentation
Set i securities /hardware, software, show-biz, t-bills/;
alias (i,j);
Scalar target target mean annual return on portfolio % /10/,
lowyield yield of lowest yielding security,
highrisk variance of highest security risk ;
Parameters mean(i) mean annual returns on individual securities (%)
/ hardware 8
software 9
show-biz 12
t-bills 7 /
Table v(i,j) variance-covariance array (%-squared annual return)
hardware software show-biz t-bills
hardware 4 3 -1 0
software 3 6 1 0
show-biz -1 1 10 0
t-bills 0 0 0 0 ;
lowyield = smin(i, mean(i)) ;
highrisk = smax(i, v(i,i)) ;
display lowyield, highrisk ;
Variables x(i) fraction of portfolio invested in asset i
variance variance of portfolio
Positive Variable x;
Equations fsum fractions must add to 1.0
dmean definition of mean return on portfolio
dvar definition of variance;
fsum.. sum(i, x(i)) =e= 1.0;
dmean.. sum(i, mean(i)*x(i)) =e= target;
dvar.. sum(i, x(i)*sum(j,v(i,j)*x(j))) =e= variance;
Model portfolio / fsum, dmean, dvar / ;
Solve portfolio using nlp minimizing variance;
display x.l, variance.l;
```

# Compilation Output

The compilation output is the output produced during the initial check of the program, often referred to as compilation. It contains the following parts: the echo print of the input file, the symbol reference map, the symbol listing map, the unique element listing map, and the include file summary.

By default only the echo print and the include file summary is shown, the other parts are suppressed and may be turned on with dollar control options. See also section Customizing the Output File on how to control the appearance and amount of detail in the output file produced by the GAMS compiler.

## The Echo Print of the Input File

The *echo* *print* of the program is always the first part of the output file. It is a listing of the input with added line numbers. It is possible to control the listing output using $offlisting to suppress the echo print and $onlisting to turn the echo print on again. The first few lines of the echo print of the Illustrative Model follow:

A Quadratic Programming Model for Portfolio Analysis (ALAN,SEQ=124a) C o m p i l a t i o n 2 4 This is a mini mean-variance portfolio selection problem described in 'GAMS/MINOS:Three examples' by Alan S. Manne, Department of Operations Research, Stanford University, May 1986. 10 11 * This model has been modified for use in the documentation

The default header of the GAMS listing file is `General Algebraic Modeling System`

. This may be replaced using the $title at the start of a line. The text on that line will be the new header, as demonstrated above. After the header the compilation output is announced with the title `Compilation`

.

The first three line numbers refer to empty lines in the input and line 11 is a comment line. If the lines on the input file are counted, it can be seen that this comment line appears after ten lines of dollar directives, comments and empty lines.

The dollar control options that follow in the model are used to display more information in the output file than the default and will be discussed in the subsections below.

- Note
- By default, dollar control option lines are not listed in the echo print. The $onDollar and $offDolar controls the echoing of Dollar Control Options lines in the listing file. Dollar control option lines are also listed if they contain errors.

The block comment enclosed by $ontext and $offtext is listed without line numbers, while single line comments starting with asterisks (*) are listed with the respective line numbers. Observe that line numbers always refer to the physical line number in the input file. The remainder of the echo print follows:

12 13 Set i securities /hardware, software, show-biz, t-bills/; 14 alias (i,j); 15 16 Scalar target target mean annual return on portfolio % /10/, 17 lowyield yield of lowest yielding security, 18 highrisk variance of highest security risk ; 19 20 Parameters mean(i) mean annual returns on individual securities (%) 21 / hardware 8 22 software 9 23 show-biz 12 24 t-bills 7 / ; 25 26 Table v(i,j) variance-covariance array (%-squared annual return) 27 hardware software show-biz t-bills 28 hardware 4 3 -1 0 29 software 3 6 1 0 30 show-biz -1 1 10 0 31 t-bills 0 0 0 0 ; 32 33 lowyield = smin(i, mean(i)) ; 34 highrisk = smax(i, v(i,i)) ; 35 display lowyield, highrisk ; 36 37 Variables x(i) fraction of portfolio invested in asset i 38 variance variance of portfolio ; 39 Positive Variable x ; 40 41 Equations fsum fractions must add to 1.0 42 dmean definition of mean return on portfolio 43 dvar definition of variance; 44 45 fsum.. sum(i, x(i)) =e= 1.0; 46 dmean.. sum(i, mean(i)*x(i)) =e= target; 47 dvar.. sum(i, x(i)*sum(j,v(i,j)*x(j))) =e= variance; 48 49 Model portfolio / fsum, dmean, dvar / ; 50 Solve portfolio using nlp minimizing variance; 51 display x.l, variance.l;

Lines in the echo print can be set to double space using $double and then reset to single space with $single. If errors were detected, the explanatory messages would be found at the end of the echo print. All discussions of error messages have been grouped together in the section Error Reporting below.

## The Symbol Reference Map

The other parts of the compilation outputs are maps. They are extremely useful for users looking at a model written by someone else or trying to make changes in their own model after spending some time away from it. By default all maps are suppressed and can be turned on with dollar control options that are specified below.

The first map is the *symbol* *cross* *reference*. It can be turned on with the dollar control option $onSymXRef at the beginning of the program. The symbol cross reference map lists all identifiers (symbols) from the model in alphabetical order, identifies them as to data type, shows the line numbers where the symbols appear and classifies each appearance. The map that was generated as part of the output of our Illustrative Model is shown below:

Symbol Listing SYMBOL TYPE REFERENCES dmean EQU declared 42 defined 46 impl-asn 50 ref 49 dvar EQU declared 43 defined 47 impl-asn 50 ref 49 fsum EQU declared 41 defined 45 impl-asn 50 ref 49 highrisk PARAM declared 18 assigned 34 ref 35 i SET declared 13 defined 13 ref 14 20 26 33 2*34 37 45 2*46 2*47 control 33 34 45 46 47 j SET declared 14 ref 26 2*47 control 47 lowyield PARAM declared 17 assigned 33 ref 35 mean PARAM declared 20 defined 21 ref 33 46 portfolio MODEL declared 49 defined 49 impl-asn 50 ref 50 target PARAM declared 16 defined 16 ref 46 v PARAM declared 26 defined 26 ref 34 47 variance VAR declared 38 impl-asn 50 ref 47 50 51 x VAR declared 37 impl-asn 50 ref 39 45 46 2*47 51

In the first two columns the name and type of each identifier are given. For example, the last symbol listed is `x`

which is defined to be of type `VAR`

, a shorthand symbol for variable. The complete list of data types and their shorthand symbols is given below:

Shorthand Symbol | GAMS Data Type |
---|---|

`ACRNM` | `acronym` |

`EQU` | `equation` |

`FILE` | `put file` |

`MODEL` | `model` |

`PARAM` | `parameter` |

`SET` | `set` |

`VAR` | `variable` |

For further details on data types in GAMS, see section Data Types and Definitions.

The symbol `highrisk`

was declared as a `scalar`

, but is listed as a `parameter`

in the map above. Recall that `parameters`

, `scalars`

, and `tables`

are three *input* *formats* for the data type `parameter`

. For more information, see the overview Parameters, Scalars and Tables.

After the name and type of the identifier, a list of references to the symbol is given. References are grouped by reference type and identified by the line number in the output file. The actual reference can be found by referring to the echo print of the program, which has line numbers on it. In the case of the symbol `x`

in the example above, the list of references as shown in the symbol reference map are as follows:

declared 37 impl-asn 50 ref 39 45 46 2*47 51

This means that `x`

is declared on line 37, implicitly assigned through a `solve`

statement on line 50 and referenced on lines 39, 45, 46, 47, and 51. The entry `2*47`

means that there are two references to `x`

on line 47 of the input file.

The complete list of reference types and their shorthand symbols in GAMS Output is given below:

Shorthand Symbol | Reference Type | Description |
---|---|---|

`declared ` | Declaration | The identifier is declared as to type. This must be the first appearance of the identifier. |

`defined ` | Definition | An initialization (for a table or a data list between slashes) or symbolic definition (for an equation) starts for the identifier. |

`assigned ` | Assignment | Values are replaced because the identifier appears on the left-hand side of an assignment statement. |

`impl-asn ` | Implicit Assignment | An equation or variable will be updated as a result of being referred to implicitly in a solve statement. |

`control ` | Control | A set is used as (part of) the driving index in an assignment, equation, loop or indexed operation. |

`ref ` | Reference | The symbol has been referenced on the right-hand side of an assignment or in a display, equation, model, solve statement or put statetement. |

`index` | Index | Like `control` , but used only for set labels. Appears only in the cross reference map of unique elements. See section The Unique Element Listing Map for details. |

Note that the symbol reference map may be useful in model development, documentation preparation, and to make sure that all declared items are actually used in the model (by checking that they all have reference symbols in addition to `declared`

and `defined`

).

## The Symbol Listing Map

The second optional map is the *symbol* *listing*. In the symbol listing map all identifiers are grouped alphabetically by data type and listed with their explanatory texts. This is another very useful aid for trying to understand a large model prepared by someone else. Note that expressive explanatory text is particularly helpful here. The symbol listing map can be turned on by entering a line containing the dollar control option $onSymList at the beginning of the program. The symbol listing map generated from our Illustrative Model follows:

SETS i securities j Aliased with i PARAMETERS highrisk variance of highest security risk lowyield yield of lowest yielding security mean mean annual returns on individual securities (%) target target mean annual return on portfolio % v variance-covariance array (%-squared annual return) VARIABLES variance variance of portfolio x fraction of portfolio invested in asset i EQUATIONS dmean definition of mean return on portfolio dvar definition of variance fsum fractions must add to 1.0 MODELS portfolio

## The Unique Element Listing Map

The last optional map is the *Unique* *Element* *Listing* (UEL). The unique element listing map can be turned on by entering a line containing the dollar control option $onUELList at the beginning of the program. All unique elements are first grouped in entry order and then in sorted order with their explanatory texts:

Unique Element Listing Unique Elements in Entry Order 1 hardware software show-biz t-bills Unique Elements in Sorted Order 1 hardware show-biz software t-bills

In addition, a map with references for every label is given if the dollar control option $onUELXRef appears at the beginning of the program.

ELEMENT REFERENCES hardware declared 13 ref 21 27 28 show-biz declared 13 ref 23 27 30 software declared 13 ref 22 27 29 t-bills declared 13 ref 24 27 31

The unique element list is important in the context of ordered sets. For details see section Ordered and Unordered Sets.

## The Include File Summary

Often the GAMS program includes a text file specified by the dollar control option $include. Consider the following example:

```
$include 'file1.inc'
Set i / i1*i10 /;
Scalar a; a = 7;
$include 'file2.inc'
```

The file `file1.inc`

contains the following two lines:

```
Set j / j1*j5 /;
Parameter k(j);
```

The file `file2.inc`

contains the following line:

```
a = a+3;
```

The echo print follows:

INCLUDE C:\models\file1.inc 2 Set j / j1*j5 /; 3 Parameter k(j); 4 Set i / i1*i10 /; 5 Scalar a; a = 7; INCLUDE C:\models\file2.inc 7 a = a+3;

Note that the contents of the two include files are expanded in the echo print and the include file names and their path is echoed in the lines with the dollar control option $include. If we insert the dollar control option $offInclude in the first line of the code, the echo print will not include the lines with the names of the include files any more, but the contents will still be echoed:

3 Set j / j1*j5 /; 4 Parameter k(j); 5 Set i / i1*i10 /; 6 Scalar a; a = 7; 8 a = a+3;

If the program contains include files, there will be an `Include File Summary`

at the end of the compilation output. The include file summary of the simple example above (without the line $offInclude) follows. If `$offInclude`

is active, it will be suppressed.

Include File Summary SEQ GLOBAL TYPE PARENT LOCAL FILENAME 1 1 INPUT 0 0 C:\models\test.gms 2 1 INCLUDE 1 1 .C:\models\file1.inc 3 6 INCLUDE 1 4 .C:\models\file2.inc

In the first column the sequence number of the input files is given. Note that the parent file called by the GAMS call is always listed first. The second column gives the global (expanded) line number which contains the respective option `include`

or one of its variants. The third column indicates the type of the respective file. An overview of the file types is given below:

File Type | Description |
---|---|

`INPUT` | The GAMS input file that was called with the GAMS call. |

`INCLUDE` | A file that was inserted with the dollar command option $include. |

`BATINCLUDE` | A file that was inserted with the dollar command option $batinclude. |

`LIBINCLUDE` | A file that was inserted with the dollar command option $libinclude. |

`SYSINCLUDE` | A file that was inserted with the dollar command option $sysinclude. |

The next column, named `PARENT`

, provides the sequence number of the respective parent file. The column with the header `LOCAL`

gives the local line number in the parent file where the file was included. The last column shows the path and the name of the respective file.

Note that compilation error messages in include files have additional information about the name of the include file and the local line number. For information on compilation errors, see section Compilation Errors below.

# Execution Output

The execution output follows the compilation output in the GAMS listing file. It is introduced with the title `Execution`

. The execution output is the output generated while GAMS is performing data manipulations and results from display statements. The output from the display statement on line 33 of our Illustrative Model is shown below.

E x e c u t i o n ---- 33 PARAMETER lowyield = 7.000 yield of lowest yielding security PARAMETER highrisk = 10.000 variance of highest security risk

If errors are detected because of illegal data operations, a brief message indicating the cause and the line number of the offending statement will appear. For further information on execution errors, see section Execution Errors below.

- Note
- In case there is no display statement before The Solve Statement in the model and there are no execution errors, there will be no execution output in the GAMS listing file.

# Model Generation Output

The model generation output, the solution report, and the post-solution Output are produced when a solve statement is executed. The actions that are initiated by a solve statement are presented in section Actions Triggered by the Solve Statement. All output generated as a result of a solve is labeled with a subtitle identifying the model, its type and the line number of the solve statement.

The output generated during model generation includes equations listing, variable listing, and model statistics.

## The Equation Listing

The *equation* *listing* is the first part of the output generated by a solve statement. It is marked with the subtitle `Equation Listing`

. By default, the first three equations in every block are listed. This can be modified with the option limrow. If there are three or fewer single equations in any equation block, then all the single equations are listed.

Note that by studying the equation listing the user may determine whether the model generated by GAMS is the the model that the user has intended - an extremely important question. This component of the output shows the specific equations generated within the model when the current values of the sets and parameters are plugged into the general algebraic form of the model.

The equation listing from our Illustrative Model is given below. In our case we have three equation blocks, each producing one single equation.

A Quadratic Programming Model for Portfolio Analysis (ALAN,SEQ=124a) Equation Listing SOLVE portfolio Using NLP From line 50 ---- fsum =E= fractions must add to 1.0 fsum.. x(hardware) + x(software) + x(show-biz) + x(t-bills) =E= 1 ; (LHS = 0, INFES = 1 ****) ---- dmean =E= definition of mean return on portfolio dmean.. 8*x(hardware) + 9*x(software) + 12*x(show-biz) + 7*x(t-bills) =E= 10 ; (LHS = 0, INFES = 10 ****) ---- dvar =E= definition of variance dvar.. (0)*x(hardware) + (0)*x(software) + (0)*x(show-biz) - variance =E= 0 ; (LHS = 0)

- Note
- The equation listing is an extremely useful debugging aid. It shows the variables that appear in each constraint. In addition, it shows what the individual coefficients and right-hand side values evaluate to after the data manipulations have been done.

Each equation block is marked with four dashes which are useful for mechanical searching. The name, type of equation and explanatory text is shown, followed by the individual equations.

- Note
- All the terms that depend on variables are collected on the left-hand side and all the constant terms are combined into one number on the right-hand side, any necessary sign changes being made.

Four places of decimals are shown if necessary, but trailing zeroes following the decimal point are suppressed. E-format is used to prevent small numbers to be displayed as zeros.

- Note
- Nonlinear equations are treated differently. If the coefficient of a variable in the equation listing is enclosed in parentheses, then the corresponding constraint is nonlinear, and the value of the coefficient depends on the activity levels of one or more of the variables. The listing is not algebraic, but shows the partial derivative of each variable evaluated at their current level values.

Note that in the equation listing from our example the equation `dvar`

is nonlinear. A simpler example will help to clarify the point. Consider the following equation and associated level values.

```
eq1.. 2*sqr(x)*power(y,3) + 5*x - 1.5/y =e= 2; x.l = 2; y.l = 3 ;
```

This equation will appear in the equation listing as:

eq1.. (221)*x + (216.1667)*y =E= 2 ; (LHS = 225.5 ***)

The coefficient of \(x\) is determined by first differentiating the equation above with respect to \(x\). This results in \(2 \times (2 \times x.l) \times (y.l)^3+5\), which evaluates to 221, given that \(x.l\) equals 2 and \(y.l\) equals 3. Similarly, the coefficient of \(y\) is obtained by differentiating the equation above with respect to `y`

, which results in \(2 \times (x.l)^2 \times 3 \times (y.l)^2 + \frac {1.5}{(y.l)^2}\), giving 216.1667. Observe that the coefficient of \(y\) could not have been determined if its level had been left at zero. The attempted division by zero would have produced an error and premature termination. For further information on modeling NLP problems with GAMS, see the tutorial Good NLP Formulations.

The result of evaluating the left-hand side of the equation at the initial point is shown at the end of each individual equation listing. In the example above it is 225.5, and the three asterisks(`***`

) are a warning that the constraint is infeasible at the starting point.

- Note
- The order in which the equations are listed depends on how the model was defined. If it was defined with a list of equation names, then the listing will be in the order of that list. If it was defined as
`/all/`

, then the list will be in the order of declaration of the equations. The order of the entries for the individual constraints is determined by the label entry order.

## The Column Listing

The *column* *listing* or *variable* *listing* is the next part of the output. It is marked with the title `Column Listing`

and contains a list of the individual coefficients sorted by column rather than by row (like in the equation listing). By default the first three entries for each variable are shown, along with their lower bound `.lo`

, upper bound `.up`

and current level values `.l`

. Note that the default number of entries shown may be modified with the option limcol.

The format for the coefficients is exactly as in the equation listing, with the nonlinear coefficients enclosed in parentheses and the trailing zeroes dropped. The column listing from our Illustrative Model follows.

A Quadratic Programming Model for Portfolio Analysis (ALAN,SEQ=124a) Column Listing SOLVE portfolio Using NLP From line 50 ---- x fraction of portfolio invested in asset i x(hardware) (.LO, .L, .UP, .M = 0, 0, +INF, 0) 1 fsum 8 dmean (0) dvar x(software) (.LO, .L, .UP, .M = 0, 0, +INF, 0) 1 fsum 9 dmean (0) dvar x(show-biz) (.LO, .L, .UP, .M = 0, 0, +INF, 0) 1 fsum 12 dmean (0) dvar REMAINING ENTRY SKIPPED ---- variance variance of portfolio variance (.LO, .L, .UP, .M = -INF, 0, +INF, 0) -1 dvar

- Note
- The order in which the variables appear is the order in which they were declared.

## The Range Statistics

This block shows a statistic about the range of values seen in the model. Namely, it prints the range of absolute non-zero values for the bounds, right hand sides and matrix coefficients. Zero values are marked explicitly. This is the example output when running the model [TRNSPORT]:

Range Statistics SOLVE transport Using LP From line 71 RANGE STATISTICS (ABSOLUTE NON-ZERO FINITE VALUES) RHS [min, max] : [ 2.750E+02, 6.000E+02] - Zero values observed as well Bound [min, max] : [ NA, NA] - Zero values observed as well Matrix [min, max] : [ 1.260E-01, 1.000E+00]

Note the `NA`

range for the bounds: For this model, the bounds are either `0`

or `+INF`

. Both values are excluded in this range calculation. Therefore we see the `NA`

here.

## The Model Statistics

The final information generated while a model is being prepared for solution is the statistics block. It is marked with the title `Model Statistics`

. Its most obvious use is to provide details on the size and nonlinearity of the model. The model statistics of our Illustrative Model follow:

A Quadratic Programming Model for Portfolio Analysis ALAN,SEQ=124a) Model Statistics SOLVE portfolio Using NLP From line 50 MODEL STATISTICS BLOCKS OF EQUATIONS 3 SINGLE EQUATIONS 3 BLOCKS OF VARIABLES 2 SINGLE VARIABLES 5 NON ZERO ELEMENTS 12 NON LINEAR N-Z 3 CODE LENGTH 25 CONSTANT POOL 17 GENERATION TIME = 0.004 SECONDS 4 MB EXECUTION TIME = 0.005 SECONDS 4 MB

The `BLOCK`

counts indicate the number of GAMS symbols (`equations`

and `variables`

, respectively) appearing in the problem generated. The `SINGLE`

counts indicate the number of individual rows and columns in the problem generated. The `NON ZERO ELEMENTS`

entry refers to the number of nonzero coefficients in the problem matrix. To understand the remaining elements, some background will be useful.

For linear models, the model can be completely specified by the problem matrix and vectors for the RHS, etc. More is needed for noninear models. GAMS passes the nonlinear expressions defining the model algebra to the solvers in the form of *NL code* - opcode/address pairs in a simple stack-based language. For example, the expression `exp(x*y-1.675)`

results in code similar to this:

PUSHV column-index-of-x MULV column-index-of-y SUBC index-of-1.675 FUNC1 index-of-exp-function STOR index-of-row

In addition to containing indices refering to the rows and columns of the model, the NL code contains indices of constants used to define the model algebra. These constants are not contained in the NL code directly but rather in a separate pool or list of constants used for the model.

There are three entries that provide additional information about nonlinear models. The `NON LINEAR N-Z`

entry refers to the number of nonlinear matrix entries in the model. Nonlinear models may differ in the complexity or size of the nonlinear expressions defining them. For example, `x*y`

is a simpler form of nonlinearity than `exp(x*y)`

and will require a shorter list of instructions to define, even though both of these terms result in two nonlinear entries in the matrix (one for x and one for y). The `CODE LENGTH`

entry indicates the length of the NL code (i.e. number of instuctions) required to define the model algebra, while the `CONSTANT POOL`

indicates the length of the constant pool that is used by the NL code. In general, the more nonlinear a problem is, the more difficult it tends to be to solve.

The times that follow statistics are also useful. The `GENERATION TIME`

is the time used since compilation (syntax check) is finished. This includes the time spent in generating the model. The measurement units are given and represent ordinary clock time on personal computers or central processor usage (CPU) time on other machines. Memory use is given in megabytes.

# The Solution Report

The *solution* *report* is the next part of the output. It is marked with the title `Solution Report`

and includes the solve summary, the solver report, the solution listing, and the report summary.

## The Solve Summary

The *solve* *summary* contains details about the solution process and is marked with the title `SOLVE SUMMARY`

. The first part of the solve summary is common to all solvers and is discussed in this subsection. The second part of the solve summary is solver specific, it is covered in the subsection Solver Report below. The first part of the solve summary for our Illustrative Model follows.

A Quadratic Programming Model for Portfolio Analysis ALAN,SEQ=124a) Solution Report SOLVE portfolio Using NLP From line 50 S O L V E S U M M A R Y MODEL portfolio OBJECTIVE variance TYPE NLP DIRECTION MINIMIZE SOLVER MINOS FROM LINE 50 **** SOLVER STATUS 1 Normal Completion **** MODEL STATUS 2 Locally Optimal **** OBJECTIVE VALUE 2.8990 RESOURCE USAGE, LIMIT 0.188 1000.000 ITERATION COUNT, LIMIT 5 2000000000 EVALUATION ERRORS 0 0

The entry `MODEL`

contains the name of the model being solved, `TYPE`

provides the model type of the model, `SOLVER`

shows the name of the solver used to solve the model, `OBJECTIVE`

gives the name of the objective variable being optimized, `DIRECTION`

shows the direction of optimization being performed and the entry `FROM LINE`

provides the line number of the solve statement the solve summary refers to.

Note that the four asterisks make it easy to find the solve summary if it is searched for mechanically.

The entries `SOLVER STATUS`

and `MODEL STATUS`

contain the solver and model status for the problem respectively. Their possible values are given in Model Status table and Solver Status tables below. The entry `OBJECTIVE VALUE`

provides the value of the objective function at the termination of the solve. This value is the optimum value for the problem provided the solver and model have the right status.

The entry `RESOURCE USAGE, LIMIT`

reports the amount of wall clock time (in seconds) taken by the solver and the upper limit allowed for the solver. Note that the solver will stop as soon as the limit on time usage has been reached. The default limit may be changed with the option reslim. Observe that the option statement `option reslim = x;`

- where `x`

is the desired limit in wall clock seconds - must be entered in the model *before* the solve statement.

The entry `ITERATION COUNT, LIMIT`

provides the number of iterations used by the solver and the upper limit allowed for the solver. The solver will stop as soon as this limit is reached. The default limit on iterations used is practically infinity. This limit may be changed with the option iterlim. Observe that the option statement `option iterlim = n;`

- where `n`

is the desired limit of the iterations used - must be entered in the model *before* the solve statement.

Finally, the entry `EVALUATION ERRORS`

reports the number of numerical errors encountered by the solver and the upper limit allowed for the solver. These errors result from numerical problems like division by zero. Note that this is suppressed for LP, RMIP and MIP models since evaluation errors are not applicable for these model types. The default limit on evaluation errors used is zero. This limit may be changed with the option domlim. Observe that the option statement `option domlim = n;`

- where `n`

is the desired limit of the evaluation errors allowed - must be entered in the model *before* the solve statement.

### Model Status

Value | Message | Description |
---|---|---|

`1 ` | `OPTIMAL` | The solution is optimal, that is, it is feasible (within tolerances) and it has been proven that no other feasible solution with better objective value exists. Note that the latter criterion is not influenced by the optcr and optca options. |

`2 ` | `LOCALLY OPTIMAL` | A local optimum for an NLP has been found. That is, a solution that is feasible (within tolerances) and it has been proven that there exists a neighborhood of this solution in which no other feasible solution with better objective value exists. |

`3 ` | `UNBOUNDED` | The solution is unbounded. This message is reliable if the problem is linear, but occasionally it appears for difficult nonlinear problems that are not truly unbounded, but that lack some strategically placed bounds to limit the variables to sensible values. |

`4 ` | `INFEASIBLE` | The problem has been proven to be infeasible. If this was not intended, something is probably misspecified in the logic or the data. |

`5 ` | `LOCALLY INFEASIBLE` | No feasible point could be found for the NLP problem from the given starting point. It does not necessarily mean that no feasible point exists. |

`6 ` | `INTERMEDIATE INFEASIBLE` | The current solution is not feasible, but the solver stopped, either because of a limit (for example, iteration or resource) or because of some sort of difficulty. The solver status will give more information. |

`7 ` | `FEASIBLE SOLUTION` | A feasible solution to a problem without discrete variables has been found. |

`8 ` | `INTEGER SOLUTION` | A feasible solution to a problem with discrete variables has been found. There is more detail following about whether this solution satisfies the termination criteria (set by options optcr and optca). |

`9 ` | `INTERMEDIATE NON-INTEGER` | An incomplete solution to a problem with discrete variables. A feasible solution has not yet been found. See section Model Termination Conditions for MIPs for more information. |

`10 ` | `INTEGER INFEASIBLE` | It has been proven that there is no feasible solution to a problem with discrete variables. See section Model Termination Conditions for MIPs for more information. |

`11 ` | `LIC PROBLEM - NO SOLUTION` | The solver cannot find the appropriate license key needed to use a specific subsolver. |

`12 ` | `ERROR UNKNOWN` | After a solver error the model status is unknown. |

`13 ` | `ERROR NO SOLUTION` | An error occurred and no solution has been returned. No solution will be returned to GAMS because of errors in the solution process. |

`14 ` | `NO SOLUTION RETURNED` | A solution is not expected for this solve. For example, the CONVERT solver only reformats the model but does not give a solution. |

`15 ` | `SOLVED UNIQUE` | Indicates the solution returned is unique, i.e. no other solution exists. Used for CNS models. Examples where this status could be returned include non-singular linear models, triangular models with constant non-zero elements on the diagonal, and triangular models where the functions are monotone in the variable on the diagonal. |

`16 ` | `SOLVED` | Indicates the model has been solved: used for CNS models. The solution might or might not be unique. If the solver uses status `17 - SOLVED SINGULAR` wherever possible then this status implies that the Jacobian is non-singular, i.e. that the solution is at least locally unique. |

`17 ` | `SOLVED SINGULAR` | Indicates the CNS model has been solved, but the Jacobian is singular at the solution. This can indicate that other solutions exist, either along a line (for linear models) or a curve (for nonlinear models) including the solution returned. |

`18 ` | `UNBOUNDED - NO SOLUTION` | The model is unbounded and no solution can be provided. |

`19 ` | `INFEASIBLE - NO SOLUTION` | The model is infeasible and no solution can be provided. |

Note that the model status is stored in the model attribute modelStat. For details on model attributes, see section Model Attributes. Observe that there are compile-time constants that are related to this model attribute.

### Solver Status

Value | Message | Description |
---|---|---|

`1 ` | `NORMAL COMPLETION` | The solver terminated in a normal way: it was not interrupted by a limit (resource, iterations, nodes or other) or by internal difficulties. The model status describes the characteristics of the accompanying solution. |

`2 ` | `ITERATION INTERRUPT` | The solver was interrupted because it used too many iterations. The option iterlim may be used to increase the iteration limit if everything seems normal. |

`3 ` | `RESOURCE INTERRUPT` | The solver was interrupted because it used too much time. The option reslim may be used to increase the time limit if everything seems normal. |

`4 ` | `TERMINATED BY SOLVER` | The solver encountered some difficulty and was unable to continue. More details will appear following the message. |

`5 ` | `EVALUATION INTERRUPT` | Too many evaluations of nonlinear terms at undefined values. We recommend to use variable bounds to prevent forbidden operations, such as division by zero. The rows in which the errors occur are listed just before the solution. |

`6 ` | `CAPABILITY PROBLEMS` | The solver does not have the capability required by the model. For example, some solvers do not support certain types of discrete variables or support a more limited set of functions than other solvers. |

`7 ` | `LICENSING PROBLEMS` | The solver cannot find the appropriate license key needed to use a specific subsolver. |

`8 ` | `USER INTERRUPT` | The user has sent a message to interrupt the solver via the interrupt button in the IDE or sending a Control+C from a command line. |

`9 ` | `ERROR SETUP FAILURE` | The solver encountered a fatal failure during problem set-up time. |

`10 ` | `ERROR SOLVER FAILURE` | The solver encountered a fatal error. |

`11 ` | `ERROR INTERNAL SOLVER FAILURE` | The solver encountered an internal fatal error. |

`12 ` | `SOLVE PROCESSING SKIPPED` | The entire solve step has been skipped. This happens if execution errors were encountered and the GAMS parameter ExecErr has been set to a nonzero value or the property MaxExecError has a nonzero value. |

`13 ` | `ERROR SYSTEM FAILURE` | This indicates a completely unknown or unexpected error condition. |

Note that the solver status is stored in the model attribute solveStat. For details on model attributes, see section Model Attributes. Observe that there are compile-time constants that are related to this model attribute.

## Solver Report

The next section in the listing file is the part of the solve summary that is particular to the solver program that has been used. This section normally begins with a message identifying the solver and its authors: MINOS and QUADMINOS was used in the example here. There will also be diagnostic messages in plain language if anything unusual was detected and specific performance details, some of them probably technical. The solver manual of the respective solver will help explain these. In case of serious trouble, the GAMS listing file will contain additional messages printed by the solver. This may help identify the cause of the difficulty. If the solver messages do not help, a perusal of the solver documentation or help from a more experienced user is recommended. The solver report from our Illustrative Model follows.

GAMS/MINOS M I N O S 5.6 (Nov 2014) GAMS/MINOS 5.6, Large Scale Nonlinear Solver B. A. Murtagh, University of New South Wales P. E. Gill, University of California at San Diego, W. Murray, M. A. Saunders, and M. H. Wright, Systems Optimization Laboratory, Stanford University Work space allocated -- 0.77 Mb EXIT - Optimal Solution found, objective: 2.899038

Note that the line `Work space allocated – 0.77 MB`

provides the amount of memory used by the solver for the problem. The solver estimates the amount of memory it will need to solve the problem. If this amount is not available on the machine used, GAMS will return a message saying that not enough memory was allocated. In addition, GAMS will return the maximum amount of memory available on the machine. The user may direct the solver to use less memory with the model attribute `.workspace`

:

```
mymodel.workspace = x;
```

Here `mymodel`

is the name of the model being solved as specified by the model statement and `x`

is the amount of memory in Megabytes. Note that the solver will attempt to solve the problem with `x`

MB of memory. However, it is not guaranteed to succeed since the problem may require more memory.

Note that more information for a successful run may be obtained using the option sysout. As usual, the respective option statement should be placed *before* the solve statement.

## The Solution Listing

The solution listing is a row-by-row then column-by-column listing of the solutions returned to GAMS by the solver program. Each individual equation and variable is listed with four pieces of information. The solution listing may be suppressed with the option solprint:

```
option solprint = off ;
```

This option statement should be placed *before* the solve statement. The solution listing generated from our Illustrative Model is shown below.

LOWER LEVEL UPPER MARGINAL ---- EQU fsum 1.0000 1.0000 1.0000 -13.5288 ---- EQU dmean 10.0000 10.0000 10.0000 1.9327 ---- EQU dvar . . . -1.0000 fsum fractions must add to 1.0 dmean definition of mean return on portfolio dvar definition of variance ---- VAR x fraction of portfolio invested in asset i LOWER LEVEL UPPER MARGINAL hardware . 0.3029 +INF . software . 0.0865 +INF 6.217249E-15 show-biz . 0.5048 +INF . t-bills . 0.1058 +INF EPS LOWER LEVEL UPPER MARGINAL ---- VAR variance -INF 2.8990 +INF . variance variance of portfolio

The order of the equations and variables is the same as in the symbol listing map.

The four columns associated with each entry correspond to the equation and variable attributes and have the following meaning:

`LOWER`

lower bound (`.lo`

)

`LEVEL`

level value (`.l`

)

`UPPER`

upper bound (`.up`

)

`MARGINAL`

marginal (`.m`

)

For variables, the values in the `LOWER`

and `UPPER`

columns refer to the lower and upper bounds. For equations, they are obtained from the (constant) right-hand side value and from the relational type of the equation. For details see section Variable Attributes and Equation Attributes. Note that instead of `level`

values, `slack`

values may be shown in equations. For more information, see section Customizing the Output File below.

- Note
- The
`LEVEL`

and`MARGINAL`

values have been determined by the solver and the values shown are used to update the GAMS values. In the list they are shown with fixed precision, but the values are returned to GAMS with full machine accuracy. The single dots '`.`

' on the list represent zeros.

EPS is the GAMS extended value used for a stored zero. It is common to see a marginal value given as `EPS`

, since GAMS uses the convention that marginals are necessarily zero for basic variables and typically non-zero for other variables.

- Note
- EPS is used to indicate non-basic variables whose marginal values are at or close to zero, and for nonlinear problems to indicate superbasic variables whose marginals are at or close to zero. A superbasic variable is one between its bounds at the final point but not in the basis.

Note that in the Glossary there are brief explanations of technical terms that were used in this section.

For models that are not solved to optimality or for models types without an objective, some constraints may additionally be marked with certain flags. The list of these flags and their description is given in the following table.

Shorthand Symbol | Description |
---|---|

`INFES` | The row or column is infeasible. This mark is made for any entry where the level value is not between the upper and lower bounds. |

`NOPT` | The row or column is non-optimal. This mark is made for any non-basic entries for which the marginal sign is incorrect, or superbasic ones for which the marginal value is too large. |

`UNBND` | The row or column can increase without limit (e.g. in an unbounded ray) or has an excessively large magnitude. |

`REDEF` | The equation type has been ignored or redefined for this solution point, e.g. because this is an MCP |

`REDIR` | The equation has been flipped (i.e. negated or reoriented) in the model statement: useful for MCP and EMP |

`DEPND` | The row or column is dependent on other rows or columns in the system: see CNS |

## Report Summary

The final section of the solution report is the report summary, marked with four asterisks (as are all important components of the output) followed by the title `REPORT SUMMARY`

. It shows the count of rows or columns that have been marked `INFES`

, `NOPT`

or `UNBND`

in the solution listing. For model types like MCP where REDEFs and REDIRs are possible, the counts for these markers may also be shown. The sum of infeasibilities will be shown if the reported solution is infeasible. The domain error count is only shown if the problem is nonlinear. If there are variables or equations where the levels were projected to one of the bounds, the count of those is also shown here.

A Quadratic Programming Model for Portfolio Analysis ALAN,SEQ=124a) Solution Report SOLVE portfolio Using NLP From line 50 **** REPORT SUMMARY : 0 NONOPT 0 INFEASIBLE 0 UNBOUNDED 0 ERRORS 42 PROJECTED

# Post-Solution Output

The final part of the listing file is the post-solution output. It contains Final Execution Summary and the File Summary.

## Final Execution Summary

The final execution summary is marked with the title `Execution`

and contains the output from display statements that were placed *after* the solve statement in the model, allowing simple reporting. In addition, it shows the final exection time and memory use. The respective ouput from our Illustrive Model follows.

A Quadratic Programming Model for Portfolio Analysis ALAN,SEQ=124a) E x e c u t i o n ---- 51 VARIABLE x.L fraction of portfolio invested in asset i hardware 0.303, software 0.087, show-biz 0.505, t-bills 0.106 ---- 51 VARIABLE variance.L = 2.899 variance of portfolio EXECUTION TIME = 0.001 SECONDS 3 MB

For further information on this output and ways to customize it, see chapter The Display Statement.

## File Summary

The file summary is the very last part of the output file. If output has been written to put files, there will be a `REPORT FILE SUMMARY`

that is marked with four asterisks. The report will list the put files with their internal names and the full paths of their external names.

All listing files have a `FILE SUMMARY`

that is marked with four asterisks and that reports the names of the input and output (listing) files.

**** FILE SUMMARY Input C:\PROGRAM FILES\\gamsIDE\ALAN.GMS Output C:\PROGRAM FILES\\gamsIDE\ALAN.LST

If work files (save or restart) have been used, they will be listed in the file summary as well.

# Error Reporting

All comments and descriptions about errors have been collected in this section for easy reference when disaster strikes.

Effective error detection and recovery are important parts of any modeling system. GAMS is designed around the assumption that the *error state* is the normal state of modeling. Experience shows that most compilations during the early stages of development will produce errors. Not to worry! The computer is much better at checking details than the human mind and should be able to provide positive feedback and suggestions about how to correct errors or avoid ambiguities. Developing a model is like writing a paper or an essay; many drafts and rewrites are required until the arguments are presented in the most effective way and meet all the requirements of proper English. GAMS acts like a personal assistant with knowledge of mathematical modeling and of the syntactic and semantic details of the language.

Errors are detected at various stages in the modeling process. Most of them are caught at the compilation stage, which behaves like the proofreading stage of the modeling process. Once a problem has passed through the rigorous test of this stage, the error rate drops to almost zero. Most of the execution runs, which are much more expensive than compilation, proceed without difficulties because GAMS *knows* about modeling and has anticipated problems. Many of the typical errors made with conventional programming languages are associated with concepts that do not exist in GAMS. Those error sources – like address calculations, storage assignment, subroutine linkages, input-output and flow control – create problems at execution time, are difficult to locate, often lead to long and frustrating searches, and leave the computer user intimidated. GAMS takes a radically different approach. Errors are spotted as early as possible, they are reported in a way that is comprehensible to the user, including clear suggestions for how to correct the problem and a presentation of the source of the error in terms of the problem of the user.

- Note
- All errors are marked with four asterisks '
`****`

' at the beginning of a line in the output listing.

As soon as an error is detected, processing will be stopped at the next convenient opportunity. A model will never be solved after an error has been detected. The only remedy is to fix the error and repeat the run.

Errors are grouped into the three phases of GAMS modeling: compilation, execution and model generation (which includes the solution that follows). In the following subsections we will discuss the errors that may occur in each of these phases.

## Compilation Errors

Compilation errors are discussed in some detail in the tutorial A GAMS Tutorial by Richard E. Rosenthal and the tutorial Fixing Compilation Errors. Note that there is some overlap between the material in the tutorials and this section. Several hundred different types of errors can be detected during compilation and can often be traced back to just one specific symbol in the GAMS input. Most of the errors are caused by simple mistakes: forgetting to declare an identifier, putting indices in the wrong order, leaving out a necessary semicolon or misspelling a label. For errors that are not caused by such simple mistakes, the explanatory error message text will help diagnose the problem and correct it.

- Note
- When a compilation error is discovered, a dollar symbol and error number are printed below the offending symbol (usually to the right) on a separate line that begins with four asterisks.

If more than one error is encountered on a line (possibly because the first error caused a series of other spurious errors) the dollar signs may be suppressed and error number squeezed. GAMS will not list more than 10 errors on any one line.

- Note
- A list of all error numbers encountered and a description of the probable cause of each error is printed at the end of the echo print of the program. The error messages are self-explanatory. For further information on compilation errors and advice on how to resolve them, see the tutorial Fixing Compilation Errors.

It is worth noting that it is easy to produce a model that does not do what you want it to do, but does not contain errors in the sense that the term is being used in this section. The best precaution is to check your work carefully and build in as many automatic consistency checks as possible.

Note that if a GAMS reserved word is accidentally used for the name of a label or an identifier it is impossible to provide helpful error messages for technical reasons. This may cause confusion. We recommend users to familiarize themselves with the reserved words.

- Attention
- In some cases an error may not be detected until the statement following its occurrence, where it may produce a number of error conditions whose explanations seem quite silly. We recommend to always check carefully for the cause of the first error in such a group. If nothing obvious is wrong, look at the previous statement and particularly watch out for missing semicolons.

The following example illustrates the general reporting format for compilation errors.

1 Set c crops / wheat, corn, wheat, longaname / **** $172 2 Parameter price(c) / wheat 200, cotton 700 / **** $170 3 Error Messages 170 Domain violation for element 172 Element is redefined **** 2 ERROR(S) 0 WARNING(S) .. **** USER ERROR(S) ENCOUNTERED

## Compilation Time Errors

The reporting format for errors found while analyzing solve statements is more complicated than for normal compilation errors, mainly because many things must be checked. All identifiers referenced must be defined or assigned, the mathematics in the equations must match the model class, and so on. More elaborate reporting is required to accurately describe any problems found. The solve statement is only checked if the model has been found to be error free up to this point. This is not only because the check is comparatively expensive, but also because many erroneous and confusing messages can be produced while checking a solve in a program containing other errors.

- Attention
- Compiler error messages related to a solve statement are reported in two places and in two formats:
- They are shown immediately after the solve statement with a short text including the name of any offending identifier and the type of model involved. This will be sufficient in most cases.
- A longer message with some hints appears with the other error messages at the end of the compilation.

The example below illustrates the general reporting format for compiler errors associated with a solve statement.

1 Variables x, y, z ; 2 Equations eq1 , eq2 ; 3 4 eq1.. x**2 - y =e= z ; 5 eq2.. min(x,y) =l= 20 ; 6 7 Model silly / all / ; 8 solve silly using lp maximizing z ; **** $54,51,256 **** THE FOLLOWING LP ERRORS WERE DETECTED IN MODEL SILLY: **** 54 IN EQUATION EQ1 .. ENDOG OPERANDS FOR ** **** 51 IN EQUATION EQ2 .. ENDOG ARGUMENT(S) IN FUNCTION 9 Error Messages 51 Endogenous function argument(s) not allowed in linear models 54 Endogenous operands for ** not allowed in linear models 256 Error(s) in analyzing solve statement. More detail appears Below the solve statement above **** 3 ERROR(S) 0 WARNING(S) **** USER ERROR(S) ENCOUNTERED

## Execution Errors

Execution time errors are usually caused by illegal arithmetic operations such as division by zero or taking the log of a negative number. GAMS prints a message on the output file with the line number of the offending statement and continues execution. A GAMS program should never abort with an unintelligible message from the computer's operating system if an invalid operation is attempted. GAMS has rigorously defined an extended algebra that contains all operations including illegal ones. Note that the model [CRAZY] contains all non-standard operations and should be executed to study for its exceptions. For advice on detecting and resolving execution errors, see the tutorial Finding and Fixing Execution Errors and Performance Problems.

Recall that the GAMS arithmetic is defined over the closed interval [`-INF`

,`+INF`

] and contains the extendedn range arithmetic values `EPS`

(small but not zero), `NA`

(not available) and `UNDF`

(the result of an illegal operation). The results of illegal operations are propagated through the entire system and can be displayed with standard display statements. However, observe that, if errors have been previously detected, a model cannot be solved and a work file cannot be saved.

## Solve Errors

The execution of a `solve`

statement can trigger additional errors called *matrix* *errors*. They report on problems encountered during transformation of the model into a format required by the solver. Problems are most often caused by illegal or inconsistent bounds, or by an extended range value that is used as a matrix coefficient. The example below shows the general format of these errors:

1 Variable x; 2 Equation eq1; 3 4 eq1.. x =l= 10 ; 5 x.lo = 10 ; 6 x.up = 5 ; 7 Model wrong /eq1/; 8 solve wrong using lp maximizing x ; 9 **** Matrix error - lower bound > upper bound x (.LO, .L, .UP = 10, 0, 5) ... **** SOLVE from line 8 ABORTED, EXECERROR = 1 ... **** USER ERROR(S) ENCOUNTERED

Some `solve`

statements require the evaluation of nonlinear functions and the computation of derivatives. Since these calculations are not carried out by GAMS but by other subsystems not under the direct control of GAMS, errors associated with these calculations are reported in the solution report. Note that by default the subsystems will interrupt the solution process if arithmetic exceptions are encountered. This may be changed with the option domlim. They are then reported on the listing as shown in the following example:

1 Variable x, y; 2 Equation one; 3 4 one.. y =e= sqrt(10/x); 5 x.l = 10; 6 x.lo = 0; 7 8 Model divide / all / ; 9 solve divide maximizing y using nlp; S O L V E S U M M A R Y MODEL divide OBJECTIVE y TYPE NLP DIRECTION MAXIMIZE SOLVER MINOS FROM LINE 9 **** SOLVER STATUS 5 Evaluation Interrupt **** MODEL STATUS 7 Feasible Solution **** OBJECTIVE VALUE 3.1622776602E+0149 RESOURCE USAGE, LIMIT 0.182 1000.000 ITERATION COUNT, LIMIT 0 2000000000 EVALUATION ERRORS 2 0 EXIT - Function evaluation error limit exceeded. **** ERRORS/WARNINGS IN EQUATION one 2 error(s): div: FUNC SINGULAR: x/y, |y| <= 1e-150 (RETURNED 1E299) **** REPORT SUMMARY : 1 NONOPT ( NOPT) 0 INFEASIBLE 0 UNBOUNDED 1 ERRORS ( ****)

Note that the solver status returned with a value of 5, meaning that the solver has been interrupted because more than `domlim`

evaluation errors have been encountered. The type of evaluation error and the equation causing the error are also reported.

In case the solver returns an intermediate feasible solution because of evaluation errors, the following solve will still be attempted. The only fatal GAMS error that can be caused by a solver program, is the failure to return any solution at all. If this happens all possible information is listed on the GAMS output file and any solves that follow will not be attempted.

# Customizing the Output File

This section reviews the most commonly used dollar control options, options, and command line parameters to customize output in the listing file. Table 1 lists dollar control options, options, and command line parameters that are used in the input file to control the amount of detail in the output file produced by the GAMS compiler. Table 2 lists dollar control options and command line parameters that can change the layout and appearance of the output. The first column of the two tables shows the purpose of customizing the output that differs from the GAMS default behavior.

The output generated by display statements can also be customized. This topic is covered in section Display Controls from chapter The Display Statement. See also the complete list of dollar control options that affect the output format in section Dollar Control Options Affecting the Output Format.

**Table 1: Customization of output to be included in the listing file**

Customization | Method | Further Details |
---|---|---|

suppress the echo print | $offlisting | $onlisting restores the default behavior. Any lines between $offlisting and $onlisting will not appear in the echo print. |

suppress include files in the echo print | $offinclude | $oninclude restores the default behavior. |

activate the symbol reference map | $onSymXRef | Maps are most often turned on or off at the beginning of the program and left as initially set. $onSymXRef activates the symbol reference map and $offSymXRef restores the default behavior. |

activate the symbol listing map | $onSymList | Maps are most often turned on or off at the beginning of the program and left as initially set. $onSymList activates the symbol listing map and $offSymList restores the default behavior. |

activate the unique element listing | $onUELList | Maps are most often turned on or off at the beginning of the program and left as initially set. $onUELList activates the unique element listing map and $offUELList restores the default behavior. |

activate the unique element reference map | $onUELXRef | Maps are most often turned on or off at the beginning of the program and left as initially set. $onUELXRef activates the unique reference map $offUELXRef restores the default behavior. |

suppress or expand the equation listing | option limrow | The statement `option limrow = 0;` will suppress the equation listing; the statement `option limrow = n;` will expand it to `n` equations. The statement must be placed before The Solve Statement. |

suppress or expand the column listing | option limcol | The statement `option limcol = 0;` will suppress the column listing; the statement `option limcol = n;` will expand it to `n` columns. The statement must be placed before The Solve Statement. |

suppress the solution listing | option solprint | The statement `option solprint = off;` will suppress the solution listing. The statement must be placed before The Solve Statement. |

restrict output to just a few displays | save restart feature | With this strategy the listing file will contain only the output generated by the desired display statements. This facilitates concentrating on a narrow set of output while remaining capable of generating a lot more output. For details see section Generating Concise Listing Files in chapter The Save and Restart Feature. |

show slack variables in the solution listing | option solslack | The statement `option solslack = 1;` causes the equation output in the solution listing to show slack (`.slack` ) variable values instead of level (`.l` ) values. The statement must be placed before The Solve Statement. |

**Table 2: Customization that changes the output layout**

Customization | Method | Further Details |
---|---|---|

change the default header | $title | The directive $title causes every page on the output to have the header specified in `text` . The header may be reset later by using another line starting with $title . Currently, the `text` may have up to 80 characters. |

add a subheader | $stitle | The statement `$stitle text` causes every page on the output to have the subheader specified in `text` . The header may be reset later by using another line starting with $stitle. Currently, the `text` may have up to 80 characters. |

start a new page in the echo print | $eject | |

start a new page in LST file if less than `n` lines are left | $lines | The directive is $lines, where `n` is the number of lines left on the current page. |

change width and length of a page | command line parameters PageWidth and PageSize | The general syntax is: `gams mymodel pw=n ps=m` . Here `n` is desired page width and the desired page length is `m` . Note that `pw` and `ps` are synonyms of PageWidth and PageSize respectively. |

change the echo print to upper case only | $onUpper | The directive `$offUpper` restores the default. |

change lines in the echo print to be double spaced | $double | The directive $single restores the default beahvior. |

change the marker `****` | $stars |