This tutorial on using GAMS Studio was written initially by and is distributed by courtesy of Bruce A. McCarl ¹⁾. 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

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
   
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
   
2. Start the installation

Installer should place an icon on the desktop yielding

Using STUDIO after Installation

During the install you will find

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

Open STUDIO through the icon

Open the File menu choice. Select a file.

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

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

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

   

   then you see something like

   

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)

   

   Select a model like trnsport.gms

   

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.

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.

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.

Make sure right file is executed

Unlike a lot of other programs, STUDIO does not necessarily execute the file you have been working on rather executing what it calls the "main" file.

In particular, if you activate the explorer view then the main file is the one marked with a green triangle as below. If the triangle is not marking the file to be run you need to right click on that file and then choose Set as main file. In turn the triangle will move.

Run GAMS by clicking the run button

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.

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

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.

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)

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

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

Navigate with LXI window

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

   

   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.

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.

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.

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

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

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

Subsequently you get

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

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

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 Ctrl + b will lead you to the matching ending parentheses whether it be 1, 100, or 1000+ lines away and vice versa.

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

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.

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

with an * typed becomes

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.

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

Accessing Documentation Via the Help

To access GAMS documentation choose help or F1

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.

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.

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.

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

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

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

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

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

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.

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

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

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.

Solver Option Files

STUDIO allows you to edit or create a solver option file. When using the solver Conopt you create conopt.opt or with Cplex use cplex.opt (or .op1 or .o10 or .111) and more generally solvername.opt. Specifying such a file allows you to manipulate the way the solver works on the model. For example, you can alter scaling, tolerances, iteration limits, solver algorithm, and branch and bound strategy along with many other things.

Now in Studio the option file editor is accessed by either

• Right clicking on the group name (red) for a group where you want an option file then choosing add new solver option file (blue) and picking the appropriate solver name (magenta)
  
• Creating a file like baron.opt then when you bring that up in the editor the option file editor appears. In the editor you see options in use (blue), possibilities and definitions (red)
  

Using Libraries

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

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

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

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

All Symbols Tab

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

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

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)

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

Entries in location columns identify files where items are

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:

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:

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)

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

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.
  

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.

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

• Ability to save output from the reference files
• 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)
• Text file differencing (can use other programs)
• Spell checking

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.
• Excessive library choices and no way to put the ones you have no interest in somewhere out of the way. Plus any user defined libraries are at the end and there is no way to reorder.

¹⁾ 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/