GAMS Studio

GAMS Studio is a completely new integrated development environment for GAMS, which is available for Windows, Mac OS X, and Linux. It is based on C++ and Qt.

Note
In addition to this technical documentation, there is also a tutorial about the usage of GAMS Studio.

Motivation

The classic GAMS IDE has been shipped with the GAMS system for the last 20 years and is still the workhorse for many GAMS programmers. However, the existing IDE does not provide all the features we see in modern development environments. Due to its underlying software technology, implementing new features in the current IDE turned out to be a poor option, so work on a new development environment started from scratch. GAMS Studio is based on C++ and Qt, which makes it fast, reliable, and platform independent (Windows, Mac OS X, and Linux). An overview about the differences between GAMS Studio and the classic GAMS IDE can be seen at the end of this chapter (for long-time GAMSIDE users, especially the difference between IDE projects and Studio groups might be interesting).

Central Widgets

Welcome Page

The Welcome page is the starting point of GAMS Studio. It is designed to give quick access to common actions and to offer helpful information. It is divided into three columns.

On the very left there is a column labeled "Last Files" which lists all files that have been opened recently in Studio with the most recent file on top. A simple left click on an item in this list opens the corresponding file. The middle column named "Getting Started" offers useful actions and links for new users. The upper half contains shortcuts to create new files in user defined locations, open the GAMS Model Library Explorer or load the Transport example. The lower half has a link to the Studio introduction video on YouTube and two further links that open the integrated help view showing either this Studio documentation or the page with the GAMS tutorial overview. The rightmost column "Further Help" contains a link to the recent changes of GAMS Studio, the latest GAMS release notes, the GAMS World Forum for support and information about how to contact GAMS.

welcome.png
Welcome page

Code Editor

The Code Editor provides common functionality for editing with GAMS specific syntax highlighting. On the left side there is a special area displaying the line numbers and icons for links and errors generated by the compiler.

1. Basic Text Manipulation

Action Shortcut macOS Description
Copy Ctrl - C Command - C Copy selected text
Cut Ctrl - X Command - X Cut selected text
Paste Ctrl - V Command - V Paste text from clipboard
Select All Ctrl - A Command - A Select whole document
Switch Comment Ctrl - * Command - * (Un)Comment all lines in selection
Undo Ctrl - Z Command - Z Reverts the latest text change
Redo Ctrl - Y or
Ctrl - Shift - Z
Command - Shift - Z Restores a previous Undo

2. Advanced Text Manipulation

Action Shortcut macOS Description
Remove Line Shift - Del Removes the current line
Duplicate Line Ctrl - D Command - D Duplicates the current line
Lowercase Alt - Shift - L Option - Shift - L Toggle selection to lower case
Uppercase Alt - Shift - U Option - Shift - U Toggle selection to upper case
Tab Tab Tab Add spaces till next tab size
Untab Shift - Tab Shift - Tab Remove spaces till previous tab size
Indent Ctrl - I Command - I Indent complete line
Outdent Ctrl - Shift - I Command - Shift - I Outdent complete line
Find Ctrl - F Command - F Open Search & Replace window, filling search field with selected text if there is any.
Find Next F3 F3 Jump to next search result if
Find Previous Shift - F3 Shift - F3 Jump to previous search result

3. Navigation & Selection

Action Shortcut macOS Description
Zoom In Ctrl - + or
Ctrl - = or
Ctrl - Wheel Up
Command - + or
Command - = or
Command - Wheel Up
Zoom in
Zoom Out Ctrl - - or
Ctrl - Wheel Down
Command - - or
Command - Wheel Down
Zoom out
Reset Zoom Ctrl - 0 Command - 0 Reset zoom
Match Parentheses Ctrl - B Command - B Jump to matching parenthesis
Select Parentheses Ctrl - Shift - B Command - Shift - B Select to matching parenthesis
Toggle Bookmark Ctrl - M Ctrl - M Toggle bookmark
Previous Bookmark Ctrl - , Ctrl - , Go to previous bookmark
Next Bookmark Ctrl - . Ctrl - . Go to next bookmark
Scroll Up Ctrl - Up Command - Up Scroll up (keeping cursor position)
Scroll Down Ctrl - Down Command - Down Scroll down (keeping cursor position)
Scroll Page Up Ctrl - PageUp Fn - Up Scroll page up (keeping cursor position)
Scroll Page Down Ctrl - PageDown Fn - Down Scroll page down (keeping cursor position)
Start of Line Home Command - Left Go to the start of line (or lines content)
End of Line End Command - Right Go to the end of the line
Start of Document Ctrl - Home Fn - Left Go to the start of the document
End of Document Ctrl - End Fn - Right Go to the end of the document
Previous Word Ctrl - Left Option - Left Go to previous start of word (or character class)
Next Word Ctrl - Right Option - Right Go to next start of word (or character class)
Start/Change Block Edit Alt - Shift - Up or
Alt - Shift - Down
Option - Shift - Left Mouse Button Start/Change block edit selection
Start/Change Block Edit Alt - Left Mouse Button Option - Shift - Left Mouse Button Draw block edit selection
Start/Change Block Edit Alt - Shift - Left Mouse Button Option - Shift - Left Mouse Button Span block edit selection from text cursor to mouse click
Change Block Edit Alt - Shift - Arrow Key Option - Shift - Left Mouse Button Span block edit selection

The Code Editor looks for parenthesis to the right then to the left of the cursor and marks valid and invalid nesting. Hitting Ctrl - B moves the cursor to the matching parenthesis keeping the state inside/outside. To select the block to the matching parenthesis hit Ctrl - Shift - B.

Syntax Highlighting

The GAMS Studio syntax highlighter recognizes different kinds of source code like

  • $control option with some special treatments (like $OffText, $OnText, etc.)
  • comments, e.g. line comments and comment block
  • keywords like declarations or loops
  • description as descriptive text for identifiers
  • data statements for identifiers or table data
  • ...

To get the best highlight result it is recommended to use strict GAMS syntax.

Automatic closing of brackets and quote characters

This feature is meant to improve convenience for users typing source code. In GAMS, as in pretty much every other programming language, opening brackets or quote characters are followed at some point by a closing equivalent. So when a user types one of the following characters the matching closing character will also be inserted after the text cursor. This allows the user to easily type the content in between. When typing the closing character which should be right after the cursor the already existing character will be jumped over. So when a user types the closing character by force of habit the autoclose feature does not interfere or causes syntax errors. Also possible is to make a text selection and then type a bracket or quote character. The selected text will then be surrounded by the chosen character pair. In the GAMS Studio under Settings > Editor > "Auto close opening brackets and quotes" a switch is available to turn this auto-close feature off.

List of characters that trigger insertion of a closing character:

  • (
  • {
  • [
  • "
  • '

Other editors also close the < character but in the GAMS language context it is used in a different way, making it unnecessary to be closed automatically (e.g. as a comparison operator). In some cases user might not like the closing character to be inserted automatically however, this is hard to predict. Other editors - like Qt Creator - check what the next character after the cursor is. Only a limited set of characters allows the automatic insertion of the closing character.

Following characters allow auto closing when being the next char after the text cursor:

  • Whitespaces
  • ,
  • ;
  • )
  • ]
  • {
  • }

All others will prevent the insertion of characters.

File Encoding

When opening a file Studio tries to assume the valid file-encoding. As it is not possible to safely determine the encoding the Edit > Encoding menu assists. To reload a file using another codec the reload with ... submenu can be used. With the convert to ... submenu the current file can be converted to another codec. A selection of encodings is preselected. This selection can be changed using the Select encoding submenu. It opens a dialog where the active encodings can be selected. One of them is marked as the Default encoding. Initially is is set to utf-8.

Bookmarks

The Code Editor provides the ability to set temporary bookmarks in the text files opened in main tabs. If Studio is closed they are dropped. Also if a file tab is closed the bookmarks for this file are dropped. A bookmark is placed at the current position of the current file using the toggle bookmark key. A line in the editor can only carry one bookmark. If this line has a bookmark already the existing one is removed. The keys for next/previous bookmark allow to navigate through the bookmarks beyond file bounds.

Listing Viewer

The Listing Viewer is used for displaying a GAMS output or listing file (*.lst) which is generated when running a GAMS (.gms) file. The Listing Viewer consists of two sides. On the left side, the content of the listing file is presented in a tree structure that allows for convenient navigation within the listing file. The right side shows the listing file itself.

By clicking on a specific item in the tree on the left hand side, the listing file will automatically jump to the corresponding location. Changes of the cursor position in the listing file are dynamically reflected in the tree by selecting the item that belongs to the current section of the listing file.

lstviewer1.png
Listing Viewer showing trnsport.lst generated by running trnsport.gms from the GAMS Model Library

When the GAMS process returns with a compilation error the Listing Viewer contains links to the source file. If the source file doesn't exist anymore the link is still shown but striked out.

lstviewer2.png
Listing Viewer showing blend.lst generated by running a modified blend.gms

GDX Viewer

The GDX Viewer is used to open and inspect GDX (GAMS Data eXchange) files. A GDX file contains GAMS symbols such as sets, parameters, variables, and equations in a binary format that serves as input and output to GAMS. The GDX Viewer component consists of two sides. The left side displays the symbol table of the open GDX file in a table format. Every entry represents a symbol and consists of the following information:

  • Entry: The index of the symbol
  • Name: The identifier of the symbol
  • Type: The type of the symbol (Alias, Equation, Parameter, Set, or Variable)
  • Dim: The dimension of the symbol
  • Records: The number of records of the symbol
  • Text: The explanatory text of the symbol
gdxviewer1.png
Symbol table showing trnsport.gdx generated by running trnsport.gms from the GAMS Model Library
A specific column can be sorted by clicking on the respective column header. Clicking again toggles the sorting direction. The Filter facility provides dynamic filtering of the list of symbols contained in the GDX file using wildcard syntax. By default, only the Name column is taken into account by the filter. By selecting the All Columns check box, the search considers all other columns as well. The right side of the GDX Viewer displays the actual data of the symbol that is selected in the symbol table. Data can be displayed in either the List View or the Table View which can be toggled using the corresponding button in the upper part of the GDX Viewer.

List View

The List View is the default representation when looking at data using the GDX Viewer. The data is presented in the form of a table in which each row represents a record of the symbol. Each record consists of key columns corresponding to the symbols dimension. The value columns vary according to symbol type:

  • Set/Alias: Column Text contains the explanatory text of a record, Y if no explanatory text is available.
  • Parameter: Column Value contains the numerical value of a record.
  • Variable/Equation: Five numerical columns: (Level, Marginal, Lower, Upper, Scale).
gdxviewer2.png
Right side of GDX Viewer showing the parameter d from the trnsport model
The header allows to manipulate the displayed data in several ways. By left clicking on a column header, the corresponding column is sorted using a stable sort mechanism that does not change the order of equal entries. Clicking again changes the sorting direction. Due to the Extended Range Arithmetic used by GAMS, columns containing numerical data can contain special values. Those values are treated in a special way when being sorted:

  • -INF: Smallest numerical value.
  • EPS: Treated as value very close but different from 0.
  • +INF: Largest numerical value.
  • NA: Treated as first non-numerical value (sorted as being greater than +INF).
  • UNDEF: Sorted as being greater than NA.
  • ACRONYMS: Sorted as being greater than UNDEF. Relative order of acronyms is by their internal number.

The order of columns can be changed by dragging a column header and dropping it at a different position. Dragging the border between column headers allows for resizing the widths of the involved columns. The columns in the List View offer a filter facility which can be opened either by right clicking on the column header or by left clicking on the filter icon. The Reset button in the top right corner can be used to reset the view to defaults. This removes all filters, resets the applied sorting as well as the applied numerical format and switches back to the List View in case the Table View was active.

The button Preferences opens a menu containing different settings for the current symbol. Squeeze Defaults can be used on variables and equations in order to hide all columns that have the default value of the respective variable or equation type. Squeeze Trailing Zeroes allows to turn on/off the truncation of trailing zeroes. The displaying format of numerical values can be specified using the Format drop down menu and the Precision spin box.

The available options for the Format are as follows:

  • g-format: The display format is chosen automatically: f-format for numbers closer to one and e-format otherwise. The value in the Precision spin box specifies the number of significant digits. When precision is set to Full, the number of digits used is the least possible such that the displayed value would convert back to the value stored in GDX. Trailing zeros do not exist when precision=Full.
gdxviewerNPg6.png
Variable mix from the prodmix model using g-format with precision=6
gdxviewerNPgFull.png
Variable mix from the prodmix model using g-format with precision=Full
  • f-format: Values are displayed in fixed format as long as appropriate. Large numbers are still displayed in scientific format. The value in the Precision spin box specifies the number of decimals.
gdxviewerNPf6.png
Variable mix from the prodmix model using f-format with precision=6
  • e-format: Values are displayed in scientific format. The value in the Precision spin box specifies the number of significant digits. When precision is set to Full, the number of digits used is the least possible such that the displayed value would convert back to the value stored in GDX. Trailing zeros do not exist when precision=Full.
gdxviewerNPe6.png
Variable mix from the prodmix model using e-format with precision=6
The value in the Precision spin box specifies the number of decimals or the number of significant digits depending on the chosen format:

  • g-format: Significant digits [1..17, Full]
  • f-format: Decimals [0..14]
  • e-format: Significant digits [1..17, Full]

Next to Preferences is the Attributes button. This button opens a menu that allows to hide certain attribute columns of variables and equations explicitly. This is especially useful when using the Table View.

Filter Facility

When the List View is active, the column header can be used in order to open the filter dialog either by right clicking on the column header or by left clicking on the filter icon. Depending on the type of the column (key or value), the appropriate filter dialog for labels or numerical values is opened.

The filter dialog for a specific key column shows all occurring labels of that column in a list. Per default all labels in all columns are visible. Shrinking the displayed data can be achieved by unchecking one or more labels. The filter is applied by clicking the Apply button. Instead of selecting labels manually one can also use the wildcard string filter in the upper part of the filter dialog. The filter is automatically applied to the list of labels. Matching labels will be selected while all others will be deselected. The Hide unselected items checkbox can be used to automatically hide all deselected labels. This is especially useful for larger amounts of labels in combination with the wildcard string filter as only the matching labels will remain in the list while typing. The Select All and Deselect All buttons allow for selecting/deselecting all labels.

gdxviewer3.png
Filter dialog on column j for variable x in trnsport.gdx
Numerical columns offer a different filter type that allows to specify an interval for values that should be included or excluded in the view for this specific column. The Min value is the lowest and the Max value is the largest one still included in the view. When the Exclude check box is activated, the specified range is excluded from the view instead of included. The lower part of the filter contains check boxes for special values like +INF or EPS. Checking/unchecking will show/hide the corresponding values in the view. Clicking the Apply button adds the filter to the column and refreshes the view accordingly. The Reset button removes an active filter.

Note
When a filter on a numerical column is applied, the values used for comparison are the actual values from the GDX file. Since the displayed values are influenced by the Format and the Precision setting, they can differ from the internal ones from the GDX file. Here is an example: Let's assume we have a parameter p(i) with p("i1")=1.34 and p("i2")=2. With format set to g-format and precision set to 2, the values are displayed as 1.3 and 2. When applying a filter with the bounds (Min, Max) set to 1.33 and 2 both records are still shown even though 1.33 is greater than 1.3 (number shown in the GDX Viewer) since the internal GDX value used for comparison is actually 1.34.
gdxviewer6.png
Filter dialog on numerical column Value for parameter c in trnsport.gdx

Table View

Switching to the Table View is possible for symbols that have at least two dimensions. In this representation data is reshaped into a format where the labels of the last dimension are moved into the column header while the remaining dimensions go into the row header. The entries in the table are the numerical values (or explanatory text in case of GAMS sets) of the record with the corresponding labels of the headers. The following image shows the List View of a GAMS Parameter on the left side and its representation in the Table View on the right side:

gdxviewer4.png
Two dimensional parameter as List View and Table View
In case of GAMS variables and equations, a virtual dimension for the five numerical values (Level, Marginal, Lower Bound, Upper Bound, Scale) is introduced and displayed in the column header. When looking at the data of variables or equations it is most of the time useful to visualize only a specific attribute like the variable levels. This can be achieved by using the Attributes menu in the upper part of the GDX Viewer. The menu allows to hide specific attributes explicitly by disabling the corresponding checkboxes.

Both column and row header dimensions can be moved into different positions in order to reshape the table view. This can be done by performing a drag-and-drop operation that starts by clicking (and holding) the left mouse button while the mouse cursor is located on the index that should be moved. Moving the mouse to an arbitrary location will bring up a drop indicator (in the form of a thin line) that previews the position in which the index will be dropped as soon as the mouse button is released. In general all index positions can be moved to arbitrary new locations, but there are a few restrictions:

  • The (virtual) numerical dimension of variables and equations (Level, Marginal, Lower Bound, Upper Bound, Scale) can not be moved and is always the last dimension in the column header.
  • If a header (column or row) runs out of dimensions, a dummy header (Value, Text) is introduced which can not be moved but can be used as a drop target for further drag-and-drop operations.
gdxviewer5.png
The table view representation of a GAMS parameter during a drag-and-drop operation that will move the dragged dimension into the position indicated by the drop indicator (thin black line)
While filters that have been applied in the List View will also be applied to the Table View, sorting does not have any effect. The labels are sorted using the internal order which can not be changed by the user. For large data it is recommended to reduce the amount of visible records by applying filters in the List View and by disabling certain value columns in case of variables and equations. Once the data has been reduced, switching to the Table View allows to look at the data in a compact format.

Summary of Actions and Shortcuts

Action Shortcut macOS Description
Jump to Symbol Search Ctrl - F Command - F Moves the focus to the Symbol Search input field located above the symbol table
Select All Ctrl - A Command - A Selects all data (right side only)
Copy (comma-separated) Ctrl - C Command - C Copy selection to clipboard using comma as separator
Copy (tab-separated) Ctrl - Shift - C Command - Shift - C Copy selection to clipboard using tab as separator (right side only)
Auto Resize Columns Ctrl - R Command - R Resizes all columns to content (right side only)

Reference File Viewer

The Reference File Viewer is a useful tool to navigate the source code of GAMS models via a reference file, especially when multiple files are involved. A reference file contains all symbol references of GAMS model and is created using the rf parameter when running the model.

refviewer_option.png
Parameter to create a symbol reference file when running the model

When the model is compiled, the reference file with ".ref" extension is created and can be opened either using the menu: File > Open or double-clicking the "RefFile" entry in the Process Log:

refviewer_outputlink.png
Process Log showing clickable entry for the reference file

The Reference Viewer is categorized by a number of tabs:

refviewer_tabs.png
Reference File Viewer showing tabs and reference file information
  • All Symbols shows an alphabetical listing of all symbols used in the model.
  • Set, Acronym, Variable, Parameter, Equation, and Model shows an alphabetical listing of symbols of the same type. See Data Types and Definitions for more details on GAMS data types.
  • File shows an alphabetical listing of all file statements used in the model.
  • Function shows a list of GAMS built-in functions that has been used in the model.
  • Unused shows an alphabetical listing of all symbols that have been declared in the model but are not used anywhere.
  • File used shows an alphabetical listing of all files used in the model including the full file path. A double-click on an file entry of the table will jump to the beginning of the reference file.

The number next to the tab name indicates how many symbols in the category, where the number of All Symbols tab sums up the number of symbols in all other tabs except Unused tab and File used tab. A click on a symbol entry of the table in every tab (except File used tab) will show the detailed reference list containing the reference location in the right hand side of the reference viewer. A mouse-over on an entry of the reference list will show the tooltip of file location and position with the file that has been referenced. A double-click on an entry of the reference list will jump to the position in the corresponding file that has been referenced.

The reference list is organized by the following reference types:

Reference Type Description
declared Declaration of the symbol.
defined Defined using a data statement.
assigned When the symbol appears on the left side of an assignment statement.
implicitly assigned Implicit assignment like a variable in a model.
control When the set is used as a control set.
reference Referenced in a statement.

The detailed description of the reference types and their shorthand symbols can be found in Reference Types in GAMS Output.

Sort and Filter referenced symbols

  • Sort : A click on a table column header in the reference table will sort the symbol in the table by either Entry, Name, Type, Dim(ension), Domain, or Text.
  • Filter : An input in the Filter box will search and display the symbol in the reference table by Name. A search in all columns can be enabled by checking All Columns next to the Filter box.

Summary of Actions and Shortcuts

Action Shortcut macOS Description
Symbol Search Ctrl - F Command - F Jump to the focus to the Symbol Search input field located above the symbol table
Auto Resize Columns Ctrl - R Command - R Resize all columns to content (right side only)

Solver Option Editor

The Solver Option Editor is used to view and edit a solver-specific option file for controlling solver and interpreting results. See usage of The Solver Options File in Solver Usage and how to set optFile parameter to instruct gams to read an option file in The GAMS Call and Command Line Parameters. The Solver Option Editor provides an editor to edit the file contents in a table form where a row entry corresponds to a line in the solver option file. The Solver Option Editor also provides a browser of solver option definitions which can be displayed in group or be filtered by search and where the option can be directly added into or deleted from the editor.

The Solver Option Editor consists of the contents editor in the left pane, option definition browser in the right pane, as well as message and configuration tab in the bottom pane.

solver_editor_components.png
  • The left pane shows the contents editor of solver option file in a table form. Each row entry is either an option entry containing the option key, option value, as well as end-of-line comment (shown if there is definition of end-of-line comment characters for a solver option file) or a comment entry. Below the editor shows Compact View checkbox and Open As Text button
    • An option key and value are shown in green color when defined correctly according to the definition, otherwise in red color when there is an error. An end-of-line comment (if defined) and a comment entry are shown in grey color. (see section Toggle comment/option selection on how to turn an option entry into a comment entry and vice versa)
    • A comment row entry is shown in a merged cell as differences between option key van value are not identified in a comment line of a solver option file.
    • The Compact View checkbox enables the editor to display the file contents without comments. Note that some editing actions are suppressed when the editor is in compact view (see section Compact View for more details).
    • The Show Messages checkbox allows to display or hide the messages log at the bottom pane.
    • The Open As Text button allows to reopen the file in the text editor once contents of the file has been saved (see Open an existing solver option file and Save a solver option file in section Basic Operations for more details).
  • The right pane shows a browser of solver option definitions.
    • The lower part of the browser lists all option definitions, each contains Option Name, Synonym, Default Value, Range, Type, and Description. The list can be sorted alphabetically in ascending or descending order by clicking the Option Name header. A checkbox in front of an option entry indicates whether there is an option of this definition entry defined in the left pane editor. An entry with enumeration type (EnumStr or EnumInt) can be expanded to show all enumerated values of the option by clicking the bullet in front of the option entry, clicking the bullet again hides all enumerated values of the option. By double clicking the entry or dragging the entry and dropping in the left pane editor adds the option key with the default value defined by this option definition in the left pane editor (See section Summary of Actions and Shortcuts on how to add or insert an option).
    • Above the list of all option definitions are a group of options and a search box. Option groups filters the list of option definitions by group name. By default all option definitions are displayed. Search box with placeholder text Search Option... allows a simple search through all option definitions. As a search keyword has been typed into the search box the results are displayed in the list of option definitions below. The search performs case insensitvely on all fields of option definitions including enumerated values.
  • The bottom pane shows the message log which reports the operations that have been carried out such as the contents have been loaded and saved as well as errors resulting from editing the contents. By default the message log is shown unless the Show Messages checkbox in the left pane has been unmarked to hide the message log.

Basic Operations

  • Create a solver option file: via either the Studio menu or the project group context menu in project explorer.
    • From the Studio menu, choose File > New... then enter a valid solver option file name and suffix into the file dialog. choosing Add new file by right clicking on project name in project explorer brings up the same file dialog for entering a valid solver option file name and suffix (See how to set different suffix values for solver option file from optFile parameter).
    • From the project group context menu, right clicking on project name in project explorer and choosing Add new solver option file brings up a list of solver names. Selecting a solver name from the list brings up a file dialog with the selected solver name as file name and the default option file suffix name opt (See how to set different suffix values for solver option file from optFile parameter).
  • Open an existing solver option file: via either the Studio menu or project group context menu in project explorer.
    • From the Studio menu, choose File > Open... and select Option Files or All Files in the file dialog and then select a solver option file.
    • From the project group context menu, right click on project name then choose Add Existing file then choose Option Files or All Files in the open file dialog and then select a solver option file.
    • In case a solver option file is already opened with solver option editor, the file can be reopened in text editor by choosing Reopen File As Text from the file context menu in project explorer.
    • It is possible to open the solver option file in either solver option editor or text editor.
      • In case a solver option file has already been opened in solver option editor, choosing Reopen File As Text from the file context menu in project explorer closes the solver option editor and reopens the file in the text editor. Note that Open As Text button in the left pane editor performs the same function.
      • In case a solver option file is already opened in text editor, choosing Reopen File using Solver Option Editor from the file context menu in project explorer closes the text editor and reopens the file in the solver option editor.
      • In case a file is already listed under the project group entry but not yet opened, choosing Open File from the project group context menu opens the file in the solver option editor; however, choosing Open File As Text from the project group context menu opens the file in the text editor.
  • Save a solver option file: activated by choosing either File > Save menu or Ctrl - S shortcut. Choosing File > Save As menu or Ctrl - S shortcut brings up a file dialog to choose a file with different name to be saved as (See also how to set different suffix values for solver option file from optFile parameter).

Navigating the contents

When a component of the solver option editor in focus, it is possible to perform further actions (see section Summary of Actions and Shortcuts for the list of actions and shortcuts). Clicking the component area will bring the component into focus or in selection. In addition to using mouse to navigate the solver option editor components, it is also possible using keyboard. Press Tab key navigates the components of the solver option editor. For example, when left pane editor is in focus, pressing Tab navigates from the left pane editor, to the right pane option group box, to the right pane Search box, and to the right pane definition browser in the describing order. When the left pane editor is in focus, press Up, Down, Left, and Right keys to navigate the left pane editor table. When the right pane browser is in focus, press Up and Down to navigate the definition entries, press Right to expand/show the enumerated entries of the definition, and press Left to collapse/hide the enumerated entries of the definition.

There is a connection between an option entry in the left pane editor and a definition entry in the right pane browser. When navigating the solver option editor, it is possible to identify this connection from both the left pane editor and the right pane browser.

  • From the left pane editor, right click on the selected entry and choose show option definition from the context menu. The entry in the right pane browser that contains the definition of the selected entry is highlighted and selected. When a cell or a row is already selected the shortcut Ctrl - F1 delivers the same behavior.
solver_editor_showdefinition.png
  • From the right pane browser, click or select on an entry. All entries in the left pane editor will be highlighted and selected if the definition has already been added. Otherwise there will be no selection in the left pane editor.

More editing actions can be performed on both the left pane editor and the right pane browser (See Editing the Contents for details).

Editing the Contents

The followings describe actions that can be performed when editing the contents:

solver_editor_actions.png
actions to be performed via the left pane editor and the right pane editor
  • Edit option key, value, and comment: This action performs in the left pane editor.
    • when the cell in the left pane editor is selected, double click on the cell or press platform-dependent edit key (eg. F2) in order to edit option key, value, or comment (if available). A drop-down list suggests possible option keys and option values as when possible. Press Enter to confirm the edit and press Esc to cancel the edit.
solver_editor_edit.png
Drop-down lists suggest possible keys (left) and values (right)
  • Add new option: This action appends a new option entry as the last entry of the left pane editor. There are several ways to add a new option entry.
    • click on the plus icon in the header of the left pane editor, a new option entry with dummy option key [KEY], option value [VALUE], and option comment [comment] (if available) is appended as the last entry.
    • it is also possible to add new option from the the right pane browser. Select the definition entry in the right pane browser that has not been added/inserted into the left pane editor (a solid checkbox in front of the entry is not marked), double click or right click on the selection then choose add this option. A new option entry ith the option key and default value of this definition will be added as the last entry in the left pane editor. and dummy option value [VALUE] is appended as the last entry.
  • Insert new option and comment: It is possible to perform this action from the left pane editor and from the the right pane browser and there are several ways to insert a new option or a comment entry.

    • right click on the selected entry in the left pane editor and choose insert new option from the context menu. A new option entry with dummy option key [KEY], option value [VALUE], and option comment [comment] (if available) will be inserted before the selected entry. When a cell or a row is already selected the shortcut Ctrl - Return delivers the same behavior.
    • right click on the selected entry in left pane editor and choose insert new comment from the context menu. A new option entry with dummy text [COMMENT] will be inserted before the selected entry. When a cell or a row is already selected the shortcut Ctrl - Shift - Return delivers the same behavior.
    • double click on a definition entry in right pane browser.

      • In case this definition has not yet been added/inserted (a checkbox in front of the entry is not marked), a new option entry with the option key, default value, and comment (if available) of this definition will be added as the last entry in the left pane editor. When there is a selection on a cell or a row the shortcut Return delivers the same behavior.
      • In case this definition has already been added/inserted (a checkbox in front of the entry is marked), by default the studio option editor will ask for overriding existing option if there is an option from the same definition that has already been added/inserted into the left pane editor. A pop-up message box appears and offers three alternatives: either to replace existing entry, or to add new entry, or to abort. Replace existing entry will remove all other entries of this definition key but the first entry from the left pane editor and replace the option value of the entry by the default value defined by the definition. Add new entry will add a new option entry with the option key and default value of this definition into the left pane editor. Abort will cancel the action. See section override existing option on how to suppress this default behavior.

      When double clicking an enumerated value entry of the definition a new option entry will be added with the option key of the parent entry and the selected enumerated value.

    • drag a definition entry from the right pane browser and drop in the left pane editor.
      • In case this definition has not yet been added/inserted (a checkbox in front of the entry is not marked), a new option entry with the option key, default value, and comment (if available) of this definition will be dropped before the position of selected entry in the left pane editor.
      • In case this definition has already been added/inserted (a checkbox in front of the entry is marked), by default the studio option editor will ask for overriding existing option if there is an option from the same definition that has already been added/inserted into the left pane editor. A pop-up message box appears and offers three alternatives: either to replace existing entry, or to add new entry, or to abort. Replace existing entry will remove all other entries of this definition key but the first entry from the left pane editor and replace the option value of the entry by the default value defined by the definition. Add new entry will insert a new option entry with the option key and value of this definition before the position of selected entry in the left pane editor. Abort will cancel the action. See section override existing option on how to suppress this default behavior.

    See also section Settings on how to insert a new option together with a comment from the definition.

  • Toggle comment/option: This action performs in the left pane editor, turning an option entry into a comment entry and turning a comment entry into an option entry.
    • select the option entry and right click on the selection, then choose toggle comment/option selection from the context menu. In case of an option entry this action turns the entry into a comment entry (shown in grey color). In case of a comment entry this action turns the entry into an option entry entry (shown in either green or red color depending on whether or not there is an error). When a cell or a row is already selected the shortcut Ctrl - * delivers the same behavior. Clicking on the color box in front of the entry row also delivers the same behavior, even without a selection.
  • Move up and down: These two actions perform in the left pane editor, changing the order of the option and comment entries.
    • to move an entry up in the left pane editor: select the option entry and right click on the selection, then choose move up from the context menu. The selected option entry will be moved one position up the option entry table. When a cell or a row is already selected the shortcut Ctrl - Up delivers the same behavior.
    • to move an entry up in the left pane editor: select the option entry and right click on the selection, then choose move down from the context menu. The selected option entry will be moved one position down the option entry table. When a cell or a row is already selected the shortcut Ctrl - Down delivers the same behavior.
  • Deleted option: It is possible to perform this action from the left pane editor and from the the right pane browser.
    • from the left pane editor, select the option entry and right click on the selected, then choose delete selection. The selected option entry will be deleted from the option entry table. When there is a selection on a cell or a row the shortcut Ctrl - Delete delivers the same behavior.
    • from the right pane browser, select the definition entry that has already been add/inserted into the left pane editor (a checkbox in front of the entry is marked) and right click on the selection then choose remove this option. All entries in the left pane editor defined by this definition will be deleted from the option entry table. When there is already a selection on a definition row the shortcut Delete delivers the same behavior.
  • Show option definition: This action performs in the left pane editor. Right click on the left pane of the option editor and choose Show option definition. The option definition entry on the right pane will be highlighted. The shortcut Ctrl - F1 delivers the same behavior.
  • Show all options of the same definition: This action performs in the left pane editor. Right click on the left pane of the extended editor and choose Show all options of the same definition. All option entries on the left pane will be highlighted. The shortcut Shift - F1 delivers the same behavior.
solver_editor_recurrent.png
All entries of the same option are highlighted

Compact View

Compact View of the solver option editor allows to view and edit solver option without comments. Comments in a solver option file are not interpreted by either GAMS or the solver but used for documentation purpose. As the contents of the solver option file grows larger with several comment lines, it can be difficult to see which options eventually will be interpreted. To this end, the compact view becomes useful to hide all comments and show only non-comment lines. In the right pane editor, mark Compact View checkbox to activate the compact view and unmark the checkbox to deactivate the compact view. The comment entry is shown again once the compact view is deactivated.

Note that the result of some actions are not visible when in compact view. For example, action toggle comment/option selection when performed on an option row entry, turning the entry into a comment entry and therefore hidden from the compact view. Action delete selection when performed on an option row entry, removing the content entry and therefore no longer visible hidden from the compact view.

Some editing actions that can change the order of the contents are suppressed. These actions are insert new option, insert new comment, move up, and move down. Nevertheless adding or inserting option from the right pane are allowed, but a comment that has been inserted with the option (if set) are not visible in compact view. See also section Settings on how to insert a new option together with a comment from the definition.

Settings

The setting tab allows to configure the behavior when inserting new option from definition and deleting option. The setting can be accessed by opening the Settings dialog (File > Settings) and switching to the Misc. tab. These configurations are:

  • Override existing option. This behavior allows Studio to override existing option when an option entry has been added or inserted from the right pane browser. In case there are more than one entry of the same option, Studio will pop-up a message box to offer three alternatives: either to replace existing entry, or to add new entry, or to abort.

    • Replace existing entry will remove all other entries of this definition key but the first entry from the left pane editor and replace the option value of the entry by the default value defined by the definition.
    • Add new entry will add or insert a new option entry with the option key and default value of this definition into the left pane editor.
    • Abort will cancel the action.

    By default this behavior has been set. In the Settings dialog, unmark the checkbox in front of the text overriding existing option to suppress the behavior and mark to enable the behavior.

  • Add option description as comment above. This behavior allows Studio to add option description as additional comment entry above an option entry that has been added or inserted from the right pane browser. The description has been taken from the option definition in the right pane browser. By default this behavior has not been set. In the Settings dialog, mark the checkbox in front of the text add option description as comment above to enable the behavior and unmark the checkbox to suppress the behavior.
  • add option description as end of line comment This behavior allows Studio to add option description as additional end-of-line comment of an option entry that has been added or inserted from the right pane browser. The end of line comment is only available when the solver defines valid end of line characters. The end-of-line comment column will be shown in the solver option editor only when available (there is definition of end-of-line comment characters for a solver option file). By default this behavior has not been set. In the Settings dialog, mark the checkbox in front of the text add option description as end of line comment to enable this behavior and unmark the checkbox to suppress the behavior.
  • delete all immediate comments above This behavior allows Studio to delete all immediate comments (if there is any) above when deleting an option. By default this behavior has not been set. In the Settings dialog, mark the checkbox in front of the text delete all immediate comments above to enable this behavior and unmark the checkbox to suppress the behavior.

Summary of Actions and Shortcuts

Actions and their shortcuts that can be performed via the left pane of solver option editor are:

Action Shortcut macOS Description
Toggle option/comment selection Ctrl - * Command - * Toggle between option and comment
Insert new option Ctrl - Return Command - Return Insert a new option
Insert new comment Ctrl - Shift - Return Ctrl - Shift - Return Insert a new comment
Delete selection Ctrl - Delete Delete the selected option/comment
Move up Ctrl - Up Command - Up Move the selected option/comment up for 1 row
Move down Ctrl - Down Command - Down Move the selected option/comment down for 1 row
Select all Ctrl - A Command - A Select all options
Show option definition Ctrl - F1 Command - F1 Show definition of this selected option in the right pane
Show all options of the same definition Shift - F1 Show all options of the same definition defined in the right pane
Resize columns to contents Ctrl - R Command - R Resize the columns in the left pane to contents

Actions and their shortcuts that can be performed via the right pane of solver option editor are:

Action Shortcut macOS Description
Option Search Ctrl - F Command - F Jump to the focus to the Option Search input field
Add this option Return Return Add option in the left pane from the selected definition
Remove this option Delete Remove option defined by this definition from the left pane
Copy option name Ctrl - C Command - C Copy option key from this selected definition
Copy option description Shift - C Shift - C Copy option description from this selected definition
Copy definition text Ctrl - Shift - C Command - Shift - C Copy option text from this selected definition
Resize columns to contents Ctrl - R Command - R Resize the columns in the right pane to contents

GAMS Configuration Editor

The GAMS Configuration Editor is used to view and edit a GAMS Configuration File in YAML Format. The editor shows the two configuration sections: command line parameters (commandLineParameters), and operating system environment variables (environmentVariables), in different tabs of the editor.

guc_editor_clp.png
guc_editor_env.png
Contents of gamsconfig.yaml shown in GAMS Configuration Editor

Note that GAMS Configuration editor does not show the contents of the third section: external solver configuration (solverConfig) if exists. However, the contents in this section will be written out to the file when saving the file via the editor. It is possible to use Reopen File as Text from Project Explorer context menu to reopen and edit the file contents in text editor when the file is already opened in the GAMS Configuration Editor and use Open File as Text from Project Explorer context menu to open the file in text editor when the file is not yet opened in any editor. See the syntax of gamsyconfig.yaml file from GAMS Configuration File in YAML Format.

GAMS will process a sequence of gamsconfig.yaml files from different locations (see the location of GAMS Configruation file from The GAMS Configuration in YAML Format and the order of precedence for command line parameters from Order of Precedence for Options). Studio can create a new gamsconfig.yaml file at the default user-specific location and open the file in the editor when the file at the location does not exist. This can be done by choosing GAMS > Default GAMS Configuration. In case the file already exists at the default location, choosing GAMS > Default GAMS Configuration will not override the gamsconfig.yaml in the default user-specific location but open the file in the editor.

guc_editor_menu.png
Menu entry point to create/open gamsconfig.yaml file from default location

It is possible to save the gamsconfig.yaml file into different location using File > Save As....

Tab Browser

The Tab Browser is accessible with a button next to the main tab bar or via the shortcut Ctrl - 4. It opens a list of all open files and features a search input field. When opening the tab browser, the search field is already focused. Typing updates the list in real time. The Enter key selects the first item in the list and opens it. It is also possible to use arrow up/down to navigate the list and select an item with Enter. The filter supports wildcard syntax.

Dock Widgets

Project Explorer

The Project Explorer provides a group organization of files opened in Studio. The Project Explorer lists all files and their corresponding group in a flat hierarchical tree structure with Project Explorer as its root. A group entry is listed with the folder icon and its tooltip tells the location of the group in the file system. To support faster detection there are several icons for different file types:

  • The runnable GAMS files (currently supported .gms and .inc) are listed with GAMS icon,
  • the main GAMS file assigned to the group additionally contains a green play symbol,
  • GDX files (.gdx) have an database icon,
  • Reference files (.ref) are shown with a reference nodes on a sheet,
  • editable files (e.g. .txt) contain a pen on a sheet,
  • read-only files (e.g. .log) contain lines on a sheet.

The tooltip of a file entry tells the location of the file in the file system. The file location and the group location can be explored using the default file system explorer via the context menu "Open location". Selecting "Open terminal" opens the systems terminal in the location of the selected file or group. The context menu of a .gdx file provides a special entry "Open in GDX Diff" that opens the specific GDX Diff Dialog.

projectexplorer.png
projectexplorer_filemenu.png
Project Explorer and its context menu

A group entry is created automatically when opening a file, the groups name is determined by the name of the opening file. One group may contain multiple runnable GAMS files but only one runnable GAMS file is set as the main file, marked with a green arrow over its GAMS icon. By default the first runnable GAMS file in a group is considered the main file. The tooltip of a group also tells the location of the folder and the name of the current main file. Additionally the name of the recently created output file (.lst) is shown after the first run. The main file can be changed to other runnable GAMS file in a group via the context menu "Set as main file".

The main file will be executed when pressing F9 or clicking the execute button (see how to set GAMS parameters and execute the main file in Quick Access Toolbar and GAMS Parameter Editor). After executing the main file, the generated listing file (.lst) is added to its group and the output view (see Process Log) is opened. A clickable log line in the process log may add the corresponding file into the group and open the file in the Central Widgets area. Users can manually add more files to a group by right-clicking and choosing either "Add existing file" or "Add new file" from the context menu.

Files can also be removed from a group and group can be removed from Project Explorer via the two actions "Close group" and "Close file" from the context menu. The action "Close group" closes all files in the group if opened as well as removes all file entries and the group entry from the Project Explorer without actually touching the file on the file system. The action "Close file" closes the file if opened and removes the file entry from the group. In case the closed file is the only entry in the group, the group is also closed accordingly. In case there are unsaved changes a message popup will appear, asking the user how to proceed.

It is possible to select multiple items in the project explorer. A selection always contains items of one kind, files or groups never both depending on the first selected item. The context menu then addresses all selected items.

Selected files can be dragged to another group. By dropping them they are moved to the destination group. Pressing the Ctrl key creates a copy of the file-reference in that group (no file copy). If the group already contains a specific file it is just ignored.

Actions like rename, move, or delete from file system are currently not supported but will be added in the future.

Note
For long-time users of the classic GAMS IDE the section about the differences between IDE projects and Studio groups might be of particular interest.

Process Log

After starting a GAMS process the LogViewer is opened to view the process Log. Usually the Log stays at the bottom to keep tracking the latest log lines. The tracking can be paused by clicking on the up arrow of the vertical scrollbar. To continue tracking drag the scrollbar to the bottom.

The Log usually contains links of different kinds:

  • compilation errors (red): Links to the gms file where the error occurred. Additionally contains a link to the listing file (.lst) at the beginning of the line (blue).
  • listing links: Links to a specific line in the listing file
  • file link (green): Links to a file without line numbers such as .gdx or .ref

Clicking on a link takes the focus to that file (and line). Double-clicking in the Log looks for the nearest link to the listing file and takes the focus there. Files that were not part of the current project are added when they are opened by link.

For general messages there is the System Log stacked together with all Process Logs. It keeps track of Studio related messages not originated from a specific GAMS run.

Quick Access Toolbar and GAMS Parameter Editor

The toolbar contains two parts: a quick access section and GAMS Parameter editor to customize how GAMS is executed the model (see The GAMS Call and Command Line Parameters).

studio_toolbar.png

The quick access section contains icons for performing common File actions like New, Open, and Save , as well as accessing Settings dialog, Model Library Explorer dialog, Project Explorer view, Process Log, and Help view.

The GAMS Parameter Editor provides a way to control and customize the execution of a GAMS model. The editor displays the parameters of the group of the file that is currently opened in Central Widgets (see also Project Explorer for group and its runnable files). The parameters can be typed into a combobox and the execution of a GAMS model can be carried out using the following pre-customized execution commands:

exec_runcompile_cmd.png
  • Run: Choose Run or press F9 to compile and execute GAMS statements in the main runnable file. This execution command is equivalent to running GAMS with the default parameter action=CE (Compile and Execution).
  • Run with GDX Creation: Choose Run with GDX Creation or press F10 to compile and execute GAMS statements in the main runnable file and create a GDX file with the name of the main runnable file and a gdx extension. This execution command is equivalent to running GAMS with the combination of the two parameters action=CE and gdx=default.
  • Compile: Choose Compile or press Shift - F9 to compile GAMS statements in the main runnable file. This execution command is equivalent to running GAMS with the parameter action=C (CompileOnly).
  • Compile with GDX Creation: Choose Compile with GDX Creation or press Shift - F10 to compile GAMS statements in the main runnable file and create a GDX file with the name of the main runnable file and a gdx extension. This execution command is equivalent to running GAMS with the combination of the two parameters action=C and gdx=default.

The pre-customized execution command will operate on the main file (marked with a little green arrow over the regular icon) of the active group (see how to manage the main file in section Project Explorer). In case GAMS parameters have been set they will be appended to the pre-customized commands. Just like the GAMS Terminal, when there are identical parameters with different values the last one "wins" and overwrites the previous ones. Thus it is possible for a user to change and override GAMS Studio default parameters, which can possibly lead to problems if done incorrectly. In this case Studio prints out a warning message, informing users about potential problems. To debug what Studio does the full GAMS call parameters will be printed to the system log. After execution, the parameters will be added into the group history. All files in a group share one parameter history. The previous GAMS parameters can be recalled from the group history via the drop-down menu of the combobox. Switching the file opened in Central Widgets will activate the different group history only when the group of the newly opened file is different from the group of the file before switch.

The parameters curDir and workDir behave slightly differently in Studio compared to the terminal. When using one of these parameters on the command line GAMS expects the gms file to be in the given folder. In Studio the path to the input file is always given as an absolute one. Therefore, there is no need to use the inputDir parameter to make the gms file accessible to GAMS if it is not in the specified working directory.

The GAMS Parameter Editor provides a way to either interrupt or stop the currently running job when an execution of a GAMS model is in progress (indicating with animated icon over the project folder icon in Project Explorer) :

exec_interruptstop_cmd.png
  • Interrupt: Click the Interrupt button or press F12 to send an interrupt request to the running job in order to perform a graceful stop and collect an incumbent result back from the execution if the solver supports this feature. The command is enabled when there is a job that is currently running in the group and disabled when there is no currently running job in the group.
  • Stop: Click the Stop button or press Shift - F12 to send a request to stop the running job immediately. The command is enabled when there is a job that is currently running in the group and disabled when there is no currently running job in the group.

The Extended GAMS Parameter Editor allows to configure the GAMS parameters. The extended parameter editor is shown when the Show button next the parameter combobox is clicked or with the shortcut Ctrl - Alt - 3. The editor can be hidden when the button is clicked again. When shown, the GAMS parameters from the parameter combobox will appear as a list of entries in the left pane of the extended parameter editor, each entry contains the Key and Value.

Note that the GAMS parameter combobox will be disabled when the extended parameter editor is shown and all editing has to be done in the extended parameter editor.

option_editor_activation.png
Extended GAMS Parameter Editor is shown when the button next to parameter combobox is clicked

The right pane of the extended editor displays the list of all valid parameter definitions, each contains Parameter Name, Synonym, Default Value, Type, and Description. The parameter definition entry with enumeration type (EnumStr or EnumInt) can be expanded to show all enumerated values of the parameter by clicking the bullet in front of the parameter entry, clicking the bullet again will hide all enumerated values of the parameter. Above the list of all valid parameter definitions is a search box (with placeholder text Search Parameter...) to allow a simple search through all parameter definitions. As a search keyword has been typed into the search box the results will be displayed in the list below. The search will perform on all fields of parameter definitions including enumerated values.

The parameter editor displays potential parameter errors in red color both in the combobox and in the left pane of the extended editor. When hovering a mouse over the error key or value, a tooltip with more detailed explanation of the error appears.

option_editor_error.png
Parameter key turns red with pop-up tooltip when there is a potential error
option_editor_erroroutput.png
Process Log reports parameter errors when running the model with an unknown option parameter

When there are several entries of the same parameter, all other entries except the last entry will be ignored when gams executes the model. In such case, the combobox of parameter editor displays a warning in yellow and the icon in front of the parameter in the extended editor turns half-yellow in combination of another color, red or green, depending of whether or not there is a potential error.

option_editor_warning_red.png
option_editor_warning_green.png
Parameter key turns yellow and the pop-up tooltip indicating a warning

See edit parameter key and value on how to edit parameter key and value that contains an error or a warning. See show all parameters of the same definition on how to locate all entries of the same parameter.

The followings describes all editing actions that can be performed via the extended parameter editor:

option_editor_menu.png
option_editor_def_menu.png
A number of actions that can be performed via the context menus of Extended Parameter Editor
  • Edit parameter key and value: double click on key cell to edit Key and on value cell to edit Value of the entry. A drop-down list will suggest possible keys and values when possible. Press Enter to confirm the edit and press Esc to cancel the edit.
option_editor_keyedit.png
GAMS Parameter editor shows a drop-down list of all possible parameters started with 'o'
option_editor_valueedit.png
GAMS Parameter editor shows a drop-down list of all enumerated values of parameter 'action'
  • Add new parameter: there are several ways to add a new parameter via extended parameter editor.

    • right click on the left pane of the parameter editor and choose add new parameter from the pop-up context menu
    • right click on the selected parameter entry of the parameter table and choose add new parameter from the pop-up context menu
    • click on the add new parameter button next to Key table header in the left pane

    A new entry will be added at the end of parameter entry table with dummy parameter key [KEY] and dummy parameter value [VALUE]. See edit parameter key and value on how to edit parameter key and Value.

    It is also possible to add a new parameter from the right pane of the parameter editor by double clicking at the definition entry in the right pane. The selected definition entry will be added as a new parameter entry at the end of table in the left pane. In case of double clicking an enumerated value entry of a parameter definition the definition entry will be added as a new parameter with the selected enumerated value. Otherwise the default value of the entry will be added.

option_editor_add_dclick.png
Parameter with enumerated value added by double clicking at the selected entry in the right pane
  • Insert new parameter: right click on the selected entry and choose insert new parameter. A new entry will be inserted before the selected entry with dummy parameter key [KEY] and dummy parameter value [VALUE]. See edit parameter key and value on how to edit parameter key and value.
  • Move up: right click on the selected entry and choose Move Up. The selected entry will be moved one position up the table. This action will change the order of parameters.
  • Move down: right click on the selected entry and choose Move Down. The selected entry will be moved one position down the table. This action will change the order of parameters.
  • Delete selection: right click on the selected entry and choose Delete Selection. The selected entry will be deleted from the table.
  • Delete all parameters: right click on the left pane of the extended editor and choose Delete all Parameters. All entries will be deleted from the table.
  • Show parameter definition: right click on the left pane of the extended editor and choose Show parameter definition. The parameter definition entry on the right pane will be highlighted.
  • Show all parameters of the same definition: right click on the left pane of the extended editor and choose Show all parameters of the same definition. All parameter entries on the left pane will be highlighted.
option_editor_recurrent_menu.png
option_editor_recurrent.png
All entries of the same parameter are highlighted
  • Resize columns to contents: right click on the left or right pane of the extended editor and choose Resize columns to contents. All columns will be resized according to their contents.
  • Add this parameter: right click on the right pane of the extended editor and choose Add this parameter. The parameter with default value (if defined) of the selected definition will be added as the last entry on the left pane of the extended parameter editor. This action in the context menu is enabled only when there is no entry of this parameter on the left pane. Note that a double click on the definition will also perform add this parameter action. Performing the action on the parameter definition that has already been added will pop-up a dialog indicating that the parameter exists on the left pane and prompting for one of the followings:
    • replace existing entry If there is only one entry or replace the first entry and delete other entries if there is more than one entry, or
    • add new entry of the same definition, or
    • show details of all entries of the same parameter, or
    • abort the action
option_editor_recurrent_dclick.png
A pop-up dialog when adding the definition parameter that has already been added
  • Remove this parameter: right click on the right pane of the extended editor and choose Remove this parameter. The parameter of the selected definition will be deleted from the left pane of the extended parameter editor. This action in the context menu is enabled only when there is an entry of this parameter definition on the left pane. In case there are multiple entries of the same parameter, all entries on the left pane will be deleted.

Press F1 on a parameter entry in the extended parameter editor will activate the The GAMS Call and Command Line Parameters help page containing the detailed description of the GAMS parameter.

Summary of Actions and Shortcuts

Actions and their shortcuts that can be performed via Toolbar and GAMS parameter editor are:

Action Shortcut macOS Description
New Ctrl - N Command - N Open new file dialog
Open Ctrl - O Command - O Open file open dialog
Save Ctrl - S Command - S Save the current file. If the file does not exist on disk open the save file dialog
Settings F7 Command - , Open the Settings dialog
Model Library F6 F6 Open the Model Library Explorer dialog
Run F9 F9 Run main file of current group with GAMS
Run with GDX Creation F10 F10 Run main file of current group with GAMS and create a GDX file
Compile Shift - F9 Shift - F9 Compile main file of current group with GAMS without execution
Compile with GDX Creation Shift - F10 Shift - F10 Compile main file of current group with GAMS and create a GDX file without execution
Interrupt F12 F12 (Gracefully) Interrupt currently running GAMS job
Stop Shift - F12 Shift - F12 Stop currently running GAMS job
Show extended parameter Ctrl - Alt - L Command - Option - 3 Open the extended GAMS parameter editor
Project explorer Ctrl - 1 Command - 1 Open Project Explorer
Process Log Ctrl - 5 Command - 5 Open Process Log
Help F1 F1 Open the GAMS Help.

Actions and their shortcuts that can be performed via the left pane of the extended GAMS parameter editor are:

Action Shortcut macOS Description
Insert new parameter Ctrl - Return Ctrl - Return Insert a new parameter
Delete selection Ctrl - Delete Delete the selected parameter
Delete all parameters Alt - Delete Delete all parameters
Move up Ctrl - Up Command - Up Move the selected parameter up for 1 row
Move down Ctrl - Down Command - Down Move the selected parameter down for 1 row
Select all Ctrl - A Command - A Select all parameters
Show parameter definition Ctrl - F1 Show definition of this selected parameter in the right pane
Show all parameters of the same definition Shift - F1 Show all options of the same definition defined in the right pane
Resize columns to contents Ctrl - R Command - R Resize the columns in the left pane to contents

Actions and their shortcuts that can be performed via the right pane of the extended GAMS parameter editor are:

Action Shortcut macOS Description
Parameter Search Ctrl - F Command - F Jump to the focus to the Parameter Search input field
Add this parameter Return Return Add option in the left pane from the selected definition
Remove this parameter Delete Remove option defined by this definition from the left pane
Resize columns to contents Ctrl - R Command - R Resize the columns in the right pane to contents

Integrated Help

The Help View is designed to integrate the navigation of the GAMS documentation into GAMS Studio. Press F1 or choose Help > Documentation or check View > Help to start the Help View and browse the documentation. The start page of the Help View is the main document page available in the GAMS distribution that has been used to run GAMS Studio. See Home on how to always navigate back to the start page of the document. Click Close button or uncheck View > Help to dismiss the Help View. GAMS Studio will remember the last viewed page along with its browsing history until GAMS Studio is restarted.

The Help View starts in docking state for the first time and can be docked around the editor in the central widgets area by either dragging the view to the desired location. Studio will remember last state of the Help View before it was closed.

helpview_docked.png
Help View when docked to the right of Code Editor

The Help View can also be floated by double clicking the title part of the Help View. Dragging or double clicking the title of the Help View again will dock the Help View.

helpview_floated.png
Help View when floated

Note that the Help View does not offer the full browsing features of a web browser. Though the help view offers a Open this page in Default Web Browser button to use the full features of a web browser.

An overview of Help features:

  • Home: Start the start help page [GAMSDir]/docs/index.html
  • Back: Back to previous page
  • Forward: Go to next page
  • Reload: Reload the content of this page
  • Stop: Stop loading the content of this page
  • Bookmarks:
    • Bookmark this page: Store the title of the page as the name of bookmark together with its location. The entry of the bookmark will appear below the Organize Bookmarks section. Click on an entry to jump to the page that has been bookmarked.
      helpview_bookmark.png
    • Organize Bookmarks: Open the bookmark dialog to edit or delete a bookmark entry. Right click on the selected entry in the bookmark table, then either load the selected bookmark in the Help View, or delete the selected bookmark. The selected bookmark Name and Location can be edited from the lower part of the bookmark dialog and press Enter. Press Esc to cancel the edit. Click close button to dismiss the bookmark dialog.
      helpview_bookmarkdialog.png
  • Zoom In: Zoom in the page to increase the font size. Press Ctrl - +, or Ctrl - Mousewheel Up or choose View > Zoom In menu to zoom in the page.
  • Zoom Out: Zoom out the page to reduce the font size. Press Ctrl - -, or Ctrl - Mousewheel Down or choose View > Zoom Out menu to zoom out the page.
  • Reset Zoom: Reset the font size of the page to its original size. Press Ctrl - 0 or choose View > Reset Zoom menu to reset zoom in the page.
  • Help Option :
    • View This Page Online : Browse the same documentation on GAMS website. This, for example, allows to use more sophisticated search functionalities across all GAMS documentation of version 31.2 or to browse different version of documentation, or to browse the GAMS website from the Help View.
    • Open in Default Web Browser : Browse the same document in default web browser. As the help view does not offer the full features of a web browser, this allows to browse the documentation using the full web browser features in default web browser.
    • Copy page URL to Clipboard : Copy of the current page's URL to the clipboard. This, for example, help to see the URL of the currently viewed page of the document.
      helpview_option.png
  • Find in page... : Press Ctrl - F or choose Edit > Search menu to activate a search at the bottom area of the Help View. Type in a word to be found in the page. The word found in the page will be highlighted as it has been typed in and the number of found occurrences will be highlighted in the scrollbar of the Help View. Click previous button to find the previous occurrence, and click next button or press Enter to find the next occurrence. Check Case Sensitivity box to find a word case sensitively. Highlighting the word stays as the document is navigated from page to page until the keyword is clear or the search is dismissed or the Help View is closed or invisible. Click the close button or press Esc to dismiss the search.
helpview_search.png

Help on Specific widgets

It is possible to jump directly from directly from different widgets (Welcome Page, Code Editor, Listing Viewer, GDX Viewer, Reference File Viewer, and Solver Option Editor) to the related part of the document.

From Welcome Page, Listing Viewer, GDX Viewer, and Reference File Viewer, press F1 will activate the GAMS Studio page and jump to the section corresponding to the widget. From GAMS Parameter Editor, press F1 on a parameter entry in the extended parameter editor will activate the The GAMS Call and Command Line Parameters help page containing the detailed description of the GAMS parameter. From Solver Option Editor, press F1 on an option entry in the editor will activate the related solver page containing the detailed description of the option.

From Code Editor, it is possible to jump to the document page that describes Dollar Control Options or to the index page that lists entries related to Data Types and Definitions and Language Items in Code Editor, as well as from the parameter editor to the GAMS parameter described in The GAMS Call and Command Line Parameters :

helpview_f1_dollar.png
helpview_f1_keyword.png
helpview_f1_option2.png
Help View when press F1 on parameter entry 'output' in extended parameter editor
helpview_f1_option1.png
Help View when press F1 on parameter definition entry 'LimRow' in extended parameter editor

Summary of Actions and Shortcuts

Action Shortcut macOS Description
Zoom In Ctrl- + or Ctrl - Wheel Up Command - + or Command - Wheel Up Zoom in the page to increase the font size
Zoom Out Ctrl- - or Ctrl - Wheel Down Command - - or Command - Wheel Down Zoom out the page to reduce the font size
Reset Zoom Ctrl - 0 Command - 0 Reset the font size of the page to its original size
Search Ctrl - F Command - F Jump to the help search box to search for a keyword in the current page

MIRO

GAMS Studio can be used to develop models for GAMS MIRO. Please go to the GAMS MIRO documentation to learn more about the features and workflow of the MIRO integration.

GAMS MIRO Shortcuts

Action Shortcut macOS Description
Run base mode F8 F8 Run main file of current group with MIRO in Base Mode
Run hypercube mode Shift - F8 Shift - F8 Run main file of current group with MIRO in Hypercube Mode
Run configuration mode Shift - F7 Shift - F7 Run MIRO configuration mode

Dialogs and Actions

About GAMS

The About GAMS dialog is part of the GAMS Studio Help menu. It provides information about the used GAMS as well as available solvers, which lists the solver licenses and their capabilities. Furthermore, the dialog can be used to install a GAMS license. To do so the steps below have to be applied.

  1. Copy the GAMS license to the clipboard
  2. Open GAMS Studio and click on About GAMS
  3. A messages box shows up if a GAMS license has been found on the clipboard. If 'Yes' is clicked the new license will be installed and presented via the About GAMS dialog; otherwise the old license is shown.

Check for Update

Check if a more recent version of GAMS or GAMS Studio is available for download (and can be used with the present license) and report the results. The information shown uses the current license file for this.

Search and Replace

Action Shortcut macOS Description
Open/Focus Search Dialog Ctrl - F Command - F Opens the search dialog or focusses it if it is already open, if Text is selected it will automatically be entered as a search term
Find next F3 or Enter F3 or Enter Jumps to the next match that fits all search criteria
Find previous Shift - F3 Shift - F3 Jumps to the previous match
Find All Shift - Enter Shift - Enter Starts a search, opens the page of search results and jumps to the first hit
Close Dialog Esc Esc Closes the search dialog. On second press any highlights of results will be removed

Pressing the Ctrl - F opens the Search and Replace window. If text is selected it will be pasted into the search field. Users can search specific files with it and do text replacement operations in the current file. Depending of which is the main file open in the editor, the search widget changes to visualize which actions are available. Due to technical limitations .gdx files cannot be searched, also replacing in read-only file types (e.g. lst or ref) is deactivated. For reasons of performance the search stops when reaching 50000 search results. This is visualized in all places where the number of matches is shown by showing "50000+" as the results number, indicating that there might be more results.

searchandreplace.png
Search window in its default configuration
In the first row of the search widget from left to right the following items are located: Search field, which takes the search term and saves a list of recent searches. Next to it there is a "Find All" button which starts a search in a user defined scope. In the output pane of studio a table containing all matches will open. Items can be double clicked to perform a jump to the result. Information about the file, the location of the match, plus some context information are also shown. Right of "Find All" there are the find previous occurrence and find next occurrence buttons located, labeled "<" and ">" respectively. These will find and highlight the next word matching the search criteria either before or after the current text cursor position.

The next row houses items related to the replace functionality. Most of these are deactivated for files that are opened in read-only mode (e.g. .lst). First comes the replace input field where users can input the text which replaces the search term. "Replace All" replaces all matches in the currently selected scope after a pop-up is shown asking the user whether the replacement of n occurrences of X with Y is intended. In this pop-up the user can also decide to start a search instead, opening the results page showing all occurrences of the would-be replace action. The next button is "Replace" and works similarly to Find Next. On the very first click it selects the next match, without replacing anything. On the next click it replaces the current selection with the replacement term and jumps to the next match, selecting it. Users can use this to click through a file, replacing words while keeping an overview over what is actually changed. If the search options are set accordingly, the editor jumps to the next file eligible for replace actions. Both replacement actions can be undone by pressing either the undo button or hotkey Ctrl - Z. The button "Clear" on the far right clears all highlighted results and both text fields. A shortcut to clear all results is to press the Esc key in the Code Editor.

The last row contains options to narrow down a search. "Whole Words" excludes partial hits from matches. For example, when searching for "in" with the option checked only the word "in" is found but no occurrences in "information". "Case Sensitivity" sets if the case of letters in the search term matters. Reminder: The GAMS language is case insensitive, so this option can actually lead to incomplete results, depending on for what it is used. "Use Regex" actives an advanced search term interpretation mode and stands for Regular Expressions. When activated, instead of a single search term users can specify a pattern that matches an array of different words. Click here for further information about regular expressions.

The "File Pattern" drop-down menu can be used to filter the files to be searched. Using a wildcard syntax patterns of filenames can be specified. The drop-down menu comes with a few default options for GAMS specific file types but can also be used to enter own patterns. Right next to it is another, non-editable drop down menu which works like a simpler filter. The scope of the search can be set here with four options available:

  • "This File" limits the search to the currently active file and is the default. File patterns are ignored for this option.
  • "This Group" searches all files that belong to the same group as the currently opened file. A group of files are all children of the same node in the Project Explorer.
  • "Open Tabs" searches all files currently opened in Studio (except GDX files).
  • "All Files" searches all files that appear in the Project Explorer and are searchable.

Tooltips are available for most items in the search window and contain further information like keyboard shortcuts.

Workflow Tips

  • Edit a file, hit Ctrl - F to open the search widget. The search field is focused automatically so you can start typing your search term. Pressing the Enter key is a shortcut for Find Next. Press Enter again or F3 to step through all matches. Press Shift - F3 to step backwards. Make changes to you document, press Ctrl - F again to re-focus the search widget without having to pick up the mouse.
  • Enter a search term, and then Shift - Enter to trigger "Find All". This will open a list of results.
  • The Esc key will close the search widget. Pressing Esc again will clear all highlighted search results.
  • Use groups or file prefixes when working with projects with many files. Use search filters to only search relevant files.

Model Library Explorer

The Model Library Explorer is used to search the different model libraries provided by GAMS and to retrieve their models in a convenient way. It can be opened either by choosing GAMS > Model Library Explorer from the menu, by using the shortcut F6 or by clicking the corresponding icon in the Quick Access Toolbar.

Every library is presented in a separate tab. The search facility in the upper part of the Model Library Explorer allows for dynamic filtering of all model libraries simultaneously using a wildcard syntax. As the search string is entered, the results are applied to the tabs representing the different libraries. The parenthesis enclosed numbers indicate the number of models found for the specific library and the current search input. For a more sophisticated search syntax select the Regular Expression checkbox next to the search input.

modlibexpl1.png
Searching for trns in the Model Library Explorer

Beside a short description, several models have a longer and more detailed description available. Selecting a model and clicking on the Description button in the lower right corner opens a pop-up dialog showing further information about the model. A model can be opened either by clicking on the Load button, by double clicking or by selecting the model and pressing the Enter key.

User Libraries

Additionally to the model libraries distributed by GAMS, it is possible to access user defined model libraries by providing a GLB file along with the corresponding files belonging to the models in the library. The Model Library Explorer looks into a specific location for user defined model libraries. This location can be accessed by opening the Settings dialog (File > Settings) and switching to the Misc. tab. The Open Location button will show the location where the Model Library Explorer tries to find user defined model libraries. Adding a new library is done by copying the required files into a subdirectory in this location. See Creating a User Library on how to create a custom model library. Newly added libraries require a restart of the Model Library Explorer to become visible.

Settings

The GAMS Studio settings dialog can be accessed via the File > Settings menu entry or with the hotkey F7. Users can change certain aspects of Studio like behavior or appearance. Settings are categorized loosely on four tab pages. On the first tab called "General" users can set the Default GAMS Studio workspace. This path is used as a default location for libraries imported from the Model Library Explorer. Automatically save modified files before GAMS run is an option that saves all modified files in the current group when the user starts a GAMS run. Thereby, previously unsaved changes will be incorporated into that GAMS execution without the need to go through all files and make sure that changes were saved manually. Open .lst file after running GAMS automatically puts the generated lst file into the foreground after each GAMS run. Jump to first compilation error is an automatism that aims to make working with Studio a little easier. When compilation errors occur, the editor and the log both jump to the first error detected if this option is activated. This also applies when the option Open .lst file after running GAMS is activated. Then, Studio opens the lst file generated and jumps to the first error in it. If you navigate back to the gms file, the view has also moved to the first error found. At the bottom of the first tab there is a section to backup all settings. When pressing the Export button a dialog pops up, asking for a filename. This name can be chosen freely and the file can than be copied to a USB stick for sharing, or just be saved for later. This is handy if you are planning a fresh install or want to copy your personal settings to a different machine. The button Import is used to load a saved settings file. These settings are applied immediately and the settings dialog will be closed automatically.

The next tab labeled "Editor" contains many self explanatory appearance options. Most notably font settings which are shared between editor and log and also a theme switcher. You can use this to set Studio to use a darker color palette for when you like to work in the dark and don't like to get blinded by bright windows.

studiodark.png
Studio using a dark theme

Enable auto-indentation activates smart line break behavior. When pressing the Enter key a line break is inserted and the indentation of the line of origin is copied instead of moving the cursor to the first column. Highlight current word under cursor without selection changes the highlighting behavior of word occurrences. While the default behavior highlights other occurrences of the same word when double clicking or selecting a word, activating this option changes the behavior so that every time there is a word under the text cursor, it and it's other occurrences will be highlighted. Only full words and no partial matches are highlighted.
GAMS Studio always replaces inserted tabs with spaces. Tab stop size lets the user decide how many tabs will be inserted when pressing the Tab-key.
Clear process log before GAMS execution empties the log before running a gms file. If deactivated old log output is kept but colored in a lighter gray so users are still able to identify that they are looking at an old run instead of the most current one. One can also decide if the log should be written to disk as well and if so, how many old versions of the same log should be kept on disk as backup. Note, that in addition to this log file written by Studio, one can instruct GAMS itself to write a log file using the GAMS parameter logOption, which could cause a file naming clash.

The "MIRO" tab is used to set the location of your local MIRO installation. This page might host more options in the future.

On the "Misc" tab a shortcut button is located that opens the user library folder. This folder can be used to store user generated model libraries, see User Libraries. There is also an option to reset the list of last files used on the Welcome Page.
Then there is also a list of options for the Solver Option Editor.

Delete scratch directories

GAMS creates working folders for running processes in your working directory. Normally these are automatically removed when a run finishes. However, if a run was interrupted sometimes these working directories remain. That in itself is not a problem as GAMS will pick a new name for the next run if the default name for the working directory is already taken. To automatically clean up the user workspace, Studio offers an action to do this. In the menu under GAMS > Delete scratch directories the user has the possibility to remove unwanted, autogenerated directories. Before deleting anything, there will be a popup asking the user for confirmation and also showing the path of the directory that will be cleaned. If the user choses "Yes", all directories that start with 225 followed by one or two letters will be deleted in the given path, which is usually the default workspace. This action is automatically triggered when GAMS has exhausted the pool of possible scratch directory names, but not without asking the user for confirmation first. To avoid any potential errors this action should only be triggered if there are no running GAMS jobs at the moment.

GDX Diff

The GDX Diff dialog serves as a graphical interface to the command line tool GDXDIFF. It compares the data of two GDX files and writes the differences to a third GDX file. The dialog can be opened by choosing Tools > GDX Diff from the menu.

gdxdiff1.png
GDX Diff dialog
The dialog consists of two parts. The upper part is used to specify the two GDX files for the comparison. The resulting GDX difference file is determined automatically as long as no manual changes have been applied. The default schema for the resulting GDX difference file is the location of the first input GDX file and the file name diff.gdx. The difference file will be updated whenever the first input is modified to an existing file. If the GDX Diff dialog gets opened and does not contain a valid first input file, the most recently used directory is used as the location for the resulting difference file instead.

The lower part of the dialog contains different options that can be used in order to control the behavior of the comparison:

  • Eps: Absolute difference for comparisons. If the difference between two values exceeds Eps, a difference will be reported. Default is 0.0.
  • RelEps: Relative difference for comparisons. If the value of RelEps is exceeded, a difference will be reported. Default is 0.0.
  • Field To Compare: The specified subfield is the only field used for deciding if a variable or equation is different. List of possible values:
    • All: All fields
    • L: Level
    • M: Marginal
    • Lo: Lower Bound
    • Up: Upper Bound
    • Prior
    • Scale
  • Ignore Set Text: Allows to ignore explanatory text of set elements.
  • Diff Only: Differences for variables and equations will be written as parameters. Each parameter will have an additional index which is used to store the field name. Only fields that are different will be written. This option can not be used in combination with Field Only.
  • Field Only: Used in combination with Field To Compare. The variables and equations will be written as parameters for the selected subfield. This option can not be used in combination with Diff Only and it requires a value for Field To Compare other than All.

As soon as the OK button is clicked, a validation check on the given input is performed and the two input files are compared. If the specified difference file is already open in a GDX Viewer, the corresponding tab remains open while the underlying GDX file is detached. As soon as the file was updated, the GDX Viewer is reinitialized. In case the GDX file was not open already it gets opened in a new tab. The Cancel button closes the dialog and stops a process that has not been finished yet. The dialog needs to be kept open for longer running comparisons of large input files. The Reset button can be used to reset the whole dialog to its default state which also enables the automatic pre-population of the difference file path in case it has been disabled before due to a manual change.

The GDX Diff dialog also has an integration in the context menu of the Project Explorer. As soon as either exactly one or two GDX files are selected, the context menu contains an entry for opening the GDX Diff dialog with the file(s). If only one file is selected, the input field that is empty is populated with the corresponding file path. If both fields are filled, the first input file path gets overwritten. In case of two selected GDX files, both input fields get overwritten.

Terminal

GAMS Studio is able to open a native terminal via the main menu Tools > Terminal or the shortcut CTRL - T. Alternatively, a terminal can be opened by right clicking on any entry of the "Project Explorer" and selecting Open terminal. The terminal points to the workspace of the current project group. On macOS the terminal location is always the user's home directory.

Command Line Options

GAMS Studio can be started with additional command line options that change the behavior or trigger certain functionality at start up time. The syntax for starting GAMS Studio from the command line is

studio [options] [files]

While files is one or more files to be opened by GAMS Studio, the following options can be supplied:

  • -?, -h, --help : Displays the help.
  • -v, --version : Displays version information.
  • --ignore-settings : Ignore settings files. Studio will load with default settings without writing them.
  • --reset-settings : Reset all settings to default. Studio will load with default settings and save them.
  • --reset-view : Reset studio visually without resetting settings. Useful when a widget got lost or studio started on a disconnected monitor.
  • --gams-dir path_to_gams : Point Studio to a specific GAMS installation.

General Shortcuts

This section lists any shortcuts that are global to Studio. Shortcuts for more specific areas are mentioned in their corresponding section.

Studio Workflow Shortcuts

Shortcut macOS Description
Ctrl - 1 Command - 1 Set focus to the project explorer. After that the arrow keys can be used for file navigation.
Ctrl - 2 Command - 2 Set focus to main editor.
Ctrl - 3 Command - 3 Set focus to the command line option input field.
Ctrl - 4 Command - 4 Opens the tab browser which has a list of all open tabs. Focus is on an input field that can be used to filter tabs. Pressing Return opens the highlighted file.
Ctrl - 5 Command - 5 Set focus to log widget.
Ctrl - Alt - 3 Command - Option - 3 Opens and closes extended command line option editor.
Ctrl - Tab Toggles through the open tabs of the central widget from left to right.
Ctrl - Shift - TAB Toggles through the open tabs of the central widget from right to left.
Alt - Return Command - Control - F Full Screen
Ctrl - Shift - T Command - Shift - T Restore recently closed tab
Ctrl - Shift - W Command - Shift - W Close all tabs
Ctrl - W Command - W Close current tab
Ctrl - Q Command - Q Close GAMS Studio

Studio Dialogs

Shortcut macOS Description
F1 F1 Open the GAMS Help. If the word under the cursor is a GAMS keyword a search in the documentation document will be started
F6 F6 Open GAMS Model Library Explorer
F7 Command - , Open Studio Settings
Ctrl - F Command - F Open search and replace widget
Ctrl - G Command - G Goto specific line number
Ctrl - N Command - N Open new file dialog
Ctrl - O Command - O Open file open dialog
Ctrl - S Command - S Save the current file. If the file does not exist on disk open the save file dialog
Ctrl - Alt - S Command - Option - S Open save as dialog
Ctrl - Shift - S Command - Shift - S Save all open files. Open save file dialog if needed
Ctrl - T Command - T Open a terminal for the current group location. On macOS the terminal points to the users home directory

Studio Recovery

Shortcut macOS Description
Ctrl - F2Command - F2 Reset Studio to default visual settings (window position and -size, widget position and -visibility)
Useful when a widget got lost or studio started on a disconnected monitor.

System Requirements

Compared to most of the GAMS system, GAMS Studio has some additional system requirements, which depend on the platform used. Also, additional information about technical requirements are listed at the GAMS Studio GitHub Wiki.

Linux

The Linux version of GAMS Studio is distributed as AppImage and requires glibc 2.14 as well as FUSE to be installed.

The GAMS Studio AppImage was tested and it was verified that it worked for the following Linux distributions (which are all under maintenance). All Linux distributions are under constant development and updates may change the behavior of the AppImage. Please check the Studio issue page if you encounter any issue.

  • Arch
  • Debian 9
  • Debian 10
  • Fedora 31
  • openSUSE Tumbleweed
  • Ubuntu 16.04 LTS
  • Ubuntu 18.04 LTS
  • Ubuntu 19.10

Other flavors might work as well, but were not tested. If you experience problems with a particular Linux distribution, please let us know.

macOS

macOS has some special platform requirements related to finding GAMS. Below the steps are listed which are used to link GAMS Studio to GAMS.

  • GAMS Studio is going to find GAMS in /Applications/** and /Users/username/Applications/** if it is part of a GAMS folder. It is required that GAMS Studio gets copied via Finder to its target location. This is the case if the GAMS installer is used or if the GAMS Studio DMG is open and GAMS Studio gets copied from there.
  • If GAMS Studio could not find GAMS like described previously then it will search /Applications/** for a valid GAMS installation, i.e. a GAMS installation which has the minimum required GAMS version or higher.
  • GAMS Studio will check the $PATH to find GAMS. In almost all cases this will not work on macOS.
  • In case of special needs the path to GAMS can be set explicitly by starting GAMS Studio with the command line argument --gams-dir.

Windows

There are dependencies on certain Visual C++ libraries. These are present on most Windows systems but are missing on some. If you get a complaint about missing libraries on startup of GAMS Studio, please run the appropriate installer for these libraries, which can be found in the GAMS installation folder:

  • Run vcredist_x64.exe, found in [GAMS system]\apifiles\C++\lib\vs2017

Comparing GAMS Studio and GAMSIDE

As mentioned above, the classic GAMS IDE has been shipped with the GAMS system for many years and is still the workhorse for many GAMS programmers. So it is still around and an alternative to GAMS Studio, especially since it has features, which are not available in GAMS Studio (yet), but it also lacks some features which are available in GAMS Studio. The following table gives a compact overview about most of the differences.

GAMSIDE only GAMS Studio only
Supported Platforms
- Windows - Windows
- Linux
- Mac OS
GDX Viewer
- Creating charts - Filtering (both, symbols and data, labels and values)
- Writing to Html/Excel - Sorting by numerical value
- Heat-map functionality (aka Data Colors) - Option to change display format of numerical values
Editor
- Fixed encoding (ISO 8859-1) - Allow change of encodings and use UTF-8 by default
- Spell checker - Block edit
- Open same file in different buffers - Help integration (pressing F1 on a keyword opens the relevant index page of the documentation)
- Customize syntax coloring - "Smart typing": Automatic insertion of closing character for brackets and quotes
- Recognize URLs and open them in the browser - Tooltips for compilation errors
- Different set of keyboard shortcuts
Execution
- Projects - Groups (see below for details)
- Set default options for the IDE only - Interactive editor for the GAMS User Configuration
- Use different GAMS versions - Interactive editor of GAMS command line parameters
- Use alternative license - Option to jump to first error automatically
- Execute program based on extension - Option to run with GDX creation automatically (F10 vs. F9)
- Solver selection menus - Integration of GAMS MIRO
- Option to not write log to disk
Other
- Text Diff - Welcome page
- Script recording - Project Explorer
- Find in Files (in given folders; independent of open files in the IDE) - Reference File Viewer allows to jump to all references etc. and not just the first one
- Email file - Filtering in Model Library Explorer (all model libraries at the same time)
- Print - Allow to switch between light and dark theme
- Save test files in UNIX format
- Link to McCarl chm
- 32-bit application - 64-bit application

GAMSIDE Projects vs. GAMS Studio Groups

With the GAMSIDE one always started with creating a "Project". This mainly defined a directory used to execute the models added to it (so, it is used to implicitly define the workDir when starting GAMS). When starting the IDE for the first time, one is asked to create a new project. For example, one creates this in directory a. After adding models a/a.gms and b/b.gms both get executed in the project directory a, meaning that data sources are expected in a (or relative to it) and also output files are generated in a, and not necessarily at the location of the gms file.

When starting GAMS Studio for the first time, it starts with an empty Project Explorer. Opening a new file creates a new "Group" per default. Groups do not know about a specific folder (meaning, in contrast to the GAMSIDE, Studio does not set the workDir implicitly). If a model gets executed, it gets executed at its location. So, if ones opens a/a.gms and b/b.gms, by default, Studio will create two groups: a and b. When a is started input files are expected in directory a and output files get generated in a. When b is started input files are expected in directory b and output files get generated in b. If one has structured the models so that they rely on the "GAMSIDE way" to execute a model, one can just set workDir explicitly when starting the model.

It is also possible to have multiple files in one group. For example, one could add b.gms to group a by drag'n'drop in the Project Explorer. Now, the concept of the "main file" of a groups becomes important: While the GAMSIDE always executed the currently active .gms file, GAMS Studio always executes the main file of the currently active group. So, in our example, you can look at a.lst and press F9 to rerun a.gms (the GAMSIDE would not run anything in this case). After adding b.gms to group a, one would also execute a.gms by pressing F9 while looking at b.gms. If you want to execute b.gms instead, you can make it the main file of the group. For this, right-click in the Project Explorer at b.gms and select "Set as main file". Note that the green arrow indicating the main file of a group in the Project Explorer switches from a.gms to b.gms. As a reminder: Groups do not know a particular working directory. Pressing F9 after switching the main file will execute b.gms in folder b.

set_as_main.png
Switching the main file