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

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

Keys Function
Ctrl - C Copy selected text
Ctrl - X Cut selected text
Ctrl - V Paste text from clipboard
Ctrl - A Select whole document
Ctrl - * (Un)Comment all lines in selection
Ctrl - Z Undo
Ctrl - Y or
Ctrl - Shift - Z
Redo
Ctrl - Shift - L Duplicate the current line
Shift - Del Remove current line

2. Advanced Text Manipulation

Keys Function
Ctrl - Shift - L Duplicate current line
Alt - Shift - L Toggle selection to lower case
Alt - Shift - U Toggle selection to upper case
Tab or
Ctrl - I
Indent Line
Shift - Tab or
Ctrl - Shift - I
Outdent Line

3. Navigation & Selection

Keys Function
Ctrl - + or Ctrl - = or Ctrl - Mousewheel Up Zoom in
Ctrl - - or Ctrl - Mousewheel Up Zoom out
Ctrl - 0 Reset zoom
F8 Jump to matching parenthesis
Shift - F8 Select to matching parenthesis
Ctrl - M Toggle bookmark
Ctrl - , Go to previous bookmark
Ctrl - . Go to next bookmark
Alt - Left Mouse Button Draw block edit selection
Alt - Shift - Left Mouse Button Span block edit selection from text cursor to mouse click
Alt - Shift - Arrow Key Span block edit selection

4. GAMS Shortcuts

Keys Function
F9 Run main file of current group with GAMS
F10 Run main file of current group with GAMS and create a gdx file
Shift - F9 Compile main file of current group with GAMS without execution
Shift - F10 Compile main file of current group with GAMS and create a gdx file without execution
F12 (Gracefully) Interrupt currently running GAMS job
Shift - F12 Stop currently running GAMS job

5. GAMS Studio Dialogs

Keys Function
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 Open GAMS Model Library Explorer
F7 Open Studio Settings
Ctrl - G Goto specific line number
Ctrl - F Open search and replace widget

6. Studio Recovery

Keys Function
Ctrl - F2Reset 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.

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

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

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. A selection of encodings is preselected. This selection can be changed using the Select encoding submenu. To reload a file using another codec the reload with ... submenu can be used. Finally with the convert to ... submenu the current file can be converted to another codec.

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

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 layout 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 consist 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 Symbol Search facility provides dynamic filtering of the list of symbols contained in the GDX file using wildcard syntax. By default, only the Name column is used. By selecting the All Columns check box the search considers all other columns as well. This can be useful if the exact symbol name is not known. 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. Depending on the symbol type, the value columns can vary as the following listing shows:

  • Set/Alias: One value for explanatory text. Y if no explanatory text is available.
  • Parameter: One numerical value.
  • Variable/Equation: Five numerical values: Level, Marginal, Lower bound, Upper bound, 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 width of the involved columns. Key columns offer a mechanism for applying a filter on the displayed labels. The filter for a key column 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 and resets the applied sorting.

The button Preferences opens a menu containing different settings for the currently viewed 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 precision of numerical data can be changed by using the Show Decimals spin box. While the default value for the number of decimals is 6, the value can be changed for each symbol individually. The spin box allows to set the precision to a value in the range from 0 to 6. The additional value -1(Max) is used to set the precision to the maximum value, which is 15. The GDX Viewer automatically switches between scientific notation and floating point notation, whatever is more convenient for a specific numerical value.

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

The filter dialog for a specific 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

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 Value Columns menu in the lower 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 an 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.

Context Menu

Right clicking on a symbols data opens the GDX Viewer context menu which allows to do the following actions:

  • Copy (comma-separated) (Ctrl+C): Copy the current selection to clipboard using comma as separator
  • Copy (tab-separated) (Ctrl+Shift+C): Copy the current selection to clipboard using tab as separator. Useful for pasting into spreadsheets
  • Auto Resize Columns (Ctrl+R): Automatically adjust the width of the first visible 100 columns to their content. The first visible 500 rows are taken into account in order to calculate the width.
  • Copy (Select All) (Ctrl+A): Select all data

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 Search 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.
  • Search : An input in the Symbol Search box will search the symbol in the reference table by name. A search in all columns can be enabled by checking All Columns next to the Symbol Search box.

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 filetered 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 entried 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 brower (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 defintion 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 defintion 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 defintion 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+T 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 defintion 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

Summary of Actions and Shortcuts

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

Action Description Shortcut
toggle option/comment selection toggle between option and comment Ctrl + T
insert new option insert a new option row Ctrl + Return
insert new comment insert a new comment row Ctrl + Shift + Return
delete selection delete the selected option/comment Ctrl + Delete
move up move the selected option/comment up for 1 row Ctrl + Up
move down move the selected option/comment down for 1 row Ctrl + Down
select all select all options Ctrl + A
show option definition show definition of this selected option in the right pane Ctrl + F1
show all options of the same definition show all options of the same defintiion defined in the right pane Shift + F1
resize columns to contents resize the columns in the left pane to contents Ctrl + R

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

Action Description Shortcut
add this option add option in the left pane from the selected definition Return
remove this option remove option defined by this definition from the left pane Delete
copy option name copy option key from this selected definition Ctrl + C
copy option description copy option description from this selected definition Shift + C
copy definition text copy option text from this selected definition Ctrl + Shift + C
resize columns to contents resize the columns in the right pane to contents Ctrl + R

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 intepreted 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 perfomed 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 acions 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 configruations 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 immedate 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.

Tab Browser

The Tab Browser is accessible with a button next to the main tab bar or via the shortcut Ctrl+K. 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. The runnable GAMS files (currently supported .gms and .inc) are listed with GAMS icon and the GDX files (.gdx) are given own icon to be identified faster. 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".

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

A group entry is created automatically when opening a file and a groups name is determined by the name of the opening file. When the group is created, Studio automatically adds certain files (.gdx and .lst with the same name as group name) into the group. By default the first runnable GAMS file in a group is considered the main file, marked with a green arrow over its GAMS icon. The tooltip of a group also tells which the current main file is. One group may contain multiple runnable GAMS files but only one runnable GAMS file is set as the main file. 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 open the file in the output view. A clickable log line in the process log may add the corresponding file into the group and open the file in 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 group 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.

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 diaglog, 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 - L. 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 infront of the parameter in the extended editor turns half-yellow in combination of another color, red or green, depending of wheteher 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 defintion 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 entiries if there is more than one entry, or
    • add new entry of the same definition, or
    • show details of all entries of the same parmeter, 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.

Integrated Help

The Help View is designed to integrate the navigation of the GAMS documentation into GAMS Studio. Press F1 or choose Help > Documentation menu or check View > Help menu 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 menu 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 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 from https://www.gams.com/30/docs : Browse the same documentation on GAMS website. This, for example, allows to use more sophisticated search functionalities across all GAMS documentation of version 30.1 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

It is also possible to jump directly from Code Editor 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 'Save' in extended parameter editor

Dialogs

About GAMS

The About GAMS dialog is part of the GAMS Studio Help menu. It provides information about the used GAMS as well as avialable 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.
  4. Check the system log for any errors, e.g. if the user has no write permissions on the GAMS folder to create the license file it will be listed in the system log.

Search and Replace

Pressing the Ctrl - F opens the Search and Replace window. 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 at once but not before 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 occurences 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 the Studio editor (except gdx files).
  • "All Files" searches all files that appear in the Project Explorer.

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, press the Tab-key to move the focus to the next interface item which is "Find All". Press the Space-key to press the button and do a full search in the currently set scope. Pressing Enter here would still act as "Find Next" but this might depend on your operating system.
  • 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 or by hitting F6. Every library is presented in a separate tab.

The search facility in the upper part of the Model Library Explorer allows for dynamically searching all model libraries simultaneously using a wildcard syntax. As the search string is entered the results are applied directly to the tabs representing the different libraries. The parenthesis enclosed numbers indicate the number of models found for this 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 three 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 for the user to go through all files and make sure that changes were saved manually. 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.

The next tab labeled "Editor" contains many self explanatory appearance options. Most notably font settings which are shared between editor and log. Enable auto-indentation activates smart line break behavior. When pressing the Return-key a line break is inserted and the indentation of the line of origin is copied instead of moving the line to 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 everytime 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.

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 set the maximum list size of last files used on the welcome page.

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.

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

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.

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

  • Arch (current version)
  • Debian 9
  • Fedora 29
  • openSUSE Leap 15 (Gnome + Wayland)
  • openSUSE Leap 15 (KDE)
  • openSUSE Tumbleweed
  • Ubuntu 16.04 LTS
  • Ubuntu 18.04 LTS

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

The Windows version of GAMS Studio supports Windows 7 and above.

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 (32 bit only) - Windows (64 bit only)
- Linux
- Mac OS
GDX Viewer
- Creating charts - Filtering
- Writing to Html/Excel - Sorting by numerical value
- Heat-map functionality (aka Data Colors)
Editor
- 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 - Tool Tips for compilation errors
- Different set of keyboard shortcuts
Execution
- Use different GAMS versions - Interactive editor of GAMS command line parameters
- Use alternative license - Option to jump to first error automatically
- Set default options - Option to not write log to disk
- Execute program based on extension - Option to run with GDX creation automatically (F10 vs F9)
- Solver selection menus - Integration of GAMS MIRO
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
- Save test files in UNIX format
- Link to McCarl chm
- Minor options to customize (e.g. eolcom, margins, date format, ...)