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:

1. 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.
2. Execution. The execution output contains the results of display statements and possibly execution error messages.
3. 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.
4. 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.
5. 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:

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:

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 (UEL) Listing. The unique element listing 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:

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

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

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.

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:

1. 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.
2. 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

Table 2: Customization that changes the output layout