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

Action Shortcut macOS Description
Remove Line Shift - Del Removes the current line
Duplicate Line Ctrl - D Command - D Duplicates the current line(s)
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 Previous Shift - F3 Shift - F3 Jump to previous search result

Action Shortcut macOS Description
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
Toggle Folding Alt - L Alt - L Toggles the folding state of the current section
Fold all Sections Alt - O Alt - O Folds all foldable sections
Fold DCO Sections Alt - I Alt - I Folds all foldable DCO sections
Unfold all Sections Alt - Shift - O Alt - Shift - O Unfolds all foldable sections
Open Code Completer Ctrl - Space Ctrl - Space Opens the Code Completer
F2
Command - Left Mouse Button or
F2
Jumps to file referenced by $include 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 - Arrow Key Option - Shift - Arrow Key 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 by Page Alt - PageUp / PageDown Option - Fn - PageUp / PageDown Change block edit selection by a page step Change Block Edit by Word Ctrl - Shift - Left / Right Command - Shift - Left / Right Change block edit selection by word bounds Change Block Edit by Word Ctrl - Left / Right Command - Left / Right Change block edit position by word bounds (skip selection) Change Block Edit Anchor Shift - Arrow Key Shift - Arrow Key Change block edits anchor (start position) Move Block Edit Arrow Key Arrow Key Move block edit selection Move Lines Up or Down Ctrl - Shift - Up / Down Command - Shift - Up / Down Move line(s) up or down 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. To support navigating to files included by the gams source, place the mouse cursor over the file name and press the Ctrl - Left Mousebutton or place the cursor at the filename an hit F2. If found, Studio will add the file to the current project and open it. Only plain text filenames can be detected this way, symbols are not resolved. ### Code Folding The Code Editor detects several kinds of sections in the source code that can be folded. These sections include all kinds of matching parentheses that extend over more than one line plus several$-control options that needs to come in pairs. To toggle the folding state of a section either the fold-marker can be clicked or the shortcut Alt - L can be pressed when the cursor is in a foldable line. To fold or unfold all foldable sections the main menu contains entries in the View menu. Additionally the shortcuts Alt - O to fold and Alt - Shift - O to unfold can be used.
To define individual blocks of folding the Dollar Control Options $onFold and $offFold can be added to the source.

List of $-control options that create a fold section: • $OnText / $OffText • $OnEmbeddedCode[V/S] / $OffEmbeddedCode • $OnEcho[V/S] / $OffEcho • $OnPut[V/S] / $OffPut • $OnExternalInput / $OffExternalInput • $OnExternalOutput / $OffExternalOutput • $ifThen[I/E] / $endIf • $onFold / $offFold ### 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
• ...

### Code Completion

GAMS Studio offers a static code completion for fixed internal keywords known by the compiler. The code completer pops up after pressing Ctrl - Space and shows keywords that matches the current syntax and starts with the already typed characters of the word to the left of the cursor. Moving the cursor to the left shortens the matching pattern while moving the cursor to the right extends it. The keys up/down, pageUp/pageDown, and home/end are processed by the results list during the completer is visible. The selected word can be inserted with the keys tab or enter/return or by double clicking a word in the list. To hide the completer, hit esc or click outside of the completer window. Additionally the completer hides if there is no match for the current start of word.

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

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.

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
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. By default, only the Name column is taken into account by the filter. 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.

The GDX Viewer automatically saves and restores its state as soon as data is reloaded due to changes to the underlying GDX file. Changes to the symbol table like an applied filter or the currently selected symbol are kept. Individual symbols keep applied filters as well as the view settings (e.g. the currently selected view (List View or Table View), preferences and the visible attributes for variables and equations) as long as the name, type, and dimension of the symbol did not change during the update of the GDX file. Resetting the state of a symbol can be achieved by clicking on the Reset button. In order to get rid of the whole GDX Viewer state, it has to be closed and reopened.

### 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).
Right side of GDX Viewer showing the parameter d from the trnsport model

The header displays the individual domains as well as the original index position using superscript notation which is especially useful if the column order has been changed. Furthermore it 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.
Variable mix from the prodmix model using g-format with precision=6
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.
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.
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.

### Table View

Switching to the Table View is possible for symbols that have at least two dimensions. This mode consists of two parts: A separate header view that shows the domains and attributes of the symbol as well as the actual data. The header view also allows to access the filter facility and highlights the positions of specific domains by using visual separators (from left to right: rows, columns, attributes). The data itself 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:

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.
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 and vice versa, 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.

### Filter Facility

Filters can be applied in both the List View and the Table View through the header view that contains the domains as well as the (numerical) attributes. In the List View, the header is part of the data view itself, while the Table View offers a separate header view above the actual data. The filter dialog can be opened either by right clicking on the 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 filter in the upper part of the filter dialog. More about the filter can be found in the Filter Section. 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 filter as only the matching labels will remain in the list while typing. The Select All, Invert, and Deselect All buttons speed up getting the desired selection.

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.
Filter dialog on numerical column Value for parameter c in trnsport.gdx

### 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)
Copy Without Labels (comma-separated) context menu only context menu only Copy selection without labels to clipboard using comma as separator (Table View only)
Copy Without Labels (tab-separated) context menu only context menu only Copy selection without labels to clipboard using tab as separator (Table View 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.

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:

Process Log showing clickable entry for the reference file

The Reference Viewer is categorized by a number of tabs:

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 filter the symbols in the reference table by Name. More about the filter can be found in the Filter Section.

### Summary of Actions and Shortcuts

Action Shortcut macOS Description
Symbol Filter Ctrl - F Command - F Jump to the Symbol Filter 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 filter-term 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.

• 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 is a group of options and a filter box. Option groups filter the list of option definitions by group name. By default all option definitions are displayed. Filter box with placeholder text Filter Options ... allows to filter the option definitions. As a filter term has been typed into the filter box the results are displayed in the list of option definitions below. More about the filter can be found in the Filter Section.
• 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 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 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 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 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 entry but not yet opened, choosing Open File from the project context menu opens the file in the solver option editor; however, choosing Open File As Text from the project 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 Filter 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.
• 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:

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.
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.
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 Filter Ctrl - F Command - F Jump to the focus to the Option Filter 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.

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.

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.

## Pin View

Studio provides a Pin View to carry a clone of a selected tab. This allows to have two file contents visible at the same time. To pin a tab there are two entries in the tabbar: "Pin right" (shortcut Ctrl - Click) splits the edit area horizontally and opens the Pin View right to the main tabs. "Pin below" (shortcut Ctrl - Shift - Click) splits the edit area vertically and opens the Pin View below the main tabs. The state and size of the Pin View is restored on restarting Studio.

Pin View

The Pin View provides additional buttons. The first button switches the split orientation from right to below and vice versa. The second button allows to activate synchronized scrolling for the two visible editors. Synchronizing is always passed from the active editor containing the focus to the passive editor, which means that scrolling in the passive editor with the mouse wheel isn't passed back to the active editor allowing adjustments without switching the function off and on. The last button closes the Pin View.

The Navigation History records a navigation history event each time the cursor is moved in some kind of text file opened in the Studio central widget. This allows the user to quickly jump back (and forward again) to text passages that were recently edited. To reduce clutter some events are set to overwrite the previous event. This happens when the cursor is moved by only a single position in either direction, so that when a user jumps through text or types something only the latest position will be put into the history. The idea behind this is to make it easier and more convenient to jump to positions that actually matter. Using the navigation history is not limited to a single file. It is easy to jump between two or more files to go back and review recent changes. If a file was closed in the meantime it will be reopened when navigating through the history. This includes even files that were completely removed from Studio. When such a file is reopened through the Navigation History feature, due to technical limitations, the affiliation of the file to its previous project is lost. Please note that after navigating back in the history all "future" history events will be deleted and overwritten if the user creates new history events.

Action Shortcut macOS Alternative Shortcut
Go Back Alt - Left Arrow Ctrl - [ Mouse Button 4
Go Forward Alt - Right Arrow Ctrl - ] Mouse Button 5

# Further Studio Widgets

## Project Explorer

The Project Explorer organizes the files opened in Studio into projects. Each project has its own base directory. All files associated to the project are organized in a hierarchical tree structure of folders relative to this base directory. A projects tooltip tells the location of the project 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 project 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 or folder entry tells the location in the file system. The file location, the project location, and the folder 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, project, or folder. The context menu of a .gdx file provides a special entry "Open in GDX Diff" that opens the specific GDX Diff Dialog.

Project Explorer and its context menu

An empty project can be created by selecting New Project from the File menu or the context menu in the Project Explorer. A file dialog opens to select the project folder. The project gets the name of that folder. If a project with that name already exists, Studio looks for a number to append until the projects name is unique. Additionally a project is created automatically when opening a file. The projects name and location is determined by the name and location of the opened file. One project may contain multiple runnable GAMS files but only one runnable GAMS file is set as the main file, marked with a green arrow overlay. By default the first runnable GAMS file in a project is considered the main file. The tooltip of a project 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 project via the context menu "Set as main file". The project base directory remains unchanged if the runnable GAMS file is changed.

The main file of the active project 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). To better recognize the active project, the current file and its project are in bold text and the icons of other projects are slightly dimmed. After executing the main file, the generated listing file (.lst) is added to its project and the output view (see Process Log) is opened. A clickable log line in the process log may add the corresponding file into the project and open the file in the Central Widgets area. Users can manually add more files to a project by right-clicking and choosing either "Add existing file" or "Add new file" from the context menu. Additionally Drag and Drop from the systems file explorer is supported.

Files can also be removed from a project and projects can be removed from Project Explorer via the two actions "Close file" and "Close project" from the context menu. The action "Close project" closes the project and all files in the project if opened as well as removes all file entries and the project entry from the Project Explorer without actually touching the files on the file system. The action "Close files in this folder" closes all files in this folder and it's subfolders. The action "Close file" closes the file if opened and removes the file entry from the project. In case the closed file is the only entry in a folder, the folder is also closed accordingly. In contrast a project can be empty during the current session but an empty project isn't restored on Studio restart. In case there are unsaved changes a message popup will appear, asking the user how to proceed.

Next to each project there is a cog wheel button that opens the Project options page. It contains these actions:

• Name: defines the name of the project
• Working directory: defines the default directory where the main GAMS file associated to the project will be executed
• Base directory: defines the directory from where the folders to each file of the project are generated. Changing this will update the folder structure to all files of this project.
• Main GMS file: informs about the current main GMS file.

The changed Project Options can be applied by selecting File > Save of pressing Ctrl - S.

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

A project can be 'exported' using the context menu to a 'GAMS Studio Project' with the suffix gsp. The files assigned to the project are referenced relatively to the projects base directory. Therefore it is highly recommended to export the project to the base directory itself to keep its consistency. The relative paths allows to share the project along with its other files. When a project file is 'imported' into GAMS Studio, the base directory is set to the location of the project file. Starting from this directory Studio expects the other files of this project.

Selected files can be dragged to another project. By dropping them they are moved to the destination project. If a folder is empty after this action its representation is removed from the project. Pressing the Ctrl key creates a copy of the file-reference in that project (no file copy). If the project 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 projects 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.

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

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 project of the file that is currently opened in Central Widgets (see also Project Explorer for project 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:

• 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.
• Run NEOS: Choose Run NEOS to compile GAMS statements in the main runnable file locally and pass the execution to the NEOS server.
• Run GAMS Engine: Choose Run GAMS Engine to compile GAMS statements in the main runnable file locally and pass the execution to the GAMS Engine server.

The pre-customized execution command will operate on the main file (marked with a little green arrow over the regular icon) of the active project (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 project history. All files in a project share one parameter history. The previous GAMS parameters can be recalled from the project history via the drop-down menu of the combobox. Switching the file opened in Central Widgets will activate the different project history only when the project of the newly opened file is different from the project of the file before the 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) :

• 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 project and disabled when there is no currently running job in the project.
• 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 project and disabled when there is no currently running job in the project.

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.

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 filter box (with placeholder text Filter Parameter...) to allow to filter all parameter definitions. As a filter term has been typed into the search box the results will be displayed in the list below. More about the filter can be found in the Filter Section.

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.

Parameter key turns red with pop-up tooltip when there is a potential error
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.

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:

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.
GAMS Parameter editor shows a drop-down list of all possible parameters started with 'o'
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.

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.
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
• 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 project with GAMS
Run with GDX Creation F10 F10 Run main file of current project with GAMS and create a GDX file
Compile Shift - F9 Shift - F9 Compile main file of current project with GAMS without execution
Compile with GDX Creation Shift - F10 Shift - F10 Compile main file of current project 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 Shift - Ctrl - 3 Control - 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 Filter Ctrl - F Command - F Jump to the focus to the Parameter Filter 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 > GAMS 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. Alternatively, choose Help > Studio Documentation to directly jump the to start of the GAMS Studio documenation. 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.

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.

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

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 :

• Press F1 on a parameter entry within the extended parameter editor to activate the help page displaying the detailed description of the GAMS parameters in The GAMS Call and Command Line Parameters.
Help View when press F1 on parameter entry 'output' in extended parameter editor
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 project with MIRO in Base Mode
Run configuration mode Shift - F7 Shift - F7 Run MIRO configuration mode

# NEOS

GAMS Studio can remotely execute models on the NEOS server. The model is compiled locally before the compilation object is send to NEOS. Note that a GDX file can be created but always has the name out.gdx. On running a dialog pops up to enable further setup:

• "Email" - The email to submit a job. It can be predefined by setting NEOS_EMAIL in the GAMS User Configuration or by defining the environment variable NEOS_EMAIL.
• "Create a GDX file" - Create a GDX file even if the Command line parameter is not set.
• "Short priority" - The execution may start earlier and provides intermediate log output, but it is limited to an execution time of five minutes.
• "Long priority" - The execution may start later and provides no intermediate log output, but it is not limited in execution time.

The selections of the dialog are stored to the settings. To reveal the Terms of Use after checked Don't show Terms of Use again there is a checkbox in Settings > Misc.

The results of the remotely executed model are placed into a sub-folder named by the base name of the model. The log output of the remote execution has a different background color which can be configured in the settings dialog (Default Text, 3rd color). Links in the remote execution log output are replaced by their local counterpart.

# GAMS Engine

GAMS Studio can remotely execute models on your own GAMS Engine server. The model is compiled locally before the compilation object is sent to GAMS Engine. Additional files can be sent to the server by creating a file with the name of the model and the extension ".efi" (for "External FIles"). Each line in this file addresses an additional file. Files defined in the EFI file that should be actualized locally by changes from the GAMS Engine server can be marked by adding a < separated by a space.

Example: if an EFI file named trnsport.efi contains these lines:
inc/trnsport.inc
inc/data.txt <
and the model trnsport.gms is executed, both files will be transferred to GAMS Engine. After solving, the file inc/trnsport.inc will stay untouched but inc/data.txt will be replaced by the version returned from the server.

GAMS Studio provides an EFI editor to select the files. The context menu of a project in the Project Explorer allows to create or open the EFI file matching the current runnable GAMS model. With this editor files can be selected and selected files can be marked to be actualized locally. You can switch an open EFI editor to a text editor by selecting Reopen as text after changes have been saved.

On running a dialog pops up asking the user to log in. If already logged in before and the login is still valid this first page is skipped.

• "Url" - The URL to your GAMS Engine server

While changing the URL, Studio tries directly to access the server and requests version information. On success it gets the GAMS Engine version placed to the right and the version of the GAMS installation on the server to the left. If the local GAMS version is newer the command line parameter "previousWork=1" will be added automatically if no "previousWork" is already present. The entries of the dialog (excluding the password) are stored to the settings. Further configuration can be done in the settings dialog.

Being logged in, the submit page allows to setup the remote job:

• Submit page
• "Namespace" - The namespace to be used on the server
• "Instance" - Allows to specify the user instance for GAMS Engine SaaS
• "Create a GDX file" - Creates a GDX file even if the command line parameter is not set

To get back to the login page click the "Logout" Button. The job is submitted to the GAMS Engine server on clicking "OK". To always run the same setup, the "OK, don't ask" can be selected. For this Studio session the job is always submitted directly without showing this dialog. To see the dialog again, use Ctrl-Click on the Engine icon, or click on "Settings > Remote > Reactivate Dialog".

The selection of an user instance and the information of available space and time quota is only visible on connecting to a GAMS Engine SaaS server.

The results of the remotely executed model are placed into the working directory:

• The LST and LXI files from the server are renamed to "<model>-server.lst" and "<model>-server.lxi" to protect the local files.
• All generated file will replace an existing file of the same name (like GDX, REF, and LOG files).
• All file entries from the EFI file that end with " <" will replace the local existing file.

The log output of the remote execution has a different background color which can be configured in the settings dialog (Default Text, 3rd color). Links in the remote execution log output are replaced by their local counterpart.

# Dialogs and Actions

## GAMS Licensing

The GAMS Licensing 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 Help > GAMS Licensing
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 GAMS Licensing dialog; otherwise the old license is shown.

Studio will also detect a license on the clipboard when it starts. If a license is detected the same message box will show up like if the GAMS Licensing dialog is used.

## 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. Depending on which file type is openend 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.

Search window in its default configuration

In the first row of the dialog there is the Search field, which takes the search term and saves a list of recent searches. Next to it is the "Clear" button that removes all highlights, results and clears both text fields. A shortcut to clear all results is to press the Esc key in the Code Editor. 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. The next button is "Replace": 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 in the same file, selecting it. Users can use this to click through a file, replacing words while keeping an overview over what is actually changed. Replacement actions can be undone by pressing either the undo button or hotkey Ctrl - Z.

"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. Then come the options to narrow down a search. "Whole Words" excludes partial hits from matches. For example, when searching for "in" with this 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 what it is used for. "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.

In the next row is the scope selector. The scope of the search or replace action can be set here with five options available:

• "Selection" searches the text selected in the current file. The search dialog will give feedback if no selection is present. To remove the search selection press either Esc or the "Clear Selection" button. Keep in mind that starting a new search moves the search selection to the currently selected text.
• "This File" limits the search to the currently active file and is the default.
• "This Project" searches all files that belong to the same project as the currently opened file. These are all children of the same project 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.
• "Folder" searches all files in a specified folder that can be located anywhere on disk and does not need to be opened in Studio beforehand. When opening a result the file will be added to the Project Explorer.

Next to it are the find previous occurrence and find next occurrence buttons, labeled "<" and ">" respectively. These will find and highlight the next word matching the search criteria either before or after the current text cursor position. Next to it there is the "Find All" button which starts a search in the scope selected by the user. 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 and the up and down arrow keys can be used to select quickly select and jump to results. Information about the file, the location of the match, plus some context information are also shown.

Depending on which scope is selected, additional elements of the search dialog will be shown:

Search window fully expanded

The first section is the file filter section which is available for all modes except "Selection" and "This File". It gives the user the possibility to limit the search to certain files (Include Filter) but exclude others (Exclude Filter). Filenames can be specified by using a wildcard syntax. See the tooltips for some simple examples. The drop-down menus come with a few default options for GAMS specific file types but can also be used to enter own patterns. Comma-seperated lists of patterns are also supported. The second section is only available when "Folder" scope is selected and lets users set the path to search. It is a drop-down style textfield, so like the others it keeps a history of recent entries. Next to it is a browse button that opens the operating systems default folder picking dialog to easily find a path. 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 project 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. As the search string is entered, the results are applied to the tabs representing the different libraries. If there are no more results on the selected model library tab, the first non-empty tab is automatically selected. This is undone as soon as the originally selected model library contains results again. The parenthesis enclosed numbers indicate the number of models found for the specific library and the current search input. More about the filter can be found in the Filter Section.

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 or changed by opening the Settings dialog (File > Settings) and switching to the Misc. tab. The Arrow button will show the location where the Model Library Explorer tries to find user defined model libraries, the Folder button allows to change the location. 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 five tab pages.

### General page

On the "General" tab users control general settings of Studio. Some additional hints:

• "Default GAMS Studio workspace". This path is used as a default location for models imported from the Model Library Explorer.
• "Automatically save modified files before running GAMS" is an option that saves all modified files 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. Studio then 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.
• "Open file in current project by default" switches the menu File > Open (Ctrl-O) to always open a file in the current project, even if it exists in another project. The alternative open (Ctrl-Shift-O) is changed to File > Open in new project....
• "Open file finds or creates new project" switches the menu File > Open (Ctrl-O) to find the file in any project and open it. If not found, a new project is created. The alternative open (Ctrl-Shift-O) is changed to File > Open in current project....
• At the bottom of this 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.

### Editor & Log page

The "Editor & Log" tab contains many self explanatory appearance options. Most notably font settings which is used for all monospace fonts like text editors and logs. The font size is used also to calculate the size of proportional fonts (see Zoom Groups)

• "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 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, all of its occurrences will be highlighted. Only full words and no partial matches are highlighted.
• "Tab stop size" lets the user decide how many tabs will be inserted when pressing the Tab-key. GAMS Studio always replaces inserted tabs with spaces.
• "Fold DCO blocks on open" folds all foldable blocks of the types "Text", "Echo", "Put", and "Fold"
• "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.

### GDX Viewer

• "Default Symbol View" controls if the list view or the table view is used as the default view when a symbol is displayed for the first time.

### Colors page

The "Colors" tab enables you to configure several colors. Studio provides two fixed themes: the "dark" theme and the "light" theme. Depending on the your operating system, this can be selected by the system and/or manually. 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.

Studio using a dark theme

The fixed themes can't be modified, modifying a value implicitly creates a copy of the theme where the changed value is applied. After copying a theme, the new user theme can be adapted to your needs. Additionally these user themes can be exported and imported to a file each.

Color Settings

The colors are listed in two sections:

• On the "Syntax colors" page you can define a text color and the attributes bold and italic.
• The "Editor colors" page allows to change the colors of text, background, and second background (for blinking). The very first entry on this page, the "Default Text", is the base of the syntax colors.

### Remote page

The "Remote" tab is used to set various remote settings.

• In the MIRO section the location of your local MIRO installation can be defined.
• The checkbox "Always agree to NEOS" allows to hide the "Terms Of Use" in the submission dialog of NEOS.
• In the GAMS Engine section it can be defined if a login token should be stored to the settings to stay logged in on restarting Studio. The next line allows to define how long the login is valid.
• If the dialog has been switched invisible by clicking "OK, don't ask", the button "Reactivate dialog" switches it on again.

### Misc page

The "Misc" tab contains some lesser common settings.

• "GAMS source file extensions" allows to add own file extensions that Studio counts as runnable GAMS. File types added here can be executed, set as main file, and are assigned to the GAMS Syntax Highlighter. The field accepts a comma separated list of file extensions.
• "Auto-reload extensions" Specific extensions that should be reloaded automatically can be added here. Files of that type are reloaded into the editor if changed externally. If they also were changed internally, a dialog asks how to proceed. The field expects a comma separated list of file extensions.
• "User model library" shows the folder that is used to find user generated model libraries, see User Libraries. This folder can be changed to a custom location. Up to 10 locations are stored in the history. To remove the current entry from the history use the trash-bin button. The arrow-button opens the file browser in the current folder.
• "Reset History" clears the list of last files used on the Welcome Page
• "Reset Window" resets the appearance of Studio if something went wrong.
• The next group contains 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.

## Full Screen & Distraction Free Mode

Especially small devices suffer from sparse screen real estate. Studio comes with a few features to make the most of the space that is available on your machine.
The Full Screen mode is activated by pressing Alt-Enter on Windows and Linux systems, while on macOS the shortcut is Command-Control-F. This enlarges Studio over the whole screen, covering the taskbar and other operating system specific items. The same shortcuts also exit Full Screen mode.
As an alternative, there is also the Distraction Free mode. Some users want to keep their taskbar so with the shortcuts Ctrl-Alt-Enter on Windows and Linux or Cmd-Option-Enter on macOS hide all Studio widgets and enlarge the central widget to the size of the studio window. You can use this to get the log-, file- and help view out of the way and concentrate writing. Pressing the shortcut again brings everything back. Running your GAMS modell in the Distraction Free mode will also open the log, so you are not missing out on anything.

Action Shortcut macOS
Enter/Exit Full Screen Alt - Enter Command - Control - F
Enter/Exit Distraction Free Mode Ctrl - Alt - Enter Command - Option - Enter

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

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. 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.
Shift - Ctrl - 3 Control - 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. Alternatively, a tab can be closed by clicking the middle mouse button.
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 - Shift - O Command - Shift - O Open file dialog to open the file(s) in the current (a new) project
Ctrl - P Command - P Open print 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 project location. On macOS the terminal points to the users home directory

## Studio Recovery

Shortcut macOS Description
Ctrl - F2 Command - 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.

## Zoom Editor and View

All editors and views can be zoomed in and out. To avoid repeating action a zoom is applied to all editors and views of the same group. Beneath the Integrated Help and the Welcome Page these groups are defined:

Action Shortcut macOS Description
Zoom In Ctrl - + or
Ctrl - = or
Ctrl - Wheel Up
Command - + or
Command - = or
Command - Wheel Up
Zoom in all editors and views of the same group
Zoom Out Ctrl - - or
Ctrl - Wheel Down
Command - - or
Command - Wheel Down
Zoom out all editors and views of the same group
Reset Zoom Ctrl - 0 Command - 0 Reset zoom of all editors and views

# Usage Hints

## Filter in Tables and Trees

To find relevant entries in tables and tree views Studio provides a special line edit containing up to four buttons aligned to the right:

• Clear - clears the term in the line edit.
• Exact Match - when active, the filter accepts only rows with one cell matching exactly the term regarding wildcard or regular expression setting
• Regular Expression - when inactive, the wildcards '*' (any amount of characters) and '?' (one character) can be used. Otherwise the filter provides full regular expression syntax. Click here for further information about regular expressions.
• All Columns - when inactive, the filter checks only the key column. When active, all cells of the table/tree-view are taken into account
Filter LineEdit inactive and active

# 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.27 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
• CentOS Stream 8
• Debian 10
• Debian 11
• Fedora 36
• openSUSE Leap 15.3
• openSUSE Tumbleweed
• Ubuntu 18.04 LTS
• Ubuntu 20.04 LTS
• Ubuntu 22.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.

In some cases the Studio AppImage might not run. If this is the case extract the AppImage by running

$./studio.AppImage --appimage-extract  via the command line and start Studio from the extracted directory. ## 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 called vcredist_x64.exe, which can be found in the GAMS installation folder at [GAMS system]\studio.

# 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
- Recognize URLs and open them in the browser - Help integration (pressing F1 on a keyword opens the relevant index page of the documentation)
- Different set of keyboard shortcuts - Tooltips for compilation errors
- Code Completion
- "Smart typing": Automatic insertion of closing character for brackets and quotes
- Distraction Free Mode
- Code Folding
- Open \$[bat/lib]include files directly from editor
Execution
- IDE Projects - Studio Projects (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
- Execute program based on extension - Option to run with GDX creation automatically (F10 vs. F9)
- Solver selection menus - Integration of GAMS MIRO
- Remote execution on NEOS Server for Optimization
- Remote execution with GAMS Engine
- Support of standard locations, e.g., to detect the license file at a standard path
- Option to not write log to disk
Other
- Text Diff - Welcome page
- Script recording - Project Explorer
- Email file - Reference File Viewer allows to jump to all references etc. and not just the first one
- Save test files in UNIX format - Filtering in Model Library Explorer (all model libraries at the same time)
- Link to McCarl chm - Allow to switch between light, dark or custom themes
- 32-bit application - 64-bit application

## GAMSIDE Projects vs. GAMS Studio Projects

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 Project per default. Studio Projects also have a "working directory". Initially, this is set automatically to the location of the file that was opened to create the new project. If a model gets executed, it gets executed in this working directory. So, if ones opens a/a.gms and b/b.gms, by default, Studio will create two projects: 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 change the working directory in the project options. Also, it is possible to start with an empty project and just define the working directory explicitly in the way the GAMSIDE did it using the entry New Project from the File menu.

It is also possible to have multiple files in one project. For example, one could add b.gms to project a by drag'n'drop in the Project Explorer. Now, the concept of the "main file" of projects becomes important: While the GAMSIDE always executed the currently active .gms file, GAMS Studio always executes the main file of the currently active project. 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 project 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 project. 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 project in the Project Explorer switches from a.gms to b.gms. As a reminder: Projects do not know a particular working directory. Pressing F9 after switching the main file will execute b.gms in folder b.

Switching the main file
GAMS Development Corp.
GAMS Software GmbH

General Information and Sales
U.S. (+1) 202 342-0180
Europe: (+49) 221 949-9170