McCarl GAMS User Guide

McCarl GAMS User Guide

McCarl GAMS User Guide

Quick Start Tutorial

Solving an optimization problem

Solving for an economic equilibrium

Solving a nonlinear equation system

Dissecting the simple models

What is the new Z variable in the optimization problem?

.. specifications

Why does my nonlinear equation system maximize something?

What are the .L items

Running the job

Command line approach

Examining the output

Incidence of compilation errors

Symbol list and cross reference maps

Generation listing

Equation listing

Variable listing

Model statistics

Execution output

Solution summary

Equation solution report

Variable solution report

Exploiting algebra

Equation writing – sums

Revised algebra exploiting optimization example

Revised equilibrium example

Dissecting the algebraic model

Direct assignment

Algebraic nature of variable and equation specifications

Algebra and model .. specifications

Output differences

Equation listing

Equation solution report

Variable solution report

Good modeling practices

Structure of GAMS statements, programs and the ;

Adding complexity

Conditionally execute an assignment

Conditionally add a term in sum or other set operation

Conditionally define an equation

Conditionally include a term in an equation

Displaying data

Why use GAMS and algebraic modeling

Use of algebraic modeling

Context changes

Aid with initial formulation and subsequent changes

Adding report writing

Self-documenting nature

Large model facilities

Automated problem handling and portability

Model library and widespread professional use

Ease of use with NLP, MIP, CGE and other problem forms

Interface with other packages

Language Basics

Set declaration

Element definition

Explicit element definition

Set definition through Tables

Element definition by computation

Multi dimensional sets

Domain checking

Set element referencing

Single elements

Operating over part of a set

Using conditionals

Sameas and Diag

Defining a tuple with the matching and # operators

Universal Set: * as a set identifier

Using set attributes

Finding sets from data

Using another name or an alias

Element order and capitalization in output

Functions specifically referencing sets

Ordered and Unordered sets

Indexing sets defined over time

Leads and Lags: + / -

Circular or Equilibrium Leads and Lags: ++ / --

Element Position

Calculated data

Variables, Equations, Models and Solves

Variable Declaration

Variable attributes

Assigning variable and equation attributes

Equation Declaration

.. Equation specifications

Equation attributes

Assigning equation attributes

Model attributes

List of attributes

Solve: Maximizing, Minimizing, and Using

Actions on executing solve

Programs with multiple solve statements

Multiple solve management - merge replace

Choosing a solver

Model Types and Solvers

Linear programs (LP)

Nonlinear program (NLP)

Quadratically constrained program (QCP)

Mixed integer programming (MIP)

Relaxed mixed integer programming (RMIP)

Mixed complementarity problem (MCP)

Mixed integer nonlinear program (MINLP)

Relaxed mixed integer nonlinear program (RMINLP)

Mixed integer quadratically constrained program (MIQCP)

Relaxed mixed integer quad. constrain program (RMIQCP)

Constrained nonlinear systems (CNS)

Nonlinear programming with discontinuous derivatives (DNLP)

Mathematical program with equilibrium constraints (MPEC)

Relaxed mathematical program with equilibrium constraints (RMPEC)

Extended Mathematical Programs (EMP)

Solver capabilities matrix

General notes on solver licensing

General notes on solver versions

Available solvers

Choosing a solver

Standard Output

Where is my output? LOG and LST files

Output overview and navigation

GAMS phases and output generated

Compilation phase output

Echo print of the input file

Compilation phase error messages

Repositioning error messages

Symbol reference map

Unique element list

Unique element cross reference

Execution output

Execution error output

Symptoms of the presence of an execution error

Output produced by a solve statement

Model generation error listing

Equation listing

Variable listing

Model characteristics statistics

Model generation time

Common solver report

The variable and equation solution listing

Including slacks in the output

Ranging analysis

Final execution summary

Managing output pages

Page width and height

Adding an output title to each page

Managing output volume

Eliminate model listing

Eliminate cross reference map

Eliminate symbol list

Eliminate solution output

Eliminate echo print

Restrict output just to a few displays

Adding slack variables to the output

Sending messages to the LOG file

Writing Models and Good Modeling Practices

Formatting models - my recommendations

Use longer names and descriptions

Include comments on procedures and data nature and sources

Entering raw versus calculated data

Avoiding use of * in input data set specification

Making sets work for you

Making subsets work for you

Formatting the typing of files to improve model readability

Other possible conventions

Changing licenses

Licenses on IDE

Licenses outside of IDE—Windows and Unix/Linux

Running Jobs with GAMS and the GAMS IDE

Basic approaches to GAMS usage

Running GAMS from the command line

IDE concept and usage

Steps to using IDE

Create a project

Defining a project name and location.

Creating or opening an existing GMS file

Preparing file for execution

Select default IDE functions

Page size and LST file opening

Make IDE the default GMS file processor

Run GAMS by clicking the run button

Open and navigate around the output

Using the process window

Using the LST file navigation window

Finding the Active Location

Working with your own file

Fixing compilation errors

Selected techniques for use of the IDE

Ways to find and/or replace text strings

Search menu and find in files

Matching parentheses

Moving column blocks

Altering syntax coloring

Finding out more through help

Help on the IDE

Accessing help on solvers

Adding your own documentation

Accessing documentation outside the IDE

Unraveling complex files: Refreader

Sets, Parameters etc. Tabs

Steps to Using Refreader

Saving the Refreader output

Spell checking in files

Saving and Using a Script

When is it not worth using?

Employing command line parameters

A difficulty you will have using IDE

Install GAMS and on Windows machines the IDE

On Windows machines make IDE icon

On Linux/Unix run Gamsinst

Choosing solvers

Solver choice outside of IDE

Unpacking software on Windows machines

Fixing Compilation Errors

Don’t bark up the wrong tree

Finding errors: ****

Finding errors: $

Repositioning error messages: Errmsg

Improperly placed semi colons - error A

Error message proliferation

Commonly found errors and their cause

Other common errors

Excess or insufficient semi colons - error B

Spelling mistakes - error C

Omitted Set elements - error D

Indexing problems - error E

Summing over sets already indexed - error F

Neglecting to deal with sets - error G

Mismatched parentheses - error H

Improper equation ".." statements - error I

Entering improper nonlinear expressions - error J

Using undefined data - error K

Improper references to individual set elements - error L

No variable, parameter, or equation definition - error M

Duplicate names - error N

Referencing item with wrong set - error O

ORD on an unordered set - error P

More Language Basics

Rules for Item Names, Element Names and Explanatory Text

Item name rules

Element name rules

Explanatory text rules

Including Comments

Single line comments

Multiple line comments

End of line comments

In line comments

Outside margin comments

Hidden comments

Calculating Items

Basic components of calculations

Basic arithmetic + - * / **

Arithmetic hierarchy

Changing hierarchy using () [] {}

Operations over set dependent items

= replacement or .. statements

Sum , Smax, Smin, Prod

Alternative set addressing schemes

Avoiding set domain errors

Conditionals to restrict set coverage

Tuples and subsets to restrict set coverage

Items that can be calculated

Equation calculations

Cautions about calculations

Repeated static

Cautions about dynamic /static calculations

Potential other components in calculations

Mixing logical expressions, sets and numbers

Common mathematical functions

Log, Log10, Log2

Other Mathematical functions

Time and Calender functions

String manipulation functions: Card

String manipulation functions: Ord, Ordascii, Ordebcdic

GAMS utility and performance functions

Model and optimal solution items

Attributes of variables and equations

Attributes of models

Including conditionals

Right and left hand side conditionals

Improving Output via Report Writing

Adding report writing

Basics of solution based report writing calculations

Adding a report

Notes on indefinite sets in parameter statements

Controlling displays

Formatting display decimals and layout

Taking control of display decimals

Controlling item ordering

Controlling item capitalization

Formatting pages and lines

Output via put commands

Reordering set order in output

Preprogrammed table making utility: Gams2tbl

Output to other programs

Obtaining graphical output

Sorting in GAMS

Rules for Item Capitalization and Ordering

Item capitalization

Reviewing capitalization: $Onsymlist and $Onuellist

Set element order

Reviewing set element ordering: $Onuellist

Basic forms of conditionals

Ways $ conditionals are employed

Suppressing calculation of items (left hand side)

Suppressing terms in equations (right hand side)

Controlling indices in sums etc

Suppressing model equations (left hand side)

Conditionally displaying information

Terminating a program: Abort

If, Else, and Elseif

Conditional placement and program execution speed

Forms of conditional / logical true false statements

Numerical comparisons

Eqv: <=> Imp: ->

Existence/nonzero data item or result

Computation over a set

Set comparisons

Element position: Ord and Card

Element text comparison: Sameas and Diag

Subset or tuple membership

Acronym comparisons

Nesting logical conditions

Nesting operators

Nested $ conditionals

Nested Operators and precedence order

Note of caution

The conditional alternative: the tuple

Control Structures

If, Else, and Elseif

Alternative syntax

Alternative syntax

Alternative syntax

For, To, Downto, and By

Alternative syntax

Doing a Comparative Analysis with GAMS

Basic approaches

Manual approach

Introducing cross scenario report writing

Percentage change cross scenario reports

Preserving changed data

An automated approach - avoiding repeated work

Adding a scenario

Changing model structure

GAMS Command Line Parameters

Important parameters

Compiler function – regional settings

Error detection and correction

LST and LOG output content and format control

Solver name choice

Option file presence

Directory management

Saves and restarts

User defined options

Alphabetic list of all GAMS command line parameters

-- // -/ /-- on command lines

AppendExpand or AE

Inputdir1 to inputdir40: Idir1 to idir40

Libincdir: Ldir

Sysincdir: Sdir

User1 to user5: U1 to U5

Saves and Restarts

Save Restart Basics

Use of save and restarts and their effect

Save and restart on command line

Save and restart calling GAMS from within GAMS

Why use save and restart?

Increasing run efficiency

Output management

Separation of code function

Save study results

Comparative statics analysis

Fast related solutions

Customizing GAMS

What types of options are there?

Possible command line parameters to customize

How can these options be set?

To set in command line via pf=

To set in Gmsprmxx.txt parameter file

Hierarchy for customizing options

Finding and Fixing Errors or Performance Problems

Fixing Execution Errors

GAMS limit errors

Arithmetic errors during GAMS execution

Execution errors during model generation

Execution errors during model solution

Solver function evaluation errors

Allowing errors to occur

Presolve errors

Problem eliminated

No feasible mixed integer solution

No feasible continuous solution

Solver specific limits

Basing conditionals on number of errors

Clearing error conditions

Scaling GAMS Models

Theory of scaling

Scaling a variable

Scaling equations

Simultaneous equation and variable scaling

Example of scaling

Scaling of GAMS models

Scaling in GAMS solvers

Using GAMS scaling assistance

Why should you scale?

Effect of scaling on GAMS output

How do you know how much to scale?

A caution when scaling – runaway cases

User defined data scaling

Nonlinear scaling

Small to Large: Aid in Development and Debugging

Expandability in an example

Essence of the small to large approach

Steps for working from small to large.

Making small parts of large models

Save and restart to isolate problem areas

Strategic sub-setting

Speeding up GAMS

Finding where excessive time is being used

Screen watching and LOG file examination

Use of profile to find slow statements

Invoking profile

On the GAMS command line

In the IDE GAMS parameters box

As an internal option

What should the number be

Limiting profile output: Profiletol

Isolating terms in slow statements

It takes too long - searching

Why programs can be slow and their repair

Set addressing and references

Avoiding considering unnecessary cases

Calculation statements

Equation existence limited using conditionals

Equation term consideration limited using conditions

Variable specification - suppression

Watch out for incomplete suppression

Post solution report writing computations

Trading memory for time

Other speed ups

Memory Use Reduction in GAMS

Finding where excessive memory is being used

Screen watching and LOG file examination

Profiling to find memory hogging statements

Invoking profile

On the GAMS command line

In the IDE GAMS parameters box

As an internal option

What should the profile number be

Limiting profile output: Profiletol

Memory use dumps: Dmpsym

Looking within memory hogs to find offending term

My code won’t work - searching

Causes of excessive memory use and repair

Avoiding considering unnecessary cases

Calculation statements

Equation existence using conditionals

Equation term consideration limited using conditions

Variable specification - suppression

Watch out for incomplete suppression

Memory traps to watch out for

Clearing memory of unnecessary items

Limiting memory use with HeapLimit

More Language Features

Including External Files

Inclusion without arguments

Includes that cause compiler error messages

Suppressing the listing of include files

Redefining the location of include files - Idir

Include with arguments

How parameter inclusion works

Influence on LST file contents: $Oninclude and $Offinclude

Passing $ commands between code segments: $Onglobal and $Offglobal

Special provision for CSV files

$Ondelim and $Offdelim

Dollar Commands

When do dollar commands occur?

Categories of $ commands

Commands for inclusion of comments

LST and other output file contents control

Ways of including external files

Contents dependent compilation

Alter numerical procedures used

Alter data for items

GDX file read/write

Alter compiler procedures

Cause execution of an external program

Restrict access to data

Tear apart strings

Compress and encrypt files

Detailed description of dollar commands

If, If not, Ifi, Ifi not

Ondelim and Offdelim

Ondigit and Offdigit

Ondollar and Offdollar

Ondotl and Offdotl

Onecho and Offecho

Onempty and Offempty

Onend and Offend

Oneolcom and Offeolcom

Oneps and Offeps

Onexpand and Offexpand

Onglobal and Offglobal

Oninclude and Offinclude

Oninline and Offinline

Onlisting and Offlisting

Onmacro and Offmacro

Onmargin and Offmargin

Onmulti and Offmulti

Onnestcom and Offnestcom

Onput, Onputs, Onputv, Offput

Onsymlist and Offsymlist

Onsymxref and Offsymxref

Ontext and Offtext

Onuellist and Offuellist

Onuelxref and Offuelxref

Onundf and Offundf

Onupper and Offupper

Onwarning and Offwarning

The Option Command

Options by function

Options for control of solver choice

Options including debugging information in LST file

Options influencing LST file contents

Options influencing solver function

Other options altering GAMS settings

Options affecting data for items in memory

Options that form projections of data items

Description of options

Option itemname:d and Option itemname:d:r:c

Option itemname < or <= itemname2

Advanced Language Features

Output via Put Commands

Details on put related commands

Sending output to the LOG file

Sending output to the SCREEN

Items within a put

Set element names via .tl

Set element explanatory text via .te and .tf

Putting out set elements for parameters via .Tn

Item explanatory text via .ts

Parameter values

Model solution status attributes: .Modelstat, .Solvestat, .Tmodstat, .Tsolstat

Variable and equation attributes: .L and .M

System attributes

GAMS command line parameters

Write position controls

Skip to a specified column: @

Skip to a new line: /

Skip to a specified row: #

Other positioning parameters

Formatting of items

File formatting – append or overwrite

Page formatting

.Bm - bottom margin

.Lm - left margin

.Pc - Page control

.Ps or page height

.Pw - page width

.Tm - top margin

Adding page titles and headers

Upper lower font case formatting: .Case and .Lcase

Width and decimal formatting

Global formatting

.Lw set element name width

.Nd number of decimals

.Nw number width

.Sw set indicator width

.Tw explanatory and quoted text width

Local formatting

Continuous vs fixed width

Global formatting

lj set element name justification

nj number justification

sj set indicator justification

tj explanatory and quoted text justification

Local formatting

Additional numeric display control

Putting out a block of text: $onput, $offput, $onputs, $onputv

Making puts conditional

Output to other programs

Put of data to a regression code

Put file for export to mapping program

Errors that arise during puts

Conditional Compilation

Control variables

Establishing control variables

Setting environment variables

Destroying Contol Variables

A problem with control variable definitions

Environment variables

Names of some system environment variables

Defining and destroying user environment variables

Augmenting environment variables

Accessing environment variable status at any point in the code: $Show

$If and $Ifi conditionals

$Ife conditionals

Not as a modifier

$ifthen, iftheni, ifthene, else, elseif, endif conditionals

Forms of conditionals

Based on control and environment variables

Numerical Value

Based on characteristics of named item or parameter

Definition status: Declared and Defined

Set dependency: Dimension

Passed parameter existence

Based on GAMS command line parameters

Based on system characteristics

Based on error and warning checks

Based on file or directory existence

Based on put file status

Incorporating Goto: $Goto and $Label

Redefining expressions

System attributes that can be included

GAMS command line attributes that can be included

Based on user options and command line: -- // -/ /- User1-5

Passed parameter inclusion

Control variable inclusion

Running external programs or commands

Writing messages to LST, LOG and other files

LST File: $Abort and $Error

Other named files: $Echo, $Offecho, $Onecho

End the job: $Exit, $Abort, $Error, $Stop, $Terminate

Longer examples

Changing model type depending on control variable

Changing form of data in model and their use

Having batincludes that deal with different data types

For more examples

Using GAMS Data Exchange or GDX Files

Creating a GDX file in GAMS

Command line GDX option - GDX dump of the whole problem

GDX Point Solution file

GDX files containing selected items

Execution time selected item GDX file creation

Compile time selected item GDX file creation

Inputting data from a GDX file into GAMS

Compile time imports from GDX files

Execution time GDX imports

Execute_Loadpoint

General notes on GDX files

Identifying contents of a GDX file

Identifying contents with $Load

Identifying contents with the IDE

Identifying contents with Gdxdump

Identifying differences in contents with Gdxdiff

Merging GDX files

Using GDX files to interface with other programs

Gdxcopy Making GDX files compatable

Writing older GDX versions with GDXCONVERT

Links to Other Programs Including Spreadsheets

Executing an external program

Spaces in file names and paths

Timing of execution with $Call and Execute

Passing data from GAMS to other programs

Put file data passage

CSV or otherwise delimited

Rutherford's CSV put: Gams2csv

Spreadsheet links

Graphics programs

Spreadsheet graphics

Geographic mapping programs

Gdxviewer links: Access, Excel pivot table, Excel, CSV, GAMS include, HTML, Text files, Plots, XML

Other programs and conversions: Convert, DB2, FLM2GMS, GAMS2TBL, HTML, Latex, MPS, Oracle, XML

Passing data from other programs to GAMS

Spreadsheet links

Interactive mode

GAMS program in Excel sheet

Interactive mode

Other programs: DB2, Latex, GNETGEN, Gnuplot, Matlab, MPS, NETGEN, Oracle

Customized data interchange links for spreadsheets

Xlexport, Xldump, Xlimport

Command line parameters

GAMS item dimension: Dim=, Rdim=, Cdim=

Data specification

Writing Text and Links

Set data: Set= and Dset=

Loading rows of set elements

Loading columns of set elements

Loading set elements only if they have data or text

Writing set elements

Sets and explanatory text – use of Set

Loading by upper left hand corner

Loading sets from data tables

Loading sets from lists with duplicates

Dealing with a tuple

Execution time set reads

Execution time set writes

Loading the set into GAMS

Unloading the set from GAMS

Parameter data: Par

Rearranging rows and columns

Variable and equation data: Equ and Var

Special options for reading from a spreadsheet: Skipempty= and Se=

Special options for writing to a spreadsheet

Is the workbook open or shared?

Special value and zero cell writing options

Options for reading in command line parameters

Command line parameters in a file

Parameters in a spreadsheet

Tracing Options

Log and Logappend

Workbook performance options

Other GDXXRW Options

Debugging Gdxxrw instructions

Spreadsheet graphics

Interactively including results

Interactive calculations in a spreadsheet

Calling GAMS from GAMS

Using equations defined by external programs

Identifying the equations and their contents: =X=

Building the external function evaluator

Controlling GAMS from External Programs

Calling GAMS from other programs

Excel spreadsheet in charge

Excel part of implementation

Defining the links through the map

Worksheets present

Inputs sheet structure

Results sheet structure

Running GAMS – the main macro

Critical user defined items

GAMS run sequence

Actions involved with executing GAMS

Examining the macros

GAMS part of implementation

Developing Excel in charge – summary steps

Compiled program in charge – Delphi

A Delphi example

Steps in application development

Passing data to GAMS

Challenges in running GAMS

Reading the GAMS solution

Web servers or programs in other languages in charge

Transferring models to other systems

Utilities included in GAMS

Posix utilities

Matrix Utilities

Interface and other utilities

Interface utilities

Solver Option Files

Telling a solver to look for an options file: .Optfile

Option file name

Alternative option file extention names: .Opt, .Op?, .O??, .???

Option file contents

Option specifications

Option file editor

Writing options during a model run

Learning about options: Solver manuals

Default settings for Optfile

Defining a central location for the option files: Optdir

Transitory nature of options

Advanced Basis Usage

Advanced basis formation in GAMS

Effect of advanced basis on solution performance

Providing a basis

Getting a basis through repeated solution

An alternative – use a GDX point file

An older alternative – use GAMSBAS: Bas files

Guessing at a basis

Why use a GAMSBAS or GDX Point basis

Problems with a basis

Symptoms and causes of a poor advanced basis

Mixed Integer, Semi, and SOS Programming

Specifying types of variables

Binary variables

Integer variables

Specially ordered set variables of type 1 (SOS1)

Specially ordered set variables of type 2 (SOS2)

Semi-continuous variables

Semi-integer variables

Imposing priorities

Branch-and-Cut-and-Heuristic Facility

GAMS options and model attributes

Modelname.Cheat = x;

Modelname.Cutoff = x;

Modelname.Nodlim = x;

Modelname.Optca=X; Option Optca=X;

Modelname.Optcr=X; Option Optcr=X;

Modelname.Optfile = 1;

Modelname.Prioropt = 1;

Modelname.Tryint = x;

Branch and bound output

Identifying the solver

Model termination conditions and actions

Things to watch out for

Ending with a gap – big default for Optcr (10%)

The nonending quest