Using GAMS Studio

This tutorial on using GAMS Studio was written initially by and is distributed by courtesy of Bruce A. McCarl 1). Bruce has extensive experience with GAMS, both as a modeler and an educator, and many GAMS users know, use, and benefit from his work. This tutorial presents a guided tour to the usage of GAMS Studio and on some items it reflects Bruce's personal view and preferences.

What Is It?

A multi platform (not only PCs with Windows) graphical interface to run GAMS

studio_icon.png

GAMS uses two phases.

  1. Text edit

    First, one uses a text editor and creates a file which contains GAMS instructions.

  2. File submission

    Second, one submits that file to GAMS which executes those instructions causing calculations to be done, solvers to be used and a solution file of the execution results to be created.

Approaches to use GAMS.

  1. More batch oriented traditional method use a text editor set up the model then use DOS (or UNIX) command line instructions to find errors in and run the model.
  2. GAMS STUDIO or GAMS IDE alternatives. Graphical interfaces to create, debug, text edit and run GAMS files.

Summary of steps to using

  1. Install GAMS and STUDIO on your computer
    studio_icon.png
  2. Open STUDIO through the icon
  3. Open or create a file by going to the file selection in the upper left corner.
  4. Prepare the file so you think it is ready for execution
  5. Run the file with GAMS by clicking the run button or pressing F9
  6. Open and navigate around the output

Installation

Install GAMS and STUDIO

GAMS STUDIO is automatically installed when GAMS is installed and you get the choice of whether to use STUDIO or the IDE as primary editor. To install do the following steps

  1. Download the GAMS installation file from www.gams.com under Resources and Download
    studio_download.png
  2. Start the installation

Installer should place an icon on the desktop yielding

studio_icon.png

Using STUDIO after Installation

During the install you will find

studio_install.png

Which allows you to choose which graphical interface to use as the default. For now choose STUDIO.

Open STUDIO through the icon

studio_icon.png

Open the File menu choice. Select a file.

studio_file_open.png

Note, the file location determines where all generated files are placed (to place files elsewhere use the save as dialogue) and where GAMS looks for files when executing. I recommend that you make sure your file is in a place where you want it also making sure that place contains all associated files ie this is the file storage directory for this endeavor.

Fix defaults and suppress cursor driven object highlighting. When first opening Studio go to settings and I would make sure check marks are as follows especially the checked ones in the red boxes and the unchecked green one

studio_settings1.png
studio_settings2.png

Here checking the Process Log and possibly the Explorer are of interest.

studio_view_output.png
The Explorer will open automatically when a file is opened and the Process Log will open when a solve is done. I usually hide the Explorer and sometimes want to get rid of the Process window.

Getting Started

Create or open an existing GMS file

Several cases are possible

  1. Create a new file (covered later)
  2. Open an existing file – at first this will be in

    studio_open1.png

    then you see something like

    studio_open2.png
  3. Open the GAMS model library explorer under the GAMS tab or press F6 (this is the simplest for first time users and the one we will use)

    studio_open3.png

    Select a model like trnsport.gms

    studio_open4.png

It will be automatically saved in the last directory you used or in the STUDIO default Workspace directory.

Prepare file for execution

When using model library trnsport.gms should now appear as part of your STUDIO screen.

studio_execution1.png

The STUDIO contains a full-featured editor. Go through the file and change what you want.

You can also customize the appearance somewhat through the settings choice under the File menu.

studio_execution2.png

There you can change font size (under editor), tabs, default file location (called workspace) and some other features on how GAMS runs. For now leave it alone.

Getting Started

Run GAMS by clicking the run button

studio_run1.png

The Process Log window (green) will then appear which logs the steps executed in running the model. The LST file (red) and the navigation window (magenta) also appear. Note to save space I would close the Explorer window and drag the Process Log window (green) to the bottom or the right hand side. The process window on the bottom is illustrated here and it is on the right side on the following picture.

studio_run2.png

Here it is after reconfiguring by dragging the Process Log up and to the right then resizing

studio_run3.png

Now use the process window (green) to navigate the LST file or open created files. By double clicking on lines in that window you access the LST file at particular locations or open created files. What and where you access is determined by the color of the line you click on.

studio_run4.png
Color of Line Function and Destination When Double Clicked
Blue line Opens LST file and jumps to corresponding place.
Non-bolded black line Control click on this takes you to LST file. Double click on error message takes you to spot in LST file.
Red line Marks errors encountered. Cursor is positioned at first red line. When clicked on cursor jumps to Source (GMS) file location of error. Control click takes you to error location in LST file. Error description text is in execution process log and in LST file. You can use a little red icon in source to jump to error message in LST file or a green arrow in the LST to go to error location in source.
Green line Causes studio to open a file that was created during the run like a GDX, PUT or REF file

Navigate with process window

After double-clicking on any non-red line, or if we used the automatically open list file option our main editing window is augmented by the LST file (green) (see the magenta tabs)

studio_lst1.png

We can navigate as we would with an editor or word processor, as we are automatically in STUDIO text editor.

Sometimes I want to get the process window and explorer out of the way. I can do this through the view window and also through the icons (red) on the right side of the top bar

studio_lst2.png

Clicking on these opens and closes the explorer and the process window.

Navigate with LXI window

studio_lxi1.png
Navig. Line Function and Destination When Clicked.
Compilation Jumps to top of echo print in LST file
Error Mess. Jumps to list of error messages when errors present
Equat. listing Jumps to list of equation contents
Equation Expandable allowing jump list of equation contents
Variab. listing Jumps to list of variable
Variable Expandable allowing jump to list of variable contents
Model stat. Jumps to model statistics part of LST file
Solut.Report Jumps to model summary solution report
SolEQU Expandable allowing jump solution for each equation
SolVAR Expandable allowing jump to solution for variable
Execution Jumps to beginning of post solve execution
Display Jump to displays of specific parameters and other items

Working with your own files

Now you are ready to work with your own files. You may already have a file or you may need to create one.

Creating a new file - Two principal ways

  1. Open an existing file through the library or from a location on your hard disk. Then use the save as dialogue from the file menu to change its name. Now modify contents to what you want. You may cut and paste as in other Windows programs.
  2. Open the file menu and use the new option. You will then be prompted for a name (I called it mine) with the extension .gms and then have a blank screen (green) into which you may type GAMS instructions

    studio_own_file1.png

    Save that file wherever you want and reopen it that will become the new default directory (this only occurs upon an open not a save as) and any subsequent non library opens, simple includes or saves will go there. Imports from the library go to the default workspace.

The Welcome and Explorer Windows

As you have worked with STUDIO you will find it shows a Welcome (magenta) window (unless you told it not to in settings), that remembers previous files plus gives access to documentation.

studio_welcome.png

There as of now you get links to files recently used, and links to some documentation.

Also on the left hand side is an Explorer (green) window that shows recent files and allows you to open by double clicking. This remains whether you are in the welcome page or editing files unless it is not checked in the View dialogue.

Fixing Compilation Errors

No one is perfect, errors always occur. The STUDIO can help you in finding and fixing those errors.

Let's look at an example with a small typo to illustrate (note: source vs. sorce). A run yields the windows below where the right part is the process window (green) positioned to show the first error and the center is the lst file (magenta) positioned to show the first error.

studio_fixerror_1.png

The red lines in the process window mark errors with error messages just below. To see where the errors occurred click on the very first red line which opens the source file or look at the LST file where the marking $ appears

A click on the red line takes you to the place in the source where the error was made. The tip here is always start at the top of the process file when doing this.

studio_fixerror_2.png

A double click on a black line takes you to the error location in the LST file.

Also in the source file window note the small red circle that appears on the line with the error

studio_fixerror_3.png

Clicking on that transfers you to the LST file where the error message appears.

studio_fixerror_4.png

And there a small gray circle with an arrow in it that when clicked on will transfer you back to the source file

Ways to find and/or replace text strings

For finding you can use the search menu under the Edit tab or control F

studio_findreplacestr_1.png

Subsequently you get

studio_findreplacestr_2.png

Which allows both search and replace. As of now this opens with the last option you used and may start with initially with an all files setting.

After the search you find

studio_findreplacestr_3.png

Where all occurrences of the search term in the current file are highlighted in yellow and to the right there is a list of all files that contain that search term (green) in all of the directories corresponding to files opened in the explorer.

The search dialogue is straight forward with arrow keys to jump to next (F3 also works for forward and shift F3 for backward) and the all files can be manipulated as shown (in yellow).

studio_findreplacestr_4.png

Matching Parentheses

The STUDIO provides you with a way of checking on how the parentheses match up in your GAMS code. This involves positioning your cursor just before an open parentheses or just after a close (Just after also works if there are not multiple parentheses). In either case the corresponding close or open is highlighted in green. Additionally positioning the cursor right before the beginning parentheses and tapping F8 will lead you to the matching ending parentheses whether it be 1, 100, or 1000+ lines away and vice versa.

studio_matchparentheses_1.png

When the expression in parentheses carries on the several lines the marking is in multiple lines and F8 will transfer position back and forth

studio_matchparentheses_2.png

This feature will also match up { } or [ ] with a red marking if the types don’t match.

Moving Blocks

The STUDIO allows one to move text blocks through standard Cut and Paste Operations in two fashions.

  1. One can identify a continuous block of text with the mouse or the keyboard (the latter involves putting the cursor at a beginning point then hold the shift key down and use the arrow keys).
  2. One can identify a column block of text (blue) with the mouse or the keyboard (these involve holding alt and shift down then moving the mouse or the cursor with the arrow keys.
studio_movingblocks_1.png

In turn copy, cut, and paste can be done with the Edit menu or with control c, x and v respectively as in normal windows. Control insert also pastes.

Also if one types with a column block highlighted than the character goes in all rows of the block and replaces what was there before

studio_movingblocks_2.png
with an * typed becomes

studio_movingblocks_3.png

Syntax Coloring

A feature in the STUDIO is syntax coloring. The STUDIO recognizes a subset of the GAMS syntax and reflects this in the display colors. Note in the display below that commands, explanatory text and set elements are differentially colored.

studio_syntaxcolor.png

For now unlike in the IDE one cannot alter these syntax colors.

Showing where a symbol appears

Studio has a feature that identifies where a symbol is used. Taking the library file agreste.gms and positioning the cursor over a symbol like c (blue) then double clicking places a (gray) highlight over all visible instances of that symbol

studio_showingsymbol.png

Accessing Documentation Via the Help

To access GAMS documentation choose help or F1

studio_dochelp_1.png

And if you choose documentation you get access through a window in lower right corner as shown. Therein you can navigate, search, and look at the index. Also if you get on the documentation page and go to the bottom you find the McCarl guide.

If your cursor is on a reserved word in the source file and you press F1 an index opens to all treatments of that word although in some strange places.

studio_dochelp_2.png

There is a document that explains features in the STUDIO and a YouTube video that can be accessed through the welcome page or in the general GAMS documentation under Tools.

Making GDX files

STUDIO can create and show GDX files. To create in STUDIO use the GAMS tab and choose a GDX creating choice. Alternatively use one of the other ways in the language as we will discuss elsewhere.

studio_gdx_1.png

To browse a GDX file open it with the file open dialogue or click on green lines for ones created during a run in the process window and then for the transport example

studio_gdx_2.png

Here in the left-hand panel one gets an alphabetical listing of the items in the GDX file and their characteristics. Then clicking on a left-hand panel item leads to the item contents being revealed in the right hand panel. As of now you can reorder columns and filter values then in table mode can move things in rows into columns and vice versa.

Examining GDX files

When you have opened a GDX file and selected an item then you get a window like that on the previous page

studio_examinegdx_1.png

If in the right-hand panel you dragged i to the right of value (brown below) you get

studio_examinegdx_2.png

Also by clicking on the header you cause the array to be sorted with a ^ marking the sort order and by clicking on

studio_examinegdx_filter.png
you can establish a filter (green above and brown below) and choose what elements to display (blue below).

studio_examinegdx_3.png
studio_examinegdx_4.png

A difficulty you will have

When using and teaching both the IDE and STUDIO, I find that file locations sometimes gives me fits. I have a rule of thumb to avoid problems, but you will most likely inadvertently not follow it.

When working with a model with multiple files make sure they are located in the same directory location.

You do not have to follow this rule but deviations are the same as asking for trouble. When you are actively working on a file that you have opened from a directory then STUDIO will look for files in the directory where active file is located.

Also when you run a file which contains includes GAMS will look in the directory where the active file is located.

Command Line Parameters

Experienced DOS or UNIX based GAMS users are used to having command line parameters associated with their GAMS execution commands. In STUDIO a command line parameter entry box (magenta) is available just to the right of the execute button. The parameters are associated with a file and STUDIO will remember these whenever the file is opened.

studio_commandline_1.png

This is particularly useful for save, restart, limrow, limcol, pw and rf parameters as once they are defined they are associated with every subsequent use of the file.

As of now there is no way to provide command line parameters for use in every run (like a wide page width) as there was in the IDE.

GAMS provides assistance with command line parameters through the command line parameter editor. To activate it check the

studio_commandline_extend.png
symbol at the far right (red) up top. Then part of the screen becomes as below. In the left hand part existing command line parameters (purple) in use (magenta) are listed along with their values. On the right all possible command line parameters are listed with definitions (green) and a search dialogue is provided (blue).

studio_commandline_2.png

The search dialogue looks for text in any of the fields, thus typing in wid brings up page width as does pw and maxi brings up those with maximum in the description.

Note pressing F1 while the cursor is on a command line entry opens help to a place with a detailed description of that parameter.

Using Libraries

STUDIO allows one to access libraries under the GAMS menu item and choosing the Model Library Explorer (purple).

studio_modlibs_1.png

In turn this opens a screen which identifies names of the libraries in tabs with a count of included files and, for the tab selected, the library contents. Furthermore across the top are tabs that when clicked on cause sorts. The picture below came after I clicked on the tab name with the model library active

studio_modlibs_2.png

Users can define their own libraries. They have to define what's called a GLB file and the formatting creation of this is discussed in my newsletter in the second issue: https://www.gams.com/mccarl/newsletter/news2.htm.

Using reference files - Listing and Unraveling Data items

GAMS has a command line parameter to create reference files (aka. .ref files) called reference (short: rf). These files give information on where things are defined and used.

Why? GAMS Modelers sometimes have to deal with complex implementations that

  • Use include statements to incorporate numerous files.
  • Have been developed by others.
  • Have a complex structure with definitions and uses of items widely spread in a file or files.
  • Contain items that are defined but never used.
  • Were developed some time ago but are not extensively documented.

When faced with such cases one often asks

  • Are there items defined in the program that are not used and if so what are they and where are they?
  • In what files is an item defined, declared and used?

To resolve these questions some years ago I wrote a Fortran program called GAMSMAP but never made it widely available. Subsequently it was included into the GAMSIDE and then STUDIO.

When a .ref file is opened it creates a window as follows

studio_reffiles.png

The column on the left (red) gives tags that can be clicked on and the key ones are

Column Description
All Symbols a list of items that are declared and a count of them
Set a list of the sets that exist in the program and a count
Variable a list of the variables in the program and a count
Parameter a list of the parameters (items defined in scalar, parameter or table statements) and a count.
Equation a list of the equations in the program and the names of files in which they appear
Model a list of the models that exist in the program and the names of files in which they appear
Unused a list of items that are declared or that are not used anywhere in the model
File used a list of the files included into the model

All Symbols Tab

The all symbols tab causes the output to appear as follows:

studio_reffiles_allsymbols.png

This shows all symbols used. The columns give

  • the symbol name (Name),
  • it’s type(Type),
  • its dimension (Dim),
  • the sets over which it is dimensioned (Domain)
  • the explanatory text used in it’s declaration (Text).

Things can be sorted by clicking on the column headings.

One can search for symbols using the box at the bottom

studio_reffiles_search.png

Sets, Parameters etc. Tabs

The display contains 5 lines that when activated give information for sets, parameters etc. The resultant display lists all items falling in a class (for all things that are sets or parameters etc.) and information on their characteristics and use. Specifically one gets output as follows (for the sets in this case)

studio_reffiles_sets.png

In this output once clicked on the entries tell the names of the files in which certain things happen relative to the identified items. The categories of things include the file name, line and column where items are declared, defined and used as discussed below.

Clicking on a line takes you to the file and place where the item appears.

Clicking on a column name causes it to be sorted.

After clicking on an item one gets

studio_reffiles_location.png

Entries in location columns identify files where items are

Column Description
Declared places where the named item is declared in a Set, Parameter, Table, Scalar, Variable, Equation, Acronym, File or Model command. This will be the first appearance.
Defined places set elements or data are explicitly entered. For equations this tells where the .. specification begins.
Assigned places where items appear on left hand side of an assignment statement
Implicitly-Assigned places where an equation or variable has data put into it by the results of a solve statement.
Controlled places where set is used in controlling a sum or defining an equation
Ref places where item is on left hand side of assignment statement or in a model equation

Clicking on lines here opens the subject file in the specific place

File used Tab

The file used tab causes the output to appear as follows:

studio_reffiles_fileused.png

This gives the names of the files included in the program with their full path references.

Unused Tab

The unused tab identifies items that are declared (in set parameter etc. statements) but are never used on the right hand side of an assignment (=) statement or in a model equation:

studio_reffiles_unused.png

which shows the same information as in the All Symbols tab except when an item is clicked on one gets information on the files where it is declared.

Steps to use the Reference File Viewer

The Reference File Viewer will only work after a particular “reference file” has been created by a GAMS run. The file is generated by adding the rf option to the command line call entering a command in the command line box of Studio as follows (a=c cause compilation only)

studio_reffiles_rfoption.png

Once the file has been run with the rf option the logfile is augmented with the (green) line identifying the .ref file name as below

studio_reffiles_reflog.png

Double clicking on this opens the Reference File Viewer window.

The run of GAMS with the rf option places the name of the .ref file in green in the GAMS log file and double clicking on that line causes the Reference File Viewer to be opened.

Several notes about the run

  • The rf= command specifies the name of the file the Reference File Viewer will use. Generally, the Reference File Viewer expects it to have the extension .ref.
  • The .ref file only covers the program components in a run and does not include any information from restart files. In general it is best to explicitly use all the files in one program without use of save and restart.
  • It is often useful to just generate the reference file without any execution on behalf of the GAMS program. This is done by including the a=c option on the command line or in the command parameter IDE box.

Editing Solver Option Files

Sometimes it is desirable to change solver specific options. This includes modifying things like branch and bound strategy, degree of scaling, barrier versus simplex solution approach, solution tolerances etc. The specific options allowed are described in the solver manuals. In addition Studio contains a solver option file editor that presents a solver specific menu of all possible options, default values and ones that have been altered. This is activated by either

  • Opening or saving a file with solvername.opt (Like MINOS.opt)
  • Right clicking on a group file name (red) in the Studio Explorer then selecting add new solver option file (blue) and subsequently selecting one of the many available solver names (magenta and only a few shown). This will create a file you then need to save.
    studio_solveroption_menu.png

Once it opens the general format of the solve option editor is as follows. Note the specific content depends on the solver chosen and in this case I use GAMSCHK.

studio_solveroption_editor.png

Here in the right part we see a list of all possible options (magenta) for this solver with boxes checked for those that are in the option file. A brief description of default values (blue), entry type (red), if relevant allowable settings (yellow) and a one sentence description of the option (green). In the left part we see the current entries (purple) in the option file and their settings (purple).

Subsequently when this file is opened or its tab activated then this solver option editor appears.

Note, pressing F1 while on an option opens help to a place with a detailed description of that option.

When is it Not Worth Using?

There are costs and benefits of these approaches.

The STUDIO is much easier for simple models and can run across platforms.

The DOS/command line approach is generally better for models in customized environments.

A development strategy for more complex implementations

  1. Use the STUDIO to get it right
  2. Debug components of large models using save and restart
  3. Then use script files or DOS/UNIX with batch files such as
    • GAMS mymodel  -lo 0 -s ./t/save1
    • call myprogram.exe
    • GAMS moremod  -lo 0 -r ./t/save1

What does it not do?

A number of IDE features are currently missing. Just to inventory (note the last three are pretty unimportant to me.)

  • The ability to do tiled windows and look at multiple cases of a file
  • Choice of default settings for solver to use for a problem type
  • Ability to save output from the reference files
  • GDX file differencing as a menu choice
  • Ability to change the file associations when clicking on them in Windows Explorer (you get more than I like at the moment and sometimes I want more)
  • Project files (mixed blessing)
  • Ability to manipulate syntax coloring scheme
  • Text file differencing (can use other programs)
  • Spell checking
  • Ability to call up a command prompt set up to run GAMS

What does it not do so well?

Here are also some difficulties with it as of today

  • Washed out colors – on my machine the syntax and error coloring is not very prominent.
  • Unusual bolding and choice of items to color in the syntax coloring with for example the column names in the table bolded but not the row names.
  • Confusing wording of just what is there for the library choice under settings and miscellaneous. Right now it simply tells you the name of the directory where library files are kept but when I first used it I thought it was where you would tell STUDIO about a new library and where it is located.

1) Specialist in Applied Optimization, Distinguished Professor of Agricultural Economics, Texas A&M University, Principal, McCarl and Associates, mccarl[at]tamu.edu, brucemccarl[at]gmail.com, http://agecon2.tamu.edu/people/faculty/mccarl-bruce/