GAMS A Users Guide

Tutorial by Richard E. Rosenthal

May 2017 GAMS Development Corporation, Washington, DC, USA

ii
Preface

This documentation guides GAMS User through several topics in GAMS system. Some introductions to software systems
are like reference manuals: they describe each command in detail. Others take you step by step through a small number of
examples. This guide uses elements of both approaches.

Introduction and Tutorial - This is a self-contained tutorial that guides you through a single example, a small
transportation model, in some detail: you can quickly investigate the flavor of GAMS by reading it.

Introduction - an introductory to GAMS User's Guide.

Tutorial - A GAMS Tutorial by Richard E. Rosenthal.

Language Basics - This part introduces the components of the GAMS language in an ordered way, interspersed with
detailed examples that are often drawn from the model library. All models from the model library are enclosed in
square parenthesis (for example, [TRNSPORT]). Some specialized material has deliberately been omitted in this
process because the primary aim is to make GAMS accessible to the widest possible audience, especially those without
extensive experience with computers or mathematical programming systems. Some familiarity with quantitative
methods and mathematical representations is assumed.

GAMS Programs - The structure of the GAMS language and its components
Set Definition - The declaration and initialization of sets, subsets, and domain checking.
Data Entry: Parameters, Scalars and Tables - Three basic forms of GAMS data types : Parameters, Scalars and
Tables.
Data Manipulations with Parameters - The declaration and assignment of GAMS parameters.
Variables - The declaration and attributes of GAMS variables.
Equations - The definition and declaration of GAMS equations.
Model and Solve Statements Model - The specificiation of a GAMS model and how to solve it.
GAMS Output - The control of GAMS compilation output, execution output, output produced by a solve
statement, and error reporting.
Conditional Expressions, Assignments and Equations - The conditional assignments, expressions and equations
in GAMS.
Dynamic Sets - The membership assignment, the usage of dollar controls, and set operations.
Sets as Sequences: Ordered Sets - Special features used to deal with a set as if it were a sequence.
The Display Statement - The syntax, control, and label order in display.
The Put Writing Facility - The put writing facility of the GAMS language.
Programming Flow Control Features - The GAMS programing flow control features : loop, if-elseif, while, and
for statements.
Special Language Features - Special features in GAMS that do not translate across solvers, or are specific to
certain smodel types.
iv

Advanced Topics - This part discusses advanced topics and can be studied as needed. Users with large, complex, or
expensive models will find much useful material in this part.
Glossary - An alphabetically list of GAMS terms.
The GAMS Model Library - Introduction of GAMS Model Library.
The GAMS Call - The list and detailed description of GAMS command line parameters.
Dollar Control Options - The list and detailed description of dollar control options.
The Option Statement - The list and detailed description of options.
The Save and Restart Feature - The GAMS save and restart feature and the work file.
Secure Work Files - The access control command, its usage, and obfuscated work files.
Compressed and Encrypted Input Files - The encryption, compression and decompression of GAMS input files.
The Grid and Multi-Threading Solve Facility - The basic concepts and Grid Features.
Extrinsic Functions - The extrinsic function library and comparison with external equations.
External Equations - A facility for connecting code written in different programming languages to equations and
variables in a GAMS model.
GAMS Return Codes - The structure of error codes, the return codes of the GAMS compiler and execution
system, and the driver return codes.
GAMS Data eXchange (GDX) - GAMS Data eXchange (GDX) facilities and utilities for Binary Data Exchange.
Data and Model Exchange with Other Applications - The different ways to exchange data and model between
GAMS and other applications.
* Data Exchange with ASCII Files
* Data Exchange with Excel
* Data Exchange with Databases
* Data Export to HTML and XML Files
* Data and Model Export to LaTeX
* Data Export to Gnuplot
* Data and Model Exchange with MPS files
* Data Exchange with NETGEN and GNETGEN - Network Problems
Stochastic Programming (SP) with EMP - the stochastic programming (SP) extension of GAMS Extended
Mathematical Programming (EMP).
Mathematical Programming System for General Equilibrium analysis (MPSGE) - A mathematical programming
system for general equilibrium analysis which operates as a subsystem within GAMS.
* MPSGE Models in GAMS
* Demand Theory and General Equilibrium: An Intermediate Level Introduction to MPSGE
* Constant Elasticity of Substitution Functions: Some Hints and Useful Formulae
* A Library of Small Examples for Self-Study
* Comparing the Performance of Flexible Functional Forms
* General Equilibrium with Public Goods
* Kevin O'Rourke: CGE and Economic History
* Linking Implan Social Accounts to MPSGE
* A partial list of publications based on MPSGE
* The MPSGE guide is also available as PDF
Table of Contents

I Introduction and Tutorial 1

1 Introduction 3
1 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2 Basic Features of GAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1 General Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.3 Portability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.4 User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.5 Model Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 A GAMS Tutorial by Richard E. Rosenthal 7

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2 Structure of a GAMS Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3 Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4 Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1 Data Entry by Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2 Data Entry by Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3 Data Entry by Direct Assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
6 Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6.1 Equation Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6.2 GAMS Summation (and Product) Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6.3 Equation Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
7 Objective Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
8 Model and Solve Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
9 Display Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
10 The .lo, .l, .up, .m Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
10.1 Assignment of Variable Bounds and/or Initial Values . . . . . . . . . . . . . . . . . . . . . . . . . 19
10.2 Transformation and Display of Optimal Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
11 GAMS Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
11.1 Echo Prints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
11.2 Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
11.3 Reference Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
11.4 Equation Listings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
11.5 Model Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
11.6 Status Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
11.7 Solution Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
12 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

II Language Basics 29

3 GAMS Programs 31
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
vi TABLE OF CONTENTS

2 The Structure of GAMS Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

2.1 Format of GAMS Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.2 Classification of GAMS Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
2.3 Organization of GAMS Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3 Data Types and Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4 Language Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.1 Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.2 Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.3 Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.4 Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.5 Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.6 Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.7 Delimiters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.8 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

4 Set Definition 43
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2 Simple Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2.1 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2.2 Set Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2.3 Set Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
2.4 Associated Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
2.5 Sequences as Set Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
2.6 Declarations for Multiple Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3 The Alias Statement: Multiple Names for a Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
4 Subsets and Domain Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5 Multi-dimensional Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.1 Mapping One-to-one Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.2 Mapping Many-to-many Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
5.3 Projection and Aggregation of Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
6 Singleton Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
7 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

5 Data Entry: Parameters, Scalars and Tables 53

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
2 Scalars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
2.1 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
2.2 An Illustrative Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
3.1 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
3.2 An Illustrative Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
3.3 Parameter Data for Higher Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4.1 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
4.2 An Illustrative Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
4.3 Continued Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
4.4 Tables with more than Two Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
TABLE OF CONTENTS vii

4.5 Condensing Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

4.6 Handling Long Row Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
5 Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.1 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.2 Illustrative Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

6 Data Manipulations with Parameters 61

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
2 The Assignment Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
2.1 Scalar Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
2.2 Indexed Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
2.3 Sparse Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
2.4 Using Labels Explicitly in Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
2.5 Assignments Over Subsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
2.6 Issues with Controlling Indices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
2.7 Extended Range Identifiers in Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
2.8 Acronyms in Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.1 Standard Arithmetic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.2 Indexed Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
3.3 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
3.4 Extended Range Arithmetic and Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
4 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

7 Variables 75
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
2 Variable Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
2.1 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
2.2 Variable Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
2.3 Styles for Variable Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
3 Variable Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
3.1 Bounds on Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
3.2 Fixing Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
3.3 Activity Levels of Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
4 Variables in Display and Assignment Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
4.1 Assigning Values to Variable Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
4.2 Variable Attributes in Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
4.3 Displaying Variable Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

8 Equations 81
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
2 Equation Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
2.1 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
2.2 An Illustrative Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
3 Equation Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
viii TABLE OF CONTENTS

3.1 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

3.2 An Illustrative Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
3.3 Scalar Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
3.4 Indexed Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
3.5 Using Labels Explicitly in Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
4 Expressions in Equation Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
4.1 Arithmetic Operators in Equation Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
4.2 Functions in Equation Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
4.3 Preventing Undefined Operations in Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
5 Data Handling Aspects of Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

9 Model and Solve Statements 87

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
2 The Model Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
2.1 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
2.2 Classification of Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
2.3 Model Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
3 The Solve Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
3.1 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
3.2 Requirements for a Valid Solve Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
3.3 Actions Triggered by the Solve Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
4 Programs with Several Solve Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
4.1 Several Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
4.2 Sensitivity or Scenario Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
4.3 Iterative Implementation of Non-Standard Algorithms . . . . . . . . . . . . . . . . . . . . . . . . 100
5 Making New Solvers Available with GAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

10 GAMS Output 103

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
2 The Illustrative Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
3 Compilation Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
3.1 Echo Print of the Input File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
3.2 The Symbol Reference Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
3.3 The Symbol Listing Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
3.4 The Unique Element Listing - Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
3.5 Useful Dollar Control Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
4 Execution Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
5 Output Produced by a Solve Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
5.1 The Equation Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
5.2 The Column Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
5.3 The Model Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
5.4 The Solve Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
5.5 Solver Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
5.6 The Solution Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
5.7 Report Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
5.8 File Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
6 Error Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
TABLE OF CONTENTS ix

6.1 Compilation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

6.2 Compilation Time Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
6.3 Execution Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
6.4 Solve Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
7 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

11 Conditional Expressions, Assignments and Equations 123

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
2 Logical Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
2.1 Numerical Expressions as Logical Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
2.2 Numerical Relationship Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
2.3 Logical Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
2.4 Set Membership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
2.5 Logical Conditions Involving Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
2.6 Numerical Values of Logical Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
2.7 Mixed Logical Conditions - Operator Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
2.8 Mixed Logical Conditions - Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
3 The Dollar Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
3.1 An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
3.2 Nested Dollar Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
4 Conditional Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
4.1 Dollar on the Left . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
4.2 Dollar on the Right . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
4.3 Filtering Sets in Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
5 Conditional Indexed Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
5.1 Filtering Controlling Indices in Indexed Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 131
6 Conditional Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
6.1 Dollar Operators within the Algebra . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
6.2 Dollar Control over the Domain of Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
6.3 Filtering the Domain of Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

12 Dynamic Sets 133

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
2 Assigning Membership to Dynamic Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
2.1 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
2.2 Illustrative Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
2.3 Dynamic Sets with Multiple Indices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
2.4 Assignments over the Domain of Dynamic Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
2.5 Equations Defined over the Domain of Dynamic Sets . . . . . . . . . . . . . . . . . . . . . . . . . 135
2.6 Assigning Membership to Singleton Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
3 Using Dollar Controls with Dynamic Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
3.1 Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
3.2 Indexed Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
3.3 Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
3.4 Filtering through Dynamic Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
4 Set Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
x TABLE OF CONTENTS

4.1 Set Union . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

4.2 Set Intersection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
4.3 Set Complement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
4.4 Set Difference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

13 Sets as Sequences: Ordered Sets 139

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
2 Ordered and Unordered Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
3 Ord and Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
3.1 The Ord Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
3.2 The Card Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
4 Lag and Lead Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
5 Lags and Leads in Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
5.1 Linear Lag and Lead Operators - Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
5.2 Linear Lag and Lead Operators - Assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
5.3 Circular Lag and Lead Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
6 Lags and Leads in Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
6.1 Linear Lag and Lead Operators - Domain Control . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
6.2 Linear Lag and Lead Operators - Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
6.3 Circular Lag and Lead Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
7 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

14 The Display Statement 147

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
2 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
3 An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
4 The Label Order in Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
4.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
5 Display Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.1 Global Display Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.2 Local Display Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
5.3 Display Statement to Generate Data in List Format . . . . . . . . . . . . . . . . . . . . . . . . . . 152

15 The Put Writing Facility 153

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
2 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
3 An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
4 Output Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
4.1 Defining Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
4.2 Assigning Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
4.3 Closing a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
4.4 Appending to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
5 Page Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
6 Page Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
6.1 Accessing Various Page Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
6.2 Paging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
TABLE OF CONTENTS xi

7 Positioning the Cursor on a Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

8 System Suffixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
9 Output Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
9.1 Text Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
9.2 Numeric Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
9.3 Set Value Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
10 Global Item Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
10.1 Field Justification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
10.2 Field Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
11 Local Item Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
12 Additional Numeric Display Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
12.1 Illustrative Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
13 Cursor Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
13.1 Current Cursor Column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
13.2 Current Cursor Row . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
13.3 Last Line Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
14 Paging Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
15 Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
16 Source of Errors Associated with the Put Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
16.1 Syntax Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
16.2 Put Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
17 Simple Spreadsheet/Database Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
17.1 An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

16 Programming Flow Control Features 171

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
2 The Loop Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
2.1 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
2.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
3 The If-Elseif-Else Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
3.1 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
3.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
4 The While Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
4.1 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
4.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
5 The For Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
5.1 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
5.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

17 Special Language Features 177

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
2 Special MIP Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
2.1 Types of Discrete Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
2.2 Special Order Sets of Type 1 (SOS1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
2.3 Special Order Sets of Type 2 (SOS2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
2.4 Semi-Continuous Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
2.5 Semi-Integer Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
xii TABLE OF CONTENTS

2.6 Setting Priorities for Branching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

3 Model Scaling - The Scale Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
3.1 The Scale Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
3.2 Variable Scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
3.3 Equation Scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
3.4 Scaling of Derivatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
4 Conic Programming in GAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
4.1 Introduction to Conic Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
4.2 Implementation of Conic Constraints in GAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
4.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
4.4 Sample Conic Models in GAMS: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
4.5 References and Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
5 Indicator Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

III Advanced Topics 191

18 Glossary 193

19 The GAMS Model Library 199

20 The GAMS Call 201

1 The Generic 'no frills' GAMS Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
1.1 Specifying Options through the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
2 List of Command Line Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
2.1 General options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
2.2 Solver related options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
3 Detailed Description of Command Line Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

21 Dollar Control Options 261

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
2 List of Dollar Control Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
2.1 Options affecting input comment format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
2.2 Options affecting input data format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
2.3 Options affecting output format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
2.4 Options affecting listing of reference maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
2.5 Options affecting program control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
2.6 GDX operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
2.7 Environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
2.8 Macro definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
2.9 Compression and encrypting of source files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
3 Detailed Description of Dollar Control Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

22 The Option Statement 313

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
1.1 The Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
2 List of Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
TABLE OF CONTENTS xiii

2.1 Options controlling output detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

2.2 Options controlling solver specific parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
2.3 Options controlling choice of solver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
2.4 Options affecting input program control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
2.5 Other options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
3 Detailed Description of Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

23 The Save and Restart Feature 323

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
2 The Save and Restart Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
2.1 Saving The Work File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
2.2 Restarting from the Work File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
3 Ways in which a Work File is Useful . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
3.1 Separation of Model and Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
3.2 Incremental Program Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
3.3 Tacking Sequences of Difficult Solves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
3.4 Multiple Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
3.5 The GAMS Runtime License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

24 Secure Work Files 329

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
2 A First Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
3 Secure Work Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
4 Access Control Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
5 Advanced Use of Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
6 Limitations and Future Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
7 Obfuscated Work Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

25 Compressed and Encrypted Input Files 337

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
2 A First Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
3 The CEFILES Gamslib Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
4 The ENCRYPT GAMSLIB Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

26 The Grid and Multi-Threading Solve Facility 343

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
2 Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
3 A First Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
4 Advanced Use of Grid Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
4.1 Very Long Job Durations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
5 Summary of Grid Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
5.1 Grid Handle Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
5.2 Grid Model Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
5.3 Grid Solution Retrieval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
5.4 Grid Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
6 Architecture and Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
6.1 Grid Submission Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
7 Multi-Threading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
xiv TABLE OF CONTENTS

7.1 Multi-threading Submission Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

8 Glossary and Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

27 Extrinsic Functions 353

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
2 Fitpack Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
3 Piecewise Polynomial Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
4 Stochastic Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
5 LINDO Sampling Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
6 Build Your Own: Trigonometric Library Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
7 Build Your Own: Reading the GAMS Parameter File in your Library . . . . . . . . . . . . . . . . . . . . . 360
8 CPP Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
8.1 Automatic differentiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
8.2 Multi-variate Normal Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
9 Extrinsic function vs. External Equation Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

28 External Equations 363

1 GAMS Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
2 The Programming Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
3 Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
4 Initialization Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
5 Termination Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
6 Evaluation Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
7 Evaluation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
8 Communication and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
9 GEstat - Utility Routine for writing messages to the Status file . . . . . . . . . . . . . . . . . . . . . . . . 368
10 GElog - Utility Routine for writing messages to the Log file . . . . . . . . . . . . . . . . . . . . . . . . . . 369
11 The Message Callback MSGCB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
12 Communicating data to the external module via files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
13 Constant Derivatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
14 Second Derivatives: Hessian times Vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
15 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
16 Debugging External Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372

29 GAMS Return Codes 375

1 Structure of the Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
2 Return codes of the GAMS Compiler and Execution system (cmexRC) . . . . . . . . . . . . . . . . . . . . 375
3 Possible Values of the Driver Return Codes (cgamsRC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

30 GAMS Data eXchange (GDX) 377

1 Using the GDX facilities in GAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
1.1 Compile Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
1.2 Execution phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
1.3 Writing a GDX file after compilation or execution . . . . . . . . . . . . . . . . . . . . . . . . . . 384
1.4 Inspecting a GDX file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
2 GDX Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

31 Data Exchange with ASCII Files 387

TABLE OF CONTENTS xv

1 Import ASCII Files to GAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

1.1 Include without arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
1.2 Include with arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
1.3 CSV Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
1.4 Dealing with three and more dimensional Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
2 Export ASCII Files from GAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
2.1 The Put Writing Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
2.2 Writing Output During Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
2.3 The Put Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
2.4 Sending messages to the LOG file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394

32 Data Exchange with Excel 397

1 A tutorial on how to read data from Excel and to write data to Excel . . . . . . . . . . . . . . . . . . . . . 397
1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
1.2 Example: GAMS to Excel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
1.3 Example: Excel to GAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
2 Import from Excel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
2.1 The gdxxrw tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
2.2 The sql2gms tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
2.3 Import CSV Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
2.4 Caveat: CSV-Files and Non American English language settings . . . . . . . . . . . . . . . . . . . 402
2.5 XLS2GMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
3 Export to Excel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
3.1 The gdxxrw tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
3.2 The gdxviewer tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
3.3 Excel CSV Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
3.4 gdx2xls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
4 Mapping Index Label Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
4.1 Using a Mapping Set in GAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
4.2 Inside the Database/Spreadsheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
5 Execute GAMS from Excel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409

33 Data Exchange with Databases 411

1 Data Exchange with DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
1.1 Import from DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
1.2 Export to DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
2 Data Exchange with MS Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
2.1 Import from MS Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
2.2 Export to MS Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
3 Data Exchange with MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
3.1 Import from MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
3.2 Export to MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
4 Data Exchange with Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
4.1 Import from Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
4.2 Export to Oracle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
5 Data Exchange with SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
xvi TABLE OF CONTENTS

5.1 Import from SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

5.2 Export to SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
6 Data Exchange with SQLite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
7 Data Exchange with Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
7.1 Import from Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

34 Data Export to HTML and XML Files 439

1 Exporting to HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
2 Exporting to XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440

35 Data and Model Export to LaTeX 441

1 Model Export to LaTeX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
2 Data Export to LaTeX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441

36 Data Export to Gnuplot 445

1 Introduction and Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
2 User contributed Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

37 Data and Model Exchange with MPS files 447

38 Data Exchange with NETGEN and GNETGEN 449

39 Stochastic Programming (SP) with EMP 451

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
2 The News Vendor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
2.1 Uncertain demand: discrete distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
2.2 Uncertain demand: continuous distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
2.3 Sampling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
3 Multistage Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
4 Chance Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
4.1 Single Chance Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
4.2 Joint Chance Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
4.3 Individual Chance Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
4.4 Joint chance constraints vs. individual chance constraints . . . . . . . . . . . . . . . . . . . . . . . 468
4.5 Penalizing violations of chance constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
5 Risk Measures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
5.1 Expected Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
5.2 Value at Risk (VaR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
5.3 Conditional Value at Risk (CVaR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
6 Summary of keywords and solver configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
7 More on scenarios and output extraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479

40 MPSGE Models in GAMS 481

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
2 A Mathematical Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
3 A small example: Harberger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
4 Alternative models: Shoven and Samuelson . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
6 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
TABLE OF CONTENTS xvii

7 Appendix A: Language Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496

8 Appendix B: File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503

41 Intermediate Demand Theory and General Equilibrium: An Intermediate Level Introduction to MPSGE 505
1 An Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
2 The Theory of Consumer Demand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
3 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
4 Modeling Consumer Demand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
4.1 Example 1: Evaluating a Demand Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
4.2 Exercises 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
4.3 Example 2: Evaluating the MRS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
4.4 Exercises 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
4.5 Example 3: Leisure Demand and Labor Supply . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
4.6 Exercises 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
5 The Pure Exchange Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
6 Modeling Pure Exchange with MPSGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
6.1 Example 4: A 2x2 Exchange Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
6.2 Exercises 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
6.3 Example 5: Import Tariffs and Market Power . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
6.4 Exercises 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524

42 CES Constant Elasticity of Substitution Functions: Some Hints and Useful Formulae 527
1 The Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
2 The Calibrated Share Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
3 Excercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
4 Flexibility and Non-Separable CES functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
5 Two NNCES calibrations for a 3-input cost functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
6 A Comparison of Locally-Identical Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
7 Numerical calibration of NNCES given KLEM elasticities . . . . . . . . . . . . . . . . . . . . . . . . . . 537
8 Calibrating Labor Supply and Savings Demand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
9 A Maquette Illustrating Labor Supply and Savings Demand Calibration . . . . . . . . . . . . . . . . . . . 544

IV Installation Notes 549

43 Installation and System Notes 551

1 GAMS Installation Notes for Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
1.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
1.2 Command Line Use of GAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
2 GAMS Installation Notes for Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
2.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
2.2 Access to GAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
2.3 Installation of the Windows system under Linux using Wine . . . . . . . . . . . . . . . . . . . . . 554
3 GAMS Installation Notes for Mac OS X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555
3.1 Installation using the DMG installer (GAMS24.8.dmg) . . . . . . . . . . . . . . . . . . . . . . . . 555
3.2 Installation using the self-extracting archive (osx x64 64 sfx.exe) . . . . . . . . . . . . . . . . . . 556
3.3 Installation of the Windows version using Wine . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
xviii TABLE OF CONTENTS

Index 561
 Part I

Introduction and Tutorial

Chapter 1

Introduction

1 Motivation
Substantial progress was made in the 1950s and 1960s with the development of algorithms and computer codes to solve
large mathematical programming problems. The number of applications of these tools in the 1970s was less then expected,
however, because the solution procedures formed only a small part of the overall modeling effort. A large part of the time
required to develop a model involved data preparation and transformation and report preparation. Each model required many
hours of analyst and programming time to organize the data and write the programs that would transform the data into the
form required by the mathematical programming optimizers. Furthermore, it was difficult to detect and eliminate errors
because the programs that performed the data operations were only accessible to the specialist who wrote them and not to the
analysts in charge of the project.
GAMS was developed to improve on this situation by:

Providing a high-level language for the compact representation of large and complex models

Allowing changes to be made in model specifications simply and safely

Allowing unambiguous statements of algebraic relationships

Permitting model descriptions that are independent of solution algorithms

2 Basic Features of GAMS

2.1 General Principles

The design of GAMS has incorporated ideas drawn from relational database theory and mathematical programming and
has attempted to merge these ideas to suit the needs of strategic modelers. Relational database theory provides a structured
framework for developing general data organization and transformation capabilities. Mathematical programming provides a
way of describing a problem and a variety of methods for solving it. The following principles were used in designing the
system:

1. All existing algorithmic methods should be available without changing the user's model representation. Introduction of
new methods, or of new implementations of existing methods, should be possible without requiring changes in existing
models. Linear, nonlinear, mixed integer, mixed integer nonlinear optimizations and mixed complementarity problems
can currently be accommodated.

2. The optimization problem should be expressible independently of the data it uses. This separation of logic and data
allows a problem to be increased in size without causing an increase in the complexity of the representation.
4 Introduction

3. The use of the relational data model requires that the allocation of computer resources be automated. This means that
large and complex models can be constructed without the user having to worry about details such as array sizes and
scratch storage.

2.2 Documentation
The GAMS model representation is in a form that can be easily read by people and by computers. This means that the GAMS
program itself is the documentation of the model, and that the separate description required in the past (which was a burden to
maintain, and which was seldom up-to-date) is no longer needed. Moreover, the design of GAMS incorporates the following
features that specifically address the user's documentation needs:

A GAMS model representation is concise, and makes full use of the elegance of the mathematical representation.
All data transformations are specified concisely and algebraically. This means that all data can be entered in their
most elemental form and that all transformations made in constructing the model and in reporting are available for
inspection.
Explanatory text can be made part of the definition of all symbols and is reproduced whenever associated values are
displayed.
All information needed to understand the model is in one document.

Of course some discipline is needed to take full advantage of these design features, but the aim is to make models more
accessible, more understandable, more verifiable, and hence more credible.

2.3 Portability
The GAMS system is designed so that models can be solved on different types of computers with no change. A model
developed on a small personal computer can later be solved on a large mainframe. One person can develop a model that is
later used by others, who may be physically distant from the original developer. In contrast to previous approaches, only one
document need be moved the GAMS statement of the model. It contains all the data and logical specifications needed to
solve the model.

2.4 User Interface

Portability concerns also have implications for the user interface. The basic GAMS system is file-oriented, and no special
editor or graphical input and output routines exist. Rather than burden the user with having to learn yet another set of editing
commands, GAMS offers an open architecture in which each user can use his word processor or editor of choice. This basic
user interface facilitates the integration of GAMS with a variety of existing and future user environments.

2.5 Model Library

When architects begin to design a new building, they develop the new structure by using ideas and techniques that have been
tested in previous structures. The same is true in other fields: design elements from previous projects serve as sources of
ideas for new developments.
From the early stages of the development of GAMS we have collected models to be used in a library of examples. Many of
these are standard textbook examples and can be used in classes on problem formulation or to illustrate points about GAMS.
Others are models that have been used in policy or sector analysis and are interesting for both the methods and the data they
use. All the substantive models in the library are described in the open literature. A collection of models is now included
with all GAMS systems, along with a database to help users locate examples that cover countries, sectors, or topics of interest
to them.
The syntax used to introduce features in the various chapters are presented using the Backus-Naur form (BNF) notation
where:
2 Basic Features of GAMS 5

Notation Description
[] the enclosed construct is optional
{} the enclosed construct may be repeated zero or more times
there is an or operator across the arguments on both sides of the symbol
6 Introduction
Chapter 2

A GAMS Tutorial by Richard E. Rosenthal

1 Introduction
The introductory part of this book ends with a detailed example of the use of GAMS for formulating, solving, and analyzing
a small and simple optimization problem. Richard E. Rosenthal of the Naval Postgraduate School in Monterey, California
wrote it. The example is a quick but complete overview of GAMS and its features. Many references are made to other parts
of the book, but they are only to tell you where to look for more details; the material here can be read profitably without
reference to the rest of the book.
The example is an instance of the transportation problem of linear programming, which has historically served as a 'laboratory
animal' in the development of optimization technology. [See, for example, Dantzig (1963) 1 . ] It is a good choice for
illustrating the power of algebraic modeling languages like GAMS because the transportation problem, no matter how large
the instance at hand, possesses a simple, exploitable algebraic structure. You will see that almost all of the statements in the
GAMS input file we are about to present would remain unchanged if a much larger transportation problem were considered.
In the familiar transportation problem, we are given the supplies at several plants and the demands at several markets for a
single commodity, and we are given the unit costs of shipping the commodity from plants to markets. The economic question
is: how much shipment should there be between each plant and each market so as to minimize total transport cost?
The algebraic representation of this problem is usually presented in a format similar to the following.
Indices:
i = plants
j = markets

Given Data:
ai = supply of commodity of plant i (in cases)
b j = demand for commodity at market j
ci j = cost per unit shipment between plant i and market j
Decision Variables:

xi j = amount of commodity to ship from plant i to market j

where xi j 0, for all i, j
Constraints:

Observe supply limit at plant i: j xi j ai for all i (cases)

Satisfy demand at market j: i xi j b j for all j (cases)
Objective Function: Minimize i j ci j xi j ($K)

1 Dantzig, George B. (1963). Linear Programming and Extensions, Princeton University Press, Princeton N.J.
8 A GAMS Tutorial by Richard E. Rosenthal

Note that this simple example reveals some modeling practices that we regard as good habits in general and that are consistent
with the design of GAMS. First, all the entities of the model are identified (and grouped) by type. Second, the ordering
of entities is chosen so that no symbol is referred to before it is defined. Third, the units of all entities are specified, and,
fourth, the units are chosen to a scale such that the numerical values to be encountered by the optimizer have relatively small
absolute orders of magnitude. (The symbol $K here means thousands of dollars.)
The names of the types of entities may differ among modelers. For example, economists use the terms exogenous variable
and endogenous variable for given data and decision variable, respectively. In GAMS, the terminology adopted is as follows:
indices are called sets, given data are called parameters, decision variables are called variables, and constraints and the
objective function are called equations.
The GAMS representation of the transportation problem closely resembles the algebraic representation above. The most
important difference, however, is that the GAMS version can be read and processed by the computer.
Table 1: Data for the transportation problem (adapted from Dantzig, 1963) illustrates Shipping Distances from Plants to
Markets (1000 miles) as well as Market Demands and Plant Supplies.

Plants New York Chicago Topeka Markets

Seattle 2.5 1.7 1.8 350
San Diego 2.5 1.8 1.4 600
Demands 325 300 275 Supplies

As an instance of the transportation problem, suppose there are two canning plants and three markets, with the data given
in table Table 1. Shipping distances are in thousands of miles, and shipping costs are assumed to be $90.00 per case per
thousand miles. The GAMS representation of this problem is as follows:

Sets
i canning plants / seattle, san-diego /
j markets / new-york, chicago, topeka / ;

Parameters

a(i) capacity of plant i in cases

/ seattle 350
san-diego 600 /

b(j) demand at market j in cases

/ new-york 325
chicago 300
topeka 275 / ;

Table d(i,j) distance in thousands of miles

new-york chicago topeka
seattle 2.5 1.7 1.8
san-diego 2.5 1.8 1.4 ;

Scalar f freight in dollars per case per thousand miles /90/ ;

Parameter c(i,j) transport cost in thousands of dollars per case ;

c(i,j) = f * d(i,j) / 1000 ;

Variables
x(i,j) shipment quantities in cases
z total transportation costs in thousands of dollars ;

Positive Variable x ;
2 Structure of a GAMS Model 9

Equations
cost define objective function
supply(i) observe supply limit at plant i
demand(j) satisfy demand at market j ;

cost .. z =e= sum((i,j), c(i,j)*x(i,j)) ;

supply(i) .. sum(j, x(i,j)) =l= a(i) ;

demand(j) .. sum(i, x(i,j)) =g= b(j) ;

Model transport /all/ ;

Solve transport using lp minimizing z ;

Display x.l, x.m ;

If you submit a file containing the statements above as input to the GAMS program, the transportation model will be
formulated and solved. Details vary on how to invoke GAMS on different of computers, but the simplest ('no frills') way to
call GAMS is to enter the word GAMS followed by the input file's name. You will see a number of terse lines describing the
progress GAMS is making, including the name of the file onto which the output is being written. When GAMS has finished,
examine this file, and if all has gone well the optimal shipments will be displayed at the bottom as follows.

new-york chicago topeka

seattle 50.000 300.000
san-diego 275.000 275.000

You will also receive the marginal costs (simplex multipliers) below.

chicago topeka
seattle 0.036
san-diego 0.009

These results indicate, for example, that it is optimal to send nothing from Seattle to Topeka, but if you insist on sending one
case it will add .036 $K (or $36.00) to the optimal cost. (Can you prove that this figure is correct from the optimal shipments
and the given data?)

2 Structure of a GAMS Model

For the remainder of the tutorial, we will discuss the basic components of a GAMS model, with reference to the example
above. The basic components are listed in table Table 2.
Table 2: The basic components of a GAMS model

Type Component
Inputs Sets
Declaration
Assignment of members

Data (Parameters, Tables, Scalars)

Declaration
Assignment of values
10 A GAMS Tutorial by Richard E. Rosenthal

Type Component
Variables
Declaration
Assignment of type

Assignment of Variable Bounds and/or Initial Values (optional)

Equations
Declaration
Definition

Model and Solve Statements

Display Statements (optional)
Outputs Echo Prints
Reference Maps
Equation Listings
Status Reports
Solution Reports

There are optional input components, such as edit checks for bad data and requests for customized reports of results. Other
optional advanced features include saving and restoring old models, and creating multiple models in a single run, but this
tutorial will discuss only the basic components.
Before treating the individual components, we give a few general remarks.

1. A GAMS model is a collection of statements in the GAMS Language. The only rule governing the ordering of
statements is that an entity of the model cannot be referenced before it is declared to exist.

2. GAMS statements may be laid out typographically in almost any style that is appealing to the user. Multiple lines per
statement, embedded blank lines, and multiple statements per line are allowed. You will get a good idea of what is
allowed from the examples in this tutorial, but precise rules of the road are given in the next Chapter.

3. When you are a beginning GAMS user, you should terminate every statement with a semicolon, as in our examples.
The GAMS compiler does not distinguish between upper-and lowercase letters, so you are free to use either.

4. Documentation is crucial to the usefulness of mathematical models. It is more useful (and most likely to be accurate)
if it is embedded within the model itself rather than written up separately. There are at least two ways to insert
documentation within a GAMS model. First, any line that starts with an asterisk in column 1 is disregarded as a
comment line by the GAMS compiler. Second, perhaps more important, documentary text can be inserted within
specific GAMS statements. All the lowercase words in the transportation model are examples of the second form of
documentation.

5. As you can see from the list of input components above, the creation of GAMS entities involves two steps: a declaration
and an assignment or definition. Declaration means declaring the existence of something and giving it a name.
Assignment or definition means giving something a specific value or form. In the case of equations, you must make the
declaration and definition in separate GAMS statements. For all other GAMS entities, however, you have the option of
making declarations and assignments in the same statement or separately.

6. The names given to the entities of the model must start with a letter and can be followed by up to thirty more letters or
digits.

3 Sets
Sets are the basic building blocks of a GAMS model, corresponding exactly to the indices in the algebraic representations of
models. The Transportation example above contains just one Set statement:
4 Data 11

Sets
i canning plants / seattle, san-diego /
j markets / new-york, chicago, topeka / ;

The effect of this statement is probably self-evident. We declared two sets and gave them the names i and j. We also assigned
members to the sets as follows:
i = {Seattle, San Diego}
j = {New York, Chicago, Topeka}.
You should note the typographical differences between the GAMS format and the usual mathematical format for listing the
elements of a set. GAMS uses slashes '/' rather than curly braces '{}' to delineate the set simply because not all computer
keyboards have keys for curly braces. Note also that multiword names like 'New York' are not allowed, so hyphens are
inserted.
The lowercase words in the sets statement above are called text. Text is optional. It is there only for internal documentation,
serving no formal purpose in the model. The GAMS compiler makes no attempt to interpret the text, but it saves the text and
'parrots' it back to you at various times for your convenience.
It was not necessary to combine the creation of sets i and j in one statement. We could have put them into separate statements
as follows:

Set i canning plants / seattle, san-diego / ;

Set j markets / new-york, chicago, topeka / ;

The placement of blank spaces and lines (as well as the choice of upper- or lowercase) is up to you. Each GAMS user tends
to develop individual stylistic conventions. (The use of the singular set is also up to you. Using set in a statement that
makes a single declaration and sets in one that makes several is good English, but GAMS treats the singular and plural
synonymously.)
A convenient feature to use when you are assigning members to a set is the asterisk. It applies to cases when the elements
follow a sequence. For example, the following are valid set statements in GAMS.

Set t time periods /1991*2000/;

Set m machines /mach1*mach24/;

Here the effect is to assign

t = {1991,1992,1993, ....., 2000}
m = {mach 1 , mach 2 ,......, mach 24 }.
Note that set elements are stored as character strings, so the elements of t are not numbers.
Another convenient feature is the alias statement, which is used to give another name to a previously declared set. In the
following example:

Alias (t,tp);

the name tp is like a t 0 in mathematical notation. It is useful in models that are concerned with the interactions of elements
within the same set.
The sets i, j, t, and m in the statements above are examples of static sets, i.e., they are assigned their members directly by the
user and do not change. GAMS has several capabilities for creating dynamic sets, which acquire their members through the
execution of set-theoretic and logical operations. Dynamic sets are discussed in Chapter Dynamic Sets. Another valuable
advanced feature is multidimensional sets, which are discussed in Section Multi-dimensional Sets.

4 Data
The GAMS model of the transportation problem demonstrates all of the three fundamentally different formats that are
allowable for entering data. The three formats are:
12 A GAMS Tutorial by Richard E. Rosenthal

Lists

Tables

Direct assignments

The next three sub-sections will discuss each of these formats in turn.

4.1 Data Entry by Lists

The first format is illustrated by the first Parameters statement of the example, which is repeated below.

Parameters

a(i) capacity of plant i in cases

/ seattle 350
san-diego 600 /

b(j) demand at market j in cases

/ new-york 325
chicago 300
topeka 275 / ;

This statement has several effects. Again, they may be self-evident, but it is worthwhile to analyze them in detail. The
statement declares the existence of two parameters, gives them the names a and b, and declares their domains to be i and j,
respectively. (A domain is the set, or tuple of sets, over which a parameter, variable, or equation is defined.) The statement
also gives documentary text for each parameter and assigns values of a(i) and b(j) for each element of i and j. It is
perfectly acceptable to break this one statement into two, if you prefer, as follows.

Parameters a(i) capacity of plant i in cases

/ seattle 350
san-diego 600 / ;

Parameters b(j) demand at market j in cases

/ new-york 325
chicago 300
topeka 275 / ;

Here are some points to remember when using the list format.

1. The list of domain elements and their respective parameter values can be laid out in almost any way you like. The only
rules are that the entire list must be enclosed in slashes and that the element-value pairs must be separated by commas
or entered on separate lines.

2. There is no semicolon separating the element-value list from the name, domain, and text that precede it. This is because
the same statement is being used for declaration and assignment when you use the list format. (An element-value list
by itself is not interpretable by GAMS and will result in an error message.)

3. The GAMS compiler has an unusual feature called domain checking, which verifies that each domain element in the
list is in fact a member of the appropriate set. For example, if you were to spell 'Seattle' correctly in the statement
declaring Set i but misspell it as 'Seatle' in a subsequent element-value list, the GAMS compiler would give you an
error message that the element 'Seatle' does not belong to the set i.

4. Zero is the default value for all parameters. Therefore, you only need to include the nonzero entries in the element-value
list, and these can be entered in any order .
4 Data 13

5. A scalar is regarded as a parameter that has no domain. It can be declared and assigned with a Scalar statement
containing a degenerate list of only one value, as in the following statement from the transportation model.

Scalar f freight in dollars per case per thousand miles /90/;

If a parameter's domain has two or more dimensions, it can still have its values entered by the list format. This is very useful
for entering arrays that are sparse (having few non-zeros) and super-sparse (having few distinct non-zeros).

4.2 Data Entry by Tables

Optimization practitioners have noticed for some time that many of the input data for a large model are derived from relatively
small tables of numbers. Thus, it is very useful to have the table format for data entry. An example of a two-dimensional
table (or matrix) is provided in the transportation model:

Table d(i,j) distance in thousands of miles

new-york chicago topeka
seattle 2.5 1.7 1.8
san-diego 2.5 1.8 1.4 ;

The effect of this statement is to declare the parameter d and to specify its domain as the set of ordered pairs in the Cartesian
product of i and j. The values of d are also given in this statement under the appropriate heading. If there are blank entries
in the table, they are interpreted as zeroes.
As in the list format, GAMS will perform domain checking to make sure that the row and column names of the table are
members of the appropriate sets. Formats for entering tables with more columns than you can fit on one line and for entering
tables with more than two dimensions are given in Chapter Data Entry: Parameters, Scalars and Tables.

4.3 Data Entry by Direct Assignment

The direct assignment method of data entry differs from the list and table methods in that it divides the tasks of parameter
declaration and parameter assignment between separate statements. The transportation model contains the following example
of this method.

Parameter c(i,j) transport cost in thousands of dollars per case ;

c(i,j) = f * d(i,j) / 1000 ;

It is important to emphasize the presence of the semicolon at the end of the first line. Without it, the GAMS compiler would
attempt to interpret both lines as parts of the same statement. (GAMS would fail to discern a valid interpretation, so it would
send you a terse but helpful error message.)
The effects of the first statement above are to declare the parameter c, to specify the domain (i,j), and to provide some
documentary text. The second statement assigns to c(i,j) the product of the values of the parameters f and d(i,j).
Naturally, this is legal in GAMS only if you have already assigned values to f and d(i,j) in previous statements.
The direct assignment above applies to all (i,j) pairs in the domain of c. If you wish to make assignments for specific
elements in the domain, you enclose the element names in quotes. For example,

c(Seattle,New-York) = 0.40;

is a valid GAMS assignment statement.

The same parameter can be assigned a value more than once. Each assignment statement takes effect immediately and
overrides any previous values. (In contrast, the same parameter may not be declared more than once. This is a GAMS error
check to keep you from accidentally using the same name for two different things.)
The right-hand side of an assignment statement can contain a great variety of mathematical expressions and built-in functions.
If you are familiar with a scientific programming language such as FORTRAN or C, you will have no trouble in becoming
14 A GAMS Tutorial by Richard E. Rosenthal

comfortable writing assignment statements in GAMS. (Notice, however, that GAMS has some efficiencies shared by neither
FORTRAN nor C. For example, we were able to assign c(i,j) values for all (i,j) pairs without constructing 'do loops'.)
The GAMS standard operations and supplied functions are given later. Here are some examples of valid assignments. In all
cases, assume the left-hand-side parameter has already been declared and the right-hand-side parameters have already been
assigned values in previous statements.

csquared = sqr(c);
e = m*csquared;
w = l/lamda;
eoq(i) = sqrt( 2*demand(i)*ordcost(i)/holdcost(i));
t(i) = min(p(i), q(i)/r(i), log(s(i)));
euclidean(i,j) = qrt(sqr(xi(i) - xi(j) + sqr(x2(i) - x2(j)));
present(j) = future(j)*exp(-interest*time(j));

The summation and product operators to be introduced later can also be used in direct assignments.

5 Variables
The decision variables (or endogenous variables ) of a GAMS-expressed model must be declared with a Variables statement.
Each variable is given a name, a domain if appropriate, and (optionally) text. The transportation model contains the following
example of a Variables statement.

Variables
x(i,j) shipment quantities in cases
z total transportation costs in thousands of dollars ;

This statement results in the declaration of a shipment variable for each (i,j) pair. (You will see in Chapter Equations, how
GAMS can handle the typical real-world situation in which only a subset of the (i,j) pairs is allowable for shipment.)
The z variable is declared without a domain because it is a scalar quantity. Every GAMS optimization model must contain
one such variable to serve as the quantity to be minimized or maximized.
Once declared, every variable must be assigned a type. The permissible types are given in table Table 3.
Table 3 : Permissible variable types

Variable Type Allowed Range of Variable

free(default) to +
positive 0 to +
negative to 0
binary 0 or 1
integer 0, 1, . . . , 100 (default)

The variable that serves as the quantity to be optimized must be a scalar and must be of the free type. In our transportation
example, z is kept free by default, but x(i,j) is constrained to non-negativity by the following statement.

Positive variable x ;

Note that the domain of x should not be repeated in the type assignment. All entries in the domain automatically have the
same variable type.
Section The .lo, .l, .up, .m Database describes how to assign lower bounds, upper bounds, and initial values to variables
6 Equations 15

6 Equations
The power of algebraic modeling languages like GAMS is most apparent in the creation of the equations and inequalities that
comprise the model under construction. This is because whenever a group of equations or inequalities has the same algebraic
structure, all the members of the group are created simultaneously, not individually.

6.1 Equation Declaration

Equations must be declared and defined in separate statements. The format of the declaration is the same as for other GAMS
entities. First comes the keyword, Equations in this case, followed by the name, domain and text of one or more groups of
equations or inequalities being declared. Our transportation model contains the following equation declaration:

Equations
cost define objective function
supply(i) observe supply limit at plant i
demand(j) satisfy demand at market j ;

Keep in mind that the word Equation has a broad meaning in GAMS. It encompasses both equality and inequality
relationships, and a GAMS equation with a single name can refer to one or several of these relationships. For example, cost
has no domain so it is a single equation, but supply refers to a set of inequalities defined over the domain i.

6.2 GAMS Summation (and Product) Notation

Before going into equation definition we describe the summation notation in GAMS. Remember that GAMS is designed for
standard keyboards and line-by-line input readers, so it is not possible (nor would it be convenient for the user) to employ the
standard mathematical notation for summations.
The summation notation in GAMS can be used for simple and complex expressions. The format is based on the idea of always
thinking of a summation as an operator with two arguments: Sum(index of summation, summand) A comma separates
the two arguments, and if the first argument requires a comma then it should be in parentheses. The second argument can be
any mathematical expression including another summation.
As a simple example, the transportation problem contains the expression

Sum(j, x(i,j))

that is equivalent to j xi j .
A slightly more complex summation is used in the following example:

Sum((i,j), c(i,j)*x(i,j))

that is equivalent to i j ci j xi j .
The last expression could also have been written as a nested summation as follows:

Sum(i, Sum(j, c(i,j)*x(i,j)))

In Section The Dollar Condition, we describe how to use the dollar operator to impose restrictions on the summation operator
so that only the elements of i and j that satisfy specified conditions are included in the summation.
Products are defined in GAMS using exactly the same format as summations, replacing Sum by Prod. For example,

prod(j, x(i, j))

is equivalent to: j xi j .
Summation and product operators may be used in direct assignment statements for parameters. For example,
16 A GAMS Tutorial by Richard E. Rosenthal

scalar totsupply total supply over all plants;

totsupply = sum(i, a(i));

6.3 Equation Definition

Equation definitions are the most complex statements in GAMS in terms of their variety. The components of an equation
definition are, in order:

1. The name of the equation being defined

2. The domain

3. Domain restriction condition (optional)

4. The symbol '..'

5. Left-hand-side expression

6. Relational operator: =l=, =e=, or =g=

7. Right-hand-side expression

The transportation example contains three of these statements.

cost .. z =e= sum((i,j), c(i,j)*x(i,j)) ;

supply(i) .. sum(j, x(i,j)) =l= a(i) ;

demand(j) .. sum(i, x(i,j)) =g= b(j) ;

Here are some points to remember.

The power to create multiple equations with a single GAMS statement is controlled by the domain. For example, the
definition for the demand constraint will result in the creation of one constraint for each element of the domain j, as
shown in the following excerpt from the GAMS output.

DEMAND(new-york)..X(seattle,new-york) + X(san-diego,new-york)=G=325 ;
DEMAND(chicago).. X(seattle,chicago) + X(san-diego,chicago) =G=300 ;
DEMAND(topeka).. X(seattle,topeka) + X(san-diego,topeka) =G=275 ;

The key idea here is that the definition of the demand constraints is exactly the same whether we are solving the
toy-sized example above or a 20,000-node real-world problem. In either case, the user enters just one generic equation
algebraically, and GAMS creates the specific equations that are appropriate for the model instance at hand. (Using
some other optimization packages, something like the extract above would be part of the input, not the output.)

In many real-world problems, some of the members of an equation domain need to be omitted or differentiated from the
pattern of the others because of an exception of some kind. GAMS can readily accommodate this loss of structure using
a powerful feature known as the dollar or 'such-that' operator, which is not illustrated here. The domain restriction
feature can be absolutely essential for keeping the size of a real-world model within the range of solvability.

The relational operators have the following meanings:

=l= less than or equal to
=g= greater than or equal to
=e= equal to
7 Objective Function 17

It is important to understand the difference between the symbols '=' and '=e='. The '=' symbol is used only in direct
assignments, and the '=e=' symbol is used only in equation definitions. These two contexts are very different. A direct
assignment gives a desired value to a parameter before the solver is called. An equation definition also describes a
desired relationship, but it cannot be satisfied until after the solver is called. It follows that equation definitions must
contain variables and direct assignments must not.

Variables can appear on the left or right-hand side of an equation or both. The same variable can appear in an equation
more than once. The GAMS processor will automatically convert the equation to its equivalent standard form (variables
on the left, no duplicate appearances) before calling the solver.
An equation definition can appear anywhere in the GAMS input, provided the equation and all variables and parameters
to which it refers are previously declared. (Note that it is permissible for a parameter appearing in the equation to be
assigned or reassigned a value after the definition. This is useful when doing multiple model runs with one GAMS
input.) The equations need not be defined in the same order in which they are declared.

7 Objective Function
This is just a reminder that GAMS has no explicit entity called the objective function. To specify the function to be optimized,
you must create a variable, which is free (unconstrained in sign) and scalar-valued (has no domain) and which appears in an
equation definition that equates it to the objective function.

8 Model and Solve Statements

The word model has a very precise meaning in GAMS. It is simply a collection of equations. Like other GAMS entities, it
must be given a name in a declaration. The format of the declaration is the keyword model followed by the name of the
model, followed by a list of equation names enclosed in slashes. If all previously defined equations are to be included, you
can enter /all/ in place of the explicit list. In our example, there is one Model statement:

model transport /all/ ;

This statement may seem superfluous, but it is useful to advanced users who may create several models in one GAMS run. If
we were to use the explicit list rather than the shortcut /all/, the statement would be written as

model transport / cost, supply, demand / ;

The domains are omitted from the list since they are not part of the equation name. The list option is used when only a subset
of the existing equations comprises a specific model (or sub-model) being generated.
Once a model has been declared and assigned equations, we are ready to call the solver. This is done with a solve statement,
which in our example is written as

solve transport using lp minimizing z ;

The format of the solve statement is as follows:

1. The key word solve

2. The name of the model to be solved
3. The key word using

4. An available solution procedure. The complete list is

Solution Description
lp for linear programming
18 A GAMS Tutorial by Richard E. Rosenthal

Solution Description
qcp for quadratic constraint programming
nlp for nonlinear programming
dnlp for nonlinear programming with discontinuous derivatives
mip for mixed integer programming
rmip for relaxed mixed integer programming
miqcp for mixed integer quadratic constraint programming
rmiqcp for relaxed mixed integer quadratic constraint programming
minlp for mixed integer nonlinear programming
rminlp for relaxed mixed integer nonlinear programming
mcp for mixed complementarity problems
mpec for mathematical programs with equilibrium constraints
rmpec for relaxed mathematical program with equilibrium constraints
cns for constrained nonlinear systems
emp for extended mathematical programming

5. The keyword 'minimizing' or 'maximizing'

6. The name of the variable to be optimized

9 Display Statements
The solve statement will cause several things to happen when executed. The specific instance of interest of the model will be
generated, the appropriate data structures for inputting this problem to the solver will be created, the solver will be invoked,
and the output from the solver will be printed to a file. To get the optimal values of the primal and/or dual variables, we can
look at the solver output, or, if we wish, we can request a display of these results from GAMS. Our example contains the
following statement:

display x.l, x.m ;

that calls for a printout of the final levels, x.l, and marginal (or reduced costs), x.m, of the shipment variables, x(i,j).
GAMS will automatically format this printout in to dimensional tables with appropriate headings.

10 The .lo, .l, .up, .m Database

GAMS was designed with a small database system in which records are maintained for the variables and equations. The most
important fields in each record are:
.lo lower bound
.l level or primal value
.up upper bound
.m marginal or dual value
The format for referencing these quantities is the variable or equation's name followed by the field's name, followed (if
necessary) by the domain (or an element of the domain).
GAMS allows the user complete read-and write-access to the database. This may not seem remarkable to you now, but it can
become a greatly appreciated feature in advanced use. Some examples of use of the database follow.
10 The .lo, .l, .up, .m Database 19

10.1 Assignment of Variable Bounds and/or Initial Values

The lower and upper bounds of a variable are set automatically according to the variable's type (free, positive,
negative, binary, or integer), but these bounds can be overwritten by the GAMS user. Some examples follow.

x.up(i,j) = capacity(i,j) ;
x.lo(i,j) = 10.0 ;
x.up(seattle,new-york) = 1.2*capacity(seattle,new-york) ;

It is assumed in the first and third examples that capacity(i,j) is a parameter that was previously declared and assigned
values. These statements must appear after the variable declaration and before the Solve statement. All the mathematical
expressions available for direct assignments are usable on the right-hand side.
In nonlinear programming it is very important for the modeler to help the solver by specifying as narrow a range as possible
between lower and upper bound. It is also very helpful to specify an initial solution from which the solver can start searching
for the optimum. For example, in a constrained inventory model, the variables are quantity(i), and it is known that the
optimal solution to the unconstrained version of the problem is a parameter called eoq(i). As a guess for the optimum of
the constrained problem we enter

quantity.l(i) = 0.5*eoq(i) ;

(The default initial level is zero unless zero is not within the bounded range, in which case it is the bound closest to zero.)
It is important to understand that the .lo and .up fields are entirely under the control of the GAMS user. The .l and .m
fields, in contrast, can be initialized by the user but are then controlled by the solver.

10.2 Transformation and Display of Optimal Values

(This section can be skipped on first reading if desired.)
After the optimizer is called via the solve statement, the values it computes for the primal and dual variables are placed in
the database in the .l and .m fields. We can then read these results and transform and display them with GAMS statements.
For example, in the transportation problem, suppose we wish to know the percentage of each market's demand that is filled
by each plant. After the solve statement, we would enter

parameter pctx(i,j) perc of market js demand filled by plant i;

pctx(i,j) = 100.0*x.l(i,j)/b(j) ;
display pctx ;

Appending these commands to the original transportation problem input results in the following output:

pctx percent of market js demand filled by plant I

new-york chicago topeka
seattle 15.385 100.000
san-diego 84.615 100.000

For an example involving marginal, we briefly consider the ratio constraints that commonly appear in blending and refining
problems. These linear programming models are concerned with determining the optimal amount of each of several available
raw materials to put into each of several desired finished products. Let y(i,j) be the variable for the number of tons of raw
material i put into finished product j. Suppose the ratio constraint is that no product can consist of more than 25 percent of
one ingredient, that is,

y(i,j)/q(j) =l= .25 ;

for all i, j. To keep the model linear, the constraint is written as

20 A GAMS Tutorial by Richard E. Rosenthal

ratio(i,j).. y(i,j) - .25*q(j) =l= 0.0 ;

rather than explicitly as a ratio.

The problem here is that ratio.m(i,j), the marginal value associated with the linear form of the constraint, has no intrinsic
meaning. At optimality, it tells us by at most how much we can benefit from relaxing the linear constraint to

y(i,j) - .25*q(j) =l= 1.0 ;

Unfortunately, this relaxed constraint has no realistic significance. The constraint we are interested in relaxing (or tightening)
is the nonlinear form of the ration constraint. For example, we would like to know the marginal benefit arising from changing
the ratio constraint to

y(i,j)/q(j) =l= .26 ;

We can in fact obtain the desired marginals by entering the following transformation on the undesired marginals:

parameter amr(i,j) appropriate marginal for ratio constraint ;

amr(i,j) = ratio.m(i,j)*0.01*q.l(j) ;
display amr ;

Notice that the assignment statement for amr accesses both .m and .l records from the database. The idea behind the
transformation is to notice that

y(i,j)/q(j) =l= .26 ;

is equivalent to

y(i,j) - .25*q(j) =l= 0.01*q(j) ;

11 GAMS Output
The default output of a GAMS run is extensive and informative. For a complete discussion, see Chapter GAMS Output. This
tutorial discusses output partially as follows:

Echo Print

Reference Maps

Status Reports

Error Messages

Model Statistics

Solution Reports

A great deal of unnecessary anxiety has been caused by textbooks and users' manuals that give the reader the false impression
that flawless use of advanced software should be easy for anyone with a positive pulse rate. GAMS is designed with the
understanding that even the most experienced users will make errors. GAMS attempts to catch the errors as soon as possible
and to minimize their consequences.
11 GAMS Output 21

11.1 Echo Prints

Whether or not errors prevent your optimization problem from being solved, the first section of output from a GAMS run is
an echo, or copy, of your input file. For the sake of future reference, GAMS puts line numbers on the left-hand side of the
echo. For our transportation example, which luckily contained no errors, the echo print is as follows:

3 Sets
4 i canning plants / seattle, san-diego /
5 j markets / new-york, chicago, topeka / ;
6
7 Parameters
8
9 a(i) capacity of plant i in cases
10 / seattle 350
11 san-diego 600 /
12
13 b(j) demand at market j in cases
14 / new-york 325
15 chicago 300
16 topeka 275 / ;
17
18 Table d(i,j) distance in thousands of miles
19 new-york chicago topeka
20 seattle 2.5 1.7 1.8
21 san-diego 2.5 1.8 1.4 ;
22
23 Scalar f freight in dollars per case per thousand miles /90/ ;
24
25 Parameter c(i,j) transport cost in thousands of dollars per case;
26
27 c(i,j) = f * d(i,j) / 1000 ;
28
29 Variables
30 x(i,j) shipment quantities in cases
31 z total transportation costs in thousands of dollars ;
32
33 Positive Variable x ;
34
35 Equations
36 cost define objective function
37 supply(i) observe supply limit at plant i
38 demand(j) satisfy demand at market j ;
39
40 cost .. z =e= sum((i,j), c(i,j)*x(i,j)) ;
41
42 supply(i) .. sum(j, x(i,j)) =l= a(i) ;
43
44 demand(j) .. sum(i, x(i,j)) =g= b(j) ;
45
46 Model transport /all/ ;
47
48 Solve transport using lp minimizing z ;
49
50 Display x.l, x.m ;
51
22 A GAMS Tutorial by Richard E. Rosenthal

The reason this echo print starts with line number 3 rather than line number 1 is because the input file contains two dollar-
print-control statements. This type of instruction controls the output printing, but since it has nothing to do with defining the
optimization model, it is omitted from the echo. The dollar print controls must start in column 1.

$title a transportation model

$offuppper

The $title statement causes the subsequent text to be printed at the top of each page of output. The $offupper statement is
needed for the echo to contain mixed upper- and lowercase. Other available instructions are given in Chapter Dollar Control
Options.

11.2 Error Messages

When the GAMS compiler encounters an error in the input file, it inserts a coded error message inside the echo print on the
line immediately following the scene of the offense. These messages always start with and contain a '$' directly below
the point at which the compiler thinks the error occurred. The $ is followed by a numerical error code, which is explained
after the echo print. Several examples follow.
Example 1 : Entering the statement
set q quarterly time periods / spring, sum, fall, wtr / ;
results in the echo
1 set q quarterly time periods / spring, sum, fall, wtr / ;
**** $160
In this case, the GAMS compiler indicates that something is wrong with the set element sum. At the bottom of
the echo print, we see the interpretation of error code160:
Error Message
160 UNIQUE ELEMENT EXPECTED
The problem is that sum is a reserved word denoting summation, so our set element must have a unique name
like 'summer'. This is a common beginner's error. The complete list of reserved words is shown in the next
chapter.
Example 2 : Another common error is the omission of a semicolon preceding a direct assignment or equation definition. In
our transportation example, suppose we omit the semicolon prior to the assignment of c(i,j), as follows.
parameter c(i,j) transport cost in 1000s of dollars per case
c(i,j) = f * d(i,j) / 1000 ;
Here is the resulting output.
16 parameter c(i,j) transport cost in 1000s of dollars per case
17 c(i,j) = f*d(i,j)/1000
**** $97 $195$96$194$1
Error Message
1 REAL NUMBER EXPECTED
96 BLANK NEEDED BETWEEN IDENTIFIER AND TEXT
(-OR-ILLEGAL CHARACTER IN IDENTIFIER)
(-OR-CHECK FOR MISSING ; ON PREVIOUS LINE)
97 EXPLANATORY TEXT CAN NOT START WITH $, =, or ..
(-OR-CHECK FOR MISSING ; ON PREVIOUS LINE)
194 SYMBOL REDEFINED
195 SYMBOL REDEFINED WITH A DIFFERENT TYPE
It is not uncommon for one little offense like our missing semicolon to generate five intimidating error messages.
The lesson here is: concentrate on fixing the first error and ignore the other! The first error detected (in line 17),
code 97, indicate that GAMS thinks the symbols in line 17 are a continuation of the documentary text at the end
of line 16 rather than a direct assignment as we intended. The error message also appropriately advises us to
check the preceding line for a missing semicolon.
11 GAMS Output 23

Unfortunately, you cannot always expect error messages to be so accurate in their advice. The compiler cannot
read your mind. It will at times fail to comprehend your intentions, so learn to detect the causes of errors by
picking up the clues that abound in the GAMS output. For example, the missing semicolon could have been
detected by looking up the c entry in the cross-reference list (to be explained in the next section) and noticing
that it was never assigned.
SYMBOL TYPE REFERENCES
C PARAM DECLARED 15 REF 17
Example 3 : Many errors are caused merely by spelling mistakes and are caught before they can be damaging. For example,
with 'Seattle' spelled in the table differently from the way it was introduced in the set declaration, we get the following
error message.
4 sets
5 i canning plants /seattle, san-diego /
6 j markets /new-york, chicago, topeka / ;
7
8 table d(i,j) distance in thousand of miles
9 new-york chicago topeka
10 seatle 2.5 1.7 1.8
**** $170
11 san-diego 2.5 1.8 1.4 ;
Error Message
170 DOMAIN VIOLATION FOR ELEMENT
Example 4 : Similarly, if we mistakenly enter dem(j) instead of b(j) as the right-hand side of the demand constraint, the
result is
45 demand(j) .. sum(i, x(i,j) ) =g= dem(j) ;
**** $140
Error Message
140 UNKNOWN SYMBOL, ENTERED AS PARAMETER
Example 5 : The next example is a mathematical error, which is sometimes committed by novice modelers and which
GAMS is adept at catching. The following is mathematically inconsistent and, hence, is not an interpretable statement.

For all i, xi j = 100

i
There are two errors in this equation, both having to do with the co ntrol of indices. Index i is over-controlled
and index j is under-controlled.
You should see that index i is getting conflicting orders. By appearing in the quantifier 'for all i', it is supposed to
remain fixed for each instance of the equation. Yet, by appearing as an index of summation, it is supposed to
vary. It can't do both. On the other hand, index j is not controlled in any way, so we have no way of knowing
which of its possible values to use.
If we enter this meaningless equation into GAMS, both errors are correctly diagnosed.
meaninglss(i) .. sum(i, x(i,j)) =e= 100 ;
**** $125 $149
ERROR MESSAGES
125 SET IS UNDER CONTROL ALREADY [This refers to set i]
149 uncontrolled set entered as constant [This refers to set j]
A great deal more information about error reporting is given in Section Error Reporting. Comprehensive error detection and
well-designed error messages are a big help in getting models implemented quickly and correctly.

11.3 Reference Maps

The next section of output, which is the last if errors have been detected, is a pair of reference maps that contain summaries
and analyses of the input file for the purposes of debugging and documentation.
24 A GAMS Tutorial by Richard E. Rosenthal

The first reference map is a cross-reference map such as one finds in most modern compilers. It is an alphabetical, cross-
referenced list of all the entities (sets, parameters, variables, and equations) of the model. The list shows the type of each
entity and a coded reference for each appearance of the entity in the input. The cross-reference map for our transportation
example is as follows (we do not display all tables).

SYMBOL TYPE REFERENCES

A PARAM DECLARED 9 DEFINED 10 REF 42
B PARAM DECLARED 13 DEFINED 14 REF 44
C PARAM DECLARED 25 ASSIGNED 27 REF 40
COST EQU DECLARED 36 DEFINED 40 IMPL-ASN 48
REF 46
D PARAM DECLARED 18 DEFINED 18 REF 27
DEMAND EQU DECLARED 38 DEFINED 44 IMPL-ASN 48
REF 46
F PARAM DECLARED 23 DEFINED 23 REF 27
SET DECLARED 4 DEFINED 4 REF 9
18 25 27 30 37 2*40
2*42 44 CONTROL 27 40 42
44
J SET DECLARED 5 DEFINED 5 REF 13
18 25 27 30 38 2*40
42 2*44 CONTROL 27 40 42
44
SUPPLY EQU DECLARED 37 DEFINED 42 IMPL-ASN 48
REF 46
TRANSPORT MODEL DECLARED 46 DEFINED 46 IMPL-ASN 48
REF 48
X VAR DECLARED 30 IMPL-ASN 48 REF 33
40 42 44 2*50
Z VAR DECLARED 31 IMPL-ASN 48 REF 40
48

For example, the cross-reference list tells us that the symbol A is a parameter that was declared in line10, defined (assigned
value) in line 11, and referenced in line 43. The symbol I has a more complicated entry in the cross-reference list. It is shown
to be a set that was declared and defined in line 5. It is referenced once in lines 10, 19, 26, 28, 31, 38, 45 and referenced
twice in lines 41 and 43. Set I is also used as a controlling index in a summation, equation definition or direct parameter
assignment in lines 28, 41, 43 and 45.
For the GAMS novice, the detailed analysis of the cross-reference list may not be important. Perhaps the most likely benefit
he or she will get from the reference maps will be the discovery of an unwanted entity that mistakenly entered the model
owing to a punctuation or syntax error.
The second part of the reference map is a list of model entities grouped by type and listed with their associated documentary
text. For example, this list is as follows.

sets
i canning plants
j markets

parameters
a capacity of plant i in cases
b demand at market j in cases
c transport cost in 1000s of dollars per case
d distance in thousands of miles
f freight in dollars per case per thousand miles

variables
11 GAMS Output 25

x shipment quantities in cases

z total transportation costs in 1000s of dollars

equations
cost define objective function
demand satisfy demand at market j
supply observe supply limit at plant i

models
transport

11.4 Equation Listings

Once you succeed in building an input file devoid of compilation errors, GAMS is able to generate a model. The question
remains, and only you can answer it, does GAMS generate the model you intended?
The equation listing is probably the best device for studying this extremely important question.
A product of the solve command, the equation listing shows the specific instance of the model that is created when the current
values of the sets and parameters are plugged into the general algebraic form of the model. For example, the generic demand
constraint given in the input file for the transportation model is

demand(j) .. sum(i, x(i,j)) =g= b(j) ;

while the equation listing of specific constraints is

--------demand =g= satisfy demand at market j

demand(new-york).. x(seattle, new-york) +x(san-diego, new-york) =g= 325 ;
demand(chicago).. x(seattle, chicago) +x(san-diego, chicago ) =g= 300 ;
demand(topeka).. x(seattle, topeka) +x(san-diego, topeka) =g= 275 ;

The default output is a maximum of three specific equations for each generic equation. To change the default, insert an input
statement prior to the solve statement:

option limrow = r ;

where r is the desired number.

The default output also contains a section called the column listing, analogous to the equation listing, which shows the
coefficients of three specific variables for each generic variable. This listing would be particularly useful for verifying a
GAMS model that was previously implemented in MPS format. To change the default number of specific column printouts
per generic variable, the above command can be extended:

option limrow = r, limcol = c ;

where c is the desired number of columns. (Setting limrow and limcol to 0 is a good way to save paper after your model
has been debugged.)
In nonlinear models, the GAMS equation listing shows first-order Taylor approximations of the nonlinear equations. The
approximations are taken at the starting values of the variables.

11.5 Model Statistics

The last section of output that GAMS produces before invoking the solver is a group of statistics about the model's size, as
shown below for the transportation example.
26 A GAMS Tutorial by Richard E. Rosenthal

MODEL STATISTICS

BLOCKS OF EQUATIONS 3 SINGLE EQUATIONS 6

BLOCKS OF VARIABLES 2 SINGLE VARIABLES 7
NON ZERO ELEMENTS 19

The BLOCK counts refer to the number of generic equations and variables. The SINGLE counts refer to individual rows and
columns in the specific model instance being generated. For nonlinear models, some other statistics are given to describe the
degree of non-linearity in the problem.

11.6 Status Reports

After the solver executes, GAMS prints out a brief solve summary whose two most important entries are SOLVER STATUS
and the MODEL STATUS. For our transportation problem the solve summary is as follows:

S O L V E S U M M A R Y

MODEL TRANSPORT OBJECTIVE Z

TYPE LP DIRECTION MINIMIZE
SOLVER BDMLP FROM LINE 49

**** SOLVER STATUS 1 NORMAL COMPLETION

**** MODEL STATUS 1 OPTIMAL

**** OBJECTIVE VALUE 153.6750

RESOURCE USAGE, LIMIT 0.110 1000.000

ITERATION COUNT, LIMIT 5 1000

The status reports are preceded by the same string as an error message, so you should probably develop the habit of
searching for all occurrences of this string whenever you look at an output file for the first time. The desired solver status
is 1 NORMAL COMPLETION, but there are other possibilities, documented in Section Output Produced by a Solve Statement,
which relate to various types of errors and mishaps.
There are eleven possible model status's, including the usual linear programming termination states (1 OPTIMAL, 3
UNBOUNDED, 4 INFEASIBLE), and others relating to nonlinear and integer programming. In nonlinear programming, the
status to look for is 2 LOCALLY OPTIMAL. The most the software can guarantee for nonlinear programming is a local
optimum. The user is responsible for analyzing the convexity of the problem to determine whether local optimality is
sufficient for global optimality.
In integer programming, the status to look for is 8 INTEGER SOLUTION. This means that a feasible integer solution has been
found. More detail follows as to whether the solution meets the relative and absolute optimality tolerances that the user
specifies.

11.7 Solution Reports

If the solver status and model status are acceptable, then you will be interested in examining the results of the optimization.
The results are first presented in as standard mathematical programming output format, with the added feature that rows and
columns are grouped and labeled according to names that are appropriate for the specific model just solved. In this format,
there is a line of printout for each row and column giving the lower limit, level, upper limit, and marginal. Generic equation
block and the column output group the row output by generic variable block. Set element names are embedded in the output
for easy reading. In the transportation example, the solver outputs for supply(i), demand(j), and x(i,j) are as follows:

---- EQU SUPPLY observe supply limit at plant i

11 GAMS Output 27

LOWER LEVEL UPPER MARGINAL

seattle -INF 350.000 350.000 EPS

san-diego -INF 550.000 600.000 .

---- EQU DEMAND satisfy demand at market j

LOWER LEVEL UPPER MARGINAL

new-york 325.000 325.000 +INF 0.225

chicago 300.000 300.000 +INF 0.153
topeka 275.000 275.000 +INF 0.126

---- VAR X shipment quantities in cases

LOWER LEVEL UPPER MARGINAL

seattle .new-york . 50.000 +INF .

seattle .chicago . 300.000 +INF .
seattle .topeka . . +INF 0.036
san-diego.new-york . 275.000 +INF .
san-diego.chicago . . +INF 0.009
san-diego.topeka . 275.000 +INF .

The single dots '.' in the output represent zeroes. The entry EPS, which stands for epsilon, mean very small but nonzero. In
this case, EPS indicates degeneracy. (The slack variable for the Seattle supply constraint is in the basis at zero level. The
marginal is marked with EPS rather than zero to facilitate restarting the optimizer from the old basis.)
If the solvers results contain either infeasibilities or marginal costs of the wrong sign, then the offending entries are marked
with INFES or NOPT, respectively. If the problem terminates unbounded, then the rows and columns corresponding to extreme
rays are marked UNBND.
At the end of the solvers solution report is a very important report summary, which gives a tally of the total number of
non-optimal, infeasible, and unbounded rows and columns. For our example, the report summary shows all zero tallies as
desired.

**** REPORT SUMMARY : 0 NONOPT

0 INFEASIBLE
0 UNBOUNDED

After the solver's report is written, control is returned from the solver back to GAMS. All the levels and marginals obtained by
the solver are entered into the GAMS database in the .l and .m fields. These values can then be transformed and displayed
in any desired report. As noted earlier, the user merely lists the quantities to be displayed, and GAMS automatically formats
and labels an appropriate array. For example, the input statement.

display x.l, x.m ;

results in the following output.

---- 50 VARIABLE X.L shipment quantities in cases

new-york chicago topeka

seattle 50.000 300.000

san-diego 275.000 275.000
28 A GAMS Tutorial by Richard E. Rosenthal

---- 50 VARIABLE X.M shipment quantities in cases

chicago topeka

seattle 0.036
san-diego 0.009

As seen in reference maps, equation listings, solution reports, and optional displays, GAMS saves the documentary text and
'parrots' it back throughout the output to help keep the model well documented.

12 Summary
This tutorial has demonstrated several of the design features of GAMS that enable you to build practical optimization models
quickly and effectively. The following discussion summarizes the advantages of using an algebraic modeling language such
as GAMS versus a matrix generator or conversational solver.

By using an algebra-based notation, you can describe an optimization model to a computer nearly as easily as you can
describe it to another mathematically trained person.

Because an algebraic description of a problem has generality, most of the statements in a GAMS model are reusable
when new instances of the same or related problems arise. This is especially important in environments where models
are constantly changing.
You save time and reduce generation errors by creating whole sets of closely related constraints in one statement.

You can save time and reduce input errors by providing formulae for calculating the data rather than entering them
explicitly.
The model is self-documenting. Since the tasks of model development and model documentation can be done
simultaneously, the modeler is much more likely to be conscientious about keeping the documentation accurate and up
to date.

The output of GAMS is easy to read and use. The solution report from the solver is automatically reformatted so that
related equations and variables are grouped together and appropriately labeled. Also, the display command allows
you to modify and tabulate results very easily.
If you are teaching or learning modeling, you can benefit from the insistence of the GAMS compiler that every equation
be mathematically consistent. Even if you are an experienced modeler, the hundreds of ways in which errors are
detected should greatly reduce development time.
By using the dollar operator and other advanced features not covered in this tutorial, one can efficiently implement
large-scale models. Specific applications of the dollar operator include the
1. It can enforce logical restrictions on the allowable combinations of indices for the variables and equations to
be included in the model. You can thereby screen out unnecessary rows and columns and keep the size of the
problem within the range of solvability.
2. It can be used to build complex summations and products, which can then be used in equations or customized
reports.
3. It can be used for issuing warning messages or for terminating prematurely conditioned upon context-specific
data edits.
 Part II

Language Basics
Chapter 3

GAMS Programs

1 Introduction
This chapter provides a look at the structure of the GAMS language and its components. It should be emphasized again
that GAMS is a programming language, and that programs must be written in the language to use it. A GAMS program is
contained in a disk file, which is normally constructed with a text editor of choice. When GAMS is 'run', the file containing
the program (the input file) is submitted to be processed. After this processing has finished the results, which are in the output
file(s), can be inspected with a text editor. On many machines a few terse lines appear on the screen while GAMS runs,
keeping the user informed about progress and error detection. But it is the responsibility of the user to inspect the output file
carefully to see the results and to diagnose any errors.
The first time or casual reader can skip this chapter: the discussion of specific parts of the language in the next Chapters does
not assume an understanding of this chapter.

2 The Structure of GAMS Programs

GAMS programs consist of one or more statements (sentences) that define data structures, initial values, data modifications,
and symbolic relationships (equations). While there is no fixed order in which statements have to be arranged, the order in
which data modifications are carried out is important. Symbols must be declared as to type before they are used, and must
have values assigned before they can be referenced in assignment statements. Each statement is followed by a semicolon
except the last statement, where a semicolon is optional.

2.1 Format of GAMS Input

GAMS input is free format. A statement can be placed anywhere on a line, multiple statements can appear on a line, or a
statement can be continued over any number of lines as follows:

statement;
statement;
statement; statement; statement;
the words that you are now reading is an example of a very
long statement which is stretched over two lines;

Blanks and end-of-lines can generally be used freely between individual symbols or words. GAMS is not case sensitive,
meaning that lower and upper case letters can be mixed freely but are treated identically. Up to 255 characters can be placed
on a line and completely blank lines can be inserted for easier reading.
Not all lines are a part of the GAMS language. Two special symbols, the asterisk '' and the dollar symbol '$' can be used
in the first position on a line to indicate a non-language input line. An asterisk in column one means that the line will not be
32 GAMS Programs

processed, but treated as a comment. A dollar symbol in the same position indicates that compiler options are contained in
the rest of the line.
Multiple files can be used as input through the use of the $include facility described in Chapter Dollar Control Options . In
short, the statement,

$include file1

inserts the contents of the specified file (file1 in this case) at the location of the call. A more complex versions of this is the
$batinclude which is described in Chapter Dollar Control Options .

2.2 Classification of GAMS Statements

Each statement in GAMS is classified into one of two groups:

1. declaration and definition statements; or

2. execution statements

A declaration statement describes the class of symbol. Often initial value are provided in a declaration, and then it may be
called a definition. The specification of symbolic relationships for an equation is a definition. The declaration and definition
statements are:

acronym
alias
equation declaration
equation definition
model
parameter
scalar
set
table
variable

Execution statements are instructions to carry out actions such as data transformation, model solution, and report generation.
The execution statements are:

abort
assignment
display
execute
for
loop
option
repeat
2 The Structure of GAMS Programs 33

solve

while

Although there is great freedom about the order in which statements can be placed in a GAMS program, certain orders are
commonly used. The two most common arrangements are discussed in the next sub-section.

2.3 Organization of GAMS Programs

There are two most common ways of organizing GAMS programs.

The first style places the data first, followed by the model and then the solution statements. In this style of organization, the
sets are placed first. Then the data are specified with parameter, scalar, and table statements. Next the model is defined with
the variable, equation declaration, equation definition, and model statement. Finally the model is solved and the results are
displayed.
Style 1:
Data:
Set declarations and defnitions
Parameter declarations and definitions
Assignments
Displays
Model:
Variable declarations
Equation declaration
Equation definition
Model definition
Solution:
Solve
Displays
A second style emphasizes the model by placing it before the data. This is a particularly useful order when the model may be
solved repeatedly with different data sets. There is a separation between declaration and definition.
Style 2:
Model:
Set declarations
Parameter declarations
Variable declarations
Equation declaration
Equation definition
Model definition
Data:
Set definitions
Parameter definitions
Assignments
Displays
34 GAMS Programs

Solution:
Solve
Displays
For example, sets and parameters may be declared first with the statements

set c "crops" ;
parameter yield "crop yield" ;

and then defined later with a statement:

set c / wheat, clover, beans/ ;

parameter yield / wheat 1.5
clover 6.5
beans 1.0 / ;

The first statement declares that the identifier c is a set and the second defines the elements in the set

Attention
Sets and parameters used in the equations must be declared before the equations are specified; they can be defined,
however, after the equation specifications but before a specific equation is used in a solve statement. This gives GAMS
programs substantial organizational flexibility.

3 Data Types and Definitions

There are five basic GAMS data types and each symbol or identifier must be declared to belong to one of the following
groups:

acronyms
equations
models

parameters
sets
variables

Scalars and tables are not separate data types but are a shorthand way to declare a symbol to be a parameter, and to use
a particular format for initializing the numeric data.
Definitions have common characteristics, for example:

parameter a (i,j) input-output matrix

data-type-keyword identifier domain list text

The domain list and the text are always optional characteristics. Other examples are:

set time time periods;

model turkey turkish fertilizer model ;
variables x,y,z ;
4 Language Items 35

In the last example a number of identifiers (separated by commas) are declared in one statement.

4 Language Items
Before proceeding with more language details, a few basic symbols need to be defined and the rules for recognizing and
writing them in GAMS established. These basic symbols are often called lexical elements and form the building blocks of the
language. They are:

characters
comments

delimiters
identifiers (indents)
labels
numbers

reserved words and tokens

text

Each of these items are discussed in detail in the following sub-sections.

Attention
As noted previously, we can use any mix of lower and upper case. GAMS makes no distinction between upper and
lower case.

4.1 Characters
A few characters are not allowed in a GAMS program because they are illegal or ambiguous on some machines. Generally
all unprintable and control characters are illegal. The only place where any character is legal is in an '$ontext-$offtext' block
as illustrated in the section on comments below. For completeness the full set of legal characters are listed in Table 1. Most
of the uncommon punctuation characters are not part of the language, but can be used freely in text or comments.
Table 1 Legal Characters

Legal Characters Description

A to Z alphabet
a to z alphabet
0 to 9 numerals
& ampersand
" double quote
# pound sign
asterisk
= equals
? question mark
@ at
> greater than
; semicolon
\ back slash
36 GAMS Programs

Legal Characters Description

< less than
' single quote
: colon
- minus
/ slash
, comma
( ) parenthesis
space
$ dollar
[ ] square brackets
underscore
. dot
{ } braces
! exclamation mark
+ plus
% percent
circumflex

4.2 Reserved Words

GAMS, like computer languages such as C and Pascal, uses reserved words (often also called keywords) that have predefined
meanings. It is not permitted to use any of these for one's own definitions, either as identifiers or labels. The complete list of
reserved words are listed below. In addition, a small number of symbols constructed from non-alphanumeric characters have
a meaning in GAMS.

abort

acronym

acronyms

alias

all

and

assign

binary

card

diag

display

else

eps

eq

equation
4 Language Items 37

equations

file

files

for

free

ge

gt

if

inf

integer

le

loop

lt

maximizing

minimizing

model

models

na

ne

negative

no

not

option

options

or

ord

parameter

parameters

positive

prod

putpage

puttl

repeat

sameas
38 GAMS Programs

scalar

scalars

semicont

semiint

set

sets

smax

smin

solve

sos1

sos2

sum

system

table

then

until

using

variable

variables

while

xor

yes

The reserved non-alphanumeric symbols are:

..

=l=

=g=

=e=

=n=

=x=

=c=

--

++

4 Language Items 39

4.3 Identifiers
Identifiers are the names given to sets, parameters, variables, models, etc. GAMS requires an identifier to start with a letter
followed by more letters or digits. The length of an identifier is currently limited to 63 characters. Identifiers can only contain
alphanumeric characters (letters or numbers). Examples of legal identifiers are:

a a15 revenue x0051

whereas the following identifiers are incorrect:

15 $casg milk&meat

Attention
A name used for one data type cannot be reused for another.

4.4 Labels
Labels are set elements. They may be up to 63 characters long and can be used in quoted or unquoted form.
The unquoted form is simpler to use but places restrictions on characters used, in that any unquoted label must start with a
letter or digit and can only be followed by letters, digits, or the sign characters + and -. Examples of unquoted labels are:

Phos-Acid 1986 1952-53 A

September H2S04 Line-1

In quoted labels, quotes are used to delimit the label, which may begin with and/or include any legal character. Either single
or double quotes can be used but the closing quote has to match the opening one. A label quoted with double quotes can
contain a single quote (and vice versa). Most experienced users avoid quoted labels because they can be tedious to enter and
confusing to read. There are a couple of special circumstances. If one wants to make a label stand out, then one can, for
instance, put asterisks in it and indent it. A more subtle example is that GAMS keywords can be used as labels if they are
quoted. If one needs to use labels like no, ne or sum then they will have to be quoted. Examples of quoted labels are:

*TOTAL* MATCH 10%INCR 12"/FOOT LINE 1

Attention
Labels do not have a value. The label '1986' does not have the numerical value 1986 and the label '01' is different from
the label '1'.

The rules for constructing identifiers and labels are shown in the following table.
Table 2 Rules for constructing identifiers and labels

Identifiers Unquoted Labels Quoted Labels

Number of Characters 63 63 63
Must Begin With A letter A letter or a number Any character
Permitted Special Characters None + or characters Any but the starting quote
40 GAMS Programs

4.5 Text

Identifiers and simple labels can also be associated with a line of descriptive text. This text is more than a comment: it is
retained by GAMS and is displayed whenever results are written for the identifier.
Text can be quoted or unquoted. Quoted text can contain any character except the quote character used. Single or double
quotes can be used but must match. Text has to fit on one line and cannot exceed 80 characters in length. Text used in
unquoted form must follow a number of mild restrictions. Unquoted text cannot start with a reserved word, '..' or '=' and
must not include semicolon ';', commas ',', or slashes '/'. End of lines terminate a text. These restrictions are a direct
consequence of the GAMS syntax and are usually followed naturally by the user. Some examples are:

this is text
final product shipment (tpy)
"quoted text containing otherwise illegal characters ; /,"
use single quotes to put a "double" quote in text

4.6 Numbers

Numeric values are entered in a style similar to that used in other computer languages

Attention
Blanks can not be used in a number: GAMS treats a blank as a separator.
The common distinction between real and integer data types does not exist in GAMS. If a number is used without
a decimal point it is still stored as a real number.

In addition, GAMS uses an extended range arithmetic that contains special symbols for infinity ( INF), negative infinity
(-INF), undefined (UNDF), epsilon (EPS), and not available ( NA). One cannot enter UNDF; it is only produced by an operation
that does not have a proper result, such as division by zero. All the other special symbols can be entered and used as if they
were ordinary numbers.
The following example shows various legal ways of entering numbers:

0 156.70 -135 .095 1.

2e10 2e+10 15.e+10 .314e5 +1.7
0.0 .0 0. INF -INF
EPS NA

The letter e denotes the well-known scientific notation allowing convenient representation of very large or small numbers.
For example:

1e-5 = 1 * 10^{-5} = 0.00001

3.56e6 = 3.56 * 10^6 = 3,560,000

Attention
GAMS uses a smaller range of numbers than many computers are able to handle. This has been done to ensure
that GAMS programs will behave in the same way on a wide variety of machines, including personal computers.
A good general rule is to avoid using or creating numbers with absolute values greater than 1.0e+20.
A number can be entered with up to ten significant digits on all machines, and more on some.
5 Summary 41

4.7 Delimiters
As mentioned before, statements are separated by a semicolon ';'. However, if the next statement begins with a reserved
word (often called keyword in succeeding chapters), then GAMS does not require that the semicolon be used.
The characters comma ',' and slash '/' are used as delimiters in data lists, to be introduced later. The comma terminates a
data element (as does an end-of-line) and the slash terminates a data list.

4.8 Comments
A comment is an explanatory text that is not processed or retained by the computer. There are three ways to include comments
in a GAMS program.

1. The first, already mentioned above, is to start a line with an asterisk '' in the first character position. The remaining
characters on the line are ignored but printed on the output file.
2. The second is to use special 'block' delimiters that cause GAMS to ignore an entire section of the program. The $
symbol must be in the first character position. The choice between the two ways is a matter of individual taste or utility.
The example below illustrates the use of the block comment.

$ontext
Following a $ontext directive in column 1 all lines are
ignored by GAMS but printed on the output file until the matching $offtext is encountered, also
in column 1. This facility is often used to logically remove parts of programs
that are not used every time, such as statements producing voluminous reports.
Every $ontext must have a matching $offtext in the same file
$offtext

1. The third style of comment allows embedding a comment within a line. It must be enabled with the compiler option
$inlinecom or $eolcom as in the following example.

$eolcom #
$inlinecom {}
x = 1 ; # this is a comment
y = 2 ; { this is also a comment } z = 3 ;

5 Summary
This completes the discussion of the components of the GAMS language. Many unfamiliar terms used in this chapter have
been further explained in the Glossary.
42 GAMS Programs
Chapter 4

Set Definition

1 Introduction
Sets are fundamental building blocks in any GAMS model. They allow the model to be succinctly stated and easily read.
In this chapter we will discuss how sets are declared and initialized. There are some more advanced set concepts, such as
assignments to sets as well as lag and lead operations, but these are not introduced until much later in the book. However the
topics covered in this chapter will be enough to provide a good start on most models.

2 Simple Sets
A set S that contains the elements a, b and c is written, using normal mathematical notation, as:

S = {a, b, c}

In GAMS notation, because of character set limitations, the same set must be written as

set S /a, b, c/

The set statement begins with the keyword set (or sets). S is the name of the set, and its members are a, b, and c. They
are labels, but are often referred to as elements or members.

2.1 The Syntax

In general, the syntax in GAMS for simple sets is as follows:

set set_name ["text"] [/element ["text"] {,element ["text"]} /]

{,set_name ["text"] [/element ["text"] {,element ["text"]} /] } ;

set name is the internal name of the set (also called an identifier) in GAMS. The accompanying text is used to describe the
set or element immediately preceding it.

2.2 Set Names

The name of the set is an identifier. An identifier has to start with a letter followed by more letters or digits. It can only
contain alphanumeric characters, and can be up to 63 characters long. This is enough to construct meaningful names, and
explanatory text can be used to provide more details.
Examples of legal identifiers are
44 Set Definition

i i15 countries s0051

whereas the following identifiers are incorrect:

25 $currency food&drink

2.3 Set Elements

The name of each set element can be up to 63 characters long, and can be used in quoted or unquoted form. The unquoted
form is simpler to use but places restrictions on characters used, in that any unquoted label must start with a letter or digit and
can only be followed by letters, digits, or the sign characters + and -. Examples of legal unquoted labels are:

Phos-Acid 1986 1952-53 A

September H2S04 Line-1

In quoted labels, quotes are used to delimit the label, which may begin with and/or include any legal character. Either single
or double quotes can be used but the closing quote has to match the opening one. A label quoted with double quotes can
contain a single quote (and vice versa). Most experienced users avoid quoted labels because they can be tedious to enter and
confusing to read. There are a couple of special circumstances. If one wants to make a label stand out, then to put asterisks in
it and indent it, as below, is common. A more subtle example is that it is possible to use GAMS keywords as labels if they are
quoted. If one need to use labels like no, ne or sum then they will have to be quoted.
Examples of quoted labels are:

*TOTAL* Match 10%incr 12"/foot Line 1

Attention
Labels do not have a value. The label '1986' does not have the numerical value 1986 and the label '01' is different
from the label '1'.

Each element in a set must be separated from other elements by a comma or by an end-of-line. In contrast, each element is
separated from any associated text by a blank.
Consider the following example from the Egyptian fertilizer model [FERTS], where the set of fertilizer nutrients could be
written as

set cq "nutrients" / N, P2O5 / ;

or as

set cq "nutrients" / N
P2O5 / ;

The order in which the set members are listed is normally not important. However, if the members represent, for example,
time periods, then it may be useful to refer to next or previous member. There are special operations to do this, and they will
be discussed in Chapter Sets as Sequences: Ordered Sets. For now, it is enough to remember that the order in which set
elements are specified is not relevant, unless and until some operation implying order is used. At that time, the rules change,
and the set becomes what we will later call an ordered set.

2.4 Associated Text

It is also possible to associate text with each set member or element. Explanatory text must not exceed 254 characters and
must all be contained on the same line as the identifier or label it describes.
For example, label text for the set of final products in [SHALE] contains details of the units of measurement.
2 Simple Sets 45

Set f "final products"

/yncrude "refined crude (million barrels)"
lpg "liquified petroleum gas(million barrels)"
ammonia "ammonia (million tons)"
coke "coke (million tons)"
sulfur "sulfur (million tons)"
/;

Notice that text may have embedded blanks, and may include special characters such as parentheses. There are, however,
restrictions on special characters in text. Include slashes, commas or semicolons only if the text is enclosed in quotes. A set
definition like

set prices prices of commodities in dollars/ounce

/ gold-price, sil-price / ;

will cause errors since the slash between dollars and ounce will signal the beginning of the set declaration, and the GAMS
compiler will treat ounce as the name of the first element. Further, the slash before gold-price will be treated as the end of the
set definition, and gold-price will be treated as a new set. However, by enclosing the explanatory text in quotes, this problem
is avoided. The following text is valid:

set prices "prices of commodities in dollars/ounce"

2.5 Sequences as Set Elements

The asterisk '' plays a special role in set definitions. It is used to relieve the tedium of typing a sequence of elements for a
set, and to make intent clearer. For example in a simulation model there might be ten annual time periods from 1991 to 2000.
Instead of typing ten years, the elements of this set can be written as

set t "time" /1991 * 2000 /;

which means that the set includes the ten elements 1991, 1992,...,2000. GAMS builds up these label lists by looking at the
differences between the two labels. If the only characters that differ are digits, with the number L formed by these digits in
the left and R in the right, then a label is constructed for every integer in the sequence L to R. Any non-numeric differences or
other inconsistencies cause errors.
The following example illustrates the most general form of the 'asterisked' definition:

set g / a1bc * a20bc /;

Note that this is not the same as

set g / a01bc * a20bc /;

although the sets, which have 20 members each, have 11 members in common. As a last example, the following are both
illegal because they are not consistent with the rule given above for making lists :

set illegal1 / a1x1 * a9x9 /

illegal2 / a1 * b9 /;

Note one last time that set elements (often referred to as labels) can contain the sign characters '-' and '+' as well as letters
and numbers.
46 Set Definition

2.6 Declarations for Multiple Sets

The keyword set (if you prefer, say sets instead: the two are equivalent) does not need to be used for each set, rather only
at the beginning of a group of sets. It is often convenient to put a group of set declarations together at the beginning of the
program. When this is done the set keyword need only be used once. If you prefer to intermingle set declarations with other
statements, you will have to use a new set statement for each additional group of sets.
The following example below shows how two sets can be declared together. Note that the semicolon is used only after the
last set is declared.

sets
s "Sector" / manuf
agri
services
government /
r "regions" / north
eastcoast
midwest
sunbelt / ;

3 The Alias Statement: Multiple Names for a Set

It is sometimes necessary to have more than one name for the same set. In input-output models, for example, each commodity
may be used in the production of all other commodities and it is necessary to have two names for the set of commodities to
specify the problem without ambiguity. In the general equilibrium model [ORANI], the set of commodities is written

set c "commodities" / food, clothing / ;

and a second name for the set c is established with either of the following statements

alias (c, cp) ;

alias (cp, c) ;

where cp is the new set that can be used instead of the original set c.

Attention
The newly introduced set can be used as an alternative name for the original set, and will always contain only the same
elements as the original set.

The alias statement can be used to introduce more than one new name for the original set.

alias (c,cp, cpp, cppp);

where the new sets cp, cpp, cppp are all new names for the original set c.

Attention
The order of the sets in the alias statement does not matter. The only restriction set by GAMS is that exactly one of the
sets in the statement be defined earlier. All the other sets are introduced by the alias statement.

We will not demonstrate the use of set aliases until later. Just remember they are used for cases when a set has to be referred
to by more than one name.
4 Subsets and Domain Checking 47

4 Subsets and Domain Checking

It is often necessary to define sets whose members must all be members of some larger set. The syntax is:

set set_ident1 (set_ident2) ;

where set ident1 is a subset of the larger set set ident2.

For instance, we may wish to define the sectors in an economic model following the style in [CHENERY].

set
i "all sectors" / light-ind, food+agr, heavy-ind, services /
t(i) "traded sectors" / light-ind, food+agr, heavy-ind /
nt "non-traded sectors" / services / ;

Some types of economic activity, for example exporting and importing, may be logically restricted to a subset of all sectors.
In order to model the trade balance, for example, we need to know which sectors are traded, and one obvious way is to
list them explicitly, as in the definition of the set t above. The specification t(i) means that each member of the set t
must also be a member of the set i. GAMS will enforce this relationship, which is called domain checking. Obviously the
order of declaration is important: the membership of i must be known before t is declared for checking to be done. There
will be much more on this topic in succeeding chapters. For now it is important to note that domain checking will find any
spelling errors that might be made in establishing the members of the set t.These would cause errors in the model if they
went undetected.
It is legal but unwise to define a subset without reference to the larger set, as is done above for the set nt. If services were
misspelled no error would be marked, but the model would give incorrect results. So we urge you to use domain checking
whenever possible. It catches errors and allows you to write models that are conceptually cleaner because logical relationships
are made explicit.
This completes the discussion of sets in which the elements are simple. This is sufficient for most GAMS applications;
however, there are a variety of problems for which it is useful to have sets that are defined in terms of two or more other sets.

5 Multi-dimensional Sets
It is often necessary to provide mappings between elements of different sets. For this purpose, GAMS allows the use of
multi-dimensional sets.

Attention
GAMS allows sets with up to 20 dimensions.

The next two sub-sections explain how to express one-to-one and many-to-many mappings between sets.

5.1 Mapping One-to-one Mapping

Consider a set whose elements are pairs: A = {(b, d), (a, c), (c, e)}.
In this set there are three elements and each element consists of a pair of letters. This kind of set is useful in many types of
modeling. As an illustrative example, consider the world aluminum model [ALUM], where it is necessary to associate, with
each bauxite-supplying country, a port that is near to the bauxite mines. The set of countries is

set c "countries"
/ jamaica
haiti
guyana
brazil / ;
48 Set Definition

and the set of ports is

set p "ports"
/ kingston
s-domingo
georgetown
belem / ;

Then a set can be created to associate each port with its country, viz.,

set ptoc(p, c) "port to country relationship"

/ kingston .jamaica
s-domingo .haiti
georgetown .guyana
belem .brazil /;

The dot between kingston and jamaica is used to create one such pair. Blanks may be used freely around the dot for
readability. The set ptoc has four elements, and each element consists of a port-country pair. The notation (p,c) after the
set name ptoc indicates that the first member of each pair must be a member of the set p of ports, and that the second must
be in the set c of countries. This is a second example of domain checking. GAMS will check the set elements to ensure that
all members belong to the appropriate sets.

5.2 Mapping Many-to-many Mapping

A many-to-many mapping is needed in certain cases. Consider the following set

set i / a, b /
j / c, d, e /
ij1(i,j) /a.c, a.d/
ij2(i,j) /a.c, b.c/
ij3(i,j) /a.c, b.c, a.d, b.d/ ;
ij1 represents a one-to-many mapping where one element of i maps onto many elements of j.
ij2 represents a many-to-one mapping where many elements of i map onto one element of j.
ij3 is the most general case where many elements of i map on to many elements of j.
These sets can be written compactly as

set i / a, b /
j / c, d, e /
ij1(i,j) /a.(c,d)/
ij2(i,j) /(a,b).c/
ij3(I,j) /(a,b).(c,d)/ ;

The parenthesis provides a list of elements that can be expanded when creating pairs.

Attention
When complex sets like this are created, it is important to check that the desired set has been obtained. The checking
can be done by using a display statement.

The hash sign (#) followed by the set name is a shorthand for referring to all the elements in a set.
The matching operator (:) can be used to map ordered sets. The operator is similar to the product operator (.), however, in
this case elements are matched pairwise by mapping elements with the same order number.
The below example demonstrates the two concepts.
5 Multi-dimensional Sets 49

set i /a, b/
j /c, d, e/
ij4a(i,j) /a.#j/
ij4b(i,j) /a.c, a.d, a.e/
ij5a(i,j) /#i.#j/
ij5b(i,j) /a.c, a.d, a.e, b.c, b.d, b.e/
ij6a(i,j) /#i:#j/
ij6b(i,j) /a.c, b.d/
ij7a(i,j) /#i:(d*e)/
ij7b(i,j) /a.d, b.e/ ;

Sets which name differ only by the last letter map to the same elements. Consider set ij6a(i,j), where the element with
the highest order number in set i is element b, with order number 2. Similarly, the element with the highest order number in
set j is element e, with order number 3. Hence, element e is without a match and, therefore, not mapped.
The concepts may be generalized to sets with more than two labels per set element. Mathematically these are called 3-tuples,
4-tuples, or more generally, n-tuples.
This section ends with some examples to illustrate definitions of multi-label set elements. Some examples of the compact
representation of sets of n-tuples using combinations of dots, parentheses, and commas are shown in Table 1.
Table 1: Examples of the compact representation of sets

Construct Result
(a,b).c.d a.c.d, b.c.d
(a,b).(c,d) .e a.c.e, b.c.e, a.d.e, b.d.e
(a.13).c (a.1, a.2, a.3).c or a.1.c, a.2.c, a.3.c
13. 13. 13 1.1.1, 1.1.2, 1.1.3, ..., 3.3.3

Note that the asterisk can also be used in conjunction with the dot. Recall, that the elements of the list 14 are {1, 2, 3, 4}.

5.3 Projection and Aggregation of Sets

Projection and aggregation operations on sets and parameters can be performed in two different ways: a slower and more
intuitive way, as well as, a faster and more compact way. The more intuitive way is to use assignment and the sum operator,
while the faster and more compact way is to use the OPTION statement. The OPTION statement can be used as follows:

Option item1 < item2 ;

Option item1 <= item2 ;

After the OPTION keyword the left and right items are identifiers with conforming domain declarations. The dimensionality
of the left symbol has to be equal or less the dimensionality of the right side. If the left dimensionality is less than the right
one, the operation performed is an aggregation or projection depending on the data type of the left side. In all cases, indices
are permuted according to the domain definitions. This means that if the domain identifier is unique, then the permutation is
performed unambiguously. However, if the domain has identical domain symbol definitions, then they are permuted right to
left ( <) or left to right ( <=). A later example in this section will clarify this. The following example demonstrates the two
ways to do projection and aggregation on sets:

Sets i / i1*i3 /
j / j1*j2 /
k / k1*k4 /
ijk(i,j,k) / #i.#j.#k /
ij1a(i,j)
ij1b(i,j);
50 Set Definition

Scalars Count_1a, Count_1b, Count_2a, Count_2b;

* Method 1: by using assignment and the sum operator

ij1a(i,j) = sum(k,ijk(i,j,k));
Count_1a = sum(ij1a(i,j),1);
Count_2a = sum(ijk(i,j,k),1);

* Method 2: Option statement performs a projection

Option ij1b <= ijk;
* Method 2: Option statement performs an aggregation (counts elements)
Option Count_1b <= ij1b;
Option Count_2b <= ijk;
Display ij1a, ij1b, ijk, Count_1a, Count_1b, Count_2a, Count_2b;

Attention
The OPTION statement for projection and aggregation operations can also be applied on parameters!

However, in the special case, where a domain has identical domain symbol definitions, e.g., set i1(i,i,i), a permutation of
the domain is ambiguous. The projection can be performed by permuting the indices from right to left ( <) or left to right (
<=). The below example clarifies the difference:

Set i / i1*i3 /
i1(i,i,i) "Set members" / i1.i2.i3, i3.i3.i1/
i2a(i,i) "i2a(i,ii) = sum(i1(iii,ii,i),1)"
i2b(i,i) "Option i2b<i1 (right to left)"
i3a(i,i) "i3a(i,ii) = sum(i1(i,ii,iii),1)"
i3b(i,i) "Option i3b<=i1 (left to right)";
Alias (i,ii,iii);

* Two ways to assign: i1.i3, i3.i2

i2a(i,ii) = sum(i1(iii,ii,i),1);
Option i2b<i1;

* Two ways to assign: i1.i2, i3.i3

i3a(i,ii) = sum(i1(i,ii,iii),1);
Option i3b<=i1;
Option i1:0:0:1, i2a:0:0:1, i2b:0:0:1, i3a:0:0:1, i3b:0:0:1;
Display i1, i2a,i2b, i3a, i3b;

Hence, the left to right ( <=) permutation might be more intuitive.

6 Singleton Sets
A singleton set in GAMS is a special set that has at most one element (zero elements are allowed as well). Like other
sets, singleton sets can have up to 20 dimensions.

Set i / a, b, c /;
Singleton Set j / d /
k(i) / b /
l(i,j) / c.d /;

A data statement for a singleton set with more than one element will create a compilation error:
7 Summary 51

1 Singleton Set s / s1*s3 /;

**** $844
2 display s;

Error Messages
844 Singleton with more than one entry (see $onStrictSingleton)

This behavior can be changed with $offStrictSingleton .

Attention
Singleton sets can be especially useful in assignment statements since they don't need to be controlled by an
controlling index nor an indexed operator. More information about this can be found in chapter Data Manipulations
with Parameters.

7 Summary
In GAMS, a simple set consists of a set name and the elements of the set. Both the name and the elements may have
associated text that explains the name or the elements in more detail. More complex sets have elements that are pairs or even
n-tuples. These sets with pairs and n-tuples are ideal for establishing relationships between the elements in different sets.
GAMS also uses a domain checking capability to help catch labeling inconsistencies and typographical errors made during
the definition of related sets.
The discussion here has been limited to sets whose members are all specified as the set is being declared. For many models
this is all you need to know about sets. Later we will discuss more complicated concepts, such as sets whose membership
changes in different parts of the model (assignment to sets) and other set operations such as unions, complements and
intersections.
52 Set Definition
Chapter 5

Data Entry: Parameters, Scalars and Tables

1 Introduction
One of the basic design paradigms of the GAMS language has been to use data in its most basic form, which may be scalar,
list oriented, or tables of two or more dimensions. Based on this criterion, three data types are introduced in this chapter.

Type Description
Scalar Single (scalar) data entry.
Parameter List oriented data.
Table Table oriented data. Must involve two or more dimensions.

Each of these data types will be explained in detail in the following sections.

Attention
Initialization of data can only be done once for parameters; thereafter data must be modified with assignment statements.

2 Scalars
The scalar statement is used to declare and (optionally) initialize a GAMS parameter of dimensionality zero. That means
there are no associated sets, and that there is therefore exactly one number associated with the parameter.

2.1 The Syntax

In general, the syntax in GAMS for a scalar declaration is:

scalar[s] scalar_name [text] [/signed_num/]

{ scalar_name [text] [/signed_num/]} ;

Scalar name is the internal name of the scalar (also called an identifier) in GAMS. The accompanying text is used to describe
the element immediately preceding it. Signed num is a signed number and is assigned to be the value of scalar name.
As with all identifiers, scalar name has to start with a letter followed by more letters or digits. It can only contain
alphanumeric characters, and can be up to 63 characters long. Explanatory text must not exceed 254 characters and must all
be contained on the same line as the identifier or label it describes.
54 Data Entry: Parameters, Scalars and Tables

2.2 An Illustrative Example

An example of a scalar definition in GAMS is shown below.

Scalars rho "discount rate" / .15 /

irr "internal rate of return"
life "financial lifetime of productive units" /20/;

The statement above initializes rho and life, but not irr. Later on another scalar} statement can be used to initialize irr,
or, (looking ahead to a notion that will be developed later), an assignment statement could be used to provide the value:

irr = 0.07;

3 Parameters
While parameter is a data type that encompasses scalars and tables, the discussion in this chapter will focus on the use
of parameters in data entry. List oriented data can be read into GAMS using the parameter statement.

3.1 The Syntax

In general, the syntax in GAMS for a parameter declaration is:

parameter[s] param_name [text] [/ element [=] signed_num

{,element [=] signed num} /]
{,param_name [text] [/ element [=] signed_num
{,element [=] signed num} /]} ;

Param name is the internal name of the parameter (also called an identifier) in GAMS. The accompanying text is used to
describe the parameter immediately preceding it. Signed num is a signed number and is declared to be the value of the entry
associated with the corresponding element.
As with all identifiers, param name has to start with a letter followed by more letters or digits. It can only contain
alphanumeric characters, and can be up to 63 long. Explanatory text must not exceed 254 characters and must all be contained
on the same line as the identifier or label it describes.
A parameter may be indexed over one or more sets (the maximum number being 20). The elements in the data should belong
to the set that the parameter is indexed over.

Attention
The default value of a parameter is 0.

Parameter initialization requires a list of data elements, each consisting of a label and a value. Slashes must be used at the
beginning and end of the list, and commas must separate data elements entered more than one to a line. An equals sign or a
blank may be used to separate the label-tuple from its associated value. A parameter can be defined in a similar syntax to that
used for a set.

3.2 An Illustrative Examples

The fragment below is adapted from [MEXSS]. We also show the set definitions because they make the example clearer.
4 Tables 55

Set i "steel plants" / hylsa "monterrey"

hylsap "puebla" /
j "markets" / mexico-df, monterrey, guadalaja / ;

parameter dd(j) distribution of demand

/ mexico-df 55,
guadalaja 15 / ;

The domain checking specification for dd means that there will be a vector of data associated with it, one number correspond-
ing to every member of the set j listed. The numbers are specified along with the declaration in a format very reminiscent of
the way we specified sets: in this simple case a label followed by a blank separator and then a value. Any of the legal number
entry formats are allowable for the value. The default data value is zero. Since monterrey has been left out of the data list,
then the value associated with dd('monterrey'), the market share in monterrey, would be zero.
We can also put several data elements on a line, separated by commas:

parameter a(i) / seattle = 350, san-diego = 600 /

b(i) / seattle 2000, san-diego 4500 / ;

As with sets, commas are optional at end-of-line.

3.3 Parameter Data for Higher Dimensions

A parameter can have up to 20 dimensions. The list oriented data initialization through the parameter statement can be
easily extended to data of higher dimensionality. The label that appears on each line in the one-dimensional case is replaced
by a label-tuple for higher dimensions. The elements in the n-tuple are separated by dots (.) just like in the case of
multi-dimensional sets.
The following example illustrates the use of parameter data for higher dimensions:

parameter salaries(employee,manager,department)
/anderson .murphy .toy = 6000
hendry .smith .toy = 9000
hoffman .morgan .cosmetics = 8000 / ;

All the mechanisms using asterisks and parenthesized lists that we introduced in our discussion of sets are available here as
well. Below is an artificial example, in which a very small fraction of the total data points are initialized. GAMS will mark
an error if the same label combination (or label-tuple) appears more than once in a data list.

Set row / row1*row10 /

col / col1*col10 / ;
parameter a(row, col)
/ (row1,row4) . col2*col7 12
row10 . col10 17
row1*row7 . col10 33 / ;

In this example, the twelve elements row1.col2 to row1.col7 and row4.col2 to row4.col7 are all initialized at 12, the
single element row10.col10 at 17, and the seven elements rows1.col10 to row7.col10 at 33. The other 80 elements (out
of a total of 100) remain at their default value, which is 0. This example shows the ability of GAMS to provide a concise
initialization, or definition, for a sparse data structure.

4 Tables
Tabular data can be declared and initialized in GAMS using a table statement For 2- and higher-dimensional parameters this
provides a more concise and easier method of data entry than the list based approach, since each label appears only once (at
least in small tables).
56 Data Entry: Parameters, Scalars and Tables

4.1 The Syntax

In general, the syntax in GAMS for a table declaration is:

table table_name [text] EOL

element { element }
element signed_num { signed_num} EOL
{element signed_num { signed_num} EOL} ;

Table name is the internal name of the table (also called an identifier) in GAMS. The accompanying text is used to describe
the parameter immediately preceding it. Signed num is a signed number and is declared to be the value of the entry associated
with the corresponding element.

Attention
The table statement is the only statement in the GAMS language that is not free format.

The following rules apply:

The relative positions of all entries in a table are significant. This is the only statement where end of line (EOL) has
meaning. The character positions of the numeric table entries must overlap the character positions of the column
headings.
The column section has to fit on one line.
The sequence of signed numbers forming a row must be on the same line.
The element definition of a row can span more than one line.
A specific column can appear only once in the entire table.

The rules for forming simple tables are straightforward. The components of the header line are the by now familiar
keyword-identifier-domain list-text sequence, the domain-list and text being optional. Labels are used on the
top and the left to map out a rectangular grid that contains the data values. The order of labels is unimportant, but if domain
checking has been specified each label must match one in the associated set. Labels must not be repeated, but can be left out
if the corresponding numbers are all zero or not needed. At least one blank must separate all labels and data entries. Blank
entries imply that the default value (zero) will be associated with that label combination.

Attention
Notice also that, in contrast to the set, scalar, and parameter statements, only one identifier can be declared and
initialized in a table statement.

4.2 An Illustrative Example

The example below, adapted from [KORPET], is preceded by the appropriate set definitions,

sets i "plants"
/ inchon,ulsan,yosu /
m "productive units" /
atmos-dist "atmospheric distillation unit"
steam-cr "steam cracker"
aromatics "aromatics unit"
hydrodeal "hydrodealkylator" / ;

table ka(m,i) "initial cap. of productive units (100 tons per yr)"
4 Tables 57

inchon ulsan yosu

atmos-dist 3702 12910 9875
steam-cr 517 1207
aromatics 181 148
hydrodeal 180 ;

In the example above, the row labels are drawn from the set m, and those on the column from the set i. Note that the data for
each row is aligned under the corresponding column headings.

Attention
If there is any uncertainty about which data column a number goes with, GAMS will protest with an error message and
mark the ambiguous entry.

4.3 Continued Tables

If a table has too many columns to fit nicely on a single line, then the columns that don't fit can be continued on additional
lines. We use the same example to illustrate:

table ka(m,i) initial cap. of productive units (100 tons per yr)
inchon ulsan
atmos-dist 3702 12910
steam-cr 517
aromatics 181
hydrodeal 180

+ yosu
atmos-dist 9875
steam-cr 1207
aromatics 148 ;

The crucial item is the plus '+' sign above the row labels and to the left of the column labels in the continued part of the
table. The row labels have been duplicated, except that hydroreal has been left out, not having associated data. Tables can
be continued as many times as necessary.

4.4 Tables with more than Two Dimensions

A table can have up to 20 dimensions. Dots are again used to separate adjacent labels, and can be used in the row or column
position. The label on the left of the row corresponds to the first set in the domain list, and that on the right of each column
header to the last. Obviously there must be the same number of labels associated with each number in the table, as there are
sets in the domain list.
The actual layout chosen will depend on the size of the controlling sets and the amount of data, and the ideal choice should be
the one that provides the most intuitively satisfactory way of organizing and inspecting the data. Most people can more easily
look down a column of numbers than across a row, but to put extra labels on the row leads to a greater density of information.
The following example, adapted from [MARCO], illustrates the use of tables with more than two dimensions.

Sets ci "commodities : intermediate"

/ naphtha "naphtha"
dist "distillate"
gas-oil "gas-oil" /
cr "commodities : crude oils"
/ mid-c "mid-continent"
w-tex "west-texas" /
58 Data Entry: Parameters, Scalars and Tables

q "attributes of intermediate products"

/ density, sulfur / ;

table attrib(ci, cr, q) blending attributes

density sulfur
naphtha. mid-c 272 .283
naphtha. w-tex 272 1.48
dist . mid-c 292 .526
dist . w-tex 297 2.83
gas-oil. mid-c 295 .98
gas-oil. w-tex 303 5.05 ;

The table attrib could also be laid out as shown below:

table attrib (ci,cr,q) blending attributes

w-tex.density mid-c.density w-tex.sulfur mid-c.sulfur
naphtha 272 272 1.48 .283
dist 297 297 2.83 .526
gas-oil 303 303 5.05 .98 ;

4.5 Condensing Tables

All the mechanisms using asterisks and parenthesized lists that were introduced in the discussion of sets are available here as
well. The following example shows how repeated columns or rows can be condensed with asterisks and lists in parentheses
follows. The set membership is not shown, but can easily be inferred.

table upgrade(strat,size,tech)
small.tech1 small.tech2 medium.tech1 medium.tech2
strategy-1 .05 .05 .05 .05
strategy-2 .2 .2 .2 .2
strategy-3 .2 .2 .2 .2
strategy-4 .2 .2

table upgradex(strat,size,tech) alternative way of writing table

tech1*tech2
strategy-1.(small,medium) .05
strategy-2*strategy-3.(small,medium) .2
trategy-4.medium .2;

display attrib, attribx;

Here we encounter the display statement again. It causes the data associated with upgrade and upgradex to be listed on
the output file.

4.6 Handling Long Row Labels

It is possible to continue the row labels in a table on a second, or even third, line in order to accommodate a reasonable
number of columns. The break must come after a dot, and the rest of each line containing an incomplete row label-tuple must
be blank.
The following example, adapted from [INDUS], is used to illustrate. As written, this table actually has nine columns and
many rows: we have just reproduced a small part to show continued row label-tuples.
5 Acronyms 59

table yield (c,t,s,w,z) crop yield (metric tons per acre)

nwfp pmw
wheat.(bullock, semi-mech).la-plant.
(heavy, january) .385 .338
wheat.(bullock, semi-mech).la-plant.light .506 .446
wheat.(bullock, semi-mech).la-plant. standard .592 .524
wheat.(bullock, semi-mech).(qk-harv, standard).
(heavy, january) .439 .387

5 Acronyms
An acronym is a special data type that allows the use of strings as values.

5.1 The Syntax

The declaration for an acronymis similar to a set or parameter declaration in that several of them can be declared in one
statement.

Acronym[s] acronym_name {,acronym_name}

Acronym name is an identifier and follows the same naming convention as other identifiers like names of sets, parameters, or
tables.

5.2 Illustrative Example

Consider the following example,

set machines /m-1*m-5/ ; acronyms monday, tuesday, wednesday, thursday, friday ;

parameter shutdown(machines) /
m-1 tuesday
m-2 wednesday
m-3 friday
m-4 monday
m-5 thursday
/ ;

In the example above, data entries are in the form of strings like 'monday' and 'tuesday'. By declaring each of those
character strings as acronyms, this kind of data entry can be used by GAMS. Sections Acronyms in Assignments and Logical
Conditions Involving Acronyms will explain the further use of acronyms once entered in this form.

6 Summary
In this chapter, the declaration and initialization of parameters with the Scalar, Parameter, and Table statement have been
discussed. Chapter Data Manipulations with Parameters will describe how this data can be changed with assignment
statements.
60 Data Entry: Parameters, Scalars and Tables
Chapter 6

Data Manipulations with Parameters

1 Introduction
Data once initialized may require manipulation in order to bring it to the form required in the model. The first part of
this chapter will deal explicitly with parameter manipulation. The rest of the chapter will be devoted to explaining the
ramifications: indexed assignment functions, index operations.

2 The Assignment Statement

The assignment statement is the fundamental data manipulation statement in GAMS. It may be used to define or alter values
associated with any sets, parameters, variables or equations.
A simple assignment is written in the style associated with many other computer languages. GAMS uses the traditional
symbols for addition (+), subtraction (-), multiplication () and division (/). We will use them in the examples that
follow, and give more details in Section Expressions .

2.1 Scalar Assignments

Consider the following artificial sequence:

scalar x / 1.5/ ;
x = 1.2;
x = x + 2;

The scalar x is initialized to be 1.5. The second statement changes the value to 1.2, and the third changes it to 3.2. The second
and third statement assignments have the effect of replacing the previous value of x, if any, with a new one.
Note that the same symbol can be used on the left and right of the = sign. The new value is not available until the calculation
is complete, and the operation gives the expected result.

Attention
An assignment cannot start with a reserved word. A semicolon is therefore required as a delimiter before all assignments.

2.2 Indexed Assignments

The syntax in GAMS for performing indexed assignments is extremely powerful. This operation offers what may be thought
of as simultaneous or parallel assignment and it provides a concise way of specifying large amounts of data. Consider the
mathematical statement, DJd = 2.75DAd for all d.
62 Data Manipulations with Parameters

This means that for every member of the set d, a value is assigned to DJ. This can be written in GAMS as follows,

dj(d) = 2.75*da(d) ;

This assignment is known technically as an indexed assignment and set d will be referred to as the controlling index or
controlling set.

Attention
The index sets on the left hand side of the assignment are together called the controlling domain of the assignment

The extension to two or more controlling indices should be obvious. There will be an assignment made for each label
combination that can be constructed using the indices inside the parenthesis. Consider the following example of an assignment
to all 100 data elements of a.

Set row / r-1*r-10 /

col / c-1*c-10 /
sro(row) / r-7*r-10 / ;
parameters a(row,col),
a(row,col) = 13.2 + r(row)*c(col) ;

The calculation in the last statement is carried out for each of the 100 unique two-label combinations that can be formed from
the elements of row and col. The first of these is, explicitly,

a(r-1,c-1) = 13.2 + r(r-1)*c(c-1).

2.3 Sparse Assignments

A sparse assignment will assign a value to the left hand side(LHS) of the = sign only if the right hand side (RHS) is nonzero.
Consider the following example:

*define end-of-line comment symbol: $eolcom !!

$eolcom !!
Set i /a,b,c/
Parameter d1(i) Data d1 /a 1, b 1, c 1/
d2(i) Data used to overwrite d1 /a 2, b 0 /
p1(i) p1(i)=d2(i) Full replacement
p2(i) p2(i)$(d2(i))=d2(i) Sparse replacement
p3(i) p3(i)$=d2(i) Shorthand for sparse replacement;
p1(i)=d1(i); !! result: p1(a)=1 p1(b)=1 p1(c)=1
p2(i)=d1(i); !! result: p2(a)=1 p2(b)=1 p2(c)=1
p3(i)=d1(i); !! result: p3(a)=1 p3(b)=1 p3(c)=1
p1(i)=d2(i); !! result: p1(a)=2
p2(i)$(d2(i))=d2(i); !! result: p2(a)=2 p2(b)=1 p2(c)=1
p3(i)$=d2(i); !! result: p3(a)=2 p3(b)=1 p3(c)=1
Display d1,d2,p1,p2,p3;

In the sparse assignments, the parameters p2(i) and p3(i) are replaced with values from parameter d2(i) only if the entry in
d2(i) is nonzero. Hence, the nonzero entry d2('a') replaces entry p2('a') and p3('a').

2.4 Using Labels Explicitly in Assignments

It is often necessary to use labels explicitly in assignments. This can be done as discussed earlier with parameters - by using
quotes around the label. Consider the following assignment,
2 The Assignment Statement 63

a(r-7,c-4) = -2.36 ;

This statement assigns a constant value to one element of a. All other elements of a remain unchanged. Either single or
double quotes can be used around the labels.

2.5 Assignments Over Subsets

In general, wherever a set name can occur in an indexed assignment, a subset (or even alabel) can be used instead if you need
to make the assignment over a subset instead of the whole domain.
Consider the following example,

a(sro,col-10) = 2.44 -33*r(sro) ;

where sro has already been established to be a proper subset of row.

2.6 Issues with Controlling Indices

Attention
The number of controlling indices on the left of the = sign should be at least as many as the number of indices on
the right. There should be no index on the right hand side of the assignment that is not present on the left unless it is
operated on by an indexed operator

Consider the following statement,

a(row,col-2) = 22 - c(col) ;

GAMS will flag this statement as an error since col is an index on the right hand side of the equation but not on the left.
There would be no error here if col would be a singleton set. Since there is not more than one element in a singleton
set it is not required that this index gets controlled by an controlling index on the left or an indexed operator.

Attention
Each set is counted only once to determine the number of controlling indices. If the same set appears more than once
within the controlling domain, the second and higher occurrences of the set should be aliases of the original set in
order for the number of controlling indices to be equal to the number of indices.

Consider the following statement as an illustration,

b(row,row) = 7.7 - r(row) ;

This statement has only one controlling index (row). If one steps through the elements of row one at a time assignments will
be made only to the diagonal entries in b. This will assign exactly 10 values! None of the off-diagonal elements of b will be
filled.
If an additional name is provided for row and used in the second index position, then there will be two controlling indices
and GAMS will make assignments over the full Cartesian product, all 100 values. Consider the following example,

alias(row,rowp) ;
b(row,rowp) = 7.7 - r(row) + r(rowp) ;
64 Data Manipulations with Parameters

2.7 Extended Range Identifiers in Assignments

The GAMS extended range identifiers can also be used in assignment statements, as in

a(row,col-10) = inf ; a(row,col-1) = -inf ;

Extended range arithmetic will be discussed later in this Section. The values most often used are NA in incomplete tables, and
INF for variable bounds.

2.8 Acronyms in Assignments

Acronyms can also be used in assignment statements, as in

acronym monday, tuesday, wednesday, thursday, friday ;

parameter dayofweek ;
dayofweek = wednesday ;

Attention
Acronyms contain no numeric value, and are treated as character strings only.

3 Expressions
An expression is an arbitrarily complicated specification for a calculation, with parentheses nested as needed for clarity and
intent. In this section, the discussion of parameter assignments will continue by showing in more detail the expressions that
can be used on the right of the = sign. All numerical facilities available in both standard and extended arithmetic will be
covered.

3.1 Standard Arithmetic Operations

The standard arithmetic symbols and operations are
exponentiation
,/ multiplication and division
+,- addition and subtraction (unary and binary)
They are listed above in precedence order, which determines the order of evaluation in an expression without parentheses.
Consider, for example:

x = 5 + 4*3**2 :

For clarity, this could have been written:

x = 5 + (4*(3**2)) ;

In both cases the result is 41.

Attention
It is better to use parentheses than to rely on the precedence of operators, since it prevents errors and clarifies
intentions.
Expressions may be freely continued over many lines: an end-of-line is permissible at any point where a blank
may be used. Blanks may be used for readability around identifiers, parentheses and operator symbols. Blanks are
not allowed within identifiers or numbers, and are significant inside the quote marks used to delimit labels.
3 Expressions 65

xn is equivalent to the function call rPower(x,y) and is calculated inside GAMS as exp[nlog(x)]. This
operation is not defined if x has a negative value, and an error will result. If the possibility of negative values for x
is to be admitted and the exponent is known to be an integer, then a function call, power(x,n), is available.

Three additional capabilities are available to add power and flexibility of expression calculations. They are indexed operations,
functions and extended range arithmetic.

3.2 Indexed Operations

In addition to the simple operations explained before, GAMS also provides the following four indexed operations.
sum Summation over controlling index
prod Product over controlling index
smin Minimum value over controlling index
smax Maximum value over controlling index
These four operations are performed over one or more controlling indices. The syntax in GAMS for these operations is,

indexed_op( (controlling_indices), expression)

If there is only one controlling index, the parentheses around it can be removed. The most common of these is sum, which
is used to calculate totals over the domain of a set. Consider the following simple example adapted from [ANDEAN] for
illustration.

sets i plants / cartagena, callao, moron /

m product / nitr-acid, sulf-acid, amm-sulf /;

parameter capacity(i,m) capacity in tons per day

totcap(m) total capacity by process ;

totcap(m) = sum(i, capacity(i,m));

This would be written, using normal mathematical representation, as totCm = i Cim .

The index over which the summation is done, i, is separated from the reserved word sum by a left parenthesis and from the
data term capacity(i,m) by a comma. i is again called the controlling index for this operation. The scope of the control is
the pair of parentheses () that starts immediately after the sum. It is not likely to be useful to have two independent index
operations controlled by the same index.
It is also possible to sum simultaneously over the domain of two or more sets, in which case more parentheses are needed.
Also, of course, an arithmetic expression may be used instead of an identifier;

count = sum((i,j), a(i,j)) ;

emp = sum(t, l(t)*m(t)) ;

The equivalent mathematical forms are:

count = Ai j and emp = Lt Mt

i j t

The smin and smax operations are used to find the largest and smallest values over the domain of the index set or sets. The
index for the smin and smax operators is specified in the same manner as in the index for the sum operator. Consider the
following example to find the largest capacity,

lrgunit = smax((i,m),capacity(i,m));
66 Data Manipulations with Parameters

3.3 Functions
Functions play an important part in the GAMS language, especially for non-linear models. Similar to other programming
languages, GAMS provides a number of built-in (intrinsic) functions. However, GAMS is used in an extremely diverse
set of application areas and this creates frequent requests for the addition of new and often sophisticated and specialized
functions. There is a trade-off between satisfying these requests and avoiding complexity not needed by most users. The
GAMS Function Library Facility (Section Functions) provides the means for managing that trade-off.

Intrinsic Functions

GAMS provides commonly used standard functions such as exponentiation, and logarithmic, and trigonometric functions.
The complete list of available functions is given in the following sections: Mathematical functions, Logical functions, Time
and Calendar functions, and GAMS utility and performance functions. There are cautions to be taken when functions appear
in equations; these are dealt with in Section Expressions in Equation Definitions, Chapter Equations.
In the following sections, the Endogenous Classification (third column) specifies in which models the function can legally
appear. In order of least to most restrictive, the choices are DNLP, NLP, any, none (see Section Classification of Models for
details). Functions classified as any are only permitted with exogenous (constant) arguments.
The following conventions are used for the function arguments. Lower case indicates that an endogenous variable is allowed.
Upper case indicates that a constant argument is required. The arguments in square brackets can be omitted and default
values will be used. Those default values are specified in the function description provided in the second column.
Mathematical functions

Function Description End. Classif.

abs(x) returns the absolute value of an expression or term x DNLP
arccos(x) returns the inverse cosine of the argument x where x is a real num- NLP
ber between -1 and 1 and the output is in radians, see MathWorld
arcsin(x) returns the inverse sine of the argument x where x is a real number NLP
between -1 and 1 and the output is in radians, see MathWorld
arctan(x) returns the inverse tangent of the argument x where x is a real NLP
number and the output is in radians, see MathWorld
arctan2(y,x) four-quadrant arctan function yielding arctangent(y/x) which is NLP
the angle the vector (x,y) makes with (1,0) in radians
(x)(y)
Beta(x,y) beta function: B(x, y) = (x+y) , see MathWorld DNLP
betaReg(x,y,z) regularized beta function, see MathWorld NLP
binomial(n,k) returns the (generalized) binomial coefficient for n, k 0 NLP
ceil(x) returns the smallest integer number greater than or equal to x DNLP
centropy(x,y[,Z]) Centropy: x ln( x+Z
y+Z ), default setting: Z = 0 NLP
cos(x) returns the cosine of the argument x where x must be in radians, NLP
see MathWorld
cosh(x) returns the hyperbolic cosine of x where x must be in radians, see NLP
MathWorld
cvPower(X,y) returns X y for X 0 NLP
dividend
div(dividend,divisor) returns divisor , undefined for divisor = 0 NLP
dividend
div0(dividend,divisor) returns divisor , returns 10299 for divisor = 0 NLP
q
eDist(x1[,x2,x3,...]) Euclidean or L-2 Norm: x12 + x22 + ..., default setting: x2 , x3 , ... = NLP
0
entropy(x) Entropy: x ln(x) NLP
3 Expressions 67

Function Description End. Classif.

errorf(x) calculates the integral of the standard normal distribution from NLP
Rx t 2
negative infinity to x, error f (x) = 1 e 2 dt
2

execSeed reads or writes the seed for the random number generator none
exp(x) returns the exponential function ex of an expression or term x, see NLP
MathWorld
fact(N) returns the factorial of N where N is an integer any
floor(x) returns the greatest integer number less than or equal to x DNLP
frac(x) returns the fractional part of x DNLP
R
gamma(x) gamma function: (x) = t x1 et dt, see MathWorld DNLP
0
gammaReg(x,a) regularized gamma function, see MathWorld NLP
log(x) returns the natural logarithm, logarithm base e, see MathWorld NLP
logBeta(x,y) log beta function: log(B(x, y)) NLP
logGamma(x) log gamma function as discussed in MathWorld NLP
log10(x) returns the common logarithm, logarithm base 10, see MathWorld NLP
log2(x) returns the binary logarithm, logarithm base 2, see MathWorld NLP
mapVal(x) Function that returns an integer value associated with a numerical any
result that can contain special values. Possible values are:
0 for all regular numbers
4 for UNDF which means undefined
5 for NA which means not available
6 for INF which means plus infinity
7 for -INF which means minus infinity
8 for EPS which means very close to zero but different from zero
max(x1,x2,x3,...) returns the maximum of a set of expressions or terms, the number DNLP
of arguments is not limited
min(x1,x2,x3,...) returns the minimum of a set of expressions or terms, the number DNLP
of arguments is not limited
mod(x,y) returns the remainder of x divided by y DNLP
ncpCM(x,y,Z) function that computes a Chen-Mangasarian smoothing equaling: NLP
xy
x Z ln(1 + e Z )
ncpF(x,y[,Z]) function
p that computes a Fisher smoothing equaling: NLP
(x2 + y2 + 2 Z) x y, Z 0, default setting: Z=0

ncpVUpow(r,s[,MU]) NCP Veelken-Ulbrich: smoothed min NLP

(r+s|t|)
(
2 i f |t|
ncpVUpow = (r+s 8 (( t )4 +6( t )2 +3))
2 otherwise
where t = r s, default setting: MU = 0

ncpVUsin(r,s[,MU]) NCP Veelken-Ulbrich: smoothed min NLP

(r+s|t|)
(
2 i f |t|
ncpVUsin = (r+s( 2 3
sin( 2 + 2 )+))
2 otherwise
where t = r s,default setting: MU = 0

normal(MEAN,STDDEV) generates a random number with normal distribution with mean none
MEAN and standard deviation STDDEV, see MathWorld
pi value of = 3.141593... any
68 Data Manipulations with Parameters

Function Description End. Classif.

poly(x,A0,A1,A2[,A3,...]) computes a polynomial over scalar x where result = A0 + A1 x + NLP
A2 x2 + A3 x3 + ... - this has a maximum of 20 arguments, default
setting: A3 , ... = 0
returns xY where Y must be an integer NLP
power(x,Y)
randBinomial(N,P) generates a random number with binomial distribution where n is none
the number of trials and p the probability of success for each trial,
see MathWorld
randLinear(LOW,SLOPE,HIGH) generates a random number between LOW and HIGH with linear none
distribution, SLOPE must be greater than HIGH2LOW
randTriangle(LOW,MID,HIGH) generates a random number between LOW and HIGH with triangu- none
lar distribution, MID is the most probable number, see MathWorld
round(x[,DECPL]) rounding x, DECPL declares the number of decimal places, default DNLP
setting: DECPL = 0
returns xy for x > 0, however, if x = 0 then other restrictions for NLP
rPower(x,y)
y apply. This function is equal to the arithmetic operation 'xy'
which is explained at Standard Arithmetic Operations
1
sigmoid(x) Sigmoid calculation: 1+ex
, see MathWorld NLP
sign(x) sign of x, returns 1 if x > 0, -1 if x < 0, and 0 if x = 0 DNLP
signPower(x,Y) signed power where Y must be greater than 0, returns xY if x 0 NLP
and 1 |x|Y if x < 0
sin(x) returns the sine of the argument x where x must be in radians, see NLP
MathWorld
sinh(x) returns the hyperbolic sine of x where x must be in radians, see NLP
MathWorld
slexp(x[,SP]) smooth (linear) exponential function, SP means smoothing param- NLP
eter, default setting: SP = 150
sllog10(x[,SP]) smooth (linear) logarithm base 10, SP means smoothing parameter, NLP
default setting: SP = 10150
slrec(x[,SP]) smooth (linear) reciprocal, SP means smoothing parameter, default NLP
setting: SP = 1010
sqexp(x[,SP]) smooth (quadratic) exponential funtion, SP means smoothing pa- NLP
rameter, default setting: SP = 150
sqlog10(x[,SP]) smooth (quadratic) logarithm base 10, SP means smoothing pa- NLP
rameter, default setting: SP = 10150
sqr(x) returns the square of an expression or term x NLP
sqrec(x[,SP]) smooth (quadratic) reciprocal, SP means smoothing parameter, NLP
default setting: SP = 1010
sqrt(x) returns the squareroot of x, see MathWorld NLP
tan(x) returns the tangent of the argument x where x must be in radians, NLP
see MathWorld
tanh(x) returns the hyperbolic tangent of x where x must be in radians, see NLP
MathWorld
trunc(x) truncation, removes decimals from x DNLP
uniform(LOW,HIGH) generates a random number between LOW and HIGH with uni- none
form distribution, see MathWorld
uniformInt(LOW,HIGH) generates an integer random number between LOW and HIGH none
with uniform distribution, see MathWorld
vcPower(x,Y) returns xY for x 0. NLP
3 Expressions 69

Logical functions

Function Description End. Classif.

bool and(x,y) boolean and: returns 0 if x = 0 y = 0, else returns 1, another DNLP
possible command is 'x and y'
bool eqv(x,y) boolean equivalence: returns 0 if exactly one argument is 0, else DNLP
returns 1, another possible command is 'x eqv y'
bool imp(x,y) boolean implication: returns 1 if x = 0 y 6= 0, else returns 0, another DNLP
possible command is 'x imp y'
bool not(x) boolean not: returns 1 if x = 0, else returns 0, another possible DNLP
command is 'not x'
bool or(x,y) boolean or: returns 0 if x = y = 0, else returns 1, another possible DNLP
command is 'x or y'
bool xor(x,y) boolean xor: returns 1 if exactly one argument is 0, else returns 0, DNLP
another possible command is 'x xor y'
ifThen(cond,iftrue,else) first argument contains a condition (e.g. x > y). If the condition is DNLP
true, the function returns iftrue else it returns else.
rel eq(x,y) relation 'equal': returns 1 if x = y, else returns 0, another possible DNLP
command is 'x eq y'
rel ge(x,y) relation 'greater equal': returns 1 if x y, else returns 0, another DNLP
possible command is 'x ge y'
rel gt(x,y) relation 'greater than': returns 1 if x > y, else returns 0, another DNLP
possible command is 'x gt y'
rel le(x,y) relation 'less equal': returns 1 if x y, else returns 0, another possible DNLP
command is 'x le y'
rel lt(x,y) relation 'less than': returns 1 if x < y, else returns 0, another possible DNLP
command is 'x lt y'
rel ne(x,y) relation 'not equal': returns 1 if x 6= y, else returns 0, another possible DNLP
command is 'x ne y'

Time and Calendar functions

Function Description End. Classif.

gday(SDAY) returns Gregorian day from a serial day number date.time, where Jan 1, any
1900 is day 1
gdow(SDAY) returns Gregorian day of week from a serial day number date.time, where any
Jan 1, 1900 is day 1
ghour(SDAY) returns Gregorian hour of day from a serial day number date.time, where any
Jan 1, 1900 is day 1
gleap(SDAY) returns 1 if the year that corresponds to a serial day number date.time, any
where Jan 1, 1900 is day 1, is a leap year, else returns 0
gmillisec(SDAY) returns Gregorian milli second from a serial day number date.time, where any
Jan 1, 1900 is day 1
gminute(SDAY) returns Gregorian minute of hour from a serial day number date.time, any
where Jan 1, 1900 is day 1
gmonth(SDAY) returns Gregorian month from a serial day number date.time, where Jan any
1, 1900 is day 1
gsecond(SDAY) returns Gregorian second of minute from a serial day number date.time, any
where Jan 1, 1900 is day 1
70 Data Manipulations with Parameters

Function Description End. Classif.

gyear(SDAY) returns Gregorian year from a serial day number date.time, where Jan 1, any
1900 is day 1
jdate(YEAR,MONTH,DAY) returns a serial day number, starting with Jan 1, 1900 as day 1 any
jnow returns the current time as a serial day number, starting with Jan 1, 1900 none
as day 1
jstart returns the time of the start of the GAMS job as a serial day number, none
starting with Jan 1, 1900 as day 1
jtime(HOUR,MIN,SEC) returns fraction of a day that corresponds to hour, minute and second any

GAMS utility and performance functions

Function Description End. Classif.

errorLevel error code of the most recently used command none
number of execution errors, may either be read or assigned to none
execError
gamsRelease returns the version number of the current GAMS release, for example none
23.8
gamsVersion returns the current gams version, for example 238 none
handleCollect(HANDLE) tests if the solve of the problem identified by the calling argument HAN- none
DLE is done and if so loads the solution into GAMS. In particular it
returns:
0: if the model associated with HANDLE had not yet finished solution
or could not be loaded
1: if the solution has been loaded
handleDelete(HANDLE) deletes the grid computing problem identified by the HANDLE calling none
argument and returns a numerical indicator of the status of the deletion
as follows:
0: if the the model instance has been removed
1: if the argument HANDLE is not a legal handle
2: if the model instance is not known to the system
3: if the deletion of the model instance encountered errors
A nonzero return indicates a failure in the deletion and causes an execu-
tion error.
handleStatus(HANDLE) tests if the solve of the problem identified by the calling argument HAN- none
DLE is done and if so loads the solution into a GDX file. A numerical
indication of the result is returned as follows:
0: if a model associated with HANDLE is not known to the system
1: the model associaed with HANDLE exists but the solution process is
incomplete
2: the solution process has terminated and the solution is ready for re-
trieval
3: the solution process signaled completion but the solution cannot be
retrieved
An execution error is triggered if GAMS cannot retrieve the status of the
handle.
3 Expressions 71

Function Description End. Classif.

handleSubmit(HANDLE) resubmits a previously created instance of the model identified by the none
HANDLE for solution. A numerical indication of the result is returned
as follows:
0: the model instance has been resubmitted for solution
1: if the argument HANDLE is not a legal handle
2: if a model associated with the HANDLE is not known to the system
3: the completion signal could not be removed
4: the resubmit procedure could not be found
5: the resubmit process could not be started
In case of a nonzero return an execution error is triggered.
heapFree allocated memory which is no more in use but not freed yet none
heapLimit interrogates the current heap limit (maximum allowable memory use) in none
Mb and allows it to be reset
heapSize returns the current heap size in Mb none
jobHandle returns the Process ID (PID) of the last job started none
jobKill(PID) sends a kill signal to the running job with Process ID PID, the return none
value is one if this was successful, otherwise it is zero
jobStatus(PID) checks for the status of the job with the Process ID PID, possible return none
values are:
0: error (input is not a valid PID or access is denied)
1: process is still running
2: process is finished with return code which could be accessed by
errorlevel
3: process not running anymore or was never running, no return code
available
jobTerminate(PID) sends an interrupt signal to the running job with Process ID PID, the none
return value is one if this was succesful, otherwise it is zero
licenseLevel returns an indicator of type of license: any
0: demo license, limited to small models
1: full unlimited developer license
2: run time license, no new variables or equations can be introduced
besides those inherited in a work file
3: application license, only works with a specific work file which is
locked to the license file
licenseStatus returns a non zero when a license error is incurred any
maximum number of execution errors, may either be read or assigned to none
maxExecError
numCores returns the number of logical cores in the system any
sleep(SEC) execution pauses for SEC seconds none
timeClose returns the model closing time none
timeComp returns the compilation time in seconds none
timeElapsed returns the elapsed time in seconds since the start of a GAMS run none
timeExec returns the execution time in seconds none
timeStart returns the model start time since last restart none

Consider the following example of a function used as an expression in an assignment statement,

x(j) = log(y(j)) ;

which replaces the current value of x with the natural logarithm of y over the domain of the index set j.
72 Data Manipulations with Parameters

Extrinsic Functions

Using the GAMS Function Library Facility, functions can be imported from an external library into a GAMS model. Apart
from the import syntax, the imported functions can be used in the same way as intrinsic functions. In particular, they can be
used in equation definitions. Some function libraries are included with the standard GAMS software distribution (see Chapter
Extrinsic Functions) but GAMS users can also create their own libraries using an open programming interface. The GAMS
Test Library instances trilib01, trilib02, trilib03, and cpplib00 are simple examples in the programming languages
C, Delphi, Fortran, and C++ that come with every GAMS system.

Using Function Libraries

Function libraries are made available to a model using a compiler directive:

$FuncLibIn <InternalLibName> <ExternalLibName>

Note that the Function Library Facility gives you complete control over naming so that potential name conflicts between
libraries can be avoided. The <InternalLibName> is a sort of handle and will be used to refer to the library inside your
model source code. The <ExternalLibName> is the file name for the shared library that implements the extrinsic functions.
To access libraries included with your GAMS distribution you use the library's name with no path prefix. GAMS will look for
the library in a standard place within the GAMS installation. To access a library that does not reside in this standard place, the
external name should include a relative or absolute path to the library's location. GAMS will search for the shared library you
specify using the mechanisms specific to the host operating system. When processing the $FuncLibIn directive, GAMS will
validate the library, make the included functions available for use, and add a table of the included functions to the listing file.
Before using individual functions you must declare them:

Function <InternalFuncName> /<InternalLibName>.<FuncName>/;

Note that the syntax is similar to that used for declaring Sets, Parameters, Variables and so forth and that the control over
potential naming conflicts extends to the names of the individual functions. The <InternalFuncName> is the one that
you will use in the rest of your model code. The <InternalLibName> is the one that you created with the $FuncLibIn
directive and <FuncName> is the name given the function when the library was created. Once functions have been declared
with the Function statement they may be used exactly like intrinsic functions in the remainder of your model code.

Example

Here is an example that adds some concrete detail.

$eolcom //

$FuncLibIn trilib testlib_ml%system.dirsep%tridclib // Make the library available.

// trilib is the internal name being created now.
// tridclib is the external name.
// With no path, GAMS will look for tridclib in
// the GAMS system directory.

* Declare each of the functions that will be used.

* myCos, mySin and MyPi are names being declared now for use in this model.
* Cosine, Sine and Pi are the function names from the library.
* Note the use of the internal library name.

Function myCos /trilib.Cosine/

mySin /trilib.Sine/
myPi /trilib.Pi/;
3 Expressions 73

scalar i, grad, rad, intrinsic;

for (i=1 to 360,

intrinsic = cos(i/180*pi);
grad = mycos(i,1);
abort$round(abs(intrinsic-grad),4) cos, i, intrinsic, grad;
rad = mycos(i/180*pi);
abort$round(abs(intrinsic-rad) ,4) cos, i, intrinsic, rad;);

variable x;
equation e;

e.. sqr(mysin(x)) + sqr(mycos(x)) =e= 1;

model m /e/;
x.lo = 0; x.l=3*mypi;
solve m min x using nlp;

The following lines from the listing file describe the library loaded.

FUNCLIBIN trilib tridclib

Function Library trilib
Mod. Function Description
Type
NLP Cosine(x[,MODE]) Cosine: mode=0 (default) -> rad, mode=1 -> grad
NLP Sine(x[,MODE]) Sine : mode=0 (default) -> rad, mode=1 -> grad
any Pi Pi

A description of the libraries included in the GAMS system can be found in Chapter Extrinsic Functions.

Stateful Libraries

While GAMS intrinsic function are stateless, a user can implement stateful extrinsic functions, meaning that the extrinsic
libraries can have some memory. This can be done in two ways:

Library initialization (see Section Piecewise Polynomial Librarty): At initialization time, the function library reads
some data to provide the necessary functions
Previous function calls (see Section Build Your Own: Trigonometric Library Example, function setMode): Function
calls that alter the execution of successive function calls

The latter type of memory is problematic, since different parts of the GAMS system potentially use different instances
of the function library. For example, if one sets SetMode(1) before the solve statement and one uses GAMS option
solvelink<>5 (see SolveLink), the solver runs in a separate process with a new instance of the function library and
therefore uses the default mode, which is 0. Even worse, if solvelink=0 is set, the GAMS process terminates in order to
execute the solve statement and restarts a new GAMSprocess after the solve which again starts up with a fresh function library
instance, so the function library's memory is lost also in this case. The GAMS Test Library model trilib04 demonstrates
this problem.

3.4 Extended Range Arithmetic and Error Handling

GAMS uses an extended range arithmetic to handle missing data, the results of undefined operations, and the representation
of bounds that solver systems regard as infinite. The special symbols are listed in table Table 1 , with the brief explanation of
the meaning of each.
Table 1: Special symbols for extended arithmetic
74 Data Manipulations with Parameters

Special symbol Description mapval

inf Plus infinity. A very large positive number 6
-inf Minus infinity. A very large negative number 7
na Not available. Used for missing data. Any Operation that uses the value NA will produce 5
the result NA
undf Undefined. The result of an undefined or illegal operation. A user cannot directly set a 4
value to UNDF
eps Very close to zero, but different from zero. 8

GAMS has defined the results of all arithmetic operations and all function values using these special values.
The results can be inspected by running the model library problem [CRAZY]. As one would expect, 1+INF evaluates to
INF, and 1-EPS to 1.

Attention
The mapval function should be used in comparisons involving extended range arithmetic. Only the extended range
arithmetic shown in the table above give non-zero values for mapval. For example, mapval(a) takes a value of 6 if a
is inf. All regular numbers result in a mapval of 0.

The following table shows a selection of results for exponentiation and division for a variety of input parameters.
Table 2: Exponentiation and Division

a b ab power(a,b) a/b
2 2 4 4 1
-2 2 undf 4 -1
2 2.1 4.28 undf .952
na 2.5 na na na
3 0 1 1 undf
inf 2 inf inf inf
2 inf undf undf 0

Attention
One should avoid creating or using numbers with absolute values larger than 1.0E20. If a number is too large, it may
be treated by GAMS as undefined (UNDF), and all values derived from it in a model may be unusable. Always use INF
(or -INF) explicitly for arbitrarily large numbers

When an attempted arithmetic operation is illegal or has undefined results because of the value of arguments (division by zero
is the normal example), an error is reported and the result is set to undefined (UNDF).
From there on, UNDF is treated as a proper data value and does not trigger additional error messages.

Attention
GAMS will not solve a model if an error has been detected, but will terminate with an error condition.

It is thus always necessary to anticipate conditions that will cause errors, such as divide by zero. This is most easily done
with the dollar control, and will be discussed in the next section.

4 Summary
GAMS provides powerful facilities for data manipulation with parallel assignment statements, built-in functions and extended
range arithmetic.
Chapter 7

Variables

1 Introduction
This chapter covers the declaration and manipulation of GAMS variables. Many of the concepts covered in the previous
Chapters are directly applicable here.
A variable is the GAMS name for what are called endogenous variables by economists, columns or activities by linear
programming experts, and decision variables by industrial Operations Research practitioners. They are the entities whose
values are generally unknown until after a model has been solved. A crucial difference between GAMSvariables and columns
in traditional mathematical programming terminology is that one GAMSvariable is likely to be associated with many columns
in the traditional formulation.

2 Variable Declarations
A GAMS variable, like all other identifiers, must be declared before it is referenced.

2.1 The Syntax

The declaration of a variable is similar to a set or parameter declaration, in that domain lists and explanatory text are
allowed and recommended, and several variables can be declared in one statement.

[var-type] variable[s] var_name [text] {, var_name [text]}

Var type is the optional variable type that is explained in detail later. Var name is the internal name of the variable (also
called an identifier) in GAMS. An identifier has to start with a letter followed by more letters or digits. It can only contain
alphanumeric characters, and can be up to 63 characters long. The accompanying text is used to describe the set or element
immediately preceding it. This must not exceed 254 characters and must all be contained on the same line as the identifier it
describes.
One important difference between variable and parameter declarations is that values cannot be initialized in a variable
declaration.
A typical variable statement, adapted from [RAMSEY], is shown below for illustration:

variables k(t) capital stock (trillion rupees)

c(t) consumption (trillion rupees per year)
i(t) investment (trillion rupees per year)
utility utility measure ;
76 Variables

The declaration of k above implies, as usual, that references to k are restricted to the domain of the set t. A model that
includes k will probably have several corresponding variables in the associated mathematical programming problem: most
likely one for each member of t. In this way, very large models can be constructed using a small number of variables. (It is
quite unusual for a model to have as many as 50 distinct variables.) It is still unclear from the declaration whether utility
is not domain checked or whether it is a scalar variable, i.e., one without associated sets. Later references will be used to
settle the issue.
It is important that variable declarations include explanatory text and that this be as descriptive as possible, since the text is
used to annotate the solution output. Note the use of 'per' instead of '/' in the text above: slashes are illegal in all unquoted
text.

2.2 Variable Types

There are five basic types of variables that may be used in variable statement. These are shown in table Table 1.
Table 1: Variable types and default bounds

Keyword Description Default Lower Bound Default Upper Bound

free (default) No bounds on variable. Both bounds can be -inf +inf
changed from the default values by the user
positive No negative values are allowed for variable. The 0 +inf
user can change the upper bound from the default
value.
negative No positive values are allowed for variables.The -inf 0
user can change the lower bound from the default
value.
binary Discrete variable that can only take values of 0 or 0 1
1
integer Discrete variable that can only take integer values 0 100
between the bounds. The user can change bounds
from the default value.

The default type is free, which means that if the type of the variable is not specified, it will not be bounded at all. The most
frequently used types are free and positive, for descriptions of variables for which negative values are meaningless, such
as capacities, quantities or prices.
Four additional, although more exotic, variable types - sos1, sos2, semicont and semiint are available in GAMS. These
are explained in Section Types of Discrete Variables .

2.3 Styles for Variable Declaration

Two styles are commonly used to declare variable types. The first is to list all variables with domain specifications and
explanatory text as a group, and later to group them separately as to type. The example shown below is adapted from
[MEXSS]. The default type is free, so phi, phipsi, etc. will be free variables in the example below. Note the use of
variable names derived from the original mathematical representation.

variables
u(c,i) "purchase of domestic materials (mill units per yr)"
v(c.j) "imports (mill tpy)"
e(c,i) "exports (mill tpy)"
phi "total cost (mill us$)"
phipsi "raw material cost (mill us$)" ;
positive variables u, v, e ;

The commas in the list of positive variables are required separators.

3 Variable Attributes 77

Attention
It is possible to declare an identifier more than once, but that the second and any subsequent declarations should only
add new information that does not contradict what has already been entered.

The second popular way of declaring variables is to list them in groups by type. We rewrite the example above using this
second method:

free variables
phi "total cost (mill us$)"
phipsi "raw material cost (mill us$)"

positive variables
u(c,i) "purchase of domestic materials (mill units per yr)"
v(c,j) "imports (mill typ)"
e(c,i) "exports (mill typ)" ;

The choice between the two approaches is best based on clarity.

3 Variable Attributes
Another important difference between parameters and variables is that an additional set of keywords can be used to specify
various attributes of variables. A GAMS parameter has one number associated with each unique label combination. A
variable, on the other hand, has seven. They represent:

Attributes Description
.lo The lower bound for the variable. Set by the user either explicitly or through default values.
.up The upper bound for the variable. Set by the user either explicitly or through default values.
.fx The fixed value for the variable.
.l The activity level for the variable. This is also equivalent to the current value of the variable. Receives new
values when a model is solved.
.m The marginal value (also called dual value) for the variable. Receives new values when a model is solved.
.scale This is the scaling factor on the variable. This is normally an issue with nonlinear programming problems
and is discussed in detail in Section Model Scaling - The Scale Option .
.prior This is the branching priority value of a variable. This parameter is used in mixed integer programming
models only, and is discussed in detail later.

The user distinguishes between these suffix numbers when necessary by appending a suffix to the variable name.

3.1 Bounds on Variables

All default bounds set at declaration time can be changed using assignment statements.

Attention
For binary and integer variable types, the consequences of the type declaration cannot be completely undone.

Bounds on variables are the responsibility of the user. After variables have been declared, default bounds have already been
assigned: for many purposes, especially in linear models, the default bounds are sufficient. In nonlinear models, on the other
hand, bounds play a far more important role. It may be necessary to provide bounds to prevent undefined operations, such as
division by zero.
78 Variables

It is also often necessary to define a 'reasonable' solution space that will help to make the nonlinear programming problem be
solved more efficiently.

Attention
The lower bound cannot be greater than the upper: if you happen to impose such a condition, GAMS will exit with an
error condition.

3.2 Fixing Variables

GAMS allows the user to set variables through the .fx variable suffix. This is equivalent to the lower bound and upper bound
being equal to the fixed value. Fixed variables can subsequently be freed by changing the lower and upper bounds.

3.3 Activity Levels of Variables

GAMS allows the user to fix the activity levels of variables through the .l variable suffix. These activity levels of the variables
prior to the solve statement serve as initial value for the solver. This is particularly important for nonlinear programming
problems.

4 Variables in Display and Assignment Statements

GAMS allows the modeler to use the values associated with the various attributes of each variable in assignment and display
statements. The next two sub-sections explain the use of variables in the left and right hand sides of assignment statements
respectively. Later we will explain the use of variables in display statements.

4.1 Assigning Values to Variable Attributes

Assignment statements operate on one variableattribute at a time, and require the suffix to specify which attribute is being
used. Any index list comes after the suffix.
The following example illustrates the use of assignment statements to set upper bounds for variables.

x.up(c,i,j) = 1000 ; phi.lo = inf ;

p.fx(pellets, ahmsa, mexico-df) = 200 ;
c.l(t) = 4*cinit(t) ;

Note that, in the first statement, the index set covering the domain of x appears after the suffix. The first assignment puts an
upper bound on all variables associated with the identifier x. The statement on the second line bounds one particular entry.
The statement on the last line sets the level values of the variables in c to four times the values in the parameter cinit.
Remember that the order is important in assignments, and notice that the two pairs of statements below produce very different
results. In the first case, the lower bound for c('1985') will be 0.01, but in the second, the lower bound is 1.

c.fx(1985) = 1; c.lo(t) = 0.01 ;

c.lo(t) = 0.01 ; c.fx (1985)= 1 ;

Everything works as described in the previous chapter, including the various mechanisms described there of indexed
operations, dollar operations, subset assignments and so on.
4 Variables in Display and Assignment Statements 79

4.2 Variable Attributes in Assignments

Using variable attributes on the right hand side of assignment statements is important for a variety of reasons. Two common
uses are for generating reports, and for generating initial values for some variables based on the values of other variables.
The following examples, adapted from [CHENERY] illustrate the use of variable attributes on the right hand side of
assignment statements:

scalar cva "total value added at current prices"

rva "real value added"
cli "cost of living index" ;

cva = sum (i, v.l(i)*x.l(i)) ;

cli = sum(i, p.l(i)*ynot(i))/sum(i, ynot(i)) ;
rva = cva/cli ;

display cli, cva, rva ;

As with parameters, a variable must have some non-default data values associated with it before one can use it in a display
statement or on the right hand side of an assignment statement. After a solve statement (to be discussed later) has been
processed or if non-default values have been set with an assignment statement, this condition is satisfied.

Attention
The .fx suffix is really just a shorthand for .lo and .up and can therefore only be used only on the left-hand side of
an assignment statement.

4.3 Displaying Variable Attributes

When variables are used in display statements you must specify which of the six value fields should be displayed. Appending
the appropriate suffix to the variable name does this. As before, no domain specification can appear. As an example we show
how to display the level of phi and the level and the marginal values of v from [MEXSS]:

display phi.l, v.l, v.m;

The output looks similar, except that (of course) the listing shows which of the values is being displayed. Because zeroes,
and especially all zero rows or columns, are suppressed, the patterns seen in the level and marginal displays will be quite
different, since non-zero marginal values are often associated with activity levels of zero.

Mexico Steel - Small Static (MEXSS,SEQ=15)

E x e c u t i o n

---- 203 VARIABLE PHI.L = 538.811 total cost

(mill us$)
---- 203 VARIABLE V.L imports
(mill tpy)
( ALL 0.000 )

---- 203 VARIABLE V.M imports

(mill tpy)
mexico-df monterrey guadalaja
steel 7.018 18.822 6.606

We should mention here a clarification of our previous discussion of displays. It is actually the default values that are
suppressed on display output. For parameters and variable levels, the default is zero, and so zero entries are not shown. For
bounds, however, the defaults can be non-zero. The default value for the upper bound of a positive variable is +INF, and if
above you also would display v.up, for example, you will see:
80 Variables

---- 203 VARIABLE V.UP imports

(mill tpy)
( ALL +INF )

If any of the bounds have been changed from the default value, then only the entries for the changed elements will be shown.
This sounds confusing, but since few users display bounds it has not proved troublesome in practice.

5 Summary
Remember that wherever a parameter can appear in a display or an assignment statement, a variable can also appear - provided
that it is qualified with one of the four suffixes. The only places where a variable name can appear without a suffix is in a
variable declaration, as shown here, or in an equation definition, which is discussed in Chapter Equations.
Chapter 8

Equations

1 Introduction
Equations are the GAMS names for the symbolic algebraic relationships that will be used to generate the constraints in the
model. As with variables, one GAMS equation will map into arbitrarily many individual constraints, depending on the
membership of the defining sets.

2 Equation Declarations
A GAMS equation, like all identifiers, must be declared before it can be used.

2.1 The Syntax

The declaration of an equation is similar to a set or parameter declaration, in that domain lists and explanatory text are
allowed and recommended, and several equations can be declared in one statement.

Equation[s] eqn_name [text] {, eqn_name [text]} ;

Eqn name is the internal name of the equation (an identifier) in GAMS. An identifier has to start with a letter followed by
more letters or digits. It can only contain alphanumeric characters, and can be up to 63 characters long. The accompanying
text is used to describe the set or element immediately preceding it. This must not exceed 254 characters and must all be
contained on the same line as the identifier it describes.
There are no modifying keywords as there are with variables, and no initializing data list as there may be with parameters or
sets.

2.2 An Illustrative Example

The example is adapted from [PRODSCH], an inventory and production management problem. The relevant set definitions
are also shown.

sets q quarters / summer,fall,winter,spring /

s shifts / first,second /;

equations
cost total cost definition
invb(q) inventory balance
sbal(q,s) shift employment balance ;
82 Equations

The declaration of the first equation follows the keyword equations. This declaration begins with the name of the equation,
in this case cost, and is followed by the text, namely 'Total cost definition'. The equation cost above is a scalar
equation, which will produce at most one equation in the associated optimization problem.
By contrast, the equation sbal is declared over the sets q (4 members) and s (2 members), and is thus likely to produce
eight individual equations, one for each unique combination of labels. The circumstances under which less than eight
equations might be produced will be discussed in later chapters. It is certainly true, however, that no more than eight equations
will be produced.

3 Equation Definitions
The definitions are the mathematical specification of the equations in the GAMS language. The next sub-section explain
the syntax for an equation definition and this is followed by an illustrative example. The rest of this section is devoted to
discussions about some of the key components of equation definitions.

3.1 The Syntax

The syntax in GAMS for defining an equation is as follows,

eqn_name(domain_list).. expression eqn_type expression ;

Eqn name is the name of the equation as in the equation declaration. The two dots '..' are always required between the
equation name and start of the algebra. The expressions in the equation definition can be of the forms discussed in the
Chapters before, but can involve variables as well. Eqn type refers to the symbol between the two expressions that form the
equation, and can be of the following types,

Type Description
=e= Equality: rhs must equal lhs
=g= Greater than: lhs must be greater than or equal to rhs
=l= Less than: lhs must be less than or equal to rhs
=n= No relationships enforced between lhs and rhs. This equation type is rarely used.
=x= External equation. Only supported by selected solvers.
=c= Conic constraint. Only supported by selected solvers.

Attention
As with the assignment statement, equation definitions can be carried over as many lines of input as needed.
Blanks can be inserted to improve readability, and expressions can be arbitrarily complicated.
An equation, once defined, can not be altered or re-defined. If one needs to change the logic, a new equation with
a new name will have to be defined. It is possible, however, to change the meaning of an equation by changing the
data it uses, or by using exception handling mechanisms (dollar operations) built into the definition

3.2 An Illustrative Example

Consider the following example, adapted from [MEXSS]. The associated declarations are also included.

Variables phi, phipsi, philam, phipi, phieps ;

equations obj ;
obj.. phi =e= phipsi + philam + phipi - phieps ;
3 Equation Definitions 83

Obj is the name of the equation being defined. The =e= symbol means that this is an equality. Any of the following forms of
the equation are mathematically equivalent,

obj.. phipsi + philam + phipi - phieps =e= phi ;

obj.. phieps - phipsi =e= philam - phi + phipi ;
obj.. phi - phieps - phipsi - philam - phipi =e= 0 ;
obj.. 0 =e= phi - phieps - phipsi - philam - phipi ;

Attention
The arrangement of the terms in the equation is a matter of choice, but often a particular one is chosen because it makes
the model easier to understand.

3.3 Scalar Equations

A scalar equation will produce at most one equation in the associated optimization problem. The equation defined in the last
Section is an example of a scalar equation, which contains only scalar variables. Note that in general, scalar equations may
contain indexed variables operated on by index operators. Consider the following example from [CHENERY].

dty.. td =e= sum(i, y(i)) ;

3.4 Indexed Equations

All the set references in scalar equations are within the scope of index operations - many references can therefore be
included in one equation. However, GAMS allows for equations to be defined over a domain, thereby developing a compact
representation for constraints. The index sets to the left of the '..' are called the domain of definition of the equation.

Attention
Domain checking ensures that the domain over which an equation is defined must be the set or a subset of the set over
which the equation is declared.

Consider the following example of a singly indexed equation, meaning one that produces a separate constraint for each
member of the driving (or controlling) set.

dg(t).. g(t) =e= mew(t) + xsi(t)*m(t) ;

As t has three members, three constraints will be generated , each one specifying separately for each member of t, the
dependence of g on m. Mew and xsi are parameters: the data associated with them are used in building up the individual
constraints. These data do not have to be known when the equation is defined, but do have to be when a model containing the
equation is solved.
The extension to two or more index positions on the left of the '..' should be obvious. There will be one constraint generated
for each label combination that can constructed using the indices inside the parenthesis. Here are two examples from
[AIRCRAFT], a scheduling model.

bd(j,h).. b(j,h) =e= dd(j,h) - y(j,h) ;

yd(j,h).. y(j,h) =l= sum(i, p(i,j)*x(i,j)) ;

The domain of definition of both equations is the Cartesian product of j and h: constraints will be generated for every label
pair that can be constructed from the membership of the two sets.
84 Equations

3.5 Using Labels Explicitly in Equations

It is often necessary to use labels explicitly in equations. This can be done as with parameters - by using quotes around the
label. Consider the following example,

dz.. tz =e= y(jan) + y(feb) + y(mar) + y(apr) ;

4 Expressions in Equation Definitions

The arithmetic operators and functions that were described in Section Expressions , can be used inside equations as well.

4.1 Arithmetic Operators in Equation Definitions

Attention
All the mechanisms that may be used to evaluate expressions in assignments are also available in equations.

Consider the following example adapted from [CHENERY] showing parentheses and exponentiation,

dem(i) .. y(i) =e= ynot(i)*(pd*p(i))**thet(i) ;

4.2 Functions in Equation Definitions

Function references in equation definitions can be classified into two types based on the type of the arguments,

1. Exogenous arguments: The arguments(s) are known. Parameters and variable attributes (for example, .l and .m
attributes) are used as arguments. The expression is evaluated once when the model is being set up, and all functions
except the random distribution functions uniform and normal are allowed.
2. Endogenous arguments: The arguments are variables and therefore unknown. The function will be evaluated many
times at intermediate points while the model is being solved.

Attention
The occurrence of any function with endogenous arguments implies that the model is not linear.
It is forbidden to use the uniform and normal functions in an equation definition.

Functions with endogenous arguments can be further classified into types listed in Table 1 .
Table 1: Classification of functions with endogenous arguments

Type Function Derivative Examples

Smooth Continuous Continuous exp, sin, log
Non-Smooth Continuous Discontinuous max, min, abs
Discontinuous Discontinuous Discontinuous ceil, sign

Smooth functions can be used routinely in nonlinear models, but non-smooth ones may cause numerical problems and
should be used only if unavoidable, and only in a special model type called dnlp. However, the use of the dnlp model type
is strongly discouraged and the use of binary variables is recommended to model non-smooth functions. Discontinuous
functions are not allowed at all with variable arguments.
5 Data Handling Aspects of Equations 85

A fuller discussion is given in Chapter Model and Solve Statements . For convenience, all the available functions are classified
in Section Functions.

4.3 Preventing Undefined Operations in Equations

Certain operations can be undefined at particular values for the arguments. For example, the log-function is undefined
when the argument is 0. Division by 0 is another example. While this can easily be determined for exogenous functions and
expressions, it is a lot more difficult when the operands are variables. The expression may be evaluated many times when
the problem is being solved. One way of preventing an expression from becoming undefined at all intermediate points is
by adding bounds to the variable concerned. Consider the following function reference from [RAMSEY], preceded by the
bounding of the variables:

c.lo(t) = 0.01 ;
util .. utility =e= sum(t, beta(t)*log(c(t))) ;

The bounding on c(t) away from 0 prevents the log function from being undefined.

5 Data Handling Aspects of Equations

The previous section dealt with the algebraic nature of equations. This section deals with the other aspect of an equation - it
also serves as data. As with variables, four data values are associated with each unique label-tuple (unique label combination)
of every equation. In practice these are used mainly for reporting purposes after a solve, and so the discussion will be brief.
The suffixes associated with the four values are .l, .m, .lo and .up, as with variables. They may be assigned values in
assignments (this is rare), or referenced in expressions or displayed, which is more common, especially for the marginal, .m.
The meanings of the attributes .lo, .l and .up will be described with respect to an individual constraint rather than the
symbolic equation.
After a solution has been obtained, there is a value associated with the unknown terms on the left, and this is by definition
.l. The meaning of .lo and .up are shown in table Table 2 in terms of the constant right-hand-side (rhs) and the variable
left-hand-side (.l) for each of the equation types. The relationship between rhs and .l is satisfied only if the constraint is
feasible at the solution point.
Table 2: Subfield definitions for equations

Type .lo .up .l

=e= rhs rhs rhs
-inf rhs rhs
=l=
=g= rhs inf rhs
=n= -inf inf any

The meaning of the marginal value (.m) in terms of the objective value is discussed in detail in most texts on mathematical
programming. The crude but useful definition is that it is the amount by which the objective function would change if the
equation level were moved one unit.
86 Equations
Chapter 9

Model and Solve Statements

1 Introduction
This chapter brings together all the concepts discussed in previous chapters by explaining how to specify a model and solve it.

2 The Model Statement

The model statement is used to collect equations into groups and to label them so that they can be solved. The simplest form
of the model statement uses the keyword all: the model consists of all equations declared before the model statement is
entered. For most simple applications this is all you need to know about the model statement.

2.1 The Syntax

In general, the syntax in GAMS for a model declaration is:

model[s] model_name [text] [/ all | eqn_name {, eqn_name} /]

{,model_name [text] [/ all | eqn_name {, eqn_name} /]} ;

Model name is the internal name of the model (also called an identifier) in GAMS . The accompanying text is used to
describe the set or element immediately preceding it. Eqn name is the name of an equation that has been declared prior to the
model statement.
As with all identifiers, model name has to start with a letter followed by more letters or digits. It can only contain
alphanumeric characters, and can be up to 63 characters long. Explanatory text must not exceed 80 characters and must all be
contained on the same line as the identifier or label it describes.
An example of a model definition in GAMS is shown below.

Model transport "a transportation model" / all / ;

The model is called transport and the keyword all is a shorthand for all known (declared) equations.
Several models can be declared (and defined) in one model statement. This is useful when experimenting with different ways
of writing a model, or if one has different models that draw on the same data. Consider the following example, adapted from
[PROLOG], in which different groups of the equations are used in alternative versions of the problem. Three versions are
solved the linear, nonlinear, and 'expenditure' versions. The model statement to define all three is

model nortonl "linear version" / cb,rc,dfl,bc,obj /

nortonn "nolinear version" / cb,rc,dfn,bc,obj /
nortone "expenditure version / cb,rc,dfe,bc,obj / ;
88 Model and Solve Statements

where cb, rc, etc. are the names of the equations. We will describe below how to obtain the solution to each of the three
models.

2.2 Classification of Models

Various types of problems can be solved with GAMS. The type of the model must be known before it is solved. The model
types are briefly discussed in this section. GAMS checks that the model is in fact the type the user thinks it is, and issues
explanatory error messages if it discovers a mismatch - for instance, that a supposedly linear model contains nonlinear terms.
This is because some problems can be solved in more than one way, and the user has to choose which way to go. For instance,
if there are binary or integer variable in the model, it can be solved either as a MIP or as a RMIP.
The problem type and their identifiers, which are needed in the a solve statement, are listed below.

Problem Type Description

Linear programming. There are no nonlinear terms or discrete (binary or integer) variables in your
LP
model.
Quadratic constraint programming. There are linear and quadratic terms but no general nonlinear term
QCP
or discrete (binary or integer) variables in your model.
Nonlinear programming. There are general nonlinear terms involving only smooth functions in the
NLP
model, but no discrete variables. The functions were classified as to smoothness in the previous chapter.
Nonlinear programming with discontinuous derivatives. This is the same as NLP, except that non-
DNLP
smooth functions can appear as well. These are more difficult to solve than normal NLP problems. The
user is strongly recommended not to use this model type.
Relaxed mixed integer programming. The model can contain discrete variables but the discrete
RMIP
requirements are relaxed, meaning that the integer and binary variables can assume any values between
their bounds.
Mixed integer programming. Like RMIP but the discrete requirements are enforced: the discrete
MIP
variables must assume integer values between their bounds.
Relaxed mixed integer quadratic constraint programming. The model can contain both discrete variables
RMIQCP
and quadratic terms. The discrete requirements are relaxed. This class of problem is the same as QCP
in terms of difficulty of solution.
Relaxed mixed integer nonlinear programming. The model can contain both discrete variables and
RMINLP
general nonlinear terms. The discrete requirements are relaxed. This class of problem is the same as
NLP in terms of difficulty of solution.
Mixed integer quadratic constraint programming. Characteristics are the same as for RMIQCP, but the
MIQCP
discrete requirements are enforced.
Mixed integer nonlinear programming. Characteristics are the same as for RMINLP, but the discrete
MINLP
requirements are enforced.
Relaxed Mathematical Programs with Equilibrium Constraints.
RMPEC
Mathematical Programs with Equilibrium Constraints.
MPEC
Mixed Complementarity Problem.
MCP
Constrained Nonlinear System.
CNS
Extended Mathematical Program.
EMP
2 The Model Statement 89

Constrained Nonlinear Systems

Mathematically, a Constrained Nonlinear System (CNS) model looks like:

find x

F(x) = 0 (9.1)
subject to L x U
G(x) b
where F and x are of equal dimension and the variables x are continuous. The (possibly empty) constraints L x U are
not intended to be binding at the solution, but instead are included to constrain the solution to a particular domain or to
avoid regions where F(x) is undefined. The (possibly empty) constraints G(x) b are intended for the same purpose and are
silently converted to equations with bounded slacks.
The CNS model is a generalization of the square system of equations F(x) = 0. There are a number of advantages to using
the CNS model type (compared to solving as an NLP with a dummy objective, say), including:
A check by GAMS that the model is really square,
solution/model diagnostics by the solver (e.g. singular at solution, locally unique solution),
and potential improvement in solution times, by taking better advantage of the model properties.
The CNS model class is solved with a solve statement of the form:

SOLVE <MODEL> USING CNS;

without the usual objective term. The CNS solver can be selected during installation or with the usual OPTION CNS =
Solver;statement.
For information on CNS solvers that can be used through GAMS see the Solver/Model type Matrix.
Solve Status values
A CNS solver will return one of the following solver status values:

Status Value Meaning

Solverstat = 1 Normal completion
Solverstat = 2 Iteration Interrupt
Solverstat = 3 Resource Interrupt
Solverstat = 5 Evaluation Error Limit
Solverstat = 8 User Interrupt

where the definitions are the same as for other model classes. The CNS solver will return one of the following model status
values:

Status Value Meaning and Description

Modelstat = 15 Solved Unique : The model was solved and the solution is globally unique.
Modelstat = 16 Solved : The model was solved.
Modelstat = 17 Solved Singular : The model was solved, but the Jacobian is singular.
Modelstat = 4 Infeasible : The model is guaranteed to have no solution, for example because the model or a critical
subset of the model is linear and inconsistent.
Modelstat = 5 Locally infeasible : The model could not be solved. The word locally indicates that the solver
has not determined that no solution could exist, as compared to the global infeasibility implied by
Modelstat=4.
Modelstat = 6 Intermediate infeasible : The solver was stopped by an iteration, resource, or evaluation error limit
or by a user interrupt.
90 Model and Solve Statements

Additional comments
Some special comments relating to CNS models apply:
There is no objective and therefore no marginal values, either for variables or for equations. The solution
listing will therefore not have the MARGINAL column. Any marginal values already stored in the GAMS
database will remain untouched.
A singular model flags a set of linearly dependent rows and columns with DEPND in the solution listing.
The number of dependencies reported is made available by GAMS via the <model>.numdepnd model
attribute. This can be tested in the usual way. Note that a row/column pair for a linear dependence
contributes one to numdepnd. Also note that there may be more linear dependencies than the ones reported.
An infeasible or locally infeasible model, or a singular model with infeasibilities, flags the infeasible
constraints and variables with the usual INFES flag. The number of infeasibilities is available via the usual
<model>.numinfes model attribute.

Nonlinear Programming with Discontinuous Derivatives

Mathematically, the Nonlinear Programming with Discontinuous Derivatives (DNLP) Problem looks like:
Minimize f (x)

st g(x) 0
L x U

where x is a vector of variables that are continuous real numbers. f (x) is the objective function, and g(x) represents the
set of constraints. L and U are vectors of lower and upper bounds on the variables. This is the same as NLP , except that
non-smooth functions (abs, min,max) can appear in f (x) and g(x).
For information on DNLP solvers that can be used through GAMS see the Solver/Model type Matrix.

Linear Programming

Mathematically, the Linear Programming (LP) Problem looks like:

Minimize or maximize cx
subject to Ax b
L x U

where x is a vector of variables that are continuous real numbers. cx is the objective function, and Ax b represents the set of
constraints. L and U are vectors of lower and upper bounds on the variables.
GAMS supports both free variables (unrestricted), positive variables, and negative variables. In addition user specified lower
and upper bounds can be provided.
In a GAMS model equations are specified as a combination of less-than-or-equal-to or greater-than-or-equal-to inequalities
and equalities (equal-to constraints).
For information on LP solvers that can be used through GAMS see the Solver/Model type Matrix.

Mixed Complementarity Problem

Mathematically, the Mixed Complementarity Problem (MCP) looks like:

Find z, w, v
such that F(z) = w v
l z u, w 0, v 0
w0 (z l) = 0, v0 (u z) = 0
2 The Model Statement 91

MCP's are a class of mathematical programs which can be formulated in GAMS and solved by one of the MCP solvers that
are hooked up to GAMS: see the Solver/Model type Matrix.
MCP's arise in many application areas including applied economics, game theory, structural engineering and chemical
engineering.
Complementarity problems are easily formulated in the GAMS language. The only additional requirement beyond general
NLP's is the definition of complementarity pairs.
MCP's constitute a fairly general problem class. It encompasses systems of nonlinear equations, non-linear complementarity
problems and finite dimensional variational inequalities. Also inequality-constrained linear, quadratic and nonlinear programs
are MCP's (although for these problems you may expect specialized solvers to do better). For instance, when we set the lower
bounds l to minus infinity and u to plus infinity, both w and v have to be zero. This results in the problem

Find z
such that F(z) = 0
which is a system of non-linear equations.

Mixed Integer Nonlinear Programming

Mathematically, the Mixed Integer Nonlinear Programming (MINLP) Problem looks like:
Minimize f (x) + Dy
st g(x) + Hy 0
L x U
y = {0, 1, 2, }

where x is a vector of variables that are continuous real numbers. f (x) + Dy is the objective function, and g(x) + Hy represents
the set of constraints. L and U are vectors of lower and upper bounds on the variables.
For information on MINLP solvers that can be used through GAMS see the Solver/Model type Matrix.

Mixed Integer Programming

Mathematically, the Mixed Integer Linear Programming (MIP) Problem looks like:

Minimize cx + dy
st Ax + By b
L x U
y = {0, 1, 2, }

where x is a vector of variables that are continuous real numbers, and y is a vector in variables that can only take integer
values. cx + dy is the objective function, and Ax + By b represents the set of constraints. L and U are vectors of lower and
upper bounds on the continuous variables, and y = {0, 1, 2, } is the integrality requirement on the integer variables y.
For information on MIP solvers that can be used through GAMS see the Solver/Model type Matrix.

Mathematical Program with Equilibrium Constraints

Mathematically, the Mathematical Program with Equilibrium Constraints (MPEC) Problem looks like:
Maximize or Minimize f (x, y)
subject to g(x, y) 0
Lx x Ux
F(x, y) perp to Ly y Uy

where x and y are vectors of continuous real variables. The variables x are often called the control or upper-level variables,
while the variables y are called the state or lower-level variables. f (x, y) is the objective function. g(x, y) represents the set of
92 Model and Solve Statements

traditional (i.e. NLP-type) contraints; in some cases, they can only involve the control variables x. The function F(x, y) and
the bounds Ly and Uy define the equilibrium constraints. If x is fixed, then F(x, y) and the bounds Ly and Uy define an MCP;
the perp-to indicates that such a complementary relationship holds. From this definition, we see that the MPEC model type
contains NLP and MCP models as special cases of MPEC.
While the MPEC model formulation is very general, it also results in problems that are very difficult to solve. Work on
MPEC algorithms is not nearly so advanced as that for the other model types. As a result, the MPEC solvers included in the
GAMS distribution are experimental or beta versions.
For information on MPEC solvers that can be used through GAMS see the Solver/Model type Matrix.

Nonlinear Programming

Mathematically, the Nonlinear Programming (NLP) Problem looks like:

Minimize f (x)
st g(x) 0
L x U

where x is a vector of variables that are continuous real numbers. f (x) is the objective function, and g(x) represents the set of
constraints. L and U are vectors of lower and upper bounds on the variables.
For information on NLP solvers that can be used through GAMS see the Solver/Model type Matrix.

Quadratically Constrained Programs

A Quadratically Constrained Program (QCP) is a special case of the NLP in which all the nonlinearities are required to be
quadratic. As such, any QCP model can also be solved as an NLP. However, most LP vendors provide routines to solve LP
models with a quadratic objective. Some allow quadratic constraints as well. Solving a model using the QCP model type
allows these LP solvers to be used to solve quadratic models as well as linear ones. Some NLP solvers may also take
advantage of the special (quadratic) form when solving QCP models. In case a model with quadratic constraints is passed to
a QCP solver that only allows a quadratic objective, a capability error (solver status 6 CAPABILITY PROBLEMS) will be
returned.
For information on QCP solvers that can be used through GAMS see the Solver/Model type Matrix.

Mixed Integer Quadratically Constrained Programs

A Mixed Integer Quadratically Constrained Program (MIQCP) is a special case of the MINLP in which all the nonlinearities
are required to be quadratic. For details see the description of the QCP, a special case of the NLP.
For information on MIQCP solvers that can be used through GAMS see the Solver/Model type Matrix.

2.3 Model Attributes

Model attributes can be accessed through

model_name.attribute

Some of the attributes are mainly used before the solve statement to provide information to GAMS or the solver link. Others
are set by GAMS or the solver link and hence are mainly used after a solve statement.
Moreover, some of the input attributes can also be set globally via an option statement or the command line, e.g.

option reslim = 10
gamsmodel.gms reslim = 10
2 The Model Statement 93

Note that a model specific option takes precedence over the global setting and that a setting via an option statement takes
precedence over one via the command line parameter.
The complete list of model attributes is shown below. The third and fourth column indicate whether there is also a global
option and/or a command line parameter.

Model Attributes mainly used before solve

Attribute Description option command

bRatio Basis acceptance test. A bratio of 0 accepts any basis, and a bratio of 1 always x x
rejects the basis.
cheat Cheat value. Requires a new integer solution to be a given amount better than the
current best integer solution. Default value is 0.
Cutoff value. Occasionally used attribute that causes MIP solvers to delete parts
cutOff
of the branch and bound tree with an objective worse than the numerical value of
the cutoff attribute.
dictFile Force writing of a dictionary file if dictfile > 0
domLim Maximum number of domain errors. This attribute allows errors to occur up to a x x
given number during solution. Default value is 0.
holdFixed This attribute can reduce the problem size by treating fixed variables as constants. x
Allowable values are:
0: fixed variables are not treated as constants (default)
1: fixed variables are treated as constants

integer1 Integer communication cell that can contain any integer number. x x
integer2 Integer communication cell that can contain any integer number. x x
integer3 Integer communication cell that can contain any integer number. x x
integer4 Integer communication cell that can contain any integer number. x x
integer5 Integer communication cell that can contain any integer number. x x
iterLim Iteration limit. The solvers will interrupt the solution process when the iteration x x
count reaches that limit. The default value is 2 billion.
limCol Maximum number of cases written to the LST file for each named variable in a x x
model. The default value is 3.
limRow Maximum number of cases written to the LST file for each named equation in a x x
model. The default value is 3.
MCPRHoldfx This attribute can be set to print a list of rows that are perpendicular to variables x x
removed due to the holdfixed setting when solvin an MCP. Allowable values are:
0: do not print the list (default)
1: print the list

nodLim Node limit. This attribute specifies the maximum number of nodes to process x
in the branch and bound tree for a MIP problem. The default value is 0 and is
interpreted as 'not set'.
optCA Absolute optimality criterion. This attribute specifies an absolute termination x x
tolerance for use in solving all mixed-integer models. The default value is 0.
optCR Relative optimality criterion. This attribute specifies a relative termination toler- x x
ance for use in solving all mixed-integer models. The default value is 0.1.
94 Model and Solve Statements

Attribute Description option command

optFile Look for a solver options file if optFile > 0. The value of optfiledetermines x
which option file is used:
If Optfile = 1 the option file solvername.opt will be used.
If Optfile = 2 the option file solvername.op2 will be used.
If Optfile = 3 the option file solvername.op3 will be used.
If Optfile = 15 the option file solvername.o15 will be used.
If Optfile = 222 the option file solvername.222 will be used.
If Optfile = 1234 the option file solvername.1234 will be used.
If Optfile = 0 no option file will be used. (default)

Priority option. Variables in mixed integer programs can have a priority attribute.
priorOpt
One can use this parameter to specify an order for picking variables to branch on
during a branch and bound search for MIP model solutions. The default value is
0 in which case priorities will not be used.
real1 Real communication cell that can contain any real number. x
real2 Real communication cell that can contain any real number. x
real3 Real communication cell that can contain any real number. x
real4 Real communication cell that can contain any real number. x
real5 Real communication cell that can contain any real number. x
reform Reformulation level. x
resLim Maximum time available in wall clock seconds to solve in seconds. The default x x
value is 1000.
savePoint This parameter tells GAMS to save a point format GDX file that contains the x x
information on the current solution point. One can save the solution information
from the last solve or from every solve. Numeric input with the following values
is expected:
0: no point gdx file is to be saved
1: a point gdx file called model name p.gdxis to be saved from the
last solve in the GAMS model
2: a point gdx file called model name pnn.gdx is to be saved from
every solve in the GAMS model, where nnis the solve number as
determined internally by GAMS

scaleOpt This attribute tells GAMS whether to employ user specified variable and equation
scaling factors. It must be set to a nonzero value if the scaling factors are to be
used.
solPrint This attribute controls the printing of the model solution to the LST x x
file. Note that the corresponding option expects a text, while the use of
model name.solPrintand the command line expect a numeric value. Allowed
are:
0/Off: remove solution listings following solves
1/On: include solution listings following solves
2/Silent: suppress all solution information
The default value is 1 respectively 'On'.
2 The Model Statement 95

Attribute Description option command

solveLink This attribute controls GAMS function when linking to solve. Allowable values x x
are:
0: GAMS operates as always (default)
1: the solver is called from a shell and GAMS remains open
2: the solver is called with a spawn (if possible as determined by
GAMS) or a shell (if the spawn is not possible) and GAMS remains
open
3: GAMS starts the solution and continues in a Grid computing
environment
4: GAMS starts the solution and waits (same submission process as
3) in a Grid computing environment
5: the problem is passed to the solver in core without use of tempo-
rary files
6: the problem is passed to the solver in core without use of tempo-
rary files, GAMS does not wait for the solver to come back
7: the problem is passed to the solver in core without use of tempo-
rary files, GAMS waits for the solver to come back but uses same
submission process as 6

solveOpt This attribute tells GAMS how to manage the model solution when only part of the x
variables and equations are in the particular problem being solved. Note that the
corresponding option expects a text, while the use of model name.solveOptand
the command line expect a numeric value. Allowed are:
0/replace: the solution information for all equations appearing in the
model is completely replaced by the new model results; variables are
only replaced if they appear in the final model
1/merge: the solution information for all equations and variables is
merged into the existing solution information; (default)
2/clear: the solution information for all equations appearing in the
model is completely replaced; in addition, variables appearing in the
symbolic equations but removed by conditionals will be removed
There is an example called 'solveopt' in the model library.

sysOut This attribute controls the incorporation of additional solver generated output x x
(that in the solver status file) to the LST file. Note that the corresponding option
expects a text, while the use of model name.solPrintand the command line
expect a numeric value. Allowed are:
0/Off: suppress additional solver generated output (default)
1/On: include additional solver generated output

threads This attribute controls the number of threads or CPU cores to be used by a solver. x x
Allowable values are:
-n: number of cores to leave free for other tasks
0: use all available cores
n: use n cores (will be reduced to the available number of cores if n
is too large)

tolInfeas Infeasibility tolerance for an empty row of the form a.. 0x =e= 0.0001;.
If not set, a tolerance of 10 times the machine precision is used. Empty rows
failing this infeasibility check are flagged with the listing file message 'Equation
infeasible due to rhs value'.
tolInfRep This attribute sets the tolerance for marking infeasible in the equation listing. The
default value is 1.0e-6.
96 Model and Solve Statements

Attribute Description option command

tolProj This attribute controls the tolerance for filtering marginals (i.e.setting marginals
within the tolerance to 0) and projecting levels to the lower or upper bound that
are within the tolerance when reading a solution, default is 1e-8.
tryInt Signals the solver to make use of a partial or near-integer-feasible solution stored
in current variable values to get a quick integer-feasible point. If or how tryint is
used is solver-dependent.
tryLinear Examine empirical NLP model to see if there are any NLP terms active.
If there are none the default LP solver will be used. To activate use
model name.trylinear=1. Default value is 0. The procedure also checks
to see if QCP, and DNLP models can be reduced to an LP; MIQCP and MINLP
can be solved as an MIP; RMIQCP and RMINLP can be solved as an RMIP.
workFactor This attribute tells the solver how much workspace to allocate for problem solution x
relative to the GAMS estimate.
workSpace This attribute tells the solver how much workspace in Megabytes to allocate for x
problem solution.

Model Attributes mainly used after solve

Attribute Description
domUsd Number of domain violations.
etAlg This attribute returns the elapsed time it took to execute the solve algorithm. The time does not include
the time to generate the model, reading and writing of files etc. The time is expressed in seconds of
wall-clock time.
etSolve This attribute returns the elapsed time it took to execute a solve statement in total. This time includes the
model generation time, time to read and write files, time to create the solution report and the time taken
by the actual solve. The time is expressed in seconds of wall-clock time.
etSolver This attribute returns the elapsed time taken by the solver only. This does not include the GAMS model
generation time and time taken to report and load the solution back into the GAMS database. The time is
expressed in seconds of wall-clock time.
handle Every solve gets unique handle number that may be used by handlecollect, handlestatus or handledelete.
See Chapter The Grid and Multi-Threading Solve Facility .
iterUsd Number of iterations used.
line Line number of last solve of the corresponding model
linkUsed Integer number that indicates the value of solveLink used for the last solve
maxInfes Max of infeasibilities
meanInfes Mean of infeasibilities
modelStat Model status. Range from 1 to 19. For details check Section Model Status.
nodUsd The number of nodes used by the MIP solver.
number Model instance serial number. The first model solved gets number 1, the second number 2 etc. The user
can also set a value and the next model solved will get value+1 as number.
numDepnd Number of dependencies in a CNS model.
numDVar Number of discrete variables.
numEqu Number of equations.
numInfes Number of infeasibilities.
numNLIns Number of nonlinear instructions.
numNLNZ Number of nonlinear nonzeros.
numNOpt Number of nonoptimalities.
numNZ Number of nonzero entries in the model coefficient matrix.
numRedef Number of MCP redefinitions.
3 The Solve Statement 97

Attribute Description
numVar Number of variables.
numVarProj Number of bound projections during model generation.
objEst The estimate of the best possible solution for a mixed-integer model.
objVal The objective function value.
procUsed Integer number that indicates the used model type. Possible values are:
1: LP
2: MIP
3: RMIP
4: NLP
5: MCP
6: MPEC
7: RMPEC
8: CNS
9: DNLP
10: RMINLP
11: MINLP
12: QCP
13: MIQCP
14: RMIQCP
15: EMP

resGen Time GAMS took to generate the model in CPU seconds.

resUsd Time the solver used to solve the model in CPU seconds.
rObj The objective function value from the relaxed solve of a mixed-integer model when the integer solver did
not finish.
solveStat This model attribute indicates the solver termination condition. Range from 1 to 13. For details check
Section The Solve Summary .
sumInfes Sum of infeasibilities.

3 The Solve Statement

Once the model has been put together through the model statement, one can now attempt to solve it using the solve statement.
On seeing this statement, GAMS calls one of the available solvers for the particular model type.

Attention
It is important to remember that GAMS itself does not solve your problem, but passes the problem definition to one of
a number of separate solver programs.

The next few sub-sections discuss the solve statement in detail.

3.1 The Syntax

In general, the syntax in GAMS for a model declaration is:

solve model_name using model_type maximizing|minimizing var_name|;

solve model_name maximizing|minimizing var_name using model_type ;

Model name is the name of the model as defined by a model statement. Var name is the name of the objective variable that
is being optimized. Model type is one of the model types described before. An example of a solve statement in GAMS is
shown below.
98 Model and Solve Statements

Solve transport using lp minimizing cost ;

Solve and using are reserved words.Transport is the name of the model, lp is the model type, minimizing is the
direction of optimization, and cost is the objective variable. The opposite of minimizing is maximizing , both reserved
words. Note that an objective variable is used instead of an objective row or function

Attention
The objective variable must be scalar and of type free, and must appear in at least one of the equations in the model.

The next two sub-sections will describe briefly below what happens when a solve statement is processed, and more details on
how the resulting output is to be interpreted will be given in the next chapter. After that sequences of solve statements will be
discussed. The final section will describe options that are important in controlling solve statements.

3.2 Requirements for a Valid Solve Statement

Requirements for a Valid Solve Statement When GAMS encounters a solve statement, the following are verified:

1. All symbolic equations have been defined and the objective variable is used in at least one of the equations
2. The objective variable is scalar and of type free
3. Each equation fits into the specified problem class (linearity for lp, continuous derivatives for nlp, as we outlined
above)
4. All sets and parameters in the equations have values assigned.

3.3 Actions Triggered by the Solve Statement

The solve statement triggers a sequence of steps that are as follows:

1. The model is translated into the representation required by the solution system to be used.
2. Debugging and comprehension aids are produced and written to the output file (EQUATION LISTING, etc).
3. GAMS verifies that there are no inconsistent bounds or unacceptable values (for example NA or UNDF) in the problem.
4. Any errors detected at this stage cause termination with as much explanation as possible, using the GAMS names for
the identifiers causing the trouble.
5. GAMS passes control to the solution subsystem and waits while the problem is solved.
6. GAMS reports on the status of the solution process and loads solution values back into the GAMS database. This
causes new values to be assigned to the .l and .m fields for all individual equations and variables in the model. A row
by row and column by column listing of the solution is provided by default. Any apparent difficulty with the solution
process will cause explanatory messages to be displayed. Errors caused by forbidden nonlinear operations are reported
at this stage.

The outputs from these steps, including any possible error messages, are discussed in detail in Chapter GAMS Output.

4 Programs with Several Solve Statements

Several solve statements can be processed in the same program. If you have to solve sequences of expensive or difficult
models, you should read the chapter on workfiles to find out how to interrupt and continue program execution. The next few
sub-sections discuss various instances where several solve statements may be needed in the same file.
4 Programs with Several Solve Statements 99

4.1 Several Models

If there are different models then the solves may be sequential, as below. Each of the models in [PROLOG] from gamslib
consists of a different set of equations, but the data are identical, so the three solves appear in sequence with no intervening
assignments:

solve nortonl using nlp maximizing z;

solve nortonn using nlp maximizing z;
solve nortone using nlp maximizing z;

When there is more than one solve statement in your program, GAMS uses as much information as possible from the
previous solution to provide a starting point in the search for the next solution.

4.2 Sensitivity or Scenario Analysis

Multiple solve statements can be used not only to solve different models, but also to conduct sensitivity tests, or to perform
case (or scenario) analysis of models by changing data or bounds and then solving the same model again. While some
commercial LP systems allow access to sensitivity analysis through GAMS it is possible to be far more general and not
restrict the analysis to either solver or model type. This facility is even more useful for studying many scenarios since no
commercial solver will provide this information.
An example of sensitivity testing is in the simple oil-refining model [MARCO]. Because of pollution control, one of the key
parameters in oil refinery models is an upper bound on the sulfur content of the fuel oil produced by the refinery. In this
example, the upper bound on the sulfur content of the fuel oil produced in the refinery. In this example, the upper bound on
the sulfur content of fuel oil was set at 3.5 percent in the original data for the problem. First the model is solved with this
value. Next a slightly lower value of 3.4 percent is used and the model is solved again. Finally, the considerably higher value
of 5 percent is used and the model is solved for the last time. After each solve, key solution values (the activity levels are
associated with z, the process levels by process p and by crude oil type cr) are saved for later reporting. This is necessary
because a following solve replaces any existing values. The complete sequence is :

parameter report(*,*,*) "process level report" ;

qs(upper,fuel-oil,sulfur) = 3.5 ;
solve oil using lp maximizing phi;
report(cr,p,base) = z.l(cr,p) ;

report(sulfur,limit,base) = qs(upper,fuel-oil,sulfur);
qs (upper,fuel-oil,sulfur) = 3.4 ;
solve oil using lp maximizing phi ;
report(cr,p,one) = z.l(cr,p) ;
report(sulfur,limit,one) = qs (upper,fuel-oil,sulfur);

qs(upper,fuel-oil,sulfur) = 5.0 ;
solve oil using lp maximizing phi ;
report(cr,p,two) = z.l(cr,p) ;
report(sulfur,limit,two) = qs(upper,fuel-oil,sulfur);

display report ;

This example shows not only how simply sensitivity analysis can be done, but also how the associated multi-case reporting
can be handled. The parameter qs is used to set the upper bound on the sulfur content in the fuel oil, and the value is
retrieved for the report.
The output from the display is shown below. Notice that there is no production at all if the permissible sulfur content is
lowered. The case attributes have been listed in the row SULFUR.LIMIT. The wild card domain is useful when generating
reports: otherwise it would be necessary to provide special sets containing the labels used in the report. Any mistakes made
100 Model and Solve Statements

in spelling labels used only in the report should be immediately apparent, and their effects should be limited to the report.
Section Global Display Controls , contains more detail on how to arrange reports in a variety of ways.

----- 205 PARAMETER REPORT PROCESS LEVEL REPORT

BASE ONE TWO

MID-C .A-DIST 89.718 35.139
MID-C .N-REFORM 20.000 6.772
MID-C .CC-DIST 7.805 3.057
W-TEX .CC-GAS-OIL 5.902
W-TEX .A-DIST 64.861
W-TEX .N-REFORM 12.713
W-TEX .CC-DIST 4.735
W-TEX .HYDRO 28.733
SULFUR.LIMIT 3.500 3.400 5.000

4.3 Iterative Implementation of Non-Standard Algorithms

Another use of multiple solve statements is to permit iterative solution of different blocks of equations, solution values from
the first are used as data in the next. These decomposition methods are useful for certain classes of problems because the
sub-problems being solved are smaller, and therefore more tractable. One of the most common examples of such a method is
the Generalized Bender's Decomposition method.
An example of a problem that is solved in this way is an input-output system with endogenous prices, described in Henaff
(1980) 1 . The model consists of two groups of equations. The first group uses a given final demand vector to determine
the output level in each sector. The second group uses some exogenous process and input-output data to compute sectoral
price levels. Then the resulting prices are used to compute a new vector of final demands, and the two block of equations
are solved again. This iterative procedure is repeated until satisfactory convergence is obtained. Henaff has used GAMS
statements to perform this kind of calculation. The statements that solve the system for the first time and the next iteration are
shown below:

model usaio / mb, output /;

model dualmodel / dual, totp /;

solve usaio using lp maximizing total ;

solve dualmodel using lp maximizing totprice;

pbar(ta) = (sum(ipd.l(i,ta))/4.);
d(i,t) = (db(i)*g(t))/(pd.l(i,t)/pbar(t)) ;

solve usaio using lp maximizing total;

solve dualmodel using lp maximizing totprice;

Mb is a set of material balance (input-output) equations, and output is a total output equation. Dual is a group of price
equations, and totp is an equation that sums all the sectoral prices. The domestic prices pd used in the calculation of the
average price pbar are divided by four because there are four sectors in this example. Also the .l is appended to pd to
indicate that this is the level of the variable in the solution of the model namely in dualmodel. Thus the iterative procedure
uses solution values from one iteration to obtain parameter values for the next one. In particular, both pbar and pd are used
to compute the demand d for the i-th product in time period t, d(i,t). Also, the base year demand db and the growth
factor g are used in that calculation. Then when the new final demand vector d is calculated, the two blocks of equations are
solved again.

1 Henaff, Patrick (1980). emAn Input-Output Model of the French Economy/em, Masters Thesis, Department of Economics, University of Maryland.
5 Making New Solvers Available with GAMS 101

5 Making New Solvers Available with GAMS

This short section is to encourage those of you who have a favorite solver not available through GAMS . Linking a solver
program with GAMS is a straightforward task, and we can provide documents that describe what is necessary and provide the
source code that has been used for existing links. The benefits of a link with GAMS to the developer of a solver are several.
They include:

Immediate access to a wide variety of test problems.

An easy way of making performance comparisons between solvers.

The guarantee that a user has not somehow provided an illegal input specification.
Elaborate documentation, particularly of input formats, is not needed.
Access to the existing community of GAMS users, for marketing or testing.

This completes the discussion of the model and solve statements. In Chapter GAMS Output the various components of
GAMS output are described in some detail.
102 Model and Solve Statements
Chapter 10

GAMS Output

1 Introduction
The output from GAMS contains many aids for checking and comprehending a model. In this chapter the contents of the
output file are discussed. Ways by which the amount of diagnostic output produced can be controlled will also be discussed,
although complete lists of all these controls are not given until later. A small nonlinear model, [ALAN] by Alan S. Manne,
is used to illustrate the output file, and list it piece by piece as we discuss the various components. The possibilities for
extension to large models with voluminous output (which is when the diagnostics are really useful) should be apparent.
The output from a GAMS run is produced on one file, which can be read using any text editor. The default name of this
output file depends on the operating system, but Chapter The GAMS Call describes how this default can be changed. The
display statement, described in detail in Chapter The Display Statement , can be used to export information from the GAMS
program to the listing file.

2 The Illustrative Model

[ALAN] is a portfolio selection model whose object 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
104 GAMS Output

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;

3 Compilation Output
This is the output produced during the initial check of the program, often referred to as compilation. It contains two or three
parts: the echo print of the program, an explanation of any errors detected, and the maps. The next four sub-sections will
discuss each of these in detail.

3.1 Echo Print of the Input File

The Echo Print of the program is always the first part of the output file. It is just a listing of the input with the lines numbers
added. The $offlisting directive would turn off the listing of the input file.

A Quadratic Programming Model for Portfolio Analysis (ALAN,SEQ=124a)

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.

9 * This model has been modified for use in the documentation

Note that the first line number shown is 9. If the lines on the input are counted, it can be seen that this comment line shown
above appears after 8 lines of dollar directives and comments.
The line starting $title has caused text of the users choice to be put on the page header, replacing the default tile, which just
announces GAMS. The following $- directives are used to display more information in the output file and we be discussed.
3 Compilation Output 105

The text within the $ontext-$offtext pair is listed without line numbers, whereas comments starting with asterisks have line
numbers shown. Line numbers always refer to the physical line number in your input file.

Attention
Dollar control directives are only listed if a directive to list them is enabled, or if they contain errors.

Here is the rest of the echo print:

10
11 Set i securities /hardware,software,show-biz,t-bills/; alias (i,j);
12
13 Scalar target target mean annual return on portfolio % /10/,
14 lowyield yield of lowest yielding security,
15 highrisk variance of highest security risk ;
16
17 Parameters mean(i) mean annual returns on individual securities (%)
18
19 / hardware 8
20 software 9
21 show-biz 12
22 t-bills 7 /
23
24 Table v(i,j) variance-covariance array (%-squared annual return)
25
26 hardware software show-biz t-bills
27
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
40 Positive Variable x;
41
42 Equations fsum fractions must add to 1.0
43 dmean definition of mean return on portfolio
44 dvar definition of variance;
45
46 fsum.. sum(i, x(i)) =e= 1.0 ;
47 dmean.. sum(i, mean(i)*x(i)) =e= target;
48 dvar.. sum(i, x(i)*sum(j,v(i,j)*x(j))) =e= variance;
49
50 Model portfolio / fsum, dmean, dvar / ;
51
52 Solve portfolio using nlp minimizing variance;

That is the end of the echo of the input file. If errors had been detected, the explanatory messages would be found in this
section of the listing file. All discussion of error messages have been grouped in the section Error Reporting .
106 GAMS Output

3.2 The Symbol Reference Map

The maps are extremely useful if one is looking into a model written by someone else, or if trying to make some changes in
one's own model after spending time away from it.
The first map is the Symbol Cross Reference, which lists the identifiers (symbols) from the model in alphabetical order,
identifies them as to type, shows the line numbers where the symbols appear, and classifies each appearance. The symbol
reference map can be turned on by entering a line containing $onsymxref at the beginning of the program. The map that
resulted from [ALAN] is shown.

Symbol Listing

SYMBOL TYPE REFERENCES

DMEAN EQU DECLARED 43 DEFINED 47 IMPL-ASN 52

REF 50
DVAR EQU DECLARED 44 DEFINED 48 IMPL-ASN 52
REF 50
FSUM EQU DECLARED 42 DEFINED 46 IMPL-ASN 52
REF 50
HIGHRISK PARAM DECLARED 15 ASSIGNED 34 REF 35
I SET DECLARED 11 DEFINED 11 REF 11
17 24 33 2*34 37 46
2*47 2*48 CONTROL 33 34 46
47 48
J SET DECLARED 11 REF 24 2*48
CONTROL 48
LOWYIELD PARAM DECLARED 14 ASSIGNED 33 REF 35
MEAN PARAM DECLARED 17 DEFINED 19 REF 33
47
PORTFOLIO MODEL DECLARED 50 DEFINED 50 IMPL-ASN 52
REF 52
TARGET PARAM DECLARED 13 DEFINED 13 REF 47
V PARAM DECLARED 24 DEFINED 24 REF 34
48
VARIANCE VAR DECLARED 38 IMPL-ASN 52 REF 48
52
X VAR DECLARED 37 IMPL-ASN 52 REF 40
46 47 2*48

For each symbol, the name and type of the symbol are first provided. For example, the last symbol listed is X which is defined
to be of type VAR. The complete list of data types are given in table Table 1 .
Table 1: List of GAMS data types

Entry in symbol reference table GAMS Data Type

EQU equation
MODEL model
PARAM parameter
SET set
VAR variable

Then comes a list of references to the symbol, grouped by reference type and identified by the line number in the output file.
The actual reference can then be found by referring to the echo print of the program, which has line numbers on it. In the
3 Compilation Output 107

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 52
REF 40 46 47 2*48

This means that X is declared on line 37, implicitly assigned through a solve statement on line 52, and referenced on lines
40, 46, and 47. The entry 248 means that there are two references to X on line 48 of the input file .
The complete list of reference types is given below.

Reference Types Description

DECLARED This is where the identifier is declared as to type. This must be the first appearance of the identifier.
DEFINED This is the line number where an initialization (a table or a data list between slashes) or symbolic
definition (equation) starts for the symbol.
ASSIGNED This is when values are replaced because the identifier appears on the left of an assignment statement.
IMPL-ASN This is an implicit assignment: an equation or variable will be updated as a result of being referred
to implicitly in a solve statement.
CONTROL This refers to the use of a set as the driving index in an assignment, equation, loop or other indexed
operation(sum, prod, smin or smax).
REF This is a reference: the symbol has been referenced on the right of an assignment, in a display, in
an equation, or in a model or solve statement.

3.3 The Symbol Listing Map

The next map is called the Symbol Listing. All identifiers are grouped alphabetically by type and listed with their explanatory
texts. This is another very useful aid to have handy when first looking into a large model prepared by someone else. The
symbol listing map can be turned on by entering a line containing $onsymlist at the beginning of the program.

Symbol Listing

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
108 GAMS Output

FSUM fractions must add to 1.0

MODELS

PORTFOLIO

3.4 The Unique Element Listing - Map

The following map is called the Unique Element Listing. All unique elements are first grouped in entry order and then in
sorted order with their explanatory texts. The unique element listing map can be turned on by entering a line containing
$onuelxref at the beginning of the program.

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

ELEMENT REFERENCES

hardware DECLARED 11 REF 19 26 28

show-biz DECLARED 11 REF 21 26 30
software DECLARED 11 REF 20 26 29
t-bills DECLARED 11 REF 22 26 31

3.5 Useful Dollar Control Directives

This sub-section reviews the most useful of the Dollar Control Directives. These must not be confused with the dollar
exception-handling operators that will be introduced later: the similarity of terminology is unfortunate. These dollar control
directives are compiler directives that can be put in the input file to control the appearance and amount of detail in the output
produced by the GAMS compiler. Directives that do not have following text can be entered many to a line, as shown below
for the map controls.
$offlisting, $onlisting
This directive stops the echo print of the input file. $onlisting restores the default.
$offsymxref, $offsymlist, $onsymxref, $onsymlist
These four directives are used to control the production of symbol maps. Maps are most often turned on or
off at the beginning of the program and left as initially set, but it is possible to produce maps of part of the
program by using a on-map directive followed later by an off-map. The symlist lists all the symbols in the model.
The symxref shows a complete cross-reference list of symbols by number. Both these maps are suppressed by
default.
$offuelxref, $offuellist, $onuelxref, $onuellist
These four directives are used to control the production of Unique Element maps which show set membership
labels. Maps are most often turned on or off at the beginning of the program and left as initially set, but it is
possible to produce maps of part of the program by using a on-map directive followed later by an off-map. The
uellist lists all labels in both GAMS entry and alphabetical order. The uelxref shows a complete cross-reference
list by number. These label maps are suppressed by default.
$offupper, $onupper
4 Execution Output 109

This directive causes the echo print of the portion of the GAMS program following the directive to appear on the
output file in the case that it has been entered in. This is the default on newer GAMS systems. It is necessary if
case conventions have been used in the program, for example to distinguish between variables and equations.
$onupper, will cause all echo print to be in upper case.
$ontext, $offtext
$ontext-$offtext pairs are used to create block comments that are ignored by GAMS . Every $ontext must
have a matching $offtext in the same file. The $offtext must be on a line by itself.
$title 'text'
The text can have up to 80 characters. This causes every page of the output to have the title specified.

Attention
In all dollar control directives, the $ symbol must be in the first character position on the line.
Dollar control directives are dynamic: they affect only what happens after they are encountered, and they can be
set and reset wherever appropriate. They are remembered in continued compilations started from work files.

4 Execution Output
The only output to the listing file while GAMS is executing (performing data manipulations) is from the display statement.
All the user controls available to change the format will be discussed in detail later. The output from the display statement on
line 41 of the example is shown below. Note the wrap of the explanatory text.

---- 32 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.

5 Output Produced by a Solve Statement

In this section, the content of the output produced when a solve statement is executed will be explained. In Chapter Model
and Solve Statements all the actions that are triggered by a solve were listed. All output produced as a result of a solve is
labeled with a subtitle identifying the model, its type, and the line number of the solve statement.

5.1 The Equation Listing

The first output is the Equation Listing, which is marked with that subtitle on the output file. By default, the first three
equations in every block are listed. If there are three or fewer single equations in any equation block, then all the single
equations are listed. The equation listing section from the example is listed below. This model has 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 48

---- FSUM =E= fractions must add to 1.0

FSUM.. X(hardware) + X(software) + X(show-biz) + X(t-bills) =E= 1 ;

110 GAMS Output

(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)

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

Most of the listing is self-explanatory. The name, text, and type of constraints are shown. The four dashes are useful for
mechanical searching.

Attention
All the terms that depend on variables are collected on the left, and all the constant terms are combined into one number
on the right, 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 being displayed as zero.

Attention
The 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 ;

then the equation listing will appear 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(2x.l)power(y.l,3)+ 5, which evaluates to 221. Similarly the coefficient of y is obtained by differentiating
the equation above with respect to y which results in 2(sqr(x.l)3sqr(y.l) + 1.5/sqr(y.l), giving 216.1667.
Notice 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.
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.
5 Output Produced by a Solve Statement 111

Attention
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 in 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.

5.2 The Column Listing

The next section of the listing file is the Column Listing. This is a list of the individual coefficients sorted by column rather
than by row. Once again the default is to show the first three entries for each variable, along with their bound and level values.
The format for the coefficients is exactly as in the equation listing, with the nonlinear ones enclosed in parentheses and the
trailing zeroes dropped. The column listing section from our example follows.

A Quadratic Programming Model for Portfolio Analysis (ALAN,SEQ=124a)

Column Listing SOLVE PORTFOLIO USING NLP FROM LINE 48

---- X fraction of portfolio invested in asset I

X(hardware)
(.LO, .L, .UP = 0, 0, +INF)
1 FSUM
8 DMEAN
(0) DVAR

X(software)
(.LO, .L, .UP = 0, 0, +INF)
1 FSUM
9 DMEAN
(0) DVAR

X(show-biz)
(.LO, .L, .UP = 0, 0, +INF)
1 FSUM
12 DMEAN
(0) DVAR

REMAINING ENTRY SKIPPED

---- VARIANCE variance of portfolio

VARIANCE
(.LO, .L, .UP = -INF, 0, +INF)
-1 DVAR

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

5.3 The Model Statistics

The final information generated while a model is being prepared for solution is the statistics block, shown below. Its most
obvious use is to provide details on the size and nonlinearity of the model.
112 GAMS Output

Model Statistics SOLVE PORTFOLIO USING NLP FROM LINE 48

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
DERIVATIVE POOL 10 CONSTANT POOL 10
CODE LENGTH 87

GENERATION TIME = 0.020 SECONDS 0.1 Mb WAT-50-094

The BLOCK counts refer to GAMS equations and variables, the SINGLE counts to individual rows and columns in the
problem generated. The NON ZERO ELEMENTS entry refers to the number of non-zero coefficients in the problem matrix.
There are four 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.
All forms of nonlinearity do not have the same level of complexity. For example, xy is a simpler form of nonlinearity than
exp(xy). So, even though both these terms count as 1 nonlinear entry in the matrix, additional information is required
to provide the user with a feel for the complexity of the nonlinearity. GAMS provides the CODE LENGTH entry as a good
yardstick for this purpose. There are two other entries - DERIVATIVE POOL and CONSTANT POOL that provide some more
information about the nonlinearity. In general, the more nonlinear a problem is, the more difficult it is to solve.
The times that follow statistics are also useful. The GENERATION TIME is the time used since the syntax check 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.

5.4 The Solve Summary

This is the point (chronologically speaking) where the model is solved, and the next piece of output contains details about
the solution process. It is divided into two parts, the first being common to all solvers, and the second being specific to a
particular one.
The section of the solve summary that is common for all solvers is first discussed. The corresponding section for the example
model is shown below.

S O L V E S U M M A R Y

MODEL PORTFOLIO OBJECTIVE VARIANCE

TYPE NLP DIRECTION MINIMIZE
SOLVER MINOS5 FROM LINE 48

**** SOLVER STATUS 1 NORMAL COMPLETION

**** MODEL STATUS 2 LOCALLY OPTIMAL
**** OBJECTIVE VALUE 2.8990

RESOURCE USAGE, LIMIT 0.020 1000.000

ITERATION COUNT, LIMIT 5 10000
EVALUATION ERRORS 0 0

The common part of the solve summary is shown above. It can be found mechanically by searching for four asterisks. The
explanation for the information provided in this section follows.

MODEL PORTFOLIO
5 Output Produced by a Solve Statement 113

This provides the name of the model being solved.

TYPE NLP

This provides the model type of the model being solved.

SOLVER MINOS5

This provides the name of the solver used to solve the model.

OBJECTIVE VARIANCE

This provides the name of the objective variable being optimized

DIRECTION MINIMIZE

This provides the direction of optimization being performed.

**** SOLVER STATUS 1 NORMAL COMPLETION

**** MODEL STATUS 2 LOCALLY OPTIMAL

These provide the solver status and model status for the problem, and are discussed in greater detail at the end of this
subsection.

**** OBJECTIVE VALUE 2.8990

This provides the value of the objective function at the termination of the solve. If the Solver and Model have the right status,
this value is the optimum value for the problem.

RESOURCE USAGE, LIMIT 0.109 1000.000

These two entries provide the amount of wall clock time (in seconds) taken by the solver, as well as the upper limit allowed
for the solver. The solver will stop as soon as the limit on time usage has been reached. The default limit on time usage is
1000 seconds. This limit can be changed by entering a line containing the statement option reslim = xx ; in the program
before the solve statement, where xx is the required limit in wall clock seconds.

ITERATION COUNT, LIMIT 5 1000

These two entries provide the number of iterations used by the solver, as well as 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 pratically infinity. This limit can be
changed by entering a line containing the statement option iterlim = nn; in the program before the solve statement,
where nn is the required limit on the iterations used.

EVALUATION ERRORS 0 0

These two entries provide the number of numerical errors encountered by the solver, as well as the upper limit allowed
for the solver. These errors result due to numerical problems like division by0. 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 0. This
limit can be changed by entering a line containing the statement option domlim = nn; in the program before the solve
statement, where nn is the required limit on the evaluation errors allowed.
The SOLVER STATUS and MODEL STATUS require special explanation. The status for the solver (the state of the program)
and the model (what the solution looks like) are characterized, and a complete list of possible MODEL STATUS and SOLVER
STATUS messages is given below.
114 GAMS Output

Model Status

Here is a list of possible MODEL STATUS messages:

1 OPTIMAL
This means that 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
This message means that a local optimum 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
This means that 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
This means that 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
This message means that no feasible point could be found for the problem from the given starting point. It does
not necessarily mean that no feasible point exists.
6 INTERMEDIATE INFEASIBLE
This means that the current solution is not feasible, but that the solver stopped, either because of a limit (e.g.,
iteration or resource), or because of some sort of difficulty. Check the solver status for more information.
7 FEASIBLE SOLUTION
A feasible solution has been found to a problem without discrete variables.
8 INTEGER SOLUTION
A feasible solution has been found to a problem with discrete variables. There is more detail following about
whether this solution satisfies the termination criteria (set by options optcr and optca ).
9 INTERMEDIATE NON-INTEGER
This is an incomplete solution to a problem with discrete variables. A feasible solution has not yet been found.
10 INTEGER INFEASIBLE
It has been proven that there is no feasible solution to a problem with discrete variables.
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 SOLUTI0N
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
5 Output Produced by a Solve Statement 115

This is used when a CNS model is solved and the solver somehow can be certain that there is only one solution.
The simplest examples are a linear model with a non-singular Jacobian, a triangular model with constant
non-zero elements on the diagonal, and a triangular model where the functions are monotone in the variable on
the diagonal.
16 SOLVED
Locally feasible in a CNS models - this is used when the model is feasible and the Jacobian is non-singular and
we do not know anything about uniqueness.
17 SOLVED SINGULAR
Singular in a CNS models - this is used when the model is feasible (all constraints are satisfied), but the Jacobian
/ Basis is singular. In this case there could be other solutions as well, in the linear case a linear ray and in the
nonlinear case some curve.
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.

Solver Status

This is the list of possible SOLVER STATUS messages:

1 NORMAL COMPLETION
This means that the solver terminated in a normal way: i.e., it was not interrupted by a limit (resource, iterations,
nodes, ...) or by internal difficulties. The model status describes the characteristics of the accompanying solution.
2 ITERATION INTERRUPT
This means that the solver was interrupted because it used too many iterations. Use option iterlim to increase the
iteration limit if everything seems normal.
3 RESOURCE INTERRUPT
This means that the solver was interrupted because it used too much time. Use option reslim to increase the time
limit if everything seems normal.
4 TERMINATED BY SOLVER
This means that the solver encountered difficulty and was unable to continue. More detail will appear following
the message.
5 EVALUATION ERROR LIMIT
Too many evaluations of nonlinear terms at undefined values. You should 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.
116 GAMS Output

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.

5.5 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 was used in the example here.
There will also be diagnostic messages in plain language if anything unusual was detected, and specific performance details
as well, some of them probably technical. The Solver Manual 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 example follows.

GAMS/MINOS
B. A. Murtagh, University of New South Wales
and
P. E. Gill, W. Murray, M. A. Saunders and M. H. Wright
Systems Optimization Laboratory, Stanford University.

Work space allocated -- 0.04 Mb

EXIT -- OPTIMAL SOLUTION FOUND

MAJOR ITNS, LIMIT 11 200
FUNOBJ, FUNCON CALLS 0 71
SUPERBASICS 4
INTERPRETER USAGE 0.02
NORM RG / NORM PI 1.801E-09

The line 'work space allocated -- 0.04 MB' provides the amount of memory used by the solver for the problem. If the
amount of memory the solver estimates that it needs is not available, GAMS will return a message saying that not enough
memory was allocated. GAMS will also return the maximum amount of memory available on the machine. The user can
direct the solver to use less memory by entering a line containing the statement mymodel.workspace = xx; were mymodel
is the name of the model being solved as specified by the model statement, and xx is the amount of memory in Megabytes.
Note that the solver will attempt to solve the problem with xx MB of memory, however it is not guaranteed to succeed since
the problem may require more memory.
More information can be obtained for a successful run by entering a line containing the statement option sysout = on ;
in the program above the solve statement.

5.6 The Solution Listing

The next section of the listing file 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.
5 Output Produced by a Solve Statement 117

This section of the listing file can be turned off by entering a line containing the statement option solprint = off ; in
the program above the solve statement.
The solution listing section from our example is shown below.

LOWER LEVEL UPPER MARGINAL

---- EQU FSUM 1.000 1.000 1.000 -13.529

---- EQU DMEAN 10.000 10.000 10.000 1.933
---- EQU DVAR . . . -1.000

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.303 +INF .

software . 0.087 +INF EPS
show-biz . 0.505 +INF .
t-bills . 0.106 +INF EPS

LOWER LEVEL UPPER MARGINAL

---- VAR VARIANCE -INF 2.899 +INF .

VARIANCE variance of portfolio

The order of the equations and variables are the same as in the symbol listing described before and will be described later
The four columns associated with each entry 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 UPPERM 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. These relationships were
described in Chapter Equations .

Attention
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 zero.

EPS is the GAMS extended value that means very close to but different from zero. It is common to see a marginal value
given as EPS, since GAMS uses the convention that marginal are zero for basic variables, and not zero for others.
118 GAMS Output

Attention
EPS is used with non-basic variables whose marginal values are very close to, or actually, zero, or in nonlinear problems
with superbasic variables whose marginals are zero or very close to it. A superbasic variable is one between its bounds
at the final point but not in the basis.

There are brief explanations of technical terms used in this section in the Glossary. For models that are not solved to
optimality, some constraints may additionally be marked with certain flags. The list of these flags and their description is
given below.
INFES The row or column is infeasible. This mark is made for any entry whose 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 that appears to cause the problem to be unbounded.

5.7 Report Summary

The final section of the solution listing is the report summary, marked with four asterisks (as are all important components
of the output). It shows the count of rows or columns that have been marked INFES, NOPT, or UNBND in the solution listing
section. The sum of infeasibilities will be shown if it the reported solution is infeasible. The error count in 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.

**** REPORT SUMMARY : 0 NONOPT

0 INFEASIBLE
0 UNBOUNDED
0 ERRORS
42 PROJECTED

If our example had display output for reporting, it would come here.

5.8 File Summary

The last piece of the output file is important: it gives the names of the input and output disk files. If work files (save or restart)
have been used, they will be named here as well.

**** FILE SUMMARY

INPUT C:\PROGRAM FILES\\gamsIDE\ALAN.GMS

OUTPUT C:\PROGRAM FILES\\gamsIDE\ALAN.LST

6 Error Reporting
All the comments and description about errors have been collected into 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 that 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 for the reader 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.
6 Error Reporting 119

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 almost to 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
such as 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, are reported in a way understandable 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 user's problem.

Attention
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). The following three sub-sections discuss these types of errors.

6.1 Compilation Errors

Compilation errors were discussed in some detail in Chapter A GAMS Tutorial by Richard E. Rosenthal . There is some
overlap between the material in those sections and this one. 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 will be 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 mistakes, the explanatory error message text will help you diagnose the
problem and correct it.

Attention
When a compilation error is discovered, a $-symbol and error number are printed below the offending symbol (usually
to the right) on a separate line that begins with the 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
$-signs may be suppressed and error number squeezed. GAMS will not list more than 10 errors on any one line.

Attention
At the end of the echo print of the program, a list of all error numbers encountered, together with a description of the
probable cause of each error, will be printed. The error messages are self-explanatory and will not be listed here.

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.
One mistake that may cause confusion is if a GAMS reserved word is used for a label or an identifier. In this case, it is
impossible to provide helpful messages for technical reasons.

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. Always check carefully for the cause of the first error is such a
group, and look at the previous statement (and especially for missing semicolons) if nothing seems obvious.

The following example illustrates the general reporting format for compiler errors.
120 GAMS Output

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

6.2 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
Solve error messages are reported in two places and in two formats.
1. they are shown immediately below 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 rest of the error messages at the end of the compilation.

The example below illustrates how 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
6 Error Reporting 121

6.3 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. The model library problem [CRAZY] contains all non-standard operations and should be executed to study its
exceptions.
Recall that GAMS arithmetic is defined over the closed interval [-INF,+INF] and contains 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 remember that one cannot solve a model or
save a work file if errors have been detected previously.

6.4 Solve Errors

The execution of a solve statement can trigger additional errors called MATRIX ERRORS, which 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 an extended range value being 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 BOUNDS > UPPER BOUND

X (.LO, .L, .UP = 10, 0, 5)
...
**** SOLVE from line 8 ABORTED, EXECERROR = 1
**** USER ERROR(S) ENCOUNTERED

Some solve statement 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 its direct control, errors associated with these
calculations are reported in the solution report. Unless reset with the domlim option the subsystems will interrupt the solution
process if arithmetic exceptions are encountered. 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
122 GAMS Output

SOLVER MINOS5 FROM LINE 9

**** SOLVER STATUS 5 EVALUATION ERROR LIMIT

**** MODEL STATUS 7 FEASIBLE SOLUTION
**** OBJECTIVE VALUE 1.0000

RESOURCE USAGE, LIMIT 0.141 1000.000

ITERATION COUNT, LIMIT 0 10000
EVALUATION ERRORS 2 0

EXIT -- Termination requested by User in subroutine FUNOBJ after 7 calls

**** ERRORS(S) IN EQUATION ONE

2 INSTANCES OF - DIVISION BY ZERO (RESULT SET TO 0.1E+05)

**** REPORT SUMMARY : 1 NONOPT ( NOPT)

0 INFEASIBLE
0 UNBOUNDED
2 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.
If 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,
as mentioned above, all possible information is listed on the GAMS output file and any solves following will not be attempted.

7 Summary
This is the end of the sequential discussion of the basic features of the GAMS language. All further chapters are geared
towards more advanced use of GAMS .
Chapter 11

Conditional Expressions, Assignments and

Equations

1 Introduction
This chapter deals with the way in which conditional assignments, expressions and equations are made in GAMS. The index
operations already described are very powerful, but it is necessary to allow for exceptions of one sort or another. For example,
heavy trucks may not be able use a particular route because of a weak bridge, or some sectors in an economy may not produce
exportable product. The use of a subset in an indexed expression has already been shown to provide some ability to handle
exceptions.

2 Logical Conditions
Logical conditions are special expressions that evaluate to a value of True or False. Numerical Expressions can also serve
as logical conditions. Additionally, GAMS provides for numerical relationship and logical operators that can be used to
generate logical conditions. The next four sub-sections discuss these various building blocks that can be used to develop
complex logical conditions.

2.1 Numerical Expressions as Logical Conditions

Attention
Numerical expressions can also serve as logical conditions - a result of zero is treated as a logical value of False, and a
non-zero result is treated as a logical value of True.

The following numerical expression can be used to illustrate this point.

2*a - 4

This expression results in a logical value of False when a is 2 because the expression numerically evaluates to 0. For all other
values of a, the expression results in a non-zero value, and therefore is equivalent to a logical value of True.

2.2 Numerical Relationship Operators

Numerical relationship operators compare two numerical expressions. For completeness all numerical relationship operators
are listed below.
124 Conditional Expressions, Assignments and Equations

Operator Meaning
strictly less than
lt, <
less than-or-equal to
le, <=
eq, = equal to
not equal to
ne, <>
greater than or equal to
ge, >=
strictly greater than
ge, gt, >

The following example of a numerical relationship illustrates its use as a logical condition.

(sqr(a) > a)

This condition evaluates to False if 1 a 1. For all other values of a, this condition evaluates to True. Note that the same
expression can also be written as (sqr(a) gt a).

2.3 Logical Operators

The logical operators available in GAMS are listed below.

Operator Meaning
not
not
and
and
or inclusive or
xor exclusive or

The truth table generated by these logical operators is given in the following table.
Table 1:Truth table of logical operators

a b a and b a or b a xor b not a

0 0 0 0 0 1
0 non-zero 0 1 1 1
non-zero 0 0 1 1 0
non-zero non-zero 1 1 0 0

2.4 Set Membership

Set membership can also be used as a logical condition. The label results in a logical value of True if it is a member of the set
in question, and False if it is not. This is used with subsets and dynamic sets.
Consider the following example for illustration.

set i /1*10/
subi(i) /1*3/ ;

The set subi(i) results in a logical value of True for all elements that belong to subi and False for all elements of i that do
not belong to subi.
2 Logical Conditions 125

The use of set membership as a logical condition is an extremely powerful feature of GAMS and while its use will be
illustrated later on in this chapter, its full power becomes clear when considered with the description of dynamic sets later.

2.5 Logical Conditions Involving Acronyms

Acronyms, which are character string values, can be used in logical conditions only with the = or <> operators only.
Consider the following example of logical conditions involving the use of acronyms,

dayofweek = wednesday
dayofweek <> thursday

where dayofweek is a parameter, and wednesday and thursday are acronyms.

2.6 Numerical Values of Logical Conditions

The previous four sub-sections have described the various features in GAMS that can be used as logical conditions. However,
GAMS does not have a Boolean data type.

Attention
GAMS follows the convention that the result of a relational operation is zero if the assertion is False, and one if True.

Consider the following example for illustration,

x = (1 < 2) + (2 < 3)

The expression to the right of the assignment evaluates to 2 since both logical conditions within parenthesis are true and
therefore assume a value of 1. Note that this is different from the assignment below,

x = (1 < 2) or (2 < 3)

which evaluates to 1 due to the or operator behaving as explained above.

2.7 Mixed Logical Conditions - Operator Precedence

The building blocks discussed in the first four subsections can be used to generate more complex logical conditions. The
default precedence order in a logical condition used by GAMS in the absence of parenthesis is shown in table Table 2 in
decreasing order.
Table 2: Operator precedence

Operation Operator
Exponentiation
Numerical Operators
- Multiplication, Division , /
- Unary operators - Plus, Minus +, -
- Binary operators - addition, subtraction +, -
Numerical Relationship operators <, <=, =, <>, >=, >
Logical Operators
- not not
- and and
- or, xor or, xor
126 Conditional Expressions, Assignments and Equations

Note that in the case of operators with the same precedence, the order in which the operator appears in the expression is used
as the precedence criterion, with the order reducing from left to right.

Attention
It is always advisable to use parentheses rather than relying on the precedence order of operators. It prevents errors and
makes the intention clear.

Consider the following example for illustration,

x - 5*y and z - 5

is treated equivalent to (x - (5y)) and (z-5). However, note that the use of parenthesis does make the expression
clearer to understand.

2.8 Mixed Logical Conditions - Examples

Some simple examples of logical conditions, containing the building blocks described in the previous sub-sections, are shown
in table Table 3 to illustrate the generation and use of more complex logical conditions.
Table 3: Examples of logical conditions

Logical Condition Numerical Value Logical Value

(1 < 2) + (3 < 4) 2 True
(2 < 1) and (3 < 4) 0 False
(45 - 3) + (10/8) 17.125 True
(45 - 3) or (10 - 8) 1 True
(4 and 5) + (23 <= 6) 2 True
(4 and 0) + (23 < 6) 0 False

3 The Dollar Condition

This section introduces the dollar operator , which is one of the most powerful features of GAMS. The dollar operator
operates with a logical condition. The term $(condition) can be read as 'such that condition is valid' where condition is a
logical condition.

Attention
The dollar logical conditions cannot contain variables. Variable attributes (like .l and .m) are permitted however.

The dollar operator is used to model conditional assignments, expressions, and equations. The following subsection provides
an example that will clarify its use. The next section will deal individually with the topic of using dollar conditions to model
conditional assignments, expressions, and equations respectively.

3.1 An Example
Consider the following simple condition,

if (b > 1.5), then a = 2

This can be modeled in GAMS using the dollar condition as follows,

a$(b > 1.5) = 2 ;

4 Conditional Assignments 127

If the condition is not satisfied, no assignment is made. Note that one can read the $ as 'such that' to clarify the meaning: 'a,
such that b is greater than 1.5, equals 2'.

3.2 Nested Dollar Conditions

Dollar conditions can be also nested. The term $(condition1$(condition2)) can be read as $(condition1 and
condition2).

Attention
For nested dollar conditions, all succeeding expressions after the dollar must be enclosed in parentheses.

Consider the following example,

u(k)$(s(k)$t(k)) = a(k) ;

where k, s(k), and t(k) are sets and u(k) and a(k) are parameters. The assignment will be made only for those members
of k that are also members of both s and t. Note the position of the parenthesis in the dollar condition. The statement above
can be rewritten as

u(k)$(s(k) and t(k)) = a(k) ;

Attention
To assist with the readability of statements, it is strongly recommended to use the logical and operator instead of nesting
dollar operators.

4 Conditional Assignments
The statement comprising the example in the Section before was a conditional assignment. In this example, the dollar
condition was on the left-hand-side of the assignment.

Attention
The effect of the dollar condition is significantly different depending on which side of the assignment it is in.
In many cases, it may be possible to use either of the two forms of the dollar condition to describe an assignment.
In such a case, clarity of logic should be used as the criterion for choice.

The next two subsections describe the use of the dollar condition on each side of the assignment.

4.1 Dollar on the Left

The example illustrated in the section above uses the dollar condition on the left-hand side of the assignment statement.

Attention
For an assignment statement with a dollar condition on the left-hand side, no assignment is made unless the logical
condition is satisfied. This means that the previous contents of the parameter on the left will remain unchanged
for labels that do not satisfy the condition.
If the parameter on the left-hand side of the assignment has not previously been initialized or assigned any values,
zeroes will be used for any label for which the assignment was suppressed.

Consider the following example adapted from [CHENERY],

128 Conditional Expressions, Assignments and Equations

rho(i)$(sig(i) ne 0) = (1./sig(i)) - 1. ;

The parameter sig(i) has been previously defined in the model and the statement above is used to calculate rho(i). The
dollar condition on the statement protects against dividing by zero. If any of the values associated with sig(i) turn out
to be zero, no assignment is made and the previous values of rho(i) remain. As it happens, rho(i) was previously not
initialized, and therefore all the labels for which sig(i) is 0 will result in a value of 0.
Now recall the convention, explained in Section Numerical Expressions as Logical Conditions that non zero implies True and
zero implies False. The assignment above could therefore be written as

rho(i)$sig(i) = (1./sig(i)) - 1. ;

4.2 Dollar on the Right

Attention
For an assignment statement with a dollar condition on the right hand side, an assignment is always made. If the logical
condition is not satisfied, the corresponding term that the logical dollar condition is operating on evaluates to 0.

Consider the following example, which is a slight modification to the one described in Section An Example,

x = 2$(y > 1.5) ;

Expressed in words, this is equivalent to,

if (y > 1.5) then (x = 2), else (x = 0)

Therefore an if-then-else type of construct is implied, but the else operation is predefined and never made explicit. Notice
that the statement in the illustrative example above can be re-written with an explicit if-then-else and equivalent meaning as

x = 2$(y gt 1.5) + 0$(y le 1.5) ;

This use of this feature is more apparent for instances when an else condition needs to be made explicit. Consider the next
example adapted from [FERTD] . The set i is the set of plants, and are calculating mur(i), the cost of transporting imported
raw materials. In some cases a barge trip must be followed by a road trip because the plant is not alongside the river and we
must combine the separate costs. The assignment is:

mur(i) =(1.0 +. 0030*ied(i,barge))$ied(i,barge)

+(0.5 + .0144*ied(i,road))$ied(i,road);

This means that if the entry in the distance table is not zero, then the cost of shipping using that link, which has a fixed and a
variable components, is added to the total cost,. If there is no distance entry, there is no contribution to the cost, presumably
because that mode is not used.

4.3 Filtering Sets in Assignments

Consider the following statement

u(k)$s(k) = a(k) ;

where k and s(k) are sets, while u and a are parameters. This can be rewritten as

u(s) = a(s) ;
4 Conditional Assignments 129

Note that the assignment has been filtered through the conditionality without the use of the dollar operator. This is a cleaner
and more understandable representation of the assignment. This feature gets more useful when dealing with tuples (sets with
multiple indices).
Consider the following example for calculating the travel cost for a fictional parcel delivery service between collection sites
(i) and regional transportation hubs (j),

set i /miami,boston,chicago,houston,sandiego,phoenix,baltimore/
j /newyork,detroit,losangeles,atlanta/ ;
set ij(i,j) /
boston.newyork
baltimore.newyork
miami.atlanta
houston.atlanta
chicago.detroit
sandiego.losangeles
phoenix.losangeles / ;

table distance(i,j) "distance in miles"

newyork detroit losangeles atlanta
miami 1327 1387 2737 665
boston 216 699 3052 1068
chicago 843 275 2095 695
houston 1636 1337 1553 814
sandiego 206
phoenix 2459 1977 398 1810;

parameter factor,shipcost(i,j) ; factor = 0.009 ;

The set ij denotes the regional transportation hub for each collection site. Factor is the cost estimate per unit mile. The
cost of transporting parcels (shipcost) from a local collection site (i) to a regional hub(j) is then provided by the following
assignment,

shipcost(i,j)$ij(i,j) = factor*distance(i,j) ;

Note that i and j do not appear separately in the assignment for shipcost. The assignment can then be simply written as,

shipcost(ij) = factor*distance(ij) ;

If i or j appear separately in any assignment, the above simplification cannot be made. For example, consider the case where
the shipping cost depends not only on factor and the distance between collection sites and regional hubs but also on the
congestion at the regional hub.

Parameter congestfac(j) /
newyork 1.5
detroit 0.7
losangeles 1.2
atlanta 0.9/ ;

Congestfac is a parameter used to model the congestion at each regional hub. The unit cost of shipment is then computed
as follows:

shipcost(i,j)$ij(i,j) = factor*congestfac(j)*distance(i,j) ;

This cannot be re-written as

130 Conditional Expressions, Assignments and Equations

shipcost(ij) = factor*congestfac(j)*distance(ij) ;

The above representation has the index j on the right hand side, but not on the left hand side. As explained before, GAMS
will flag this assignment as an error. However, the following representation will work:

shipcost(ij(i,j)) = factor*congestfac(j)*distance(ij) ;

In the above assignment ij is specifically denoted as a tuple of i and j which then appear on the left hand side.

5 Conditional Indexed Operations

Another important use of the dollar condition is to control the domain of operation of indexed operations. This is conceptually
similar to the 'dollar on the left' described in Section An Example.
Consider the following example adapted from [GTM].

tsubc = sum(i$(supc(i) ne inf), supc(i)) ;

This statement evaluates the sum of the finite values in supc.

Attention
A common use of dollar controlled index operations is where the control is itself a set. The importance of this concept
will become apparent with the discussion of dynamic sets.

A set was used to define the mapping between mines and ports in Chapter Set Definition. Another typical example is a
set-to-set mapping defining the relationship between states and regions, useful for aggregating data from the state to the
regional level.

sets r / north,south /
s / florida,texas,vermont,maine /
corr(r,s) / north.(vermont,maine)
south.(florida,texas) /

parameter y(r)
income (s) "income of each state"
/ florida 4.5, vermont 4.2
texas 6.4, maine 4.1 / ;

The set corr provides a correspondence to show which states belong to which regions. The parameter income is the income
of each state. Y(r) can be calculated with this assignment statement:

y(r) = sum(s$corr(r,s), income(s)) ;

For each region r, the summation over s is only over those pairs of (r,s) for which corr(r,s) exists. Conceptually, set
existence is analogous to the Boolean value True or the arithmetic value 'not zero'. The effect is that only the contributions
for 'vermont' and 'maine' are included in the total for 'north', and 'south' includes only 'texas' and 'florida'.
Note that the summation above can also be written as sum(s,income(s)$corr(r,s)), but this form is not as easy to read
as controlling the index of summation.
6 Conditional Equations 131

5.1 Filtering Controlling Indices in Indexed Operations

The controlling indices can, in certain cases, be filtered through the conditional set without the use of the dollar operator.
Consider the shipping cost example described previously in this section. The total cost of shipment is obtained through the
following equation:

variable shipped(i,j), totcost ;

equation costequ ;

cost.. totcost =e= sum((i,j)$ij(i,j), shipcost(i,j)*shipped(i,j));

where shipped is the amount of material shipped from i to j, and totcost is the total cost of all shipment. The equation
above can be written as

cost.. totcost =e= sum(ij, shipcost(ij)*shipped(ij));

However, if the original equation includes a term dependent only on index j, as follows

cost.. totcost =e= sum((i,j)$ij(i,j),

factor*congestfac(j)*distance(i,j) *shipped(i,j));

then the equation needs to be simplified as

cost.. totcost =e= sum(ij(i,j),

factor*congestfac(j)*distance(ij) *shipped(ij));

Note that the presence of a parameter indexed solely by j in the indexed expression above necessitated the use of ij(i,j)
rather than ij.

6 Conditional Equations
The dollar operator is also used for exception handling in equations. The next two subsections discuss the two main uses of
dollar operators within equations - within the body of an equation, and over the domain of definition.

6.1 Dollar Operators within the Algebra

A dollar operator within an equation is analogous to the dollar control on the right of assignments as discussed in Section
Dollar on the Right , and if one thinks of 'on the right' as meaning on the right of the '..' then the analogy is even closer. An
if-else operation is implied as it was with assignments. It is used to exclude parts of the definition from some of the generated
constraints.
Consider the following example adapted from [CHENERY],

mb(i).. x(i) =g= y(i) + (e(i) - m(i))$t(i) ;

The term is added to the right hand side of the equation only for those elements of i that belong to t(i).
Controlling indexing operations using the dollar condition can also be done as with any assignment. Consider the following
supply balance (sb) equation from [GTM],

sb(i).. sum(j$ij(i,j), x(i,j)) =l= s(i) ;

132 Conditional Expressions, Assignments and Equations

6.2 Dollar Control over the Domain of Definition

This is analogous to the dollar control on the left of assignments as discussed in Section Dollar on the Left , and if one thinks
of 'on the left' as meaning on the left of the '..' then the analogy is even closer.

Attention
The purpose of the dollar control over the domain of definition of equations is to restrict the number of constraints
generated to less than that implied by the domain of the defining sets.

Consider the following example adapted from [FERTS] :

cc(m,i)$mpos(m,i)..
sum(p$ppos(p,i), b(m,p)*z(p,i)) =l= util*k(m,i);

Cc is a capacity constraint defined for all units (m) and locations (i).
Not all types of units exist at all locations, however, and the mapping set mpos(m,i) is used to restrict the number of
constraints actually generated. The control of the summation over p with ppos(p,i) is an additional one, and is required
because not all processes (p) are possible at all locations (i).

6.3 Filtering the Domain of Definition

The same rules that apply to filtering assignments and controlling indices in indexed operations applies to equation domains
as well. Consider the following equation using the same set definitions as described before,

parameter bigM(i,j) ;
variable shipped(i,j) ;
binary variable bin(i,j) ;

equation logical(i,j) ;
logical(i,j)$ij(i,j).. shipped(i,j) =l= bigM(i,j)*bin(i,j) ;

The equation logical relates the continuous variable shipped(i,j) to the binary variable bin(i,j). This can be
simplified as follows:

logical(ij).. shipped(ij) =l= bigM(ij)*bin(ij) ;

Note that if the right hand side of the equation contained any term that was indexed over i or j separately, then the equation
logical(i,j)$ij(i,j) would have to be simplified as logical(ij(i,j)).
Chapter 12

Dynamic Sets

1 Introduction
All the sets that have been discussed so far had their membership declared as the set itself was declared, and the membership
was never changed. In this chapter we will discuss changing the membership of sets. A set whose membership can change
is called a dynamic set to contrast it with a static set whose membership will never change. The distinction is important and
will be discussed in detail in this chapter. This is a topic that has been avoided until now because of a potential confusion for
new users. Advanced Users will, however, find it useful.

2 Assigning Membership to Dynamic Sets

Sets can be assigned in a similar way to other data types. One difference is that arithmetic operations cannot be performed
on sets in the same way that they can on value typed identifiers (parameters, or variables and equations subtypes). A
dynamic set is most often used as a controlling index in an assignment or an equation definition, or as the controlling entity in
a dollar-controlled indexed operation.

2.1 The Syntax

In general, the syntax in GAMS for assigning membership to dynamic sets is:

set_name(domain_name | domain_label) = yes | no ;

Set name is the internal name of the set (also called an identifier) in GAMS. Yes and no are keywords used in GAMS to
denote membership or absence respectively from the assigned set.

Attention
The most important principle to follow is that a dynamic set should always be domain checked at declaration time
to be a subset of a static set (or sets).
It is of course possible to use dynamic sets that are not domain checked, and this provides additional power,
flexibility, lack of intelligibility, and danger. Any label is legal as long as the set dimension, once established, is
preserved.

2.2 Illustrative Example

The following example, adapted from [ZLOOF], is used to illustrate the assignment of membership to dynamic sets.
134 Dynamic Sets

set item all items / dish,ink,lipstick,pen,pencil,perfume /

subitem1(item) first subset of item / pen,pencil /
subitem2(item) second subset of item;

subitem1(ink) = yes ; subitem1(lipstick) = yes ;

subitem2(item) = yes ; subitem2(perfume) = no ;
display subitem1, subitem2;

Note that the sets subitem1 and subitem2 are declared like any other set. The two sets become dynamic because of
assignments. They are also domain checked: the only members they will ever be able to have must also be members of item.
And item is a static set and henceforth its membership is frozen. The first two assignments each add one new element to
subitem1. The third is an example of the familiar indexed assignment: subitem2 is assigned all the members of item. The
output caused by the display statement, that will reveal the membership of the sets, is shown below for verification.

---- 7 SET SUBITEM1 first subset of item

INK , LIPSTICK, PEN , PENCIL

---- 7 SET SUBITEM2 second subset of item

DISH , INK , LIPSTICK, PEN , PENCIL

Attention
The elements are displayed in the order specified in the declaration of item.

2.3 Dynamic Sets with Multiple Indices

Dynamic sets, like static sets, can have up to 20 dimensions. The following example illustrates assignments for multi-
dimensional sets.

Sets item items sold /pencil, pen/

sup suppliers /bic, parker, waterman /
supply(item,sup) ;

supply(pencil,bic) = yes ;
supply(pen,sup) = yes ;

All the mechanisms using asterisks and parenthesized lists that we introduced in the discussion on static sets in Chapter Set
Definition are available for dynamic sets as well.

2.4 Assignments over the Domain of Dynamic Sets

One can make an assignment over the domain of a dynamic set because dynamic sets are known to be proper subsets of static
sets. This is not the same as doing domain checking using a dynamic set.
The following example, adapted from the Section Illustrative Example illustrates the use of dynamic sets as domains:

subitem1(item) = no
subitem1(subitem2) = yes;

The first assignment ensures that subitem1 is empty. Note that this can also be done with parameters. For example,

parameter inventory(item) ;
inventory(subitem1) = 25 ;
2 Assigning Membership to Dynamic Sets 135

2.5 Equations Defined over the Domain of Dynamic Sets

It is sometimes necessary to define an equation over a dynamic set.

Attention
The trick is to declare the equation over the entire domain but define it over the dynamic set.

The following example illustrates its use,

set allr all regions / n, s, w, e, n-e, s-w /

r(allr) region subset for particular solution ;

scalar price /10/ ;

equations prodbal(allr) production balance ;

variables activity(allr) first activity

revenue(allr) revenue ;

prodbal(r).. activity(r)*price =e= revenue(r) ;

To repeat the important point: the equation is declared over allr but referenced over r. Then arbitrary assignments can be
made to r within the membership of allr.

2.6 Assigning Membership to Singleton Sets

Assigning membership to singleton sets is different than to usual sets. Since singleton sets can never have more
than one element, any assignment to a singleton set first clears or empties the set, so no explicit clear is necessary. This
is illustrated in the following example:

Set i Static Set / a, b, c /

ii(i) Dynamic Set / b /;
Singleton Set si(i) Dynamic Singleton Set / b /;

ii(c) = yes;
si(c) = yes;

Display ii, si;

Here is the output from the display statement in the listing file:

---- 8 SET ii Dynamic Set

b, c

---- 8 SET si Dynamic Singleton Set

Attention
That an assignment to a singleton set first clears the set always, means that it is even cleared if there would be no
change at all for a regular set:
136 Dynamic Sets

Singleton Set s / 1 /;
s(s)$0 = yes;
display s;

Here is the output from the display statement in the listing file:

---- 3 SET s

( EMPTY )

The assignment behavior can be changed with strictSingleton, and option strictSingleton.

3 Using Dollar Controls with Dynamic Sets

The rest of this chapter requires an understanding of the dollar condition. All the dollar control machinery is available for use
with dynamic sets. In fact, the full power of dynamic sets can be exploited using these dollar controls.
Note that the dynamic set has values of yes and no only, and can therefore be treated as a logical statement. The only
operations that can be performed on dynamic sets inside the dollar operator are therefore not, and, or, or xor, as well as the
set operations described in Section Set Operations, chapter Dynamic Sets.
The main uses of dynamic sets inside dollar conditions are in assignments, indexed operations and in equations. Each of these
will be discussed in detail in the following subsections. Examples will be used to illustrate its use in each of the three cases.

3.1 Assignments
Dynamic sets can be used inside dollar conditions within assignments defining other dynamic sets or parameters.
As an illustration of its use in defining other dynamic sets, the two statements in the example from Section Assignments over
the Domain of Dynamic Sets can be written with equivalent effect as

subitem1(item) = yes$subitem2(item) ;

which is a terse form of the following statement

subitem1(item) = yes$subitem2(item) + no$(not subitem2(item)) ;

Attention
The value used in the implied else that goes with dollar on the right is no in a set assignment, rather than zero
which is used with normal data.

The second example from Section Assignments over the Domain of Dynamic Sets can be rewritten as follows to illustrate the
use of dynamic sets in defining parameters,

inventory(item)$subitem1(item) = 25 ;

3.2 Indexed Operations

Another important use of dollar controls with dynamic sets is to control the domain while performing indexed operations like
sum and prod. Consider the following adaptation of the second example from Section Assignments .

parameter totinv total inventory ;

totinv = sum(item$subitem1(item),inventory(item)) ;
4 Set Operations 137

This example has been shown only for illustration. Note that the second statement above can also be rewritten tersely as

totinv = sum(subitem1,inventory(subitem1)) ;

This is not always possible. Consider the following artificially created example,

sets item items sold /pencil, pen/

sup suppliers /bic, parker, waterman /
dep department /stationery, household/
supply(item,sup) ;
supply(pencil, bic) = yes ; supply(pen,sup) = yes ;

parameter totsales(dep) ;
totsales(dep) = sum(item$supply(item,bic), sales(dep,item)) ;

The assignment above is used to find the total sales of all departments that sell items supplied by bic. Note that the dynamic
set is used to limit the domain of summation to those for which supply(item,'bic') is true.

3.3 Equations
Dynamic sets can be used inside dollar conditions in equations both as part of the equation algebra, or while defining the
domain of the equation. The first case is similar to the case of assignments discussed in Section Assignments . The latter
case is used to restrict the equation over the domain of a dynamic set. The equation defined in the example from Section
Equations Defined over the Domain of Dynamic Sets can be rewritten with equivalent effect as follows,

prodbal(allr)$r(allr).. activity(allr)*price =e= revenue(allr) ;

The domain of definition of equation prodbal is restricted to those elements that belong to the dynamic set r.

3.4 Filtering through Dynamic Sets

The filtering process explained in previous sections is valid when the conditional set is a dynamic one. Consider the following
two examples as described before,

inventory(item)$subitem1(item) = 25 ;
prodbal(allr)$r(allr).. activity(allr)*price =e= revenue(allr) ;

These statements can be rewritten as,

inventory(subitem1) = 25 ;
prodbal(r).. activity(r)*price =e= revenue(r) ;

4 Set Operations
This section describes how various symbolic set operations can be performed in GAMS using dynamic sets. The Union,
Intersection, Complement, and Difference set operations are described individually in the following subsections. Once again
the example from Section Illustrative Example is used to illustrate each operation.

4.1 Set Union

The symbol + performs the set union operation. Consider the following example,
138 Dynamic Sets

subitem3(item) = subitem1(item) + subitem2(item) ;

The membership of subitem3 is set equal to all the elements of subitem1 and all the elements of subitem2. The operation
above is equivalent to the following longer way of representation,

subitem3(item)=no; subitem3(subitem2)=yes; subitem3(subitem1)=yes;

4.2 Set Intersection

The symbol performs the set intersection operation. Consider the following example,

subitem3(item) = subitem1(item) * subitem2(item) ;

The membership of subitem3 is set equal to only those present in both subitem1 and subitem2. The operation above is
equivalent to the following longer way of representation,

subitem3(item)=yes$(subitem1(item) and subitem2(item)) ;

4.3 Set Complement

The operator not performs the set complement operation. Consider the following example,

subitem3(item) = not subitem1(item) ;

The membership of subitem3 is set equal to all those in item but not in subitem1. The operation above is equivalent to the
following longer way of representation,

subitem3(item)=yes; subitem3(subitem1)=no;

4.4 Set Difference

The operator - performs the set difference operation. Consider the following example,

subitem3(item) = subitem1(item) - subitem2(item) ;

The membership of subitem3 is set equal to all elements that are members of subitem1 but subitem2. The operation
above is equivalent to the following longer way of representation,

subitem3(item)=yes$(subitem1(item)); subitem3(subitem2)=no;

5 Summary
The purpose of set assignments is to make calculations based on given data (the static sets) for use in exception handling. It
is one more example of the principle of entering a small amount of data and building a model up from the most elemental
information.
Chapter 13

Sets as Sequences: Ordered Sets

1 Introduction
In our original discussion of sets in Chapter Set Definition , we said that unless there is a special need to do things differently,
a one-dimensional set should be regarded as an unordered collection of labels. In this chapter we will discuss special features
that can be used when you need to be able to deal with a set as if it were a sequence.
For example, in economic models that explicitly represent conditions in different time periods, it is necessary to refer to the
next or previous time period, because there must be links between the periods. As another example, stocks of capital are
normally tracked through such models by equations of the form 'stocks at the end of period n are equal to stocks at the end
of period n 1 plus net gains during period n'. Location problems, where the formulation may require a representation of
contiguous areas, as in a grid representation of a city, and scheduling problems are other classes of problems in which sets
must also have the properties of sequences.

Attention
Models involving sequences of time periods are often called dynamic models, because they describe how conditions
change over time. This use of the word dynamic unfortunately has a different meaning from that used in connection
with sets, but this is unavoidable.

2 Ordered and Unordered Sets

As with sets used in domain checking, restrictions are imposed when the set needs to be referred as if it were a sequence. The
notion of static sets was introduced already: the set must be initialized with a list of labels enclosed in slashes at the time the
set is declared, and never changed afterwards.

Attention
Ordered sets must be static sets. In other words, no order is possible for dynamic sets.
GAMS maintains one list of unique elements - the labels that are used as elements in one or more sets. The order
of the elements in any one set is the same as the order of those elements in that unique element list. This means
that the order of a set may not be what it appears to be if some of the labels were used in an earlier definition.
The map of your labels in the GAMS order can be seen by putting the compiler directive $onuellist somewhere
before the first set declaration.
A good rule of thumb is that if the labels in a set one wants to be ordered have not been used already, then they
will be ordered.

The map is shown with the other compiler maps after the listing of your program. In the example below we show ordered and
unordered sets and the map showing the order. The input is:
140 Sets as Sequences: Ordered Sets

$onuellist
set t1 / 1987, 1988, 1989, 1990, 1991 /
t2 / 1983, 1984, 1985, 1986, 1987 /
t3 / 1987, 1989, 1991, 1983, 1985 / ;

The map below shows the entry order (the important one) and the sorted order, obtained by sorting the labels into dictionary
order. The single digits on the left are the sequence numbers of the first label on that line.

G e n e r a l A l g e b r a i c M o d e l i n g S y s t e m
Unique Element Listing

Unique Elements in Entry Order

1 1987 1988 1989 1990 1991 1983

7 1984 1985 1986
Unique Elements in Sorted Order
1 1983 1984 1985 1986 1987 1988
7 1989 1990 1991

A set can always be made ordered by moving its declaration closer to the beginning of the program. With these restrictions in
mind, we move on the operations that are used in dealing with sets as sequences.

3 Ord and Card

In Chapter Set Definition, it was explained that labels do not have a numerical value. The examples used were that the label
'1986' does not have a numerical value of 1986 and the label '01' is different from the label '1'. This section introduces two
operators - ord and card that return integer values when applied to sets. While the integer values returned do not represent
the numerical value of the label, they can be used for the same purpose.
The next two subsections describe each of these two functions in turn.

3.1 The Ord Operator

Ord returns the relative position of a member in a set.

Attention
Ord can be used only with a one-dimensional, static, ordered set.

Some examples show the usage.

set t time periods / 1985*1995 /

parameter val(t) ;
val(t) = ord(t);

As a result of the statements above, the value of val('1985') will be 1, val('1986') will be 2 and so on.
A common use of ord is in setting up vectors that represent quantities growing in some analytically specified way. For
example, suppose a country has 56 million people in the base period and population is growing at the rate of 1.5 percent per
year. Then the population in succeeding years can be calculated by using:

population(t) = 56*(1.015**(ord(t) - 1)) ;

It is often useful to simulate general matrix operations in GAMS. The first index on a two dimensional parameter can
conveniently represent the rows, and the second the columns, and order is necessary. The example below shows how to set
the upper triangle of a matrix equal to the row index plus the column index, and the diagonal and lower triangle to zero.
4 Lag and Lead Operators 141

set i row and column labels / x1*x10 /; alias (i,j);

parameter a(i,j) a general square matrix;
a(i,j)$(ord(i) lt ord(j)) = ord(i) + ord(j) ;

3.2 The Card Operator

Card returns the number of elements in a set. Card can be used with any set, even dynamic or unordered ones. The following
example illustrates its use:

set t time periods / 1985*1995 /

parameter s ; s = card(t);

As a result of the statement above, s will be assigned the value 11.

A common use of card is to specify some condition only for the final period, for example to fix a variable. An artificial
example is:

c.fx(t)$(ord(t) = card(t)) = demand(t) ;

which fixes the variable for the last member only: no assignment is made for other members of t. The advantage of this way
of fixing c is that the membership of t can be changed safely and this statement will always fix c for the last one.

4 Lag and Lead Operators

The lag and lead operators are used to relate the current to the next or previous member of a set. In order to use these
operators the set in question must, of course, be ordered. GAMS provides two forms of lag and lead operators

Linear Lag and Lead Operators (+, -)

Circular Lag and Lead Operators (++, --)

The difference between these two types of operators involves the handling of endpoints in the sequence. GAMS provides
some built in facilities to deal with this issue, but in any work involving sequences the user must think carefully about the
treatment of endpoints, and all models will need special exception handling logic to deal with them.
In the linear case, the members of the set that are endpoints are left hanging. In other words, there are no members preceding
the first member or following the last one. This may cause the use of non-existent elements. The next section will describe
how this is handled in GAMS . This form of the lag and lead operators is useful for modeling time periods that do not repeat.
A set of years (say 1990 to 1997) is an example. The operators are + and --.

Attention
GAMS is able to distinguish linear lag and lead operators (+,-) from arithmetic operators by context. To avoid
ambiguity, GAMS does not allow to mix lag and lead operators with arithmetic operators. For example, i + 1 + 1 is
not allowed, but writing i + (1 + 1) would work.

In the circular case, the first and last members of the set are assumed to be adjacent, so as to form a circular sequence of
members. The notion is that 'first - 1' is a reference to 'last' and 'last + 2' is the same as 'first + 1' and so on. All
references and assignments are defined. This is useful for modeling time periods that repeat, such as months of the year or
hours in the day. It is quite natural to think of January as the month following December. Agricultural farm budget models
and workforce scheduling models are examples of applications where circular leads occur naturally. The operators are ++ and
--.
The next two sections will describe the use of these lag and lead operators in assignment statements and in equations
respectively.
142 Sets as Sequences: Ordered Sets

5 Lags and Leads in Assignments

One use of the lag and lead operator is in assignment statements. The use of a lag and lead operator on the right-hand-side of
an assignment is called a reference, while its use in the left-hand-side is called an assignment and involves the definition of a
domain of the assignment. The concepts behind reference and assignment are equally valid for the linear and circular forms
of the lag and lead operator. However, the importance of the distinction between reference and assignment is not pronounced
for circular lag and lead operators because non-existent elements are not used in this case.

Attention
A reference to a non-existent element causes the default value (zero in this case) to be used, whereas an attempt to
assign to a non-existent element results in no assignment being made.

The next two sub-sections provide examples illustrating the use of the linear form of the lag and lead operators for reference
and assignment. Section Circular Lag and Lead Operators will illustrate the use of the circular form of the lag and lead
operator.

5.1 Linear Lag and Lead Operators - Reference

Consider the following example, where two parameters a and b are used to illustrate the linear lag and lead operators for
reference.

set t time sequence / y-1987*y-1991 / ;

parameter a(t), b(t) ;
a(t) = 1986 + ord(t) ;
b(t) = -1; b(t) = a(t-1) ;
option decimals=0; display a, b ;

The option statement suppresses the decimal places from the display. The results are shown below.

---- 6 PARAMETER A
Y-1987 1987, Y-1988 1988, Y-1989 1989, Y-1990 1990, Y-1991 1991

---- 6 PARAMETER B
Y-1988 1987, Y-1989 1988, Y-1990 1989, Y-1991 1990

For a, as expected, the values 1987, 1988 up to 1991 are obtained corresponding to the labels y-1987, y-1988 and so on. b
is initialized to 1.
For b, the assignment is done over all members of t, and for each, the value of a from the previous period is assigned to the
current member of b. If no previous period, as with y-1987, zero is used, and b('y-1987') becomes zero, replacing the
previous value of 1.

5.2 Linear Lag and Lead Operators - Assignment

Consider the following example, where two parameters a and care used to illustrate the assignment of linear lag and lead
operators.

set t time sequence / y-1987*y-1991 / ;

parameter a(t), c(t) ;
a(t) = 1986 + ord(t) ;
c(t) = -1; c(t+2) = a(t) ;0; display a, c;

The results are shown below,

5 Lags and Leads in Assignments 143

---- 6 PARAMETER A
Y-1987 1987, Y-1988 1988, Y-1989 1989, Y-1990 1990, Y-1991 1991

---- 6 PARAMETER C
Y-1987 -1, Y-1988 -1, Y-1989 1987, Y-1990 1988, Y-1991 1989

The assignment to ais explained in Section Linear Lag and Lead Operators - Reference . The assignment to c is different. It is
best to spell it out in words. For each member of t in sequence, find the member of c associated with t+2. If it exists, replace
its value with that of a(t). If not (as with y-1990 and y-1991) make no assignment. The first member of t is y+1987, and
therefore the first assignment is made to c('y-1989') which takes the value of a('y-1987'), viz., 1987. No assignments
at all are made to c('y-1987') or c('y-1988'): these two retain their previous values of 1.
The lag (or lead) value does not have to be an explicit constant: it can be arbitrary expression, provided that it evaluates to
an integer. If it does not, error messages will be produced. A negative result causes a switch in sense (from lag to lead, for
example). The following is guaranteed to set d(t) to all zero:

d(t) = d(t - ord(t));

5.3 Circular Lag and Lead Operators

The following example illustrates the use of circular lag and lead operators.

set s seasons / spring, summer, autumn, winter /;

parameter val(s) /spring 10, summer 15, autumn 12, winter 8 /
lagval2(s)
leadval(s);
lagval2(s) = -1 ; lagval2(s) = val(s--2) ;
leadval(s) = -1 ; leadval(s++1) = val(s) ;
option decimals=0; display val, lagval2, leadval;

The results are shown below,

---- 7 PARAMETER VAL

SPRING 10, SUMMER 15, AUTUMN 12, WINTER 8

---- 7 PARAMETER LAGVAL2

SPRING 12, SUMMER 8, AUTUMN 10, WINTER 15

---- 7 PARAMETER LEADVAL

SPRING 8, SUMMER 10, AUTUMN 15, WINTER 12

The parameter lagval2 is used for reference while lagval1if used for assignment. Notice that the case of circular lag and
lead operators does not lead to any non-existent elements. The difference between reference and assignment is therefore not
important. Note that the following two statements from the example above,

lagval2(s) = val(s--2) ;
leadval(s++1) = val(s) ;

are equivalent to

lagval2(s++2) = val(s) ;
leadval(s) = val(s--1) ;

The use of reference and assignment have been reversed with no difference in effect.
144 Sets as Sequences: Ordered Sets

6 Lags and Leads in Equations

The principles established in the previous section follow quite naturally into equation definitions. A lag or lead operation in
the body of an equation (to the right of the '..' symbol) is a reference, and if the associated label is not defined, the term
vanishes. A lag or lead to the left of the '..' is a modification to the domain of definition of the equation. The linear form
may cause one or more individual equations to be suppressed.

Attention
All lag and lead operands must be exogenous.

The next two sub-sections provide examples illustrating the use of the linear form of the lag and lead operators in equations
for reference and to modify the domain of its definition. Section Circular Lag and Lead Operators will illustrate the use of the
circular form of the lag and lead operator in equations.

6.1 Linear Lag and Lead Operators - Domain Control

Consider the following example adapted from [RAMSEY],

sets t time periods /1990*2000/

tfirst(t) first period
tlast(t) last period;

tfirst(t) = yes$(ord(t) eq 1);

tlast(t) = yes$(ord(t) eq card(t) ) ;
display tfirst, tlast;

variables k(t) capital stock (trillion rupees)

i(t) investment (trillion rupees per year) ;

equations kk(t) capital balance (trillion rupees)

tc(t) terminal condition(provides for post-term growth) ;

kk(t+1).. k(t+1) =e= k(t) + i(t) ;

tc(tlast).. g*k(tlast) =l= i(tlast);

The declaration of t is included, as are a couple of dynamic sets that are used to handle the first and last periods (terminal
conditions) in a clean way.
The interesting equation is kk, the capital balance. The set t contains members 1990 to 2000, and so there will be a capital
stock constraint for 1991 to 2000. Spelling out the constraint for 1991,

k(1991) =e= k(1990) + i(1990) ;

The lead operator on the domain of definition has restricted the number of constraints generated so that there are no references
to non-existent variables: the generated problem will have 10 kk constraints defining the relationship between the 11 k capital
values.
The other interesting point in the [RAMSEY] excerpt is that the constraint tc is explicitly defined only for the final period
because of the assignment to the set tlast. Notice the use of dynamic sets to control the domain of the two equations. The
set tfirst is also used in other parts of the model to set initial conditions, particularly the capital stock in the first period,
k('1990').

6.2 Linear Lag and Lead Operators - Reference

In the example discussed in Section Linear Lag and Lead Operators - Domain Control equation kk can be rewritten with
equivalent effect as
7 Summary 145

kk(t)$(not tfirst(t)).. k(t+1) =e= k(t) + i(t) ;

The dollar condition will cause one of the individual equations to be suppressed.
However, note that using lags and leads in the equation domain will always cause one or more individual equations to
be suppressed, and this may not be desirable in every case. Consider the following modified set of constraints to the one
discussed in the previous example. It is expressed with the lag and lead operators being used to control the domain of the
equation definition.

kk(t+1).. k(t+1) =e= k(t) + i(t);

kfirst(tfirst) k(tfirst) =e= k0 ;

Here, the important boundary is the one at the beginning of the set rather than at the end. This can be expressed more
compactly as

kk(t).. k(t) =e= k(t-1) + k0$tfirst(t) + i(t-1);

In general, the choice between using lag and lead operators as reference or in domain control is often a matter of taste.

6.3 Circular Lag and Lead Operators

In the case of circular lag and lead operators, the difference between its use in domain control and as reference is not important
because it does not lead to any equations or terms being suppressed. Consider the following artificial example,

set s seasons / spring, summer, autumn, winter /;

variable prod(s) amount of goods produced in each season

avail(s) amount of goods available in each season
sold(s) amount of goods sold in each season ;

equation matbal(s) ;

matbal(s).. avail(s++1) =e= prod(s) + sold(s) ;

In this example, four individual examples are generated. They are listed below.

avail(summer) =e= prodn(spring) + sold(spring) ;

avail(autumn) =e= prodn(summer) + sold(summer) ;
avail(winter) =e= prodn(autumn) + sold(autumn) ;
avail(spring) =e= prodn(winter) + sold(winter) ;

Note that none of the equations are suppressed.

7 Summary
This chapter introduced the concept of ordering in sets. All the features in GAMS that dealt with this issue including the ord
and card functions, as well as the linear and circular forms of the lag and lead operators were described in detail.
146 Sets as Sequences: Ordered Sets
Chapter 14

The Display Statement

1 Introduction
In this chapter we will provide more detail about display statements, including the controls that a user has over the layout
and appearance of the output. These controls are a compromise to provide some flexibility. The display statement will
not provide a publication quality reporting function, but is instead aimed for functionality that is easy to use, and provides
graceful defaults. The execution of the display statement allows the data to be written into the listing file only.

2 The Syntax
In general, the syntax in GAMS for the display statement is:

display ident-ref | quoted text {, ident-ref | quoted text}

Ident-ref means the name without domain lists or driving indices of a set or parameter, or a sub-field of an equation
or variable. The identifier references and the text can be mixed and matched in any order, and the whole statement can be
continued over several lines.
The output produced by a display consists of labels and data. For sets, the character string yes (indicating existence) is used
instead of values.

Attention
Only the non-default values are displayed for all data types.

The default value is generally zero, except for the .lo and .up subtypes of variables and equations. The default values
for these are shown in the following table.
Table 1: Default values for .lo and .up subtypes

Type .lo .up

Variable positive 0 +INF
positive 0 +INF
free -INF +INF
negative -INF 0
integer 0 100
binary 0 1
Equation =g= 0 +INF
=n= -INF +INF
148 The Display Statement

Type .lo .up

=c= 0 +INF
=l= -INF 0
=e= 0 0

3 An Example
An example of a display statement is given below.

set s /s1*s4/ , t /t5*t7/ ;

parameter p(s) / s1 0.33, s3 0.67 / ;
parameter q(t) / t5 0.33, t7 0.67 / ;
variable v(s,t) ; v.l(s,t) = p(s)*q(t);
display first a set, s, then a parameter,p,
then the activity level of a variable,v.l;

The resulting listing file will contain the following section that corresponds to the display statement.

---- 5 first a set

---- 5 SET S

S1, S2, S3, S4

---- 5 then a parameter

---- 5 PARAMETER P

S1 0.330, S3 0.670

---- 5 then the activity level of a variable

---- 5 VARIABLE V.L

T5 T7

S1 0.109 0.221
S3 0.221 0.449

Note that only the non-zero values are displayed. In the case of multi-dimensional identifiers, the data is reported in a tabular
form that is easy to read.

4 The Label Order in Displays

The default layout of a display for identifiers of different dimensionality is summarized in table Table 2 . The figures in the
table refer to the index position in the domain list of the identifier. As an example, if we display c, where c has been declared
as c(i,j,k,l), then the i labels (the first index) will be associated with the planes or individual sub-tables, the j and k with
the row labels, and the l (the fourth and last index) with the column headings.
Table 2: Default layout of display output

Numbers of Indices Plane Index Position(s) on the Row Column

1 List Format 1
2 - 1 2
4 The Label Order in Displays 149

Numbers of Indices Plane Index Position(s) on the Row Column

3 - 1,2 3
4 1 2,3 4
5 1,2 3,4 5
6 1,2,3 4,5 6

For 7 to 10 indices, the natural progression is followed. The labels vary slowest for the first index position, and quickest for
the highest. Within each index position the order is the GAMS entry order of the labels.
The order of the indices is always as in the declaration statement for the symbol. One can declare them in the order that is
found appealing, or make an assignment to a new identifier with a different order.

Attention
The only way to change the order in which the labels for each index position appear on display output is to change
the order of appearance of the labels in the GAMS program. This is most easily done by declaring a set whose only
purpose is to list all the labels in the order that is needed. Make this set the very first declaration in the GAMS program.

4.1 Example
Consider the following example. X has four dimensions or index positions. It is initialized using parameter format and then
displayed as shown below:

set i first index /first, second /

j second index /one, two, three /
k third index /a, b /
l fourth index /i, ii / ;

parameter x(i,j,k,l) a four dimensional structure /

second.one.a.i +inf, first .three.b.i -6.3161
first .one.b.i 5.63559, second.two .b.i 19.8350
second.one.b.ii -17.29948, first .two .b.ii 10.3457
first .two.a.ii 0.02873, second.one .a.ii 1.0037
second.two.a.ii +inf, first .two .a.i -2.9393
first .one.a.ii 0.00000 / ;
display x;

This code fragment produces the following output:

---- 12 PARAMETER X a four dimensional structure

INDEX 1 = first

i ii

one .b 5.636
two .a -2.939 0.029
two .b 10.346
three.b -6.316

INDEX 1 = second

i ii
150 The Display Statement

one.a +INF 1.004

one.b -17.299
two.a +INF
two.b 19.835

Notice that there are two sub-tables, one for each label in the first index position. Note that the zero in the list for
x('first','one','a','ii') has vanished, since zero values are suppressed in each sub-table separately. The order of
the labels is not the same as in the input data list.

5 Display Controls
GAMS allows the user to modify the number of row and column labels in the display listing, as well as the accuracy of the
data being displayed. The global display controls allows the user to affect more than one display statement. If specific data
need to be listed in a particular format, the local display controls can be used to over-ride the global controls. The next two
sub-sections will deal with each of these display controls in turn.

5.1 Global Display Controls

The simplest of these options is the one controlling the number of digits shown after the decimal point. It affects numbers
appearing in all display output following the option statement, unless changed for a specific identifier as shown below. The
general form of the statement is: 'option decimals = value;' where value is an integer between 0 and 8. If you use 0,
the decimal point is suppressed as well. The width of the number field does not change, just the number of decimals, but this
may cause numbers which would normally be displayed in fixed to appear in E-format, i.e., with the exponent represented
explicitly.
Consider the following extension to the example discussed in the previous section.

option decimals = 1; display x ;

GAMS has rounded or converted numbers to E-format where necessary and the output is as follows:

---- 12 PARAMETER X a four dimensional structure

INDEX 1 = first

i ii

one .b 5.6
two .a -2.9 2.873000E-2
two .b 10.3
three.b -6.3

INDEX 1 = second

i ii

one.a +INF 1.0

one.b -17.3
two.a +INF
two.b 19.8
5 Display Controls 151

5.2 Local Display Control

It is often more useful to control the number of decimals for specific identifiers separately. Using a statement whose general
form can do this:

option ident:d-value:

Ident represent the name of a parameter, variable or equation, and d-value must be (as before) in the range 0 and
8 . Exactly d-value places of decimals will be shown on all displays of ident that follow. This form can be extended to
control layout of the data. The general form is:

option ident:d-value:r-value:c-value ;

Here r-value means the number of index positions that are combined to form the row label and c-value means the number
on the column headers.
The example discussed in the previous section is further extended in order to illustrate the local display control.

option x :5:3:1; display x;

and the output:

---- 12 PARAMETER X a four dimensional structure

i ii
first .one .b 5.63559
first .two .a -2.93930 0.02873
first .two .b 10.34570
first .three.b -6.31610
second.one .a +INF 1.00370
second.one .b -17.29948
second.two .a +INF
second.two .b 19.83500

Five places of decimals are shown, and three labels are used to mark the rows and one on the column. Since this is a
four-dimensional structure, there are no remaining indices to be used as sub-table labels (on the plane), and we now have the
results in one piece. The option statement is checked for consistency against the dimensionality of the identifier, and error
messages issued if necessary. Here is an example that puts two indices on each of the row and column labels, and retains five
decimal places:

option x:5:2:2; display x ;

The output is :

---- 12 PARAMETER X a four dimensional structure

a.i a.ii b.i b.ii

first .one 5.63559

first .two -2.93930 0.02873 10.34570
first .three -6.31610
second.one +INF 1.00370 -17.29948
second.two +INF 19.83500
152 The Display Statement

5.3 Display Statement to Generate Data in List Format

This is a special use of the local display controls to generate data in list format using the display statement. This is when
all the labels are spelled out for each value as in the parameter style of data initialization. The format of the option is
option:ident:d-value:0:c-value; and in this case the c-value specifies the maximum number of items displayed on
a line. The actual number will depend on the page width and the number and length of your labels.
Using the same example as in the previous sections, the following extension:

option x:5:0:1; display x;

changes the output to look like below:

---- 12 PARAMETER X a four dimensional structure

first .one .b.i 5.63559

first .two .a.i -2.93930
first .two .a.ii 0.02873
first .two .b.ii 10.34570
first .three.b.i -6.31610
second.one .a.i +INF
second.one .a.ii 1.00370
second.one .b.ii -17.29948
second.two .a.ii +INF
second.two .b.i 19.83500

This output nicely illustrates the label order used. The first index varies the slowest, the last the fastest, and each one runs
from beginning to end before the next one to the left advances. This ordering scheme is also used on equation and column
lists and on the solution report, all produced by the solve statement.
Chapter 15

The Put Writing Facility

1 Introduction
In this chapter, the put writing facility of the GAMS language is introduced. The purpose of this writing facility is to
output individual items under format control onto different files. Unlike the display statement, the entire set of values for
indexed identifiers cannot be output using a single put statement (identifiers are the names given to data entities such as
the names for parameters, sets, variables, equations, models, etc). While its structure is more complex and requires
more programming than is required for the display statement, there is much greater flexibility and control over the output of
individual items.
In this chapter, the working of the put writing facility is described as well as the syntax for accessing files and globally
formatting documents using file suffixes for various attributes of a file. The put writing facility enables one to generate
structured documents using information that is stored by the GAMS system. This information is available using numerous
suffixes connected with identifiers, models, and the system. Formatting of the document can be facilitated by the use of file
suffixes and control characters.
The put writing facility generates documents automatically when GAMS is executed. A document is written to an external
file sequentially, a single page at a time. The current page is stored in a buffer, which is automatically written to an external
file whenever the page length attribute is exceeded. Consequently, the put writing facility only has control of the current
page and does not have the ability to go back into the file to alter former pages of the document. However, while a particular
page is current, information placed on it can be overwritten or removed at will.

2 The Syntax
The basic structure of the put writing facility in its simplest form is:

file fname(s);
put fname;
put item(s);

where fname represents the name used inside the GAMS model to refer to an external file. Items are any type of output such
as explanatory text, labels, parameters, variable or equation values. In the basic structure shown above, the first line defines
the one or more files which you intend to write to. The second line assigns one of these defined files as the current file, that is
the file to be written to. Lastly, the third line represents the actual writing of output items to the current file.

3 An Example
It is instructive to use a small example to introduce the basics of the put writing facility. The example will be based on the
transportation model [TRNSPORT]. The following program segment could be placed at the end of the transportation model
154 The Put Writing Facility

to create a report:

file factors /factors.dat/, results /results.dat/ ;

put factors ;
put Transportation Model Factors///
Freight cost , f,
@1#6, Plant capacity/;
loop(i, put @3, i.tl, @15, a(i)/);
put /Market demand/;
loop(j, put @3, j.tl, @15, b(j)/);

put results;
put Transportation Model Results// ;
loop((i,j), put i.tl, @12, j.tl, @24, x.l(i,j):8:4 /);

In the first line, the internal file names factors and results are defined and connected to the external file names factors.dat
and results.dat. These internal file names are used inside the model to reference files, which are external to the model.
The second line of this example assigns the file factors.dat as the current file, that is the file which is currently available
to be written to.
In the third line of the example, writing to the document begins using a put statement with the textual item 'Transportation
Model Factors'. Notice that the text is quoted. The slashes following the quoted text represent carriage returns. The
example continues with another textual item followed by the scalar f. Notice that these output items are separated with
commas. Blanks, commas, and slashes serve as delimiters for separating different output items. As mentioned above, the
slash is used as a carriage return. Commas and blank spaces serve as item delimiters. These delimiters leave the cursor at the
next column position in the document following the last item written. In most cases, the blank and the comma can be used
interchangeably; however, the comma is the stronger form and will eliminate any ambiguities.
In the fifth line of the program above, the cursor is repositioned to the first column of the sixth row of the output file where
another textual item is written. The cursor control characters # and @ serve to reposition the cursor to a specific row or column
as designated by the row or column number following the cursor control character. Lastly, the put statement is terminated
with a semicolon.
Next, the parameters a and b are written along with their corresponding set labels. Only one element of the index set can be
written using a put. To write the entire contents of the parameters a and b, the put statement is embedded inside a loop
which iterates over the index set. In the example above, the set element labels are identified using their set identifier and the
suffix .tl. As can be seen, the set element labels are located starting in the third column and the parameter a at column 15.
The example continues with the display of another quoted textual item followed by the parameter b. When executed, the
factors.dat file will look like:

Transportation Model Factors

Freight cost 90.00

Plant capacity
seattle 350.00
san-diego 600.00

Market demand
new-york 325.00
chicago 300.00
topeka 275.00

This output has been formatted using the default file format values. The methods to change these defaults will be described
later in this chapter.
In the last two lines of the example, the file results.dat is made current and the values associated with the variable x along
with their corresponding set element index labels are written line by line. The output results of the variable x are formatted
4 Output Files 155

by specifying a field width of eight spaces with four of these spaces reserved for the decimal. Notice that the local formatting
options are delimited with colons. The results.dat file will look like:

Transportation Model Results

seattle new-york 0.0000

seattle chicago 300.0000
seattle topeka 0.0000
san-diego new-york 325.0000
san-diego chicago 0.0000
san-diego topeka 275.0000

With just this brief introduction to the put writing facility, it is easy to envision its many uses such as report writing, providing
output to a file for use by another computer program, or simply the display of intermediate calculations. But, the surface of
the put writing facility has just barely been scratched. In the sections that follow, the many features and structure of the put
writing facility are described in more detail, along with examples.

4 Output Files
As noted earlier, the put statement allows the user to write to external files. This section describes the various features related
to the use of external files.

4.1 Defining Files

The complete syntax for defining files is:

file fname text / external file name /

where file is the keyword used to define files. Fname is the internal file name and is used inside the GAMS model to refer to
an external file. External files are the actual files that output is written to. During file declaration, the external file name and
explanatory text are optional. When the external file name is omitted, GAMS will provide a system specific default external
file name, often fname.put. Note that multiple files can be defined using a single file statement. Consider the following
example:

file class1
class2 this defines a specific external file /report.txt/
con this defines access to the console (screen) for PC systems;

The first output file is recognized in the model by the name class1 and corresponds to the default file class1.put for a PC
system. The second output file is recognized in the model by the name class2 and it corresponds to the defined external file
report.txt. Lastly, the special internal file name con is defined to write output to the console (screen) for a PC systems.
Writing to the screen can be useful to advise the user of various aspects of the model during the model's execution.

4.2 Assigning Files

The put statement is used both to assign the current file and to write output items to that file. The complete syntax for using
the put statement is:

put fname item(s) fname item(s) . . . ;

As indicated by this syntax, multiple files can be sequentially written using a single put statement. Note that only one file is
current at a time. After the output items following an internal file name are written, the current file is reassigned based on the
next internal file name in the statement. The last internal file name used in a put statement remains as the current file until a
subsequent put statement uses an internal file name.
156 The Put Writing Facility

4.3 Closing a File

The keyword putclose is used to close a file during the execution of a GAMS program. The syntax is as follows:

putclose myfile item(s)

where myfile is the internal name of the file to be closed, and item(s) are the final entries into the file before it is closed.
If the internal file name is omitted from the putclose statement, the current put file is closed. Note that after using the
putclose command, the file does not have to be redefined in order to use it again. Simply make the file current and use put
statements as would be done normally. Of course, the existing file will either be overwritten or appended to depending on the
value of the append file suffix.

Attention
One application where this is useful is to write the solver option file from within the GAMS model. Option file
statements can be written using put and the file closed with a putclose prior to the solve statement. This makes the
option file available for use by the solver.

The following example shows the creation and closing of an option file for the MINOS solver:

file opt Minos option file / minos.opt /;

put opt;
put Iteration limit 500/
Feasibility tolerance 1.0E-7/ ;
putclose opt;

This program segment would be placed inside the GAMS model prior to the solve statement.

4.4 Appending to a File

The put writing facility has the ability to append to or overwrite an existing file. The file suffix .ap determines which
operation occurs. The default suffix value 0 overwrites the existing file while the value 1 causes appending to the file. Let's
consider our report.txt file to be an existing file.
Using the following statement appends output items to it:

class2.ap = 1;

Any items put into report.txt will from that point on be added to the end of the existing file contents. If the file had not
existed, the file would be created.

5 Page Format
The pages within files can also be structured using file suffixes to specify many attributes such as the printing format, page
size, page width, margins, and the case which text is displayed in. The following file suffixes can be used for formatting:
print control (.pc) Used to specify the format of the external file. The options 4,5,6, and 8 create delimited
files, which are especially useful when preparing output for the direct importation into other computer programs
such as spreadsheets.
0 Standard paging based on the current page size. Partial pages are padded with blank lines. Note
that the .bm file suffix is only functional when used with this print control option.
1 FORTRAN page format. This option places the numeral one in the first column of the first row of
each page in the standard FORTRAN convention.
6 Page Sections 157

2 Continuous page (default). This option is similar to .pc option zero, with the exception that
partial pages in the file are not padded with blank lines to fill out the page.
3 ASCII page control characters inserted.
4 Formatted output; Non-numeric output is quoted, and each item is delimited with a blank space.
5 Formatted output; Non-numeric output is quoted, and each item is delimited with commas.
6 Formatted output; Non-numeric output is quoted, and each item is delimited with tabs.
7 Fixed width; Fills up line with trailing blanks.
8 Formatted output; Each item is delimited with a blank space.
page size (.ps) Used to specify the number of rows (lines) which can be placed on a page of the document.
Can be reset by the user at any place in the program. However, an error will result if set to a value less than the
number of rows which have already been written to the current page. Maximum value is 130. The default value
is 60
page width (.pw) Used to specify the number of columns (characters) which can be placed on a single row of
the page. Can be reset by the user at any place in the program. However, an error will result if set to a value less
than the number of rows or columns which have already been written to the current page. The default value is
255.
top margin (.tm) Number of blank lines to be placed at the top margin of the page. These lines are in addition
to the number of lines specified in the .ps file suffix. Default value is 0.
bottom margin (.bm) Number of blank lines to be placed in the bottom margin of the page. These lines are in
addition to the number of lines specified in the .ps file suffix. This is functional with .pc option 0 only. Default
value is 0.
alphabetic case (.case) Used to specify the case in which alphabetic characters are displayed in the output file.
0 (default) Causes mixed case to be displayed.
1 Causes the output to be displayed in upper case regardless of the case used for the input.
To illustrate the use of these file suffixes, the following example involves formatting report.txt so that the pages are 72
spaces wide with 58 lines of output, an additional top margin of 6 lines, using ASCII page control characters (inserted every
64 lines), and with the output displayed in upper case.

file class2 /report.txt/ ;

class2.pw = 72; class2.ps = 58; class2.tm = 6;
class2.pc = 3; class2.case = 1;

Attention
Using a value of 4, 5, or 6 for the print control suffix (.pc) will cause data to be squeezed and therefore will ignore
spacing information provided by the user through the @ character. However, these values can be used to pass data on to
be read by spreadsheets.

6 Page Sections
There are three independent writing areas on each page of a document. These areas are the title block, the header block, and
the window. This is quite useful when there are sections of a page which remain relatively constant throughout a document.
Title and header blocks are often used to provide organizational information in a document with the window being used for
specific reporting.
These writing areas are always sequentially located on the page in the order shown on the following diagram.

+-----------------+
| Title Block |
158 The Put Writing Facility

+-----------------+
| Header Block |
+-----------------+
| |
| Window |
| |
+-----------------+

It is important to note that the title and header blocks are essentially the same as the window and use exactly the same syntax
rules. However, the window is required in each page of your document, while the title and headers are optional. Also note
that once the window is written to, any further modifications of the title or header blocks will be shown on subsequent pages
and not the current page. Writing to the window is what ultimately forces a page to be written.
In the illustrative example described in Section An Example , all the data was written to the window. A title block might
have been included, if more elaboration were needed, to provide the model name along with the page number. In addition, a
header block might have been used to display a disclaimer or an instruction, which we wanted consistently, repeated on every
page. Once this information is placed in the title or header blocks, it is displayed on each page thereafter unless modified.
This could be especially useful for a long document covering many pages.

6.1 Accessing Various Page Sections

Each of these areas of a page are accessed by using different variations of the keyword put. These variations are:

Keyword Description
puttl write to title block
puthd write to header block
put write to window

The size of any area within a given page is based entirely on the number of lines put into it. Note that the total number of
lines for all areas must fit within the specified page size. If the total number of lines written to the title and header block
equals or exceeds the page size, an overflow error will be displayed in the program listing. When this occurs, this means
there is no room remaining on the page to write to the window.
As mentioned above, the syntax for writing an output item to any of the three possible writing areas of the page is basically the
same, the only difference being the choice of put keyword. This is illustrated by writing to the title block of our report.dat
file:

puttl class2 GAMS Put Example ;

In this case, the text 'GAMS Put Example' has been placed in the first column of the first row of the title block. Any
subsequent pages in the report.dat file will now start with this information.

Attention
If the title block was modified or the header block was started after the window of the current page has been written to,
these modifications would appear in the next page and not the current page.

6.2 Paging
Paging occurs automatically whenever a page is full. However, note that the window must be used in order for the page to be
written to the output file. When a page has no output in its window, the page is not written to file regardless of whether there
are output items in the title or header blocks. To force a page that has an empty window out to file, simply write something
innocuous to the window such as:
8 System Suffixes 159

put ;

Now the window of the page has been initiated and it will be written.

7 Positioning the Cursor on a Page

The cursor is positioned at the space immediately following the last character written unless the cursor is specifically moved
using one of the following cursor control characters:

Keyword Description
Move cursor position to row n of current page
#
Move cursor position to column n of current line
@n
Move cursor to first column of next line. Also acts as a delimiter between output items
/

In addition to numerals, any expression or symbol with a numeric value can be used to follow the # and @ characters. The
following example illustrates the use of these position controls to write out the value of a parameter a(i,j) in a tabular form:

file out; put out;

scalar col column number /1/ ;
loop(i,
loop (j, put @col a(i,j); col=col+10; ) ; put / ;
) ;

8 System Suffixes
The complete list of system suffixes that can be used to recover information about the GAMS run are:

Suffix Description
.date program execution date
.ifile input file name
.ofile output file name
.page current file page
.rdate restart file date
.rfile restart file name
.rtime restart file time
.sfile save file name
.time program execution time
.title title of the model as specified by $title

As an illustration, consider the example discussed in the previous section. One can add page numbers to the title of the report
file by modifying the puttl statement to read

puttl class2 GAMS Put Example, @65,page ,system.page ///;

160 The Put Writing Facility

This causes the word page followed by the page number to appear on the title of every page starting at column 65.

9 Output Items
Output items for the put statement are of the following forms:

Item Description
text Any quoted text, set element label or text, any identifier symbol text or contents of the system
suffixes.
numeric Values associated with parameters, variables, equations, or any of the model suffixes.
set values Represent existence of set elements and carry the values yes or no only.

The methods for identifying and using each of these different types of output items are described in the following sub-sections.

9.1 Text Items

Output items, which are quoted text, are any combination of characters or numbers set apart by a pair of single or double
quotes. However, the length of quoted text, as well as any output item, has a limit. No portion of the output item can be
placed outside of the page margin. When the page width is exceeded, several asterisks are placed at the end of the line and a
put error is recorded in the program listing.
In addition to quoted text, the output of other text items is possible through the use of system and identifier suffixes. The
identifier suffixes are:
identifier symbol text (.ts) Displays the text associated with any identifier
set element labels (.tl) Displays the individual element labels of a set
set element text (.te(index)) Displays the text associated with an element of a set. Notice that the .te suffix
requires a driving index. This driving index controls the set, which will be displayed and does not necessarily
have to be the same as the controlled set. Often a subset of indices of the controlled set is used.
text fill (.tf) Used to control the display of missing text for set elements.
0 suppresses the fill of missing explanatory text with element names leaving blanks
1 results in blank entries when an element is referenced which does not exist and does the default
fill otherwise
2 (default) always fills empty explanatory text with the element name
3 always fills the .te output with the element names not using the defined explanatory text
4 puts out the .te as when 3 in quotes with comma separators
5 same as 4 with periods as separators
6 same as 4 with blanks as separators
The following example illustrates these ideas:

file out; put out;

set i master set of sites / i1 Seattle, i2 Portland
i3 San Francisco, i4 Los Angeles
i5 /
j subset of sites / i3 * i5 / ;
put j.ts /;
loop(j, put j.tl, i.te(j) /);
9 Output Items 161

The resulting file out.put will look like:

subset of sites
i3 San Francisco
i4 Los Angeles
i5 i5

In this example, the symbol text for the identifier of the subset j is written first. This is followed with the labels for the subset
j and the associated element text found in its domain, that is, the set i. Notice the driving set j is used for the element text
specification of the set i. Since there was no set element text associated with the i5 element of set i, the set element label
was displayed again. By placing the following before the last line:

out.tf = 0;

The missing element text is now no longer replaced with the label text. The resulting file out.put file would now look like:

subset of sites
i3 San Francisco
i4 Los Angeles
i5

9.2 Numeric Items

The syntax used for the display of numeric items is generally easier to work with. To output a parameter, only the identifier
along with its index set (as appropriate) has to be used. To output a variable or equation value, the identifier is combined with
one of the variable and equation suffixes. The variable and equation suffixes are:

Suffix Description
.l level or marginal value
.lo lower bound
.m marginal or dual value
.prior priority
.scale scaling
.up upper bound

9.3 Set Value Items

Set value items are easy to work with. To output the set value, only the identifier along with its index set has to be used. In
the example from Section Text Items , consider altering the loop statement to read:

loop(i, put i.tl, j(i), ,i.te(i) /);

The resulting output file looks as follows:

subset of sites
i1 NO Seattle
i2 NO Portland
i3 YES San Francisco
162 The Put Writing Facility

i4 YES Los Angeles

i5 YES

The second columns represents whether the element belongs to set jor not.

10 Global Item Formatting

It is often important to be able to control the display format of output items. In this section we describe how this is done. For
formatting purposes, output items are classified into four categories. These are labels, numeric values, set values, and text.
For each, global formatting of the field width and field justification is possible.

10.1 Field Justification

The possible global justifications are right (value 1), left (value 2), and center(value 3). The field justification is represented
by the following file suffixes:

Suffix Description
.lj label justification (default 2)
.nj numeric justification (default 1)
.sj set value justification (default 1)
.tj text justification (default 2)

10.2 Field Width

This is done using the following file suffixes:

Suffix Description
.lw label field width (default 12)
.nw numeric field width (default 12)
.sw set value field width (default 12), (maximum 20)
.tw text field width (default 0)

The field width is specified with the number of spaces to be allocated to the field. Variable length field widths are possible by
using a suffix value of 0. This forces the field width to match the exact size of the item being displayed. If a textual output
item does not fit within the specified field, truncation occurs to the right. For numeric output items, the decimal portion of a
number is rounded or scientific notation used to fit the number within the given field. If a number is still too large, asterisks
replace the value in the output file.
As an example, to set the global numeric field width to four spaces from its default of 12 in the file out.put, we would use
the following statement:

out.nw = 4;
12 Additional Numeric Display Control 163

11 Local Item Formatting

It is often useful to format only specific put items. For this, we use the local format feature, which overrides global format
settings. The syntax of this feature is as follows:

item:{<>}width:decimals;

The item is followed by a justification symbol, the field width, and the number of decimals to be displayed. The
specification of the number of decimals is only valid for numeric output. The following local justification symbols are
applicable:

Symbol Description
> right justified
< left justified
<> center justified

Omitting any of the components causes their corresponding global format settings to be used. As with global formatting, when
the field width is given a value of 0, the field width is variable in size. The item, width, and decimals are delimited with
colons as shown above. The use of the local format feature as well as the inclusion any of the components for justification,
field width, or the number of decimals is entirely optional.
The following example shows some examples of the local formatting feature:

* default justification and a field width of variable size

* with no decimals
loop(i, put dist(i):0:0 /);

put Right justified comment:>50,

Center justified truncated comment:<>20;

* left justified scalar with a six space field width and

* two decimals
put f:<6:2 ;

12 Additional Numeric Display Control

In addition to the numeric field width and the numeric justification as mentioned in the previous section, the following file
suffixes can also be globally specified for numeric display:
display control
number of decimals displayed (.nd) Sets the number of decimals displayed for numeric items. A value of 0
results in only the integer portion of a number being displayed. The maximum value is 10. The default value is 2.
numeric round format (.nr) Allows one to display a numeric value in scientific notation, which would
otherwise be displayed as zero because of being smaller than the number of decimals allowed by the .nd suffix.
This situation occurs when a number is smaller than the .nd specification, but is larger than the zero tolerance
level set by .nz. In many situations, it is important to know that these small values exist. The default is 1.
0 displayed in F or E format
1 rounded to fit fields
2 displayed in scientific notation
164 The Put Writing Facility

numeric zero tolerance (.nz) Sets the tolerance level for which a number will be rounded to zero for display
purposes. When it is set equal to zero, rounding is determined by the field width. Default value is 1.0e-5.
The maximum size of a displayed number must fit within 20 spaces using at most 10 significant digits. The remaining 10
spaces are used for the sign, exponential notation, or padding with zeros.

12.1 Illustrative Example

The following illustrative example shows the results of different combinations of these numeric file suffixes. The example
uses five combinations of the numeric file suffixes .nd, .nz, .nr, and .nw. Four number values, each of which is shifted by
three decimal places from its predecessor, are used with these suffix combinations. The combinations are chosen to show
various format results when these suffix values are used together in put statements:

set c suffix combinations / comb1 * comb6 /

v value indices / value1* value3 / ;

table suffix(c,*) numeric suffix combinations

nd nz nr nw
comb1 3 0 0 12
comb2 3 1e-5 0 12
comb3 3 1e-5 1 12
comb4 8 0 0 10
comb5 6 1e-5 1 12
comb6 0 1e-5 1 12 ;

parameter value(v) test values

/ value1 123.4567
value2 0.1234567
value3 0.0001234567 / ;

file out; put out; out.nj=2; out.lw=10; out.cc=11;

loop (v, put v.tl:21);
loop (c,
out.nd=suffix(c,"nd");
out.nz=suffix(c,"nz");
out.nr=suffix(c,"nr");
out.nw=suffix(c,"nw");
put / c.tl;
loop (v,
put @(ord(v)*21-10), value(v)
)
);

For readability, the numeric values have purposely been made left justified using the .nj suffix since the numeric field width
is changed as the model goes through the suffix combinations. The following is the resulting file out.put, which shows the
value/suffix combinations:

value1 value2 value3

comb1 123.457 0.123 1.2345670E-4
comb2 123.457 0.123 1.2345670E-4
comb3 123.457 0.123 0.000
comb4 1.23457E+2 0.12345670 0.00012346
comb5 123.456700 0.123457 0.000123
comb6 123 0 0
13 Cursor Control 165

Notice that in comb1, the display of values switch to exponential notation when a value becomes smaller than the number of
decimal places allowed. This is triggered by the suffix .nr being set to zero. Of particular interest is value3 for comb2 and
comb3. Value3 is greater than the zero tolerance level in .nz, but smaller than the number of decimals allowed by .nd. In
comb2, since .nr is set to zero, the value is displayed in exponential format. In comb3, .nr is set to 1, so this small value is
rounded to 0. In comb6, all values are rounded to integers because .nd is set to 0.

13 Cursor Control
Having described the display of various output items using the put statement, this section describes features available to
position these items in the output file. GAMS has several file suffixes which determine the location of the cursor and the last
line of the file. These suffixes can also be used to reposition the cursor or reset the last line. As such, they are instrumental in
formatting output items in documents. These suffixes are grouped by the title, header, or window writing area for which they
are valid.

13.1 Current Cursor Column

These suffixes have numeric values corresponding to the current column of the page main window, the header, and the title,
respectively. Because of this, they can be used in conjunction with cursor control characters to manipulate the position of the
cursor in the output file.

Suffix Description
.cc current cursor column in window
.hdcc header current column
.tlcc title current column

The convention for updating the values stored for the .cc, .hdcc, and .tlcc suffixes is that they are updated at the conclusion
of a put statement. Consequently, these values remain constant for the duration of a single put statement, even if multiple
items or lines are displayed.
The following example illustrates the updating of the cursor control suffixes and the use of cursor control characters. The
example is trivial but instructive:

scalar lmarg left margin /6/;

file out; put out;
put @(lmarg+2) out.cc = , out.cc:0:0 ;
put @out.cc x/ @out.cc y/ @out.cc z ;
put out.cc = out.cc:0:0;

The following is the resulting file out.put:

out.cc = 1 x
y
z out.cc = 23

Initially, the scalar lmarg is set to a specific value to use as an alignment tab. Symbols which hold common alignment values
such as margins or tabs are often useful for large structured documents. The first put statement uses the current column
cursor control character to relocate the cursor. In this example, the cursor is moved to column 8 where out.cc and its value
are displayed.
The second put statement illustrates the updating of the cursor control suffixes by writing the letters x, y , and z on three
different lines. Each is preceded by the cursor being moved to the out.cc value. Initially, the value for the cursor control
suffix is 20. Since a single put statement is used for these three items, the out.cc value remains constant and consequently
166 The Put Writing Facility

the letters end up in the same column. Following this put statement, the out.cc value is updated to 23, which is the location
of the cursor at the end of the second put statement (note the additional blank spaces displayed with the letter z).

13.2 Current Cursor Row

These suffixes have numeric values corresponding to the current row of the page main window, the header, and the title,
respectively. Because of this, they can be used in conjunction with cursor control characters to manipulate the position of the
cursor in the output file.

Suffix Description
.cr current cursor row in window
.hdcr header current row
.tlcr title current row

The convention for updating the values stored for the .cr, .hdcr, and .tlcr suffixes is that they are updated at the conclusion
of a put statement. Consequently, these values remain constant for the duration of a single put statement, even if multiple
items or lines are displayed. Their behavior is similar to that of .cc.

13.3 Last Line Control

These suffixes control the last line used in a writing area.

Suffix Description
.ll last line used in window
.hdll header last line
.tlll title last line

Unlike the row and column control, the last line suffix is updated continuously. Last line suffixes are especially useful for
modifying the various writing areas of a page.

Attention
The .tlll and .hdll suffixes may not hold values applicable to the current page because when the title or header
blocks are modified, they correspond to the title or header blocks of the next page whenever the window has been
written to on the current page.
Not only can this suffix be used to determine the last line used in a writing area, but it can also be used to delete
lines within this area.

In the following example, the header section will be completely deleted by resetting the .hdll suffix to 0.

file out;
puthd out This header statement will be eliminated;
out.hdll = 0;

In this example, a header is initially written. By changing the .hdll suffix to 0, the cursor is reset to the top of the header
block. Consequently the header will not be written unless something new is added to the header block.
14 Paging Control 167

14 Paging Control
In addition to the automatic paging, which occurs when the bottom of the page is reached, a page can also be written to file
early. The keyword putpage is used to do this. Putpage forces the current page to immediately be written to file, making a
new page available for put statements. In its simplest form, the keyword putpage is used by itself to eject the current page.
Additionally, it can be used with output items. When it is used with output items, the page is written to file including the
output items contained in the putpage statement. The putpage statement is in fact another variation of the put statement.
In the following statement, the quoted text is placed in the current page, which is then written to the file out.put:

putpage out This text is placed in window and the page ends;

Two additional file suffixes that can help the user in determining when to page a file are:
last page (.lp) Indicates the number of pages that are already in the document. Note that setting this to 0 does
not erase the pages that have previously been written to the file.
window size (.ws) Shows the number of rows, which can be placed in the window, considering the number of
lines that are in the title and header blocks of the current page and the existing page size. The .ws file suffix
value is calculated by GAMS and is not changeable by the user. This suffix is useful for manual pagination when
used in conjunction with the .ll file suffix.

15 Exception Handling
In this section, the topic of exception handling is dealt with. As with other GAMS statements, dollar control exception
handling can be used with put statements to control whether particular output items are displayed. In the following example,
the put statement is only displayed if the dollar condition is true. If it is not, the put statement is ignored:

put$(flag gt 10) some output items;

16 Source of Errors Associated with the Put Statement

There are two types of errors that can occur when using the put writing facility: syntax errors and put errors. The following
subsections discuss each of these types of errors.

16.1 Syntax Errors

Syntax errors are caused by the incorrect usage of the GAMS language. These errors are the same or are similar to what one
finds elsewhere with GAMS such as unmatched parentheses, undefined identifiers, uncontrolled sets, or the incorrect use of a
keyword or suffix. These errors are detected during program compilation and are always fatal to program execution. Errors
of this kind are identified in the program listing at the location of the error with a $ symbol and corresponding error numbers.
The program listing includes a brief description of the probable cause of the error.

16.2 Put Errors

Put errors are unique to the put writing facility. This type of error occurs during program execution and is caused when
one or more of the file or page attributes are violated. These errors are non-fatal and are listed at the end of the program
listing. They typically occur when a put statement attempts to write outside of a page, such as moving the cursor with the @
character to a location beyond the page width. Other typical errors are the inability to open a specified file, the overflow of a
page, or an inappropriate value being assigned to a suffix. For many of these errors, an additional set of asterisks will be
placed at the location of the error in the output file.
168 The Put Writing Facility

Since put errors are non-fatal and are not overemphasized in the output file, their presence is sometimes overlooked. Without
reviewing the program listing, these put errors might go undetected, especially in large output files. Consequently, GAMS
has included the following file suffix to help one detect errors:
.errors Allows one to display the number of put errors occurring in a file.
To illustrate its use, the following statement could be inserted at any point of a program to detect the number of errors, which
have occurred up to its location. The choice of output file could be the same file, a different file, or the console as appropriate:

putpage error ///*** put errors: , out.errors:0:0, ***/;

In this example it is assumed that the files out.put and error.put have previously been defined with a file statement. With
this statement, the number of put errors that occur in the file out.put are displayed in the file error.put. Using putpage
would allow the immediate display to the screen of a PC system at the location of this statement if the console had been the
output device.

17 Simple Spreadsheet/Database Application

This last section provides a simple example of the preparation of output for spreadsheets, databases, or other software
packages, which allow importation of delimited files. As mentioned in Section An Example , output items can be prepared
with comma delimiters and text items in quotes. This is implemented by using .pc suffix value 5. Delimited files are different
than normal put files. All output items are written with variable field widths and separated by delimiters. Consequently,
all global and local format specifications for field widths and justification are ignored by GAMS. Note that the number of
decimals for numeric items can still be specified with the .nd file suffix. Each item is written immediately following the
previous delimiter on the same line unless the cursor is reset.

Attention
Avoid horizontal cursor relocations in a program, which creates a delimited file. Horizontally relocating the cursor in a
delimited file is potentially damaging since a delimiter could be overwritten.

While the comma is the most common delimiting character for spreadsheets, other delimiters like blank space and tab
characters can also be used.

17.1 An Example
In the following example, the capacity sub-table of the [MEXSS] report program is prepared as a delimited file. The
following program segment demonstrates .pc suffix value 5. The program segment could be placed at the end of the original
[MEXSS] model:

file out; put out; out.pc=5;

put capacity (metric tons);
loop(i, put i.tl);
loop(m,
put / m.te(m);
loop(i, put k(m,i));
);

The first line of this program segment creates the file out.put as the delimited file. Notice that in the remainder of this
program, field widths, justifications, and horizontal cursor relocations are completely avoided. All text items are quoted. The
following is the resulting output file:

"CAPACITY (tons)","AHMSA","FUNDIDORA","SICARTSA","HYLSA","HYLSAP"
"BLAST FURNACES",3.25,1.40,1.10,0.00,0.00
17 Simple Spreadsheet/Database Application 169

"oPEN HEARTH FURNACES",1.50,0.85,0.00,0.00,0.00

"BASIC OXYGEN CONVERTERS",2.07,1.50,1.30,0.00,0.00
"DIRECT REDUCTION UNITS",0.00,0.00,0.00,0.98,1.00
"ELECTRIC ARC FURNACES",0.00,0.00,0.00,1.13,0.56

Notice that each item is delimited with a comma and that textual output is quoted.
170 The Put Writing Facility
Chapter 16

Programming Flow Control Features

1 Introduction
The previous chapters have focused on the ability of GAMS to describe models. This chapter will describe the various
programming features available in GAMS to help the advanced user. The various programming flow control features
discussed in this chapter are

The Loop Statement

The If-Elseif-Else Statement

The For Statement

The While Statement

Each of these statements will be discussed in detail in the following sections.

2 The Loop Statement

The loop statement is provided for cases when parallel assignments are not sufficient. This happens most often when there is
no analytic relationship between, for example, the values to be assigned to a parameter. It is, of course, also useful to have a
looping statement for general programming - for example, the production of reports with the put statement.

2.1 The Syntax

The syntax of the loop statement is,

loop(controlling_domain[$(condition)],
statement {; statement}
) ;

If the controlling domain consists of more than one set, then parentheses are required around it.
The loop statement causes GAMS to execute the statements within the scope of the loop for each member of the driving
set(s) in turn. The order of evaluation is the entry order of the labels. A loop is thus another, more general, type of indexed
operation. The loop set may be dollar-controlled and does not need to be static or nested. Loops may be controlled by
more than one set.
172 Programming Flow Control Features

Attention
One cannot make declarations or define equations inside a loop statement.
It is illegal to modify any controlling set inside the body of the loop.

2.2 Examples
Consider a hypothetical case when a growth rate is empirical:

set t / 1985*1990 /
parameter pop(t) / 1985 3456 /
growth(t) / 1985 25.3, 1986 27.3, 1987 26.2
1988 27.1, 1989 26.6, 1990 26.6 /;

The loop statement is then used to calculate the cumulative sums

loop(t, pop(t+1) = pop(t) + growth(t) ) ;

in an iterative rather than a parallel way. In this example there is one statement in the scope of the loop, and one driving, or
controlling, set.
A loop is often used to perform iterative calculations. Consider the following example, which finds square roots by Newton's
method. This example is purely for illustration - in practice, the function sqrt should be used. Newton's method is the
assertion that if x is an approximation to the square root of v, then (x + v/x)/2 is a better one

set i "set to drive iterations" / i-1*i-100 /;

parameter value(i) "used to hold successive approximations" ;

scalars
target "number whose square root is needed" /23.456 /
sqrtval "final approximation to sqrt(target)"
curacc "accuracy of current approximation"
reltol "required relative accuracy" / 1.0e-06 / ;

abort$(target <= 0) "argument to newton must be positive", target;

value("i-1") = target/2 ; curacc = 1 ;
loop(i$(curacc > reltol),
value(i+1) = 0.5*(value(i) + target/value(i));
sqrtval = value(i+1);
curacc = abs (value(i+1)-value(i))/(1+abs(value(i+1)))
) ;
abort$(curacc > reltol) "square root not found"
option decimals=8;
display "square root found within tolerance", sqrtval, value;

The output is:

---- 18 square root found within tolerance

---- 18 PARAMETER SQRTVAL = 4.84313948 final approximation

to sqrt(target)

---- 18 PARAMETER VALUE used to hold successive approximations

i-1 11.72800000, i-2 6.86400000, i-3 5.14062471, i-4 4.85174713

i-5 4.84314711, i-6 4.84313948, i-7 4.84313948
3 The If-Elseif-Else Statement 173

3 The If-Elseif-Else Statement

The if-else statement is useful to branch conditionally around a group of statements. In some cases this can also be written
as a set of dollar conditions, but the if statement may be used to make the GAMS code more readable. An optional else
part allows you to formulate traditional if-then-else constructs.

3.1 The Syntax

The syntax for an if-elseif-else statement is:

if (condition,
statements;
{elseif condition, statements; }
[else statements;]
);

where condition is a logical condition.

Attention
One cannot make declarations or define equations inside an if statement.

3.2 Examples
Consider the following set of statements

p(i)$(f <= 0) = -1 ;
p(i)$((f > 0) and (f < 1)) = p(i)**2 ;
p(i)$(f > 1) = p(i)**3 ;
q(j)$(f <= 0) = -1 ;
q(j)$((f > 0) and (f < 1)) = q(j)**2 ;
q(j)$(f > 1) = q(j)**3 ;

They can be expressed using the if-elseif-else statement as

if (f <= 0,
p(i) = -1 ;
q(j) = -1 ;
elseif ((f > 0) and (f < 1)),
p(i) = p(i)**2 ;
q(j) = q(j)**2 ;
else
p(i) = p(i)**3 ;
q(j) = q(j)**3 ;
) ;

The body of the if statement can contain solve statements. For instance, consider the following bit of GAMS code:

if ((ml.modelstat eq 4),
* model ml was infeasible
* relax bounds on x and solve again
x.up(j) = 2*x.up(j) ;
solve ml using lp minimizing lp ;
174 Programming Flow Control Features

else
if ((ml.modelstat ne 1),
abort "error solving model ml ;
);
);

The following GAMS code is illegal since one cannot define equations inside an if statement.

if (s gt 0,
eq.. sum(i,x(i)) =g= 2 ;
);

The following GAMS code is illegal since one cannot make declarations inside an if statement.

if (s gt 0,
scalar y ; y = 5 ;
);

4 The While Statement

The while statement is used in order to loop over a block of statements.

4.1 The Syntax

The syntax of the while statement is:

while(condition,
statements;
);

Attention
One cannot make declarations or define equations inside a while statement.

4.2 Examples
One can use while statements to control the solve statement. For instance, consider the following bit of GAMS code that
randomly searches for a global optimum of a non-convex model:

scalar count ; count = 1 ;

scalar globmin ; globmin = inf ;
option bratio = 1 ;
while((count le 1000),
x.l(j) = uniform(0,1) ;
solve ml using nlp minimizing obj ;
if (obj.l le globmin,
globmin = obj.l ;
globinit(j) = x.l(j) ;
) ;
count = count+1 ;
) ;
5 The For Statement 175

In this example, a non-convex model is solved from 1000 random starting points, and the global solution is tracked. The
model [PRIME] from the model library illustrates the use of the while statement through an example where the set of
prime numbers less than 200 are generated
The following GAMS code is illegal since one cannot define equations inside a while statement.

while (s gt 0,
eq.. sum(i,x(i)) =g= 2 ;
);

The following GAMS code is illegal since one cannot make declarations inside a while statement.

while(s gt 0,
scalar y ; y = 5 ;
);

5 The For Statement

The for statement is used in order to loop over a block of statements.

5.1 The Syntax

The syntax is:

for (i = start to|downto end [by incr],

statements;
);

Note that i is not a set but a parameter. Start and end are the start and end, and incr is the increment by which i is
changed after every pass of the loop.

Attention
One cannot make declarations or define equations inside a for statement.
The values of start, end and incr need not be integer. The start and end values can be positive or negative
real numbers. The value of incr has to be a positive real number.

5.2 Examples
One can use forstatements to control the solve statement. For instance, consider the following bit of GAMS code that
randomly searches for a global optimum of a non-convex model:

scalar i ;
scalar globmin ; globmin = inf ;
option bratio = 1 ;
for (i = 1 to 1000,
x.l(j) = uniform(0,1) ;
solve ml using nlp minimizing obj ;
if (obj.l le globmin,
globmin = obj.l ;
globinit(j) = x.l(j) ;
);) ;
176 Programming Flow Control Features

In this example, a non-convex model is solved from 1000 random starting points, and the global solution is tracked.
The use of real numbers as start, end and incr can be understood from the following example,

for (s = -3.4 to 0.3 by 1.4,

display s ;
);

The resulting listing file will contain the following lines,

---- 2 PARAMETER S = -3.400

---- 2 PARAMETER S = -2.000
---- 2 PARAMETER S = -0.600

Notice that the value of s was incremented by 1.4 with each pass of the loop as long as it did not exceed 0.3.
The following GAMS code is illegal since one cannot define equations inside a for statement.

for (s = 1 to 5 by 1,
eq.. sum(i,x(i)) =g= 2 ;
);

The following GAMS code is illegal since one cannot make declarations inside a for statement.

for (s=1 to 5 by 1,
scalar y ; y = 5 ;
);
Chapter 17

Special Language Features

1 Introduction
This chapter introduces special features in GAMS that do not translate across solvers, or are specific to certain model types.
These features can be extremely useful for relevant models, and are among the most widely used.

2 Special MIP Features

Some special features have been added to GAMS to help in simplifying the modeling of MIP problems. Two special types of
discrete variables are defined and discussed. Finally, creating priorities for the discrete variables is discussed. The solvers use
this information when solving the problem.

2.1 Types of Discrete Variables

The following types of discrete variables have been discussed so far in the book,

binary variables These can take on values of 0 or 1 only.

integer variables These can take on integer values between the defined bounds. The default lower and upper
bounds are 0 and 100 respectively.

In addition to these two, two new types of discrete variables that are introduced in this section. Both these variables exploit
special structures in MIP models during the solution phase. These are the following

Special Ordered Sets (SOS) The precise definition of special ordered sets differ from one solver to another and the
development of these features has been driven more by internal algorithmic consideration than by broader modeling
concepts. GAMS offers sos1 and sos2 variables as two types of compromise features that model special ordered sets.
Sections Special Order Sets of Type 1 (SOS1) and Special Order Sets of Type 2 (SOS2) discuss these two types of
variables in greater detail.

Semi-continuous variables GAMS offers semicont and semiint variables to model this class of variables. These
are explained in Sections Special Order Sets of Type 2 (SOS2) and Semi-Continuous Variables .

The presence of any of the above types of discrete variables requires a mixed integer model and all the discreteness is handled
by the branch and bound algorithm in the same way as binary and general integer variables are handled.
178 Special Language Features

2.2 Special Order Sets of Type 1 (SOS1)

At most one variable within a SOS1 set can have a non-zero value. This variable can take any positive value. Special ordered
sets of type 1 are defined as follows,

sos1 Variable s1(i), t1(k,j), w1(i,j,k) ;

The members of the innermost (the right-most) index belongs to the same set. For example, in the sets defined above, s1
represents one special ordered set of type 1 with i elements, t1 defines k sets of j elements each, and w1 defines (i,j) sets
with k elements each.

Attention
The default bounds for SOS1 variables are 0 to +. As with any other variable, the user may set these bounds to
whatever is required.
The user can, in addition, explicitly provide whatever convexity row that the problem may need through an
equation that requires the members of the SOS set to be less than a certain value. Any such convexity row would
implicitly define bounds on each of the variables.

Consider the following example,

sos1 Variable s1(i) ;

Equation defsoss1 ;
defsoss1.. sum(i,s1(i)) =l= 3.5 ;

The equation defsoss1 implicitly defines the non-zero values that one of the elements of the SOS1 variable s1 can take.
A special case of SOS1 variables is when exactly one of the elements of the set have to be non-zero. In this case, the defsoss1
equation will be

defsoss1.. sum(i,s1(i)) =e= 3.5 ;

A common use of the use of this set is for the case where the non-zero value is 1. In such cases, the SOS1 variable behaves
like a binary variable. It is only treated differently by the solver at the level of the branch and bound algorithm. For example,
consider the following example to model the case where at most one out of n options can be selected. This is expressed as

sos1 variable x(i)

equation defx ;
defx.. sum(i,x(i)) =l= 1 ;

The variable x can be made binary without any change in meaning and the solution provided by the solver will be
indistinguishable from the SOS1 case.
The use of special ordered sets may not always improve the performance of the branch and bound algorithm. If there is no
natural order the use of binary variables may be a better choice. A good example of this is the assignment problem.

Attention
Not all MIP solvers allow SOS1 variables. Furthermore, among the solvers that allow their use, the precise definition can
vary from solver to solver. Any model that contains these variables may not be transferable among solvers. Please verify
how the solver you are interested in handles SOS1 variables by checking the relevant section of the Solver Manual.
2 Special MIP Features 179

2.3 Special Order Sets of Type 2 (SOS2)

At most two variables within a SOS2 set can have non-zero values. The two non-zero values have to be adjacent. The most
common use of SOS2 sets is to model piece-wise linear approximations to nonlinear functions.

Attention
The default bounds for SOS2 variables are 0 to +. As with any other variable, the user may set these bounds to
whatever is required.

Special ordered sets of type 2 are defined as follows,

sos2 Variable s2(i), t2(k,j), w2(i,j,k) ;

The members of the innermost (the right-most) index belongs to the same set. For example, in the sets defined above, s2
represents one special ordered set of type 2 with i elements, t2 defines k sets of j elements each, and w2 defines (i,j) sets
with k elements each.
[PRODSCHX] shows SOS type formulations with binary, SOS1 and SOS2 sets. The default bounds for SOS variables are 0
to +. As with any other variable, the user may set these bounds to whatever is required.

Attention
Not all MIP solvers allow SOS2 variables. Furthermore, among the solvers that allow their use, the precise definition can
vary from solver to solver. Any model that contains these variables may not be transferable among solvers. Please verify
how the solver you are interested in handles SOS2 variables by checking the relevant section of the Solver Manual.

2.4 Semi-Continuous Variables

Semi-continuous variables are those whose values, if non-zero, must be above a given minimum level. This can be expressed
algebraically as: Either x = 0 or L x U.
By default, this lower bound ( L) is 1 and the upper bound ( U) is +. The lower and upper bounds are set through .lo
and .up. In GAMS , a semi-continuous variable is declared using the reserved phrase semicont variable. The following
example illustrates its use.

semicont variable x ;
x.lo = 1.5 ; x.up = 23.1 ;

The above slice of code declares the variable x to be semi-continuous variable that can either be 0, or can behave as a
continuous variable between 1.5 and 23.1.

Attention
Not all MIP solvers allow semi-continuous variables. Please verify that the solver you are interested in can handle
semi-continuous variables by checking the relevant section of the Solver Manual.
The lower bound has to be less than the upper bound, and both bounds have to be greater than 0. GAMS will flag
an error if it finds that this is not the case.

2.5 Semi-Integer Variables

Semi-integer variables are those whose values, if non-zero, must be integral above a given minimum value. This can be
expressed algebraically as: Either x = 0 or x {L, . . . ,U}
By default, this lower bound ( L) is 1 and the upper bound ( U) is 100. The lower and upper bounds are set through .lo and
.up. In GAMS , a semi-integer variable is declared using the reserved phrase semiint variable. The following example
illustrates its use.
180 Special Language Features

semiint variable x ;
x.lo = 2 ; x.up = 25 ;

The above slice of code declares the variable x to be semi-continuous variable that can either be 0, or can take any integer
value between 2 and 25.

Attention
Not all MIP solvers allow semi-integer variables. Please verify that the solver you are interested in can handle
semi-integer variables by checking the relevant section of the Solver Manual.
The lower bound ( L) has to be less than the upper bound ( U), and both bounds have to be greater than 0. GAMS
will flag an error during model generation if it finds that this is not the case.
The bounds for semiint variables have to take integer values. GAMS will flag an error during model generation
if it finds that this is not the case.

2.6 Setting Priorities for Branching

The user can specify an order for picking variables to branch on during a branch and bound search for MIP models through
the use of priorities. Without priorities, the MIP algorithm will determine which variable is the most suitable to branch on.
The GAMS statement to use priorities for branching during the branch and bound search is:

mymodel.prioropt = 1 ;

where mymodel is the name of the model specified in the model statement. The default value is 0 in which case priorities
will not be used.
Using the .prior suffix sets the priorities of the individual variables. Note that there is one prior value for each individual
component of a multidimensional variable. Priorities can be set to any real value. The default value is 1. As a general rule of
thumb, the most important variables should be given the highest priority.
The following example illustrates its use,

z.prior(i,small) = 3 ;
z.prior(i,medium) = 2 ;
z.prior(i,large) = 1 ;

In the above example, z(i,'large') variables are branched on before z(i, 'small') variables.

Attention
The lower the value given to the .prior suffix, the higher the priority for branching.
All members of any SOS1 or SOS2 set should be given the same priority value since it is the set itself which is
branched upon rather than the individual members of the set.

3 Model Scaling - The Scale Option

The rules for good scaling are exclusively based on algorithmic needs. GAMS has been developed to increase the efficiency
of modelers, and one of the best ways seems to be to encourage modelers to write their models using a notation that is as
natural as possible. The units of measurement are one part of this natural notation, and there is unfortunately a potential
conflict between what the modeler thinks is a good unit and what constitutes a well-scaled model.
3 Model Scaling - The Scale Option 181

3.1 The Scale Option

To facilitate the translation between a natural model and a well scaled model, GAMS has introduced the concept of a scale
factor, both for variables and equations. The notations and definitions are quite simple. Scaling is turned off by default.
Setting the model suffix .scaleopt to 1 turns on the scaling feature. For example,

model mymodel /all/ ;

mymodel.scaleopt = 1 ;
solve mymodel using nlp maximizing dollars ;

The statement should be inserted somewhere after the model statement and before the solve statement. In order to turn
scaling off again, set the model.scaleopt parameter to 0 before the next solve.
The scale factor of a variable or an equation is referenced with the suffix .scale, i.e. the scale factor of variable x(i) is
referenced as x.scale(i). Note that there is one scale value for each individual component of a multidimensional variable
or equation. Scale factors can be defined using assignment statements. The default scale factor is always 1.
GAMS scaling is in most respects hidden from the user. The solution values reported back from a solution algorithm are
always reported in the user's notation. The algorithm's versions of the equations and variables are only reflected in the
derivatives in the equation and column listings in the GAMS output if the options limrow and limcol are positive, and the
debugging output from the solution algorithm generated with sysout option set to on.

3.2 Variable Scaling

The scale factor on a variable, Vs , is used to relate the variable as seen by the user, Vu , to the variable as seen by the algorithm,
Va , as follows: Va = Vu /Vs
For example, consider the following equation,

positive variables x1,x2 ;

equation eq ;
eq.. 200*x1 + 0.5*x2 =l= 5 ;
x1.up = 0.01; x2.up = 10 ;
x1.scale = 0.01; x2.scale = 10 ;

By setting x1.scale to 0.01 and x2.scale to 10, the model seen by the solver is,

positive variables xprime1,xprime2 ;

equation eq ;
eq.. 2*xprime1 + 5*xprime2 =l= 5 ;
xprime1.up = 1; xprime2.up = 1 ;

Note that the solver does not see the variables x1 or x2, but rather the scaled (and better-behaved) variables xprime1 and
xprime2.

Attention
Upper and lower bounds on variables are automatically scaled in the same way as the variable itself.
Integer and binary variables cannot be scaled.

3.3 Equation Scaling

Similarly, the scale factor on an equation, Gs , is used to relate the equation as seen by the user, Gu , to the equation as seen by
the algorithm, Ga , as follows: Ga = Gu /Gs
For example, consider the following equations,
182 Special Language Features

positive variables y1,y2 ;

equation eq1, eq2 ;
eq1.. 200*y1 + 100*y2 =l= 500 ;
eq2.. 3*y1 - 4*y2 =g= 6 ;

By setting eq1.scale to 100, the model seen by the solver is,

positive variables y1,y2 ;

equation eqprime1, eq2 ;
eqprime1.. 2*y1 + 1*y2 =l= 5 ;
eq2.. 3*y1 - 4*y2 =g= 6 ;

Attention
The user may have to perform a combination of equation and variable scaling until a well-scaled model is obtained.

Consider the following example,

positive variables x1,x2 ;

equation eq1, eq2 ;
eq1.. 100*x1 + 5*x2 =g= 20 ;
eq2.. 50*x1 - 10*x2 =l= 5 ;
x1.up = 0.2 ; x2.up = 1.5 ;

Setting the following scale values:

x1.scale = 0.1 ;
eq1.scale = 5 ;
eq2.scale = 5 ;

will result in the solver seeing the following well scaled model,

positive variables xprime1,x2 ;

equation eqprime1, eqprime2 ;
eqprime1.. 2*xprime1 + x2 =g= 4 ;
eqprime2.. xprime1 - 2*xprime2 =l= 1 ;
xprime1.up = 2 ; x2.up = 1.5 ;

3.4 Scaling of Derivatives

For nonlinear models, the derivatives also need to be well scaled. The derivatives in the scaled model seen by the algorithm,
i.e. d(Ga )/d(Va ) are related to the derivatives in the user's model, d(Gu )/d(Vu ) through the formula: d(Ga )/d(Va ) =
d(Gu )/d(Vu ) Vs /Gs .
The user can affect the scaling of derivatives by scaling both the equation and variable involved.

4 Conic Programming in GAMS

Conic programming models minimize a linear function over the intersection of an affine set and the product of nonlinear
cones. The problem class involving second order (quadratic) cones is known as Second Order Cone Programs (SOCP). These
are nonlinear convex problems that include linear and (convex) quadratic programs as special cases.
Conic programs allow the formulation of a wide variety of application models, including problems in engineering and
financial management, for example:
4 Conic Programming in GAMS 183

Portfolio Optimization

Truss Topology Design in Structural Engineering

Finite Impulse Response (FIR) Filter Design and Signal Processing

Antenna Array Weight Design

Grasping Force Optimization

Quadratic Programming

Robust linear programming

Norm Minimization Problems

For more information, see References and Links.

4.1 Introduction to Conic Programming

Co