Introducing the McCarl GAMS User Guide
Also known as the McCarl Guide
Bruce A. McCarl
Specialist in Applied Optimization
Regents Professor of Agricultural Economics,
Texas A&M University
Principal, McCarl and Associates
mccarl@tamu.edu
brucemccarl@cox.net
http://agecon2.tamu.edu/people/faculty/mccarl-bruce/
979-693-5694
979-845-1706
©B.A. McCarl, June 2006
McCarl GAMS User Guide
1
Introducing the McCarl GAMS User Guide
Document Characteristics
In early 2003 a new GAMS User Guide was released
expanding on the earlier Guides by Brooke, Kendrick
and Meeraus and later Ramen. In particular the new
document
1.
2.
3.
Covers all of the material incorporated in the
predecessor User Guide.
Incorporates dozens of new language elements
including command line parameters, functions, options,
and dollar commands having all user accessible GAMS
features in versions as recent as February 2003.
Adds coverage of topics such as
Chapter 7
Chapter 8
Chapter 10
Chapter 14
Chapter 17
Chapter 20
Chapter 24
Chapter 25
Chapter 30
Chapter 31
Chapter 32
Chapter 33
Chapter 34
Chapter 36
Chapter 37
Chapter 38
Chapter 39
3.
4.
Writing Models and Good Modeling Practices
Running Jobs with GAMS and the GAMS IDE
Rules for Item Names, Element Names and Explanatory Text
Rules for Item Capitalization and Ordering
Doing a Comparative Analysis with GAMS
Customizing GAMS
Speeding up GAMS
Memory Use Reduction in GAMS
Acronyms
Conditional Compilation
Using GAMS Data Exchange or GDX Files
Links to Other Programs Including Spreadsheets
Controlling GAMS from External Programs
Advanced Basis Usage
Mixed Integer, Semi, and SOS Programming
NLP and MCP Model Types
Model Attributes
Expands on the coverage in the previous Guides
providing additional details on many features.
Is designed as both a print and electronic document
with many supporting and accessible GMS example
files and web site links.
These notes introduce the Guide and it’s features.
©B.A. McCarl, June 2006
McCarl GAMS User Guide
2
Introducing the McCarl GAMS User Guide
Basic Structure
The User Guide is structured in Microsoft Helper
format with 7 basic components
1.
Expandable table of contents
Initially by major class of GAMS related items,
Expandable to chapter and topic within chapter
2.
Clickable Tables of Contents for each of the major classes of
GAMS related options.
3.
An associated PDF file for the whole document with working
links and an index that can be printed.
4.
An index of GAMS related features and topics discussed in
the Guide in the form of clickable links.
5.
A search feature.
6.
An ability to identify favorite sections.
7.
Use of color to emphasize points.
The first 6 of these components are discussed below.
©B.A. McCarl, June 2006
McCarl GAMS User Guide
3
Introducing the McCarl GAMS User Guide
Expandable Table of Contents
When the document opens one gets
The items in the green box are broad topic descriptors and
are also clickable links. If one were to do a left mouse
click on Quick Start Tutorial one is moved to the screen
In turn the both the left and right parts of the window
contain clickable links.
©B.A. McCarl, June 2006
McCarl GAMS User Guide
4
Introducing the McCarl GAMS User Guide
Structure of each Chapter
Each of the major sections in the document has a
common structure. Namely each contains
1.
A chapter level Table of contents composed of
clickable links
2.
Text on GAMS features and usage which also
can contain clickable links to
a. Related discussions of the same topic in
other chapters.
b. Clickable links to GMS files illustrating the
point at hand.
c. Solver and installation manuals installed
with GAMS
d. More technical web documents and possibly
program files on the GAMS web site
e. Documents related to the topic elsewhere on
the Web.
Illustrations of each are below.
©B.A. McCarl, June 2006
McCarl GAMS User Guide
5
Introducing the McCarl GAMS User Guide
Table of contents in each Chapter
At the beginning of each chapter is a table of contents
with page numbers. An example from the Sets
chapters is below. Green entries are clickable links.
A left mouse click on Domain checking causes the
screen to change to
©B.A. McCarl, June 2006
McCarl GAMS User Guide
6
Introducing the McCarl GAMS User Guide
Links in each Chapter
The SAMEAS section of the Sets chapter is as below
Here we see clickable links that if pressed references to the
Sameas and Diag discussion in the Conditionals chapter as
well as the Sets.gms example file where points in the text
are illustrated in a file that implements the point discussed
in a running GMS file. Furthermore if the IDE is the file
registered to run GMS files then clicking invokes the IDE
and one gets
The chapters can also contain links to solver guides,
or documents on the Web from GAMS or others.
©B.A. McCarl, June 2006
McCarl GAMS User Guide
7
Introducing the McCarl GAMS User Guide
Index of List of Features
If one selects the index tab one gets an alphabetic list
of all commands with clickable references to
illustrations of them.
This illustrates
1. Clickable links where activating the link
transfers one into the topic discussion.
2. Multiple occurrences of most items pointing
to treatment in different contexts.
©B.A. McCarl, June 2006
McCarl GAMS User Guide
8
Introducing the McCarl GAMS User Guide
Index of List of Features
If one enters text into the keyword box then the code
references forward to text that matches that entry in
the index.
Clicking on any topic opens the text discussing it.
©B.A. McCarl, June 2006
McCarl GAMS User Guide
9
Introducing the McCarl GAMS User Guide
Search for Features
If one selects the search tab and enters text into the
words to search for box then the code finds all text
entries that match that text in the entire document and
makes them clickable links.
©B.A. McCarl, June 2006
McCarl GAMS User Guide
10
Introducing the McCarl GAMS User Guide
Favorite Features
If one selects the favorites tab when looking at a page
one wants to repeatedly visit and clicks add then one
gets clickable links to sections in the favorites box.
©B.A. McCarl, June 2006
McCarl GAMS User Guide
11
Introducing the McCarl GAMS User Guide
PDF Copy and Index
A PDF composite document is distributed which is called
mccarlgamsuserguide.pdf. That will soon be referenced by
accessing the top-level document forward and clicking on
the link for the composite document. For now it is in
c:\program files\C:\Program Files\GAMS22.2\docs\bigdocs\gams2002\mccarlgamsuserguide.pdf
For printing this document contains an index referencing
items discussed and page numbers plus a numbered table of
contents. A part of that index appears below.
It also has links and can be used with searches like
other PDF files
©B.A. McCarl, June 2006
McCarl GAMS User Guide
12
Introducing the McCarl GAMS User Guide
Accessing the Document
One can access the Users Guide in a number of ways involving
PDF Document access over the Web through
http://www.gams.com/dd/docs/bigdocs/gams2002/mccarlgamsuserguide.pdf
Access through the IDE as below
Access on your computer after
1.
a PDF download through the web but this does
not contain the examples.
2.
loading the document from the GAMS CD where
the zip file can be found in the \docs directory and
then a subsequent unzipping.
3.
Installation from the CD of any GAMS system
newer than 22.0 wherein the document will be
automatically installed
The Unzip may be carried out conventionally or by
going to file and options under the IDE and then
pressing the Update button as shown below.
Access after installation of the files is covered on the
next page
©B.A. McCarl, June 2006
McCarl GAMS User Guide
13
Introducing the McCarl GAMS User Guide
Direct Accessing the document once installed
Once the files are installed on your computer you can
access them directly or through the IDE
Use Explorer or some other method to activate the
file
mccarlgamsuserguide.chm to open the
file
mccarlgamsuserguide.pdf for PDF and
printable document (now with links)
Generally these files are found in the
docs/bigdocs/gams2002/
subdirectory of the GAMS system directory.
By default with GAMS version 22.2 this would be
the subdirectory
C:\Program Files\gams22.2\docs\bigdocs\gams2002
©B.A. McCarl, June 2006
McCarl GAMS User Guide
14
Introducing the McCarl GAMS User Guide
IDE supported access
Choose Help and the McCarl Guide choice
The IDE will then bring up
©B.A. McCarl, June 2006
McCarl GAMS User Guide
15
Introducing the McCarl GAMS User Guide
Document status, Edits and Contributions
This User Guide will probably be under continuous
revision as new GAMS releases are developed. It is
also anticipated that comments by others may lead to
improvements in content or the addition of new
features.
Others are invited to submit comments, new
materials for inclusion and even new chapters.
Naturally, if incorporated, appropriate credit will be
given.
Please contact mccarl@gams.com if you have
questions or contributions or wish formatting
information to facilitate document preparation.
©B.A. McCarl, June 2006
McCarl GAMS User Guide
16