GAMS Studio is a completely new integrated development environment for GAMS, which is available for Windows, macOS, 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, macOS, and Linux). An overview of 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 provide quick access to common actions and offer helpful information. The page is divided into four columns.

The first two columns, labeled "Last Projects" and "Last Files", list all projects and files recently opened in Studio, with the most recent at the top. A simple left click on an item in these lists opens the corresponding file. An "x" at the top right of each entry allows you to remove it.

The third column, named "Getting Started", offers useful actions and links for new users. The upper section includes shortcuts for creating new files in user-defined locations, opening the GAMS Model Library Explorer, or loading the Transport example. The lower section contains two links to open the integrated help view, displaying either this Studio documentation or the GAMS tutorial overview page.

The rightmost column, "Further Help", contains links to the recent changes in GAMS Studio, the latest GAMS release notes, the GAMS World Forum for support, and information on 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 line numbers and icons for links and errors generated by the compiler.

1. Basic Text Manipulation

2. Advanced Text Manipulation

3. Navigation & Selection

The Code Editor checks for parentheses to the right and left of the cursor and marks valid and invalid nesting. Hitting Ctrl - B moves the cursor to the matching parenthesis while maintaining the inside/outside state. To select the block up to the matching parenthesis, hit Ctrl - Shift - B.

To navigate to files included in the GAMS source, hover over the file name and press Ctrl - click or place the cursor at the filename and press F2. If found, Studio will add the file to the current project and open it. Only plain text filenames are detected this way; symbols are not resolved.

Line Number Area

The Line Number Area offers several features beneath showing the line numbers:

• Folding control folding, see Code Folding
• Bookmarks The Code Editor allows setting temporary bookmarks in text files opened in the main tabs. Bookmarks are discarded when Studio is closed, or when a file tab is closed. A bookmark is placed at the current position in the active file using the toggle bookmark key. Each line in the editor can hold only one bookmark; if a bookmark already exists on the line, it will be removed. The next/previous bookmark keys allow navigation through bookmarks across file boundaries.
• Errors When a GAMS run results in errors, these errors are shown beneath the line number. Hovering with the mouse over the error shows details in a tooltip. The context menu opened with a right-click on the Line Number Area allows to clear all errors.
• Breakpoints control breakpoints, see Debugger

Code Folding

The Code Editor detects several types of sections in the source code that can be folded. These sections include all types of matching parentheses that extend over more than one line, as well as several Dollar Control Options that need to appear in pairs. To toggle the folding state of a section, either click the fold-marker or press the shortcut Alt - L 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 folding blocks, the Dollar Control Options $onFold and $offFold can be added to the source.

List of Dollar 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, such as:

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

For optimal highlighting, it is recommended to use strict GAMS syntax.

Code Completion

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

Automatic closing of brackets and quote characters

This feature is designed to enhance convenience for users typing source code. In GAMS, as in pretty much every other programming language, opening brackets or quote characters are eventually followed by a closing equivalent. When a user types one of the following characters, the matching closing character will be automatically inserted after the text cursor, allowing the user to easily type content in between. When typing the closing character, which should be right after the cursor, the cursor will jump over the existing character. This way, if a user types the closing character by habit, the autoclose feature does not interfere or cause syntax errors. It is also possible to select text, then type a bracket or quote character to surround the selected text with the chosen character pair. In GAMS Studio, under Settings > Editor > "Auto close opening brackets and quotes", a switch is available to turn off this auto-close feature.

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 differently (e.g., as a comparison operator), making auto-closing unnecessary. In some cases, users may not want the closing character to be inserted automatically; however, this is difficult to predict. Other editors, like Qt Creator, check the character immediately after the cursor, limiting auto-insertion of closing characters to specific cases.

The following characters allow auto-closing when they are the next character after the text cursor:

• Whitespace
• ,
• ;
• )
• ]
• {
• }

All other characters will prevent the insertion of closing characters.

File Encoding

When opening a file, Studio attempts to determine the valid file encoding. Since it is not always possible to accurately identify the encoding, the Edit > Encoding menu provides assistance. To reload a file using another codec, use the reload with ... submenu. The convert to ... submenu allows the current file to be converted to another codec. A selection of encodings is preselected, and this selection can be adjusted using the Select encoding submenu, which opens a dialog for choosing active encodings. One of the encodings is marked as the Default encoding, initially set to UTF-8.

Listing Viewer

The Listing Viewer displays a GAMS output or listing file (*.lst) generated when running a GAMS (.gms) file. The Listing Viewer is divided into two sections. On the left side, the content of the listing file is shown in a tree structure for easy navigation, while the right side displays the listing file itself.

By clicking on a specific item in the tree on the left side, the listing file will automatically jump to the corresponding location. Any changes to the cursor position in the listing file are dynamically reflected in the tree, selecting the item that matches 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 a compilation error, the Listing Viewer includes links to the source file. If the source file no longer exists, the link will still be shown but will appear struck through.

Listing Viewer showing trnsport.lst generated by running a modified trnsport.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 sections. The left side displays the symbol table of the open GDX file in a table format. Each entry represents a symbol and includes 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), including the subtype if available
• 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

Columns can be sorted by clicking on the respective column header; clicking again toggles the sorting direction. The Filter feature provides dynamic filtering of the symbol list in the GDX file. By default, only the Name column is considered by the filter. The Export button opens the export dialog.

The right side of the GDX Viewer displays the actual data of the symbol selected in the symbol table. Data can be shown in either the List View or the Table View, which can be toggled using the button in the upper part of the GDX Viewer.

The GDX Viewer automatically saves and restores its state when closing or whenever data is reloaded due to changes to the underlying GDX file. Changes such as applied filters or the currently selected symbol are retained. Each symbol maintains its applied filters and view settings (e.g., the currently selected view — List View or Table View — preferences, and visible attributes for variables and equations) as long as the name, type, and dimension of the symbol remain unchanged during the update of the GDX file. Resetting a symbol’s state can be done by clicking the Reset button. For each GDX file known to the Project Explorer, the state is saved in the Settings. The Project Explorer’s context menu provides an option to reset the GDX Viewer state for that file. Removing the GDX file from the project also clears its state.

Note

The GDX Viewer currently supports displaying up to ~107 million records for an individual symbol. If a symbol reaches this limit, a warning is added to the system log, and any records beyond this limit are truncated from view. A note about truncated data is also shown in the GDX Viewer. Applying filters can reduce the number of displayed records, allowing the full filtered dataset to be displayed again, after which the note about truncated data is removed.

List View

The List View is the default representation for viewing data in the GDX Viewer. Data is presented as a table where each row represents a record of the symbol. Each record consists of key columns corresponding to the symbol's dimensions, and value columns that vary according to symbol type:

• Set/Alias: Column Text contains the explanatory text of a record, or 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 individual domains and the original index position using superscript notation, which is especially useful if the column order has been changed. The header also allows data manipulation. By left-clicking a column header, the corresponding column is sorted with a stable sorting mechanism that maintains the order of equal entries. Clicking again toggles the sorting direction. Due to Extended Range Arithmetic used by GAMS, columns containing numerical data may include special values, which are handled uniquely during sorting:

• -INF: Smallest numerical value.
• EPS: Treated as a value very close to but not equal to 0.
• +INF: Largest numerical value.
• NA: Treated as the first non-numerical value (sorted as greater than +INF).
• UNDEF: Sorted as greater than NA.
• ACRONYMS: Sorted as greater than UNDEF, with relative order by internal number.

Column order can be changed by dragging a column header to a different position. Resizing columns can be done by dragging the border between headers. The columns in List View offer a filter facility, accessible by right-clicking the column header or left-clicking the filter icon. The Reset button in the top right corner resets the view to defaults, removing all filters, resetting sorting and numerical format, and switching back to List View if Table View was active.

The Preferences button opens a menu with settings for the current symbol. Squeeze Defaults hides columns with default values for variables and equations, and Squeeze Trailing Zeroes toggles the truncation of trailing zeros. Numerical value display format can be customized using the Format dropdown and the Precision spin box.

The available options for Format are:

• g-format: The display format is chosen automatically: f-format for numbers closer to one and e-format otherwise. The Precision setting specifies significant digits, or Full for the least digits needed to match the stored value in GDX. No trailing zeros are displayed 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 unless too large, in which case scientific format is used. The Precision setting specifies decimal places.

Variable mix from the prodmix model using f-format with precision=6

• e-format: Values are displayed in scientific format. The Precision setting specifies significant digits, or Full for the least digits needed to match the stored value in GDX. No trailing zeros are displayed when precision=Full.

Variable mix from the prodmix model using e-format with precision=6

The Precision spin box specifies the number of decimals or significant digits, depending on the 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, which opens a menu to hide specific attribute columns for variables and equations, particularly useful when using Table View.

Table View

Switching to the Table View is possible for symbols with at least two dimensions. This mode has two parts: a separate header view displaying the symbol's domains and attributes, and the actual data. The header view also provides access to the filter facility and uses visual separators to highlight specific domain positions (left to right: rows, columns, attributes). The data is reshaped so that labels of the last dimension appear in the column header, while the remaining dimensions are placed in the row header. Each table entry contains the numerical values (or explanatory text, in the case of GAMS sets) corresponding to the labels in the headers.

The following image shows the List View of a GAMS Parameter on the left side and its Table View representation on the right side:

Two-dimensional parameter as List View and Table View

For 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 working with variables or equations, it can be useful to focus on a specific attribute like variable levels. This can be done via the Attributes menu at the top of the GDX Viewer, where specific attributes can be hidden by disabling their checkboxes.

The column and row header dimensions can be rearranged by dragging them to different positions. To move an index, click and hold the left mouse button while hovering over the index, then drag it to the desired location. A thin line drop indicator will appear to preview the new position before releasing the mouse button. In general, all index positions can be moved freely, but there are a few restrictions:

• The (virtual) numerical dimension of variables and equations (Level, Marginal, Lower Bound, Upper Bound, Scale) cannot be moved and always remains the last dimension in the column header.
• If a header (row or column) has no dimensions left, a dummy header (Value, Text) is introduced. This cannot be moved but can serve as a drop target for additional drag-and-drop operations.

The table view representation of a GAMS parameter during a drag-and-drop operation, moving the dragged dimension to the position indicated by the drop indicator (thin black line)

While filters applied in List View also apply to Table View and vice versa, sorting does not affect the labels in Table View; they remain in internal order, which cannot be modified by the user. For large datasets, it’s recommended to limit visible records by applying filters in List View and by disabling specific value columns for variables and equations. Once the data has been reduced, switching to Table View allows viewing 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, which displays the domains and (numerical) attributes. In List View, the header is part of the data view itself, while in Table View, it appears as a separate header above the data. The filter dialog can be opened by right-clicking the header or by left-clicking the filter icon. Depending on the column type (key or value), the appropriate filter dialog for labels or numerical values will open.

The filter dialog for a key column lists all occurring labels for that column. By default, all labels in all columns are visible. To narrow down the displayed data, uncheck one or more labels, then click the Apply button. Instead of manually selecting labels, you can also use the filter at the top of the dialog, as explained in the Filter Section. The filter automatically applies to the list of labels, selecting matching labels and deselecting all others.

The Hide unselected items checkbox hides all deselected labels automatically, which is especially useful for large sets of labels. Only matching labels will remain in the list as you type. The Select All, Invert, and Deselect All buttons allow faster selection. You can also quickly select one specific label while deselecting all others by using middle-click or Ctrl - left-click (or Command - left-click on macOS). This applies the filter automatically and closes the dialog without needing to click Apply.

To select or deselect a range of labels, first select a label, then Shift - left-click another label to change the selection state of all labels within that range. If no label is initially selected, the range starts from the first label by default.

Filter dialog on column j for variable x in trnsport.gdx

Numerical columns provide a different filter type, allowing you to specify a range of values to include or exclude from view. The Min value is the lowest, and the Max value is the highest included in the view. When the Exclude checkbox is activated, the specified range is excluded instead of included. The lower part of the filter dialog contains checkboxes for special values like +INF and EPS. Checking or unchecking these options will show or hide the corresponding values in the view. The Apply button adds the filter, refreshing the view accordingly, and the Reset button removes any active filter.

Note

When a filter is applied to a numerical column, the values used for comparison are the actual values from the GDX file. Since displayed values are influenced by the Format and Precision settings, they may differ from the internal GDX values. For example: Suppose 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 still appear, even though 1.33 is greater than the displayed 1.3. This is because the internal GDX value used for comparison is actually 1.34.

Filter dialog on numerical column Value for parameter c in trnsport.gdx

Search Facility

Both the List View and Table View can be searched by entering a term into the search field located above the Data View. The search behavior can be customized using the buttons on the right side of the search field. See Filter in Tables and Trees for more details. As soon as the search term is entered, all matches in the Data View are highlighted automatically. The Search Forward (F3) and Search Backward (Shift - F3) buttons allow you to select the next or previous element that matches the search criteria. The search continues from the beginning of the Data View when the end is reached, and vice versa.

In List View, all cells except for the header are considered in the search. In Table View, all cells and header entries are searched, except for symbol type-specific headers such as Value (parameters), Text (sets/aliases), Level, Marginal, Lower, Upper, and Scale (variables/equations).

Searching the List View of a parameter by 'seattle'

Searching the Table View of a parameter by 'seattle'

Export Dialog

The GDX Viewer offers export functionality accessible by clicking the Export button above the symbol table on the left side of the GDX Viewer. The export dialog uses GAMS Connect to export data from a GDX file into another data format.

GDX Export dialog opened from trnsport.gdx

The Target Format dropdown menu allows selection of the export format (currently, only Excel is available). The upper part of the dialog also provides options to specify the Excel output file and the GAMS Connect instructions file in YAML format. The Apply Filters checkbox controls whether active filters in the GDX Viewer are applied to the exported data.

The input fields for GAMS special values allow customization of their representation. For instance, to export the GAMS special value EPS as 0 instead of its default string representation EPS, change the corresponding input field to 0.

Symbols can be selected for export using the checkboxes in the Export column of the symbol table. The Select All/Deselect All button can be used to select or deselect all symbols for export. Clicking Export generates and executes the GAMS Connect instructions file, while Save generates the instructions file without executing it. The dialog is disabled while the export process is running. Clicking Cancel closes the dialog and halts any unfinished export process.

The export mechanism uses the GDX file currently opened in the GDX Viewer. If a symbol is displayed in Table View mode, the order and placement of individual dimensions are maintained in the Excel output.

Summary of Actions and Shortcuts

Reference File Viewer

The Reference File Viewer is a useful tool for navigating the source code of GAMS models via a reference file, especially when multiple files are involved. A reference file contains all symbol references of a 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, a reference file with the ".ref" extension is created, which can be opened either through the File > Open menu or by 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 displays an alphabetical listing of all symbols used in the model.
• Set, Acronym, Variable, Parameter, Equation, and Model provide an alphabetical listing of symbols of each type. For more information on GAMS data types, see Data Types and Definitions.
• File lists all file statements used in the model, in alphabetical order.
• Function lists the GAMS built-in functions used in the model.
• Unused displays an alphabetical listing of symbols declared in the model but not used.
• File used lists all files used in the model, including the full file path. Double-clicking an entry jumps to the beginning of the reference file.

The number next to each tab name indicates the count of symbols in that category. The number in the All Symbols tab is the sum of symbols in all other tabs, except the Unused and File used tabs. Clicking on a symbol entry in any tab (except File used) displays a detailed reference list on the right side of the viewer, showing reference locations. Hovering over an entry shows a tooltip with file location and position details, and double-clicking jumps to the referenced position in the corresponding file.

The reference list is organized by the following reference types:

For a detailed description of reference types and their shorthand symbols, refer to Reference Types in GAMS Output.

Sort and Filter referenced symbols

• Sort: Clicking a column header in the reference table sorts the symbols by Entry, Name, Type, Dimension (Dim), Domain, or Text.
• Filter: Entering text in the Filter box filters the symbols in the reference table by Name. More details about the filter can be found in the Filter Section.

Summary of Actions and Shortcuts

Solver Option Editor

The Solver Option Editor allows viewing and editing of a solver-specific option file to control solver settings and interpret results. For more details on using The Solver Options File, refer to Solver Usage. See how to set the optFile parameter to instruct GAMS to read an option file in The GAMS Call and Command Line Parameters.

The Solver Option Editor provides a table-form editor where each row corresponds to a line in the solver option file. It also includes a browser for solver option definitions, which can be grouped, filtered by term, and directly added to or removed from the editor.

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

• The left pane displays the contents editor in a table format. Each row entry is either an option entry with an option key, value, and optional end-of-line comment (shown if end-of-line comment characters are defined for the solver option file) or a comment entry.
  • Option keys and values appear in green when defined correctly and red when there’s an error. End-of-line comments and comment entries are shown in grey. (For toggling an option entry to a comment entry and vice versa, see Toggle comment/option selection).
  • Comment rows display in merged cells, as differences between option keys and values are not relevant for comment lines.
  • The Compact View checkbox hides comments in the display, though some editing actions are disabled in this view (see Compact View for details).
  • The Show Messages checkbox toggles the display of the message log at the bottom.
  • The Open As Text button allows reopening the file in a text editor once it has been saved (see Open an existing solver option file and Save a solver option file in Basic Operations for details).
• The right pane contains the solver option definitions browser.
  • The lower part lists all option definitions with columns for Name, Synonym, Default Value, Range, Type, and Description. Options can be sorted alphabetically by clicking the Name header. A checkbox beside each option indicates if it is defined in the left pane editor. Options with enumeration types (EnumStr or EnumInt) can be expanded to show all enumerated values by clicking the bullet beside the entry; clicking it again hides them.
  • Double-clicking an entry or dragging it into the left pane adds the option key with its default value (see Summary of Actions and Shortcuts for details on adding or inserting an option).
  • Above the option definitions list is a grouping selector and a filter box. The grouping option filters definitions by group name; by default, all definitions are shown. The filter box, labeled Filter Options ..., filters option definitions as terms are typed. For more on filtering, see Filter Section.
• The bottom pane shows the message log, reporting operations such as loading, saving, and any errors from editing. By default, the log is shown unless Show Messages is unchecked in the left pane.

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 in the file dialog. Choosing Add new file by right-clicking on the 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 files with the optFile parameter).
  • From the project context menu, right-click on the project name in Project Explorer and choose Add new solver option file to see a list of solver names. Selecting a solver name from the list opens a file dialog with the selected solver name as the file name and the default option file suffix opt (see how to set different suffix values for solver option files with the 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, then select a solver option file.
  • From the project context menu, right-click on the project name, choose Add Existing file, then choose Option Files or All Files in the open file dialog, and select a solver option file.
  • If a solver option file is already open in the Solver Option Editor, you can reopen it in the 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 the Solver Option Editor or text editor:
    • If a solver option file is already open in the Solver Option Editor, choosing Reopen File As Text from the file context menu in Project Explorer closes the editor and reopens the file in the text editor. The Open As Text button in the left pane editor performs the same function.
    • If a solver option file is already open in the 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.
    • If a file is already listed under the project but not yet opened, choosing Open File from the project context menu opens the file in the Solver Option Editor; choosing Open File As Text opens the file in the text editor.
• Save a solver option file: via the File > Save menu or Ctrl - S shortcut. Choosing File > Save As or using the Ctrl - S shortcut again opens a file dialog to save the file with a different name (see how to set different suffix values for solver option files with the optFile parameter).

Navigating the contents

When a component of the solver option editor is in focus, further actions can be performed (see Summary of Actions and Shortcuts for the list of actions and shortcuts). Clicking on a component brings it into focus or selection. In addition to using the mouse, navigation within the solver option editor components is possible with the keyboard. Pressing the Tab key navigates between components, moving from the left pane editor to the right pane option group box, the right pane Filter box, and the right pane definition browser in that order. In the left pane editor, press Up, Down, Left, and Right keys to navigate within the table. In the right pane browser, Up and Down navigate the entries, Right expands enumerated entries, and Left collapses them.

A connection exists between an option entry in the left pane editor and a definition entry in the right pane browser. This connection can be identified from both the left pane editor and the right pane browser.

• From the left pane editor, right-click on a selected entry and choose Show option definition from the context menu. The entry in the right pane browser that contains the definition for the selected entry is highlighted and selected. When a cell or row is already selected, the shortcut Ctrl - F1 performs the same function.

• From the right pane browser, clicking or selecting an entry highlights all corresponding entries in the left pane editor if the definition has already been added; otherwise, there is no selection in the left pane editor.

Further editing actions can be performed in both the left pane editor and the right pane browser (see Editing the Contents for details).

Editing the Contents

The following actions can be performed when editing the contents:

actions that can be performed via the left pane editor and the right pane browser

• Edit option key, value, and comment: This action is performed in the left pane editor.
  • When a cell in the left pane editor is selected, double-click on the cell or press the platform-dependent edit key (e.g., F2) to edit the option key, value, or comment (if available). A drop-down list suggests possible option keys and values when available. Press Enter to confirm the edit and 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 in 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 a new option from 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 with the option key and default value of this definition will be added as the last entry in the left pane editor.

• Insert new option and comment: This action can be performed from the left pane editor and from the right pane browser in several ways.

  • 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 row is already selected, the shortcut Ctrl - Return results in the same behavior.
  • Right-click on the selected entry in the left pane editor and choose Insert new comment from the context menu. A new entry with dummy text [COMMENT] will be inserted before the selected entry. When a cell or row is already selected, the shortcut Ctrl - Shift - Return results in the same behavior.

  • Double-click on a definition entry in the right pane browser.

    • If this definition has not yet been added (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 a cell or row is selected, the shortcut Return results in the same behavior.
    • If this definition has already been added (a checkbox in front of the entry is marked), by default, the studio option editor will prompt to override an existing option if it has already been added to the left pane editor. A pop-up message box appears with three options: Replace existing entry, Add new entry, or Abort. Replace existing entry removes all other entries of this definition key but the first one in the left pane editor and replaces the option value of the entry with the default value. Add new entry adds a new option entry with the option key and default value of this definition in the left pane editor. Abort cancels the action. See 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 it in the left pane editor.
    • If this definition has not yet been added (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 selected entry in the left pane editor.
    • If this definition has already been added (a checkbox in front of the entry is marked), by default, the studio option editor will prompt to override an existing option if it has already been added to the left pane editor. A pop-up message box appears with three options: Replace existing entry, Add new entry, or Abort. Replace existing entry removes all other entries of this definition key but the first one in the left pane editor and replaces the option value with the default value. Add new entry inserts a new option entry with the option key and value of this definition before the selected entry in the left pane editor. Abort cancels the action. See override existing option on how to suppress this default behavior.

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

• Toggle comment/option: This action is performed in the left pane editor, turning an option entry into a comment entry and vice versa.
  • Select the option entry, right-click on the selection, then choose Toggle comment/option selection from the context menu. In the case of an option entry, this action turns the entry into a comment entry (shown in grey color). In the case of a comment entry, this action turns it into an option entry (shown in either green or red depending on whether or not there is an error). When a cell or row is selected, the shortcut Ctrl - * results in the same behavior. Clicking on the color box in front of the entry row also results in the same behavior, even without selection.
• Move up and down: These actions change the order of the option and comment entries in the left pane editor.
  • To move an entry up: select the option entry, right-click on the selection, and choose Move up from the context menu. The selected option entry will be moved up by one position in the option entry table. When a cell or row is selected, the shortcut Ctrl - Up results in the same behavior.
  • To move an entry down: select the option entry, right-click on the selection, and choose Move down from the context menu. The selected option entry will be moved down by one position in the option entry table. When a cell or row is selected, the shortcut Ctrl - Down results in the same behavior.
• Delete option: This action can be performed from the left pane editor and from the right pane browser.
  • From the left pane editor, select the option entry, right-click on it, then choose Delete selection. The selected option entry will be deleted from the option entry table. When a cell or row is selected, the shortcut Ctrl - Delete results in the same behavior.
  • From the right pane browser, select the definition entry that has already been added to the left pane editor (indicated by a marked checkbox), right-click on it, then choose Remove this option. All entries in the left pane editor defined by this definition will be deleted. When a definition row is already selected, the shortcut Delete results in the same behavior.
• Show option definition: This action is performed 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 results in the same behavior.
• Show all options of the same definition: This action is performed 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 in the left pane will be highlighted. The shortcut Shift - F1 results in the same behavior.

All entries of the same option are highlighted

Compact View

Compact View in the solver option editor allows viewing and editing solver options without comments. Comments in a solver option file are not interpreted by either GAMS or the solver and are used only for documentation purposes. As a solver option file grows with many comment lines, it can be difficult to see which options will be interpreted. The compact view is helpful here, hiding all comments and displaying only non-comment lines. In the right pane editor, check the Compact View checkbox to activate compact view, and uncheck it to deactivate compact view. Comment entries reappear once compact view is deactivated.

Note that some actions may not show visible results in compact view. For example, the toggle comment/option selection action, when performed on an option row entry, turns the entry into a comment entry, which is hidden in compact view. Similarly, the delete selection action, when used on an option row entry, removes the entry, which is then no longer visible in compact view.

Certain editing actions that change the order of contents are also suppressed in compact view. These include insert new option, insert new comment, move up, and move down. Adding or inserting options from the right pane is allowed, but any comment inserted with an option (if set) is not visible in compact view. See also Settings on how to insert a new option along with a comment from the definition.

Settings

The Settings tab allows configuring behaviors for inserting new options from definitions and for deleting options. Access the settings by opening the Settings dialog (File > Settings) and switching to the Misc. tab. The configurations available are:

• Override existing option. This setting allows Studio to override an existing option when an option entry is added or inserted from the right pane browser. If there are multiple entries of the same option, Studio displays a pop-up offering three choices: replace existing entry, add new entry, or abort.

  • Replace existing entry removes all other entries of this definition key except the first entry from the left pane editor and replaces the option value of the entry with the default value defined in the definition.
  • Add new entry adds or inserts a new option entry with the option key and default value from the definition into the left pane editor.
  • Abort cancels the action.

  This behavior is enabled by default. In the Settings dialog, uncheck the checkbox in front of Override existing option to suppress this behavior, or check it to enable the behavior.

• Add option description as comment above. This setting allows Studio to add an option description as an additional comment entry above an option entry added or inserted from the right pane browser. The description is taken from the option definition in the right pane browser. This behavior is disabled by default. In the Settings dialog, check the checkbox in front of Add option description as comment above to enable this behavior, or uncheck it to suppress the behavior.
• Add option description as end-of-line comment. This setting allows Studio to add an option description as an additional end-of-line comment to an option entry added or inserted from the right pane browser. The end-of-line comment is available only if the solver defines valid end-of-line characters. The end-of-line comment column will appear in the solver option editor only if this is defined for the solver option file. This behavior is disabled by default. In the Settings dialog, check the checkbox in front of Add option description as end-of-line comment to enable this behavior, or uncheck it to suppress the behavior.
• Delete all immediate comments above. This setting allows Studio to delete any immediate comments (if present) above an option when the option is deleted. This behavior is disabled by default. In the Settings dialog, check the checkbox in front of Delete all immediate comments above to enable this behavior, or uncheck it to suppress the behavior.

Summary of Actions and Shortcuts

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

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

GAMS Configuration Editor

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

Contents of gamsconfig.yaml shown in GAMS Configuration Editor

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

GAMS processes a sequence of gamsconfig.yaml files from different locations (see section The GAMS Configuration in YAML Format for the location of GAMS configuration files and Order of Precedence for Options for the order of precedence for command line parameters). Studio can create a new gamsconfig.yaml file at the default user-specific location and open the file in the editor if the file does not already exist at this location. This can be done by choosing GAMS > Default GAMS Configuration. If the file already exists at the default location, choosing GAMS > Default GAMS Configuration will not override the existing gamsconfig.yaml in the default user-specific location but will 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 to a different location using File > Save As....

Connect Editor

The Connect Editor provides fundamental functionality for creating and editing a GAMS Connect file, which contains instructions in YAML syntax to be processed by the GAMS Connect interfaces. The Connect Editor consists of three main sections:

• the left section displays instructions from the file in a tree structure. The top-level entries are Connect agent names with option entries as their children.
• the middle section lists all available Connect Agents. Double-clicking or drag-and-dropping an agent name from this section into the left section will add or insert instructions for the selected agent.
• the right section shows the definition of the Connect agent selected in the middle section. Clicking an agent name in the middle section will display the definition of the selected agent in this section.

A new Connect file can be created by selecting Add new file from the File menu or the project context menu in Project Explorer. An existing Connect file can be opened by selecting Open... from the File menu or Open in Current Project... or Add existing file from the project context menu in Project Explorer. In both cases, a file dialog opens to select the project folder, and you should choose Gams Connect Yaml File (*.yaml) as the file type.

A top-level entry of instructions is a Connect agent name with option entries as its children. Each option entry is represented as either a map of option key to option value or a list of option values or option entries, depending on the agent’s definition. Only an option value can be edited. An edited option value that does not conform to the definition (e.g., wrong type or disallowed value) will be highlighted in red, as will the agent name. By clicking the Help icon next to the agent name at the top-level entry, the agent name in the middle section will be selected, and the definition of the agent will be shown in the right section.

New instructions for an agent can be added by double-clicking an agent name in the middle section or by dragging an agent name from the middle section and dropping it into the left section at the desired position. Double-clicking an agent name will append instructions for the selected agent as the last entry in the left section, while dragging an agent name will either append instructions as the last entry or insert them below the drop position. When the Only required option when adding new agent checkbox is checked, only the agent's required options will be added. An option missing from the agent name entry can be inserted or appended by dragging it from the definition in the right section and dropping it at the desired position in the left section. Dropping the option onto the agent name entry will append it as the last child entry of the agent name. The missing option can still be added even if it is not required by definition and the Only required option when adding new agent checkbox is checked.

A new child entry of a list entry can be added using the plus icon at the last child entry of the list. An option entry and all its children can be removed, moved up, and moved down using the delete icon, move up icon, and move down icon at the end of each entry. An option entry with children can be either expanded or collapsed by clicking the icon in front of the entry. The tree structure can be fully expanded by clicking Expand All and collapsed by clicking Collapse All.

The content of a Connect file can also be displayed and edited in plain YAML format using a text editor. Switching from the Connect Editor to the text editor can be done by either clicking the Open As Text button or selecting Reopen File as Text from the file’s context menu in the Project Explorer.

• The Open As Text button will be enabled once the file content has been saved, allowing a switch to the text editor.
• Selecting Reopen File as Text from the context menu, when the file has unsaved changes, will open a dialog to report modified content and offer options to discard the content, save the content, or cancel the operation.
  • If discarding the content, Studio will switch to the text editor to display the file content before modification.
    
  • If saving the content, Studio will save the file before switching to the text editor.
  • Canceling the operation will return to the current modified state in the Connect Editor.

Parameter File

To support fast switching between parameter sets, Studio contains an editor for "GAMS Parameter Files". To create a Parameter File, open the context menu of a project and select "Add New Gams Parameter File". The project settings contain a box to switch between different parameter files or to deselect a file for the project.

Add new GAMS Parameter file

Select GAMS Parameter file

Parameters defined in the parameter file will override parameters defined in the GAMS configuration file. The usage of this editor is equivalent to the Solver Option Editor.

Tab Browser (Deprecated)

Deprecation Notice: This feature will be removed in a future version of GAMS as it is replaced by the Navigator.
The Tab Browser can be accessed with a button next to the main tab bar or via the shortcut Ctrl - 4. It opens a list of all open files and includes a search input field. When opening the tab browser, the search field is already focused. Typing updates the list in real time. Pressing Enter selects the first item in the list and opens it. It is also possible to use the up/down arrows to navigate the list and select an item with Enter. The filter supports wildcard syntax.

Navigator

The Navigator allows users to quickly navigate between files and can be opened with the shortcut Ctrl - K or by clicking in the Navigator input field located in the Status Bar in the bottom right. The default view shows a list of all files from the Project Explorer with three columns. The first column contains the file name, the second shows the path relative to the current project's directory (if it is the same path, the field is empty), and the third column contains additional information, such as the type of result by default. Typing in the input field filters this list. Using the arrow keys, a result can be selected and confirmed with Enter. The filter also supports wildcards: for example, typing *.gdx will find all ".gdx" files.
To narrow a search further, the Navigator supports different modes accessed with prefixes in front of the search term. Typing "?" in the input field shows a list of all available modes, allowing, for example, filtering for files currently opened in a tab (t), files associated with the current project (p), or all open log tabs (l). Additionally, using the : prefix followed by a number lets users jump to a certain line in the current file. There is also an option to jump to files not yet known to Studio: using the f prefix allows navigation of the filesystem from the current project's workspace. With the quick action prefix (x), users can call frequently used Studio functions like "Open Model Library Explorer", "Clean Scratch Directories", and "Run Engine". For a complete list, type x into the Navigator.

Navigator showing some example files

Pin View

Studio provides a Pin View to keep a clone of a selected tab, allowing two file contents to be visible simultaneously. To pin a tab, there are two options in the tab bar: "Pin right" (shortcut Ctrl - Click) splits the edit area horizontally and opens the Pin View to the right of the main tabs, while "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 are restored upon 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 enables synchronized scrolling for the two visible editors. Synchronization is always passed from the active editor to the passive editor, so scrolling with the mouse wheel in the passive editor doesn’t affect the active editor, allowing adjustments without toggling the function off and on. The last button closes the Pin View.

Navigation History

The Navigation History records a navigation history event each time the cursor moves in any 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 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, only the latest position is stored in the history. The purpose 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 multiple 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 even includes files that were completely removed from Studio. When such a file is reopened through the Navigation History feature, due to technical limitations, the file’s affiliation with 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.

Further Studio Widgets

Project Explorer

The Project Explorer organizes files opened in Studio into projects. Each project has its own base directory. All files associated with the project are organized in a hierarchical tree structure of folders relative to this base directory. A project’s tooltip shows its location in the file system, displaying the project file’s path (the .gsp file - gsp stands for Gams Studio project). To support faster identification, there are several icons for different file types:

• Runnable GAMS files (default: .gms and .inc) are marked with a GAMS icon.
• The main GAMS file assigned to the project additionally shows a green play symbol.
• GDX files (.gdx) are represented with a database icon.
• Reference files (.ref) have a reference nodes icon on a sheet.
• Editable files (e.g., .txt) display a pen on a sheet.
• Read-only files (e.g., .log) are indicated by lines on a sheet.

A file or folder entry’s tooltip shows its location in the file system. The file, project, and folder locations can be opened in the default file system explorer via the context menu’s "Open Location". Selecting "Open Terminal" opens the system’s terminal window at the location of the selected file, project, or folder. The context menu of a .gdx file provides a special option "Open in GDX Diff" to open the GDX Diff Dialog.

Project Explorer and its context menu

An empty project can be created by selecting "New Project..." from the "File" menu or from the Project Explorer context menu. A file dialog will open to select the project file name. If a project with that name already exists, Studio will look for a number to append until the project name is unique. A project is also created automatically when opening a file; the project’s name and location are based on the file’s name and location. It is possible to add projects with the same name to Studio; a gray number helps to differentiate them.
One project may contain multiple runnable GAMS files, but only one can be 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 shows the folder’s location and the current main file name. After the first run, it also shows the name of the most recent output file (.lst). The main file can be set to a different runnable GAMS file within a project via the context menu option "Set as Main File". The project base directory remains unchanged if the main file is changed.

The main file of the active project is executed by pressing F9 or clicking the execute button (see Quick Access Toolbar and GAMS Parameter Editor for setting GAMS parameters and executing the main file). To identify the active project, the current file and its project appear in bold text, and icons of other projects are slightly dimmed. After executing the main file, the generated listing file (.lst) is added to the project, and the output view (see Process Log) is opened. A clickable log line in the process log may add the corresponding file to the project and open it in the Central Widgets area. Users can manually add more files to a project by right-clicking and selecting "Add Existing File" or "Add New File" from the context menu. Drag and drop from the system’s file explorer is also supported.

Multiple items can be selected in the Project Explorer, but a selection contains only items of one kind (either files or projects, not both), depending on the first selected item. Folders count as multiple file selections. The context menu then applies to all selected items.

Files can be removed from a project, and projects can be removed from the Project Explorer using the "Close File" and "Close Project" actions 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 affecting the files on the file system. The action "Close Files in This Folder" closes all files in this folder and its subfolders. The action "Close File" closes the file if opened and removes the file entry from the project. If the closed file is the only entry in a folder, the folder is also closed. A project can be empty during the current session, but an empty project will not be restored on Studio restart. If there are unsaved changes, a message popup will appear, asking the user how to proceed.

Selected files and folders can be deleted by selecting "Delete File" from the context menu. Be aware that files that are part of multiple projects will be deleted too and will be removed from the other projects that contain the files. When selecting a folder entry, only the files that are part of the project will be deleted, no other files and not the folder itself. The context menu for a project allows you to delete the project file.

Each project is usually stored in its own file, but projects with fewer than six files or without a runnable GAMS file are stored internally (this can be changed in the Project options). Related paths are stored relative to the project file’s location, enabling easy sharing of the project and its files. You can use "Move Project File" to rename a project or to move it to another folder. In this case, the relative paths are adjusted to reach the original referenced files. The option "Copy Project" allows creating a copy of the project file and all of its referenced files.

Selected files can be dragged to another project. Dropping them moves them 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 (without copying the file itself). If the project already contains a specific file, it is ignored.

Actions like renaming, moving, or deleting files from the file system are currently not supported but will be added in the future.

Project options

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

• Project file: shows the location of the project file or [internal] for internally stored projects. The button next to the location allows creating or deleting the project file.
• Name: shows the name of the project.
• Base directory: defines the directory from which the folders to each file of the project are generated. Changing this updates the visible folder structure for all files of this project.
• Working directory: defines the directory where the main GAMS file associated with the project will be executed.
• Main file: shows the current main file and allows changing it. The drop-down box lists all runnable files in the project.
• Parameter file: shows the current parameter file and allows changing it.

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

Project Focus

Having multiple projects with many files in the Project Explorer can get confusing. The drop-down box at the top of the Project Explorer allows focusing on one project at a time.

When a project is focused, only the files referenced in this project will be shown in the Project Explorer. Additionally, Studio hides all other process logs and all open tabs that are not referenced in the focused project. The hidden files remain open in the background and will become visible if their project or -Show All- is selected. This allows instant switching to another project without needing to reopen or modify files. If the open tabs do not contain any file from the focused project, the main file of that project will open.

Note

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

Process Log

After starting a GAMS process, the LogViewer opens to view the process log. Usually, the log stays at the bottom to display the latest log lines. Tracking can be paused by clicking the up arrow on the vertical scrollbar. To resume tracking, scroll to the bottom.

The log typically contains various links:

• Compilation errors (red): Links to the GAMS file where the error occurred. Also includes 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 a link takes the focus to that file (and line). Double-clicking in the log finds the nearest link to the listing file and takes the focus there. Files not part of the current project are added when opened via link.

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

Quick Access Toolbar and GAMS Parameter Editor

The toolbar contains two parts: a quick access section and a GAMS Parameter editor to customize how GAMS executes 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 associated with the file currently open 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, RF Creation: Choose Run with GDX, RF Creation or press F10 to compile and execute GAMS statements in the main runnable file and create a GDX and Reference file with the name of the main runnable file and a gdx and rf extension. This execution command is equivalent to running GAMS with the combination of the parameters action=CE, gdx=default and rf=default.
• Run with Debugger: Choose Run with Debugger or press F11 (macOS Meta - F11) to compile and execute GAMS statements in the main runnable file with the debugger enabled.
• Step start with Debugger: Choose Step start with Debugger or press Shift - F11 to compile and execute GAMS statements in the main runnable file with the debugger enabled and pause the process at the first possible line.
• 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, RF Creation: Choose Compile with GDX, RF Creation or press Shift - F10 to compile GAMS statements in the main runnable file and create a GDX and Reference file with the name of the main runnable file and a gdx and rf extension. This execution command is equivalent to running GAMS with the combination of the parameters action=C, gdx=default and rf=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). If GAMS parameters have been set, they will be appended to the pre-customized commands. Like in the GAMS Terminal, when identical parameters have different values, the last one "wins" and overwrites the previous ones. This allows users to change and override GAMS Studio default parameters, which can lead to problems if done incorrectly. In such cases, Studio prints a warning message to inform users about potential issues. To debug Studio’s actions, the full GAMS call parameters are printed in the System Log. After execution, parameters are added to the project history, shared across all files in the project. Previous GAMS parameters can be recalled from the project history via the drop-down menu of the combobox. Switching files in Central Widgets will activate a different project history only if the newly opened file belongs to a different project.

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

The GAMS Parameter Editor provides options to interrupt or stop a running GAMS model job (identified by an 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 to perform a graceful stop and collect an incumbent result from the execution if the solver supports this feature. This command is enabled when there is an active job in the project and disabled when no job is running.
• Stop: Click the Stop button or press Shift - F12 to send a request to immediately stop the running job. This command is enabled when there is an active job in the project and disabled when no job is running.

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

Note that the GAMS parameter combobox is disabled when the extended parameter editor is active; all editing must be done in the extended 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 containing Parameter Name, Synonym, Default Value, Type, and Description. Definitions with enumeration types (EnumStr or EnumInt) can be expanded by clicking the bullet in front of the entry to show all possible values; clicking the bullet again collapses the list. A filter box (with placeholder text Filter Parameter...) above the definitions list allows filtering parameters. Typing a filter term displays matching results in the list below. More information on filtering is in the Filter Section.

The parameter editor highlights potential errors in red in both the combobox and the left pane of the extended editor. Hovering over an error key or value displays a tooltip with further error details.

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 multiple entries of the same parameter, only the last entry is considered when GAMS executes the model. In such cases, the parameter editor combobox displays a warning in yellow, and the icon beside the parameter in the extended editor turns half-yellow combined with another color, red or green, depending on whether an error exists.

Parameter key turns yellow and the pop-up tooltip indicating a warning

Refer to edit parameter key and value for guidance on editing a parameter key or value that shows an error or warning. Refer to show all parameters of the same definition for locating all entries of the same parameter.

Below are all editing actions available in the extended parameter editor:

Actions available via the context menus of Extended Parameter Editor

• Edit parameter key and value: Double-click on the key cell to edit Key and on the value cell to edit Value of an entry. A drop-down list suggests possible keys and values when available. Press Enter to confirm the edit and Esc to cancel.

GAMS Parameter editor shows a drop-down list of all possible parameters starting with 'o'

GAMS Parameter editor shows a drop-down list of all enumerated values for the 'action' parameter

• Add new parameter: There are several ways to add a new parameter in the extended parameter editor.

  • Right-click on the left pane of the parameter editor and choose add new parameter from the context menu.
  • Right-click on a selected parameter entry in the parameter table and choose add new parameter from the context menu.
  • Click on the add new parameter button located next to the Key table header in the left pane.

  A new entry will be added at the end of the parameter entry table with a placeholder key [KEY] and placeholder value [VALUE]. Refer to edit parameter key and value for instructions on editing the key and value.

  Additionally, a new parameter can be added from the right pane by double-clicking a definition entry. The selected definition entry will be added as a new parameter at the end of the left pane table.

  If you double-click an enumerated value entry of a parameter definition, it will be added with the selected enumerated value. If not, the default value for the entry is added.

Parameter with enumerated value added by double-clicking 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 a placeholder key [KEY] and placeholder value [VALUE]. Refer to edit parameter key and value for instructions on editing key and value.
• Move up: Right-click on the selected entry and choose Move Up. The selected entry will move up one position in the table, changing the parameter order.
• Move down: Right-click on the selected entry and choose Move Down. The selected entry will move down one position in the table, changing the parameter order.
• Delete selection: Right-click on the selected entry and choose Delete Selection. The selected entry will be removed 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 removed from the table.
• Show parameter definition: Right-click on the left pane of the extended editor and choose Show parameter definition. The corresponding parameter definition entry in 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 of the same definition 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 select Resize columns to contents. All columns will be resized based on their contents.
  • Add this parameter: Right-click on the right pane of the extended editor and select Add this parameter. The parameter, with its default value if defined, will be added as the last entry on the left pane of the extended parameter editor. This option is enabled only if the parameter does not already exist in the left pane. Note that double-clicking the parameter definition will also add it. If the parameter is already present, a dialog will appear with options to:
    • Replace the existing entry if only one exists, or replace the first and delete duplicates if there are multiple entries,
    • Add a new entry with the same definition,
    • Show details of all instances of the parameter, or
    • Abort the action.

Dialog when adding a parameter definition that already exists

• Remove this parameter: Right-click on the right pane of the extended editor and select Remove this parameter. The selected parameter definition will be deleted from the left pane of the extended parameter editor. This action is enabled only if the parameter is present in the left pane. If multiple entries exist, all instances will be removed.

Press F1 on a parameter entry in the extended parameter editor to open the GAMS Call and Command Line Parameters help page for a detailed description of the GAMS parameter.

Summary of Actions and Shortcuts

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

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

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

Integrated Help

The Help View integrates GAMS documentation navigation directly into GAMS Studio. Press F1 or select Help > GAMS Documentation or check View > Help to open the Help View and browse the documentation. The Help View start page is the main document page available in the GAMS distribution used for GAMS Studio. See Home to return to this start page at any time. Alternatively, select Help > Studio Documentation to directly access the GAMS Studio documentation start page. Click the Close button or uncheck View > Help to close the Help View. GAMS Studio will remember the last viewed page and its browsing history until GAMS Studio restarts.

The Help View starts in a docked state and can be repositioned around the editor in the central widget area by dragging it to a preferred location. Studio will remember the last Help View state before it was closed.

Help View when docked to the right of Code Editor

The Help View can also be floated by double-clicking its title bar. Double-clicking the title bar again will dock the Help View back.

Help View when floated

Note that the Help View does not support all browsing features of a web browser. However, it provides an Open this page in Default Web Browser button to access the full features of a web browser.

An overview of Help features:

• Home: Start the help page [GAMSDir]/docs/index.html
• Back: Return to the previous page
• Forward: Go to the next page
• Reload: Reload the current page’s content
• Stop: Stop loading the current page
• Bookmarks:
  • Bookmark this page: Save the page title as the bookmark name along with its location. The bookmark will appear below the Organize Bookmarks section. Click a bookmark entry to jump to the saved page.
    
  • Organize Bookmarks: Opens the bookmark dialog to edit or delete bookmark entries. Right-click on an entry in the bookmark table to load or delete it in the Help View. The selected bookmark's Name and Location can be edited in the dialog’s lower section. Press Enter to save changes, or Esc to cancel. Click the close button to exit the bookmark dialog.
    
• Zoom In: Zoom in on the page to increase font size. Press Ctrl - +, Ctrl - Mousewheel Up, or choose View > Zoom In.
• Zoom Out: Zoom out to decrease font size. Press Ctrl - -, Ctrl - Mousewheel Down, or choose View > Zoom Out.
• Reset Zoom: Reset font size to the original. Press Ctrl - 0 or choose View > Reset Zoom.
• Help Option:
  • View This Page Online: Opens the same documentation on the GAMS website. This allows use of advanced search functionalities across all GAMS documentation of version 49.3, browsing different versions, or exploring the GAMS website from the Help View.
  • Open in Default Web Browser: Opens the document in the default web browser. This enables browsing with full web browser features, as the Help View does not support all browser functionalities.
  • Copy page URL to Clipboard: Copies the URL of the current page to the clipboard, useful for viewing the address of the currently viewed document page.
    
• Find in page...: Press Ctrl - F or select Edit > Search to activate a search at the bottom of the Help View. Type a word to search within the page. Matches will be highlighted as you type, and the scrollbar will indicate the number of occurrences. Click previous button to move to the previous occurrence, next button or press Enter for the next. Enable Case Sensitivity to search case-sensitively. Highlights persist as you navigate pages until the keyword is cleared, the search is dismissed, or the Help View is closed. Click the close button or press Esc to exit the search.

Help on Specific Widgets

You can jump directly from various widgets (Welcome Page, Code Editor, Listing Viewer, GDX Viewer, Reference File Viewer, and Solver Option Editor) to related documentation sections.

From Welcome Page, Listing Viewer, GDX Viewer, and Reference File Viewer, pressing F1 activates the GAMS Studio page, navigating to the relevant section for each widget. In the GAMS Parameter Editor, pressing F1 on a parameter entry opens the The GAMS Call and Command Line Parameters help page for detailed parameter information. In Solver Option Editor, pressing F1 on an option entry opens the solver page with a detailed option description.

From Code Editor, you can jump to documentation on Dollar Control Options or the index pages for Data Types and Definitions and Language Items, and from the parameter editor to GAMS parameter descriptions in The GAMS Call and Command Line Parameters :

• Press F1 on a Dollar Control Option within the editor to activate Dollar Control Options in the Help View, jumping to the corresponding description in Dollar Control Options chapter.

• Press F1 on a keyword in Data Types and Definitions or Language Items within the editor to activate the Index Page, listing related index entries for the keyword.

• Press F1 on a parameter entry within the extended parameter editor to open the help page with a detailed description of GAMS parameters in The GAMS Call and Command Line Parameters.

Help View when pressing F1 on parameter entry 'output' in the extended parameter editor

Help View when pressing F1 on parameter definition entry 'LimRow' in the extended parameter editor

Summary of Actions and Shortcuts

Debugger

GAMS Studio provides a debugger to detect errors. It is started by selecting Run with Debugger or Step start with Debugger from the GAMS menu or the Quick Access Toolbar. When pausing the process, GAMS Studio marks the line in the source code that will be processed next and opens a temporary GDX file in the Pin View containing the current data state. It is possible to have more than one active debug session.

To pause a debug process, you can:

• set a breakpoint
• use step
• use pause

Breakpoints can be set on any line in the source code, though not all lines are valid spots where the process can be paused. GAMS can pause on lines containing an operation. If a breakpoint is set to an invalid line (e.g., empty line, comment, or declaration), it will move to the next possible line or the last possible line in this file. The original line keeps a mark until the end of the debug session, showing its new line number.

Step can be triggered initially by selecting the menu GAMS > Step start with Debugger or by using the shortcut F11 (Meta - F11 on macOS). During the debug session, step can be triggered in the debug pane below the editor and also using the shortcut.

Pause can be triggered when a debug session is running and not paused. This is available in the debug pane below the editor.

Debug pane and breakpoints

During a debug session, the Debug Pane below the editor allows control over the flow:

• Continue - resumes execution until the next breakpoint or the end of the program is reached.
• Step - advances to the next possible pause line or the program's end.
• Pause - pauses the process at the next possible pause line.
• Stop - halts the execution of the process.
• The name of the active project appears to the right of these buttons.

Debugger Shortcuts

MIRO

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

GAMS MIRO Shortcuts

NEOS

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

• Email - The email address to use for submitting 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 - Option to create a GDX file even if the command line parameter is not set.
• Short priority - Execution may start earlier and provides intermediate log output, but is limited to a five-minute execution time.
• Long priority - Execution may start later and provides no intermediate log output, but is not limited in execution time.

Selections from the dialog are saved in the settings. To re-enable the Terms of Use after checking Don't show Terms of Use again, there is a checkbox in Settings > Misc.

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

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 updated locally 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, inc/trnsport.inc will stay unchanged, but inc/data.txt will be replaced by the version returned from the server.

GAMS Studio provides an EFI editor to select files. The context menu of a project in the Project Explorer allows creating or opening the EFI file matching the current runnable GAMS model. The editor enables file selection, with an option to mark selected files for local updates. Switching an open EFI editor to a text editor can be done by selecting Reopen as text after saving changes. All operations (check, uncheck, select all, and clear) apply to visible files, and directory checkboxes reflect the select state of all files (visible and hidden by filter).

On running, a dialog appears for login. If previously logged in and valid, this page is skipped. The login page offers several authorization methods:

• Login page
  • Engine URL - The URL to your GAMS Engine server
  • Login via - A list of available authorization methods:
    • Username / Password - Enter username and password
    • JWT Token - Use a token for login
    • SSO - Select an authorization provider
    • Additional predefined authorization providers (depending on the GAMS Engine installation)

When changing the URL, Studio attempts to directly access the server and request version information. If successful, it displays the GAMS Engine version on the right and the server’s GAMS version on the left. If the local GAMS version is newer, the command line parameter "previousWork=1" is added automatically unless "previousWork" is already specified. Dialog entries (excluding the password) are saved in settings, with further configuration available in the settings dialog.

To log in via an authorization provider, an SSO name can be entered, or one of the predefined providers can be selected. After clicking "Login", Studio contacts the provider and displays a code and a link where it can be entered to verify identity. For convenience, the "Copy and Visit" button copies the code to the clipboard and opens the link in the system’s default browser. The code can then be pasted (Ctrl + V) on the provider’s site.

Once logged in, the submit page allows configuration of the remote job:

• Submit page
  • "Namespace" - Specifies the namespace to be used on the server
  • "Instance" - Allows selection of the user instance or instance pool for GAMS Engine SaaS
    • With suficcient rights the size of an instance pool can be changed here
  • "Create a GDX file" - Enables GDX file creation even if not set by the command line parameter

To return to the login page, click the "Logout" button. The job is submitted to the GAMS Engine server by clicking "OK." To skip this prompt in future runs, select "OK, don't ask." During this Studio session, jobs will then submit directly without the dialog. To show it again, Ctrl-Click on the Engine icon or select "Settings > Remote > Reactivate Dialog."

Selecting a user instance and viewing space and time quotas is available only when connected to a GAMS Engine SaaS server. The instance list shows all instances and instance pools available for the user. For instance pools the pool size can be changed here if the user has sufficient rights. It may take some time until the pool size is scaled up. Please use reload to update the instance list and the current number of available instances in the pools.

When a job is submitted, GAMS Studio continuously displays output from the GAMS Engine server. Since this may take time, Studio can be closed during remote execution. If closed, a prompt will ask if the remote job should be kept or canceled. If "keep" is chosen, the job token is stored, and on restarting Studio, a dialog will allow resuming the job. On resume, pending messages are retrieved from the Engine server, and execution continues as if Studio was uninterrupted.

The results from the remotely executed model are saved to the working directory:

• LST and LXI files from the server are renamed to "<model>-server.lst" and "<model>-server.lxi" to avoid overwriting local files.
• All generated files will overwrite existing files of the same name (e.g., GDX, REF, and LOG files).
• Files listed in the EFI file ending with " <" will replace local versions.

The remote execution log has a distinct background color, configurable in settings (Default Text, 3rd color). Links in the remote log output are replaced with local equivalents.

Dialogs and Actions

GAMS Licensing

The GAMS Licensing dialog, accessible from the GAMS Studio Help menu, provides information about the current GAMS version, available solvers, licenses, and capabilities. The dialog offers multiple ways to install or update your GAMS license. Depending on what you received, follow one of the methods below.

Installing a License with an Access Code

If you received a 36-character access code (e.g., from the GAMS Academic Portal):

1. Open GAMS Studio and go to Help → GAMS Licensing.
2. In the GAMS Licensing dialog, find the "Access Code" field.
3. Paste or type the 36-character access code.
4. Click "Install License".
5. If the code is valid, GAMS Studio automatically retrieves and installs your license.

Installing a License from the Clipboard

If you received the license contents (six lines of text):

1. Copy the entire license text to your clipboard.
2. Open GAMS Studio and go to Help → GAMS Licensing.
3. If GAMS detects valid license text in the clipboard, a prompt appears:
   1. Click "Yes" to install the new license and display it.
   2. Click "No" to cancel and keep the existing license.

GAMS Studio also checks the clipboard at startup, prompting the same dialog if a license is found.

Installing a License from a File

If you have a license file (commonly named gamslice.txt):

1. Open GAMS Studio and go to Help → GAMS Licensing.
2. Click "Install License File".
3. Browse to and select your license file.
4. If the file is valid, the new license is installed; otherwise, the old license remains active.

Check for Update

Studio can check for updates at startup, which can be enabled in the settings. To manually check for updates for GAMS and GAMS Studio, go to Help > Check for Update or File > Settings > Update. This opens a dialog where you can enable/disable the startup check and configure the check interval.

Search and Replace

Pressing Ctrl - F opens the Search and Replace window, where selected text is pasted into the search field if available. Users can search specific files and perform text replacement operations. The search widget adapts based on the file type open in the editor to show available actions. For technical reasons, .gdx files cannot be searched, and replacing text in read-only files (e.g., .lst or .ref) is disabled. To ensure performance, searches stop upon reaching 50,000 results, indicated by "50000+" in the result count to show that more results may exist.

Search window in its default configuration

Located at the top, the search field accepts the search term and keeps a list of recent searches. The Clear button removes all search results and clears both search and replace fields. You can also press Esc in the Code Editor to clear results quickly.

Replace Options: Below the search field, these options are mostly disabled for read-only files (e.g., .lst). The replace field accepts replacement text. The Replace button highlights the next match on the first click and replaces it on the second, allowing review before replacing. Undo replacements with Ctrl + Z.

Replace All replaces all matches within the selected scope. A pop-up confirms the total replacements made. Users may also choose to initiate a search instead, showing all occurrences of the intended replacement on the results page.

Options to narrow down a search include:

• Whole Words - Finds only exact word matches (e.g., only finds "in" as a standalone word, not within "information").
• Case Sensitivity - Matches the case exactly.
• Use Regex - Enables advanced searches using Regular Expressions. More on Regular Expressions.

In the next row is the scope selector, which defines where the search or replace action applies, with five options available:

• Selection - Searches only within highlighted text. If no text is selected, a prompt appears. To clear the selection, press Esc or click Clear Selection. Note that starting a new search moves the selection to the currently highlighted text.
• This File - Limits the search to the currently active file (default setting).
• This Project - Searches all files in the current project.
• Open Tabs - Searches all files currently open in Studio (excluding GDX files).
• All Files - Searches all searchable files in the Project Explorer.
• Folder - Searches files within a specified folder, regardless of whether it’s open in Studio. When a result is opened, the file is added to the Project Explorer.

Navigation: Find Previous and Find Next buttons, labeled < and >, move between matches. Find All shows all occurrences in the selected scope, displaying results in a table in the output pane. Double-clicking a result or using the up and down arrow keys navigates to the file and highlights the match.

Additional elements appear based on the selected search scope:

Search window fully expanded

The first section is the "File Filter", shown for all modes except Selection and This File. This filter allows limiting the search to specific files (Include Filter) or excluding certain files (Exclude Filter). Wildcard syntax is supported for file names, with tooltips offering basic examples. Drop-down menus provide default GAMS-specific file types, and custom patterns can also be entered. Comma-separated lists of patterns are accepted.

The second section appears only when the "Folder" scope is selected and allows users to set the search path. This is a drop-down text field that maintains a history of recent entries, with a browse button beside it that opens the operating system’s default folder selection dialog. Tooltips provide additional information and shortcuts for many search window items.

Workflow Tips

• Edit a file, hit Ctrl - F to open the search widget. The search field focuses automatically, so you can type your search term directly. Press Enter as a shortcut for "Find Next", and press Enter again or F3 to step through matches. Press Shift - F3 to step backwards. To re-focus the search widget after edits, press Ctrl - F again.
• Enter a search term, then use Shift - Enter to trigger "Find All", which opens a list of results.
• Press Esc to close the search widget. Pressing Esc again clears all highlighted results.
• For projects with many files, use project or file prefixes and search filters to narrow the search scope.
• Regular Expressions offer powerful tools, including capture groups. A capture group saves part of your match using parentheses, referenced in the replacement string. For example, to locate files named FILENAME_DD_MM_YYYY, use the regular expression (\w+)_(\d\d)_(\d\d)_(\d\d\d\d). To convert these to YYYY-MM-DD_FILENAME, use $4-$3-$2_$1 as the replacement string. Each set of parentheses creates a capture group, numbered left to right, starting at 1.
  • Backreferences let you reference a capture group within the search term itself using \NUMBER. For example, (\w+)\s*'\1' finds symbols with their own name as descriptive text.

Model Library Explorer

The Model Library Explorer allows users to search various model libraries provided by GAMS and retrieve their models conveniently. It can be opened by selecting GAMS > Model Library Explorer from the menu, using the shortcut F6, or clicking the icon in the Quick Access Toolbar.

Each library is displayed in a separate tab. The search field in the upper part of the Model Library Explorer enables dynamic filtering across all model libraries simultaneously. As the search string is entered, results update in the tabs representing the different libraries. If no results are found in the currently selected tab, the first non-empty tab is automatically selected, reverting to the original tab once results are found there. Numbers in parentheses show the count of models found per library based on the current search input. More details about filtering can be found in the Filter Section.

Searching for trns in the Model Library Explorer

Alongside a brief description, some models offer a longer, more detailed description. Selecting a model and clicking on the Description button in the lower-right corner opens a dialog with additional information about the model. A model can be opened by clicking the Load button, double-clicking the model, or selecting it and pressing the Enter key.

User Libraries

In addition to the model libraries distributed by GAMS, user-defined model libraries can be accessed by providing a GLB file along with the model files in the library. The Model Library Explorer searches a specific location for these user-defined libraries. This location can be viewed or changed in the Settings dialog (File > Settings) under the Misc. tab. The Arrow button shows the current location, and the Folder button allows changing it. To add a new library, copy the required files into a subdirectory in this location. Refer to Creating a User Library for instructions on creating custom libraries. Restarting the Model Library Explorer is necessary for newly added libraries to appear.

Settings

The GAMS Studio settings dialog is accessible via File > Settings or the F7 hotkey. Users can adjust various Studio settings related to behavior and appearance. Settings are organized across five tabs.

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.
• Save modified files before running GAMS - When enabled, this option saves all modified files automatically before starting a GAMS run, ensuring that any unsaved changes are included in the execution without the need for manual saving.
• Open .lst file after running GAMS - Automatically brings the generated .lst file to the foreground after each GAMS run, making it easier to review results immediately.
• Jump to first compilation error - Activates an automatic focus on the first compilation error detected. When this option is enabled, both the editor and log view jump to the first error in the code, enhancing debugging efficiency. This also applies when the option Open .lst file after running GAMS is activated. Studio then opens the lst file and highlights the first error. When returning to the GAMS file, the view is also focused on 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....
• Store options for each ... - Allows to switch the binding of the options between Project/main file.
• The box Backup and Restore allows you to store and restore the Studio settings. Pressing the Export button opens a dialog to save your settings file under a freely chosen name, useful for backups or sharing settings across machines. Once saved, this file can be copied for future use. The button Import allows importing saved settings from a file. The settings apply immediately, and the dialog closes automatically.
• The box Projects allows to adjust the generation of a project file. For further details, refer to the project options documentation.

Editor & Log page

The "Editor & Log" tab contains many self-explanatory appearance options. Most notably font settings which are used for all monospace fonts like text editors and logs. The font size is also used 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 spaces 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".
• Syntax Highlight max width - stops highlighting lines with more than the given count of characters. Highlighting long lines is a very time-consuming process which can be controlled this way. It's likely that the highlighting will get out of sync for one or more lines. By placing syntax-relevant characters to the next (shorter) line this side effect can be reduced. To switch off highlighting set this value to 0. To always turn on highlighting set it to -1.
• Syntax Highlight max lines - stops highlighting lines after the specified line number. Highlighting many lines is a very time-consuming process which can be controlled this way. When syntax pairs like brackets or dollar command options (e.g., $onText / $offText) are split, this may result in a warning mark at the opening part of the pair. Additionally, the folding of a split pair can be broken. To switch off highlighting set this value to 0. To always highlight all lines set it to -1.
• Clear process log before GAMS execution - empties the log before running a GAMS 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

• Symbol View - controls whether the list view or the table view is used as the default view when a symbol is displayed for the first time.
• Attributes - allows control over which of the variable and equation attributes should be visible by default.
• Preferences - controls different default settings for symbol data:
  • Squeeze Defaults - affects variables and equations only and can be used to hide all columns that have the default value of the respective variable or equation type.
  • Squeeze Trailing Zeroes - allows turning on/off the truncation of trailing zeroes.
  • Format - controls the default format of numerical values. For detailed information see the corresponding section in the GDX Viewer documentation.
  • Precision - specifies the number of decimals or the number of significant digits depending on the chosen format. For detailed information see the corresponding section in the GDX Viewer documentation.
• Decimal Separator in Copied Data - controls the decimal separator used when copying data from a GDX symbol. Note that this setting affects only the copied data, not the displayed data itself. The following options are available:
  • Use Studio default - by default, . is used as the decimal separator in copied data.
  • Follow system language - uses the decimal separator from the system language settings.
  • Use custom character - allows specifying a custom character.

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 your operating system, this can be selected by the system and/or manually. You can set Studio to use a darker color palette if you prefer to work in the dark and avoid bright windows.

Studio using a dark theme

The fixed themes can't be modified. Modifying a value implicitly creates a copy of the theme with the changed value applied. After copying a theme, the new user theme can be adapted to your needs. Additionally, these user themes can be exported and imported as files.

Color Settings

The colors are listed in two sections:

• The Syntax colors page - defines a text color, background color, and the attributes bold and italic. The background color can be reset to the default editor background by right-clicking.
• The Editor colors page - allows changes to the colors of text, background, and second background (for blinking). The very first entry on this page, the Default Text, serves as the base for the syntax colors.

Remote page

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

• The MIRO section - allows you to define the location of your local MIRO installation.
• The checkbox "Always agree to NEOS" - allows you to hide the Terms Of Use in the NEOS submission dialog.
• The GAMS Engine section - allows you to store a login token to stay logged in when restarting Studio. The next line allows you to define how long the login remains valid.
• If the dialog has been hidden by clicking OK, don't ask, the button Reactivate dialog enables it again.

Misc page

The "Misc" tab contains some less common settings.

• GAMS source file extensions - allows you to add custom file extensions that Studio recognizes as runnable GAMS files. Files with these extensions can be executed, set as the main file, and use the GAMS Syntax Highlighter. The field accepts a comma-separated list of file extensions.
• Auto-reload extensions - allows specific extensions to be reloaded automatically when changed externally. If changes were made internally as well, a dialog asks how to proceed. This field also accepts a comma-separated list of file extensions.
• Clean-up workspace directory on startup - clears workspace files based on a specified file pattern. You can also clean up the workspace immediately by pressing the Clean-up now button.
• User model library - displays the folder used to find user-generated model libraries (see User Libraries). You can change this folder to a custom location. Up to 10 locations are stored in history. Use the trash bin button to remove the current entry from history. The arrow button opens the file browser in the current folder.
• Reset History - clears the list of recently used projects and files on the Welcome Page.
• Reset Window - resets Studio’s appearance to default settings if issues arise.
• The final group contains options for the Solver Option Editor.

Recover files

While editing files, GAMS Studio creates a backup of each changed file’s current state every minute. If Studio closes unexpectedly, these files remain in the working directory. Upon restarting Studio, a prompt will ask if the latest state of the files should be recovered. Recovery loads the original files into editors and updates each to the latest content, marking these files with an asterisk (*) as edited. To revert to the previously saved version, use the undo function. Additionally, a backup file with the extension .bk stores a copy of the original content, which will be overwritten during recovery.

Delete scratch directories

GAMS creates temporary folders for running processes in your working directory, which are usually removed upon run completion. However, if a run is interrupted, these folders may remain. To clean up the user workspace, Studio provides an action under GAMS > Delete scratch directories to remove unwanted, auto-generated directories. A confirmation popup will appear, showing the path of the directory to be cleaned. Selecting "Yes" deletes all directories starting with 225 followed by one or two letters within the default workspace. This action is also triggered when GAMS exhausts possible scratch directory names, but not without confirmation. Ensure no GAMS jobs are running before using this feature.

Full Screen & Distraction Free Mode

To optimize screen space, especially on smaller devices, Studio offers Full Screen and Distraction Free modes.

• Full Screen mode is activated by pressing Alt-Enter on Windows/Linux or Command-Control-F on macOS, expanding Studio to cover the entire screen. Press the same shortcut to exit.
• Distraction Free mode, activated by Ctrl-Alt-Enter on Windows/Linux or Cmd-Option-Enter on macOS, hides all Studio widgets and enlarges the central widget to the studio window size. Pressing the shortcut again restores the original view. Running a GAMS model in Distraction Free mode automatically opens the log.

GDX Diff

The GDX Diff dialog provides a graphical interface for the command-line tool GDXDIFF. It compares the data of two GDX files and outputs the differences to a third GDX file. Access this dialog via Tools > GDX Diff in the menu.

GDX Diff dialog

The dialog consists of two parts. The upper section specifies the two GDX files for comparison, while the output GDX difference file is auto-generated unless manually modified. By default, the difference file is named diff.gdx and saved in the same directory as the first input GDX file. The output updates automatically if the first input is changed to an existing file. If the dialog is opened without a valid first input, the most recently used directory is suggested for the difference file.

The lower part of the dialog provides various options to control comparison behavior:

• Eps: Specifies an absolute difference threshold. If the difference between two values exceeds this threshold, it will be reported. Default is 0.0.
• RelEps: Sets a relative difference threshold. A difference is reported if this threshold is exceeded. Default is 0.0.
• Field To Compare: Specifies the subfield used to determine differences in a variable or equation. Options include:
  • All: All fields
  • L: Level
  • M: Marginal
  • Lo: Lower Bound
  • Up: Upper Bound
  • Prior
  • Scale
• Ignore Set Text: Ignores explanatory text of set elements.
• Diff Only: Outputs differences in variables and equations as parameters, adding an index to denote the field name. Only differing fields are recorded. Cannot be combined with Field Only.
• Field Only: When used with Field To Compare, outputs variables and equations as parameters for the chosen subfield. This cannot be used with Diff Only and requires Field To Compare to be set to a specific field (not All).
• Compare Defaults: Determines whether default values, like 0 for parameters, are reported as differences when found in one file but missing in the other.
• Compare Domains: Reports differences if domains differ for the same symbol.
• Ignore Order: Ignores UEL order in input files, which can reduce the output file size.

When the OK button is clicked, the input validation is performed, and the two input files are compared. If the specified difference file is already open in a GDX Viewer, the corresponding tab stays open while the underlying GDX file detaches. Once the file is updated, the GDX Viewer reinitializes. If the GDX file was not open before, it opens in a new tab.

The Cancel button closes the dialog and stops any ongoing process. For lengthy comparisons of large files, the dialog needs to remain open.

The Reset button resets the dialog to its default state, which also re-enables the automatic population of the difference file path if it had been disabled by a manual change.

Additionally, the GDX Diff dialog integrates with the context menu in the Project Explorer. When one or two GDX files are selected, the context menu shows an option to open the GDX Diff dialog with the file(s). If one file is selected, it fills the corresponding empty input field. If both fields are filled, the first input file path is overwritten. For two selected files, both input fields are populated.

Terminal

GAMS Studio can open a native terminal through Tools > Terminal in the main menu or by pressing CTRL - T. A terminal can also be accessed by right-clicking any entry in the "Project Explorer" and selecting Open terminal. The terminal defaults to the workspace of the current project, except on macOS, where it always opens in the user’s home directory.

Command Line Options

GAMS Studio can be started with additional command line options to change behavior or trigger specific functionalities at startup. 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 : Starts Studio with default settings without saving them.
• --reset-settings : Resets all settings to default, loads Studio with these settings, and saves them.
• --reset-view : Resets Studio visually without altering settings; helpful if widgets are misplaced or Studio starts on a disconnected monitor.
• --gams-dir path_to_gams : Specifies a GAMS installation path for Studio.
• --log : Creates a Studio system log at $HOME/Documents/GAMS/Studio/studio.log.
• --no-log : Disables the Studio system log.
• --log-file file : Specifies a custom file for the Studio system log.
• --skip-check-for-update : Disables all online update checks.
• --dump-c4u-data : Dumps the C4U response and additional data if available.

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

Studio Dialogs

Studio Recovery

Zoom Editor and View

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

• Text: contains all editors and views that show flowing text in monospace fonts and appear as Central Widget, like the Code Editor and the Listing Viewer.
• Log: contains the Process Logs and the System Log.
• Table: contains all editors and viewers that show table and tree elements in proportional fonts as a Central Widget, like the GDX Viewer and the Solver Option Editor. It also includes the Command Line Option Editor.

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 additional system requirements, which vary depending on the platform used.

Linux

The Linux version of GAMS Studio is distributed as an AppImage and requires glibc 2.35, glibcxx 3.4.30, as well as FUSE to be installed.

The GAMS Studio AppImage has been tested and verified to work on the following Linux distributions (all currently maintained). Note that Linux distributions are frequently updated, which may affect the AppImage’s behavior. Please check the Studio issue page if you encounter any issues.

• Debian 12
• Fedora 40/41
• openSUSE Tumbleweed
• Ubuntu 22.04/24.04 LTS
• Manjaro

Other distributions might work as well, though they were not tested. If you experience problems with a specific Linux distribution, please let us know.

If the Studio AppImage does not run, you may need to extract the AppImage using the command:

$ ./studio.AppImage --appimage-extract

and then start Studio from the extracted directory.

Some Linux distributions use Wayland, which can cause issues. In such cases, try running Studio with the following command:

$ QT_QPA_PLATFORM=xcb ./GAMS_Studio-1.12.1-x86_64.AppImage

macOS

macOS has some specific platform requirements for locating GAMS. The following steps are used to link GAMS Studio to GAMS:

• GAMS Studio will attempt to locate GAMS in /Applications/** and /Users/username/Applications/** if it is part of a GAMS folder. GAMS Studio needs to be copied via Finder to its target location, as occurs with the GAMS installer or when GAMS Studio is copied from the DMG file.
• If GAMS Studio does not find GAMS as described above, it will search /Applications/** for a valid GAMS installation, i.e., one with the minimum required GAMS version or higher.
• GAMS Studio will check $PATH for GAMS, although this rarely works on macOS.
• If needed, the path to GAMS can be set explicitly by launching 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 vc_redist.x64.exe, which can be found in the GAMS installation folder at [GAMS system]\studio.

GAMS Studio supports the following Windows platforms:

• Windows 10 (1809 or later)
• Windows 11 (all)

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. Therefore, it remains available as an alternative to GAMS Studio, especially since it has features that are not available in GAMS Studio yet. However, it also lacks some features that are available in GAMS Studio. The following table gives a compact overview of most of the differences.

GAMSIDE Projects vs. GAMS Studio Projects

With the GAMSIDE, you always start by creating a "Project". This mainly defines a directory used to execute the models added to it (i.e., it implicitly defined the workDir when starting GAMS). When starting the IDE for the first time, you are asked to create a new project. For example, in directory a. After adding models a/a.gms and b/b.gms, both are executed in the project directory a, meaning that data sources are expected in a (or relative to it), and output files are also generated in a, 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 by default. Studio projects also have a "working directory", initially set automatically to the location of the file that was opened to create the new project. If a model is executed, it runs in this working directory. So, if you open a/a.gms and b/b.gms, Studio will create two projects: a and b. When a runs, input files are expected in directory a, and output files get generated in a. When b runs, input files are expected in directory b, and output files get generated in b. If models are structured to rely on the "GAMSIDE way" of executing, you can adjust the working directory in the project options. Alternatively, you can start with an empty project and define the working directory explicitly, as in GAMSIDE, using the New Project option from the File menu.

It is also possible to have multiple files in one project. For example, b.gms can be added to project a by drag and drop in the Project Explorer. Here, the concept of the "main file" of projects becomes relevant: While GAMSIDE always executed the currently active .gms file, GAMS Studio executes the main file of the currently active project. So, if you are viewing a.lst and press F9, a.gms will be rerun (GAMSIDE would not run anything in this case). After adding b.gms to project a, pressing F9 while viewing b.gms would still execute a.gms. If you want to execute b.gms, set it as the main file of the project by right-clicking b.gms in the Project Explorer and selecting "Set as main file." The green arrow indicating the main file in the Project Explorer will switch from a.gms to b.gms. Remember that projects do not inherently know a particular working directory; pressing F9 after changing the main file will execute b.gms in folder b.

Switching the main file