Tools Manuals

A large number of tools are included in GAMS distribution. Below are a functional categorization of all tools, an alphabetically sorted list of all tools, and a brief description of each tool with their Supported Platforms.

Note
Traditionally, GAMS tools consisted of a collection of executables with a file (mostly GDX) interface. These tool executables will be replaced over time by GAMS Connect agents and a collection of tools in a new GAMS tools library. For some time both ways will be supported but the executable tools will go away, so when in doubt what tool to pick, select Connect or a GAMS tool.

Tools Category

All tools included in GAMS distribution are categorized as

GAMS Integrated Development Environments

There are two integrated model development environments including a general text editor with the ability to launch and monitor the compilation and execution of GAMS models: GAMS Studio and the GAMS IDE (deprecated).

GAMS Tools Library

In the GAMS Tools Library, various tools are collected to provide an easy access to complex task. The tools in this library complement facilities of GAMS Connect and tools available as executables (e.g. GDXXRW). Currently the library includes the following tool categories:

Algorithmic tools (alg)

Provide algorithmic functionality like sorting data: Rank.

Data tools (data)

Provide access to external data sources: ExcelDump.

GDX Service (gdxservice)

Provide functionality for GDX file manipulation: GDXEncoding and GDXRename.

Linear Algebra (linalg)

Provide functionality for computational linear algebra: Cholesky, Eigenvalue, Eigenvector, Invert and Ordinary Least Squares (OLS).

Windows Only Tools (win32)

Provide functionality specific to the Windows operating system: ShellExecute, MSAppAvail, ExcelTalk and ExcelMerge.


There are a couple of things to note:

  • A tool can be invoked directly in the model code during compile ($callTool) or execution time (executeTool) or by using the standalone command line utility gamstool.
  • When invoked from the model code the exchange of GAMS symbols is done in memory. If a tool is called from the command line, this is not possible and hence for some tools that deal with GAMS symbols it is necessary to specify GDX input and/or output files. Even for use inside GAMS models the GDX file interface can be useful (e.g. for debugging) hence the specification of GDX input/output files is optional in that case.
  • Similar to the $call (compile time) and execute (execution time) commands, a GAMS tool returns a shell code that can be checked via errorLevel. In case one expects the tools to perform without error, it is recommended to add the suffix .checkErrorLevel. This will stop the entire execution of GAMS if an error occurs while executing the tool.
  • If a tool of the GAMS Tool library is used at execution time to populate a GAMS symbol with data for the first time, the compiler does not know the outcome of the tool. As a result, the compiler does not have information about any symbols that might be filled with data, and therefore cannot reliably define these symbols at compile time. Code that later on references a corresponding symbol would result in a compilation error 141: Symbol declared but no values have been assigned. In order to be able to load symbols implicitly during execution time, the dollar control option $onImplicitAssign needs to be set. There are other methods to convince the compiler that the symbols has been defined, e.g. execute_load$0 symName; which is otherwise a no-op.
  • The compile time variant of a tool ($callTool [...]) is ignored while $onExternalInput is active and IDCGDXInput is set.
  • Tool arguments: All tools follow the same logic to process arguments. The list of arguments starts with a number of positional arguments followed by named argument [-]name=val.
  • For each tool there is a short and a long help available. If a tool is called without arguments or with -h , a short description is displayed, e.g. gamstool linalg.eigenvector -h. With the argument --help a detailed help text appears: gamstool linalg.eigenvector --help. If only the category and not a contained tool is requested, the help text of all included tools will be displayed: gamstool linalg or gamstool linalg --help.

For more information please refer to the individual tool manuals.

Command Line Utility gamstool

The GAMS system directory contains the utility gamstool to run GAMS Tool instructions directly from the command line. On Windows the utility has the callable extension .cmd which does not need to part of the command because the shell automatically checks for the extension. This script wraps the Python script tooldriver.py by calling the Python interpreter that ships with GAMS. gamstool is called like this:

gamstool [toolCategory.]toolName positionalArguments [namedArguments]

Data Exchange

A collection of tools that provide functionality to exchange data between GAMS and other data sources. This category contains tools for popular data sources and high-level programming environment and like databases (GDX2ACCESS, GDX2SQLITE, MDB2GMS, SQL2GMS), Matlab (GDXMRW), and R (GDXRRW). There are also tools for specialized systems like VEDA (GDX2VEDA).

Excel

A collection of tools that provide functionality to exchange data between GAMS and Excel. The tools in this category are GDX2XLS, GDXXRW, XLS2GMS, and ExcelDump. Many of the tools described here use the GAMS Data eXchange facility GAMS Data eXchange (GDX). Note that the executable tools in this category will be or have been replaced over time by GAMS GAMS Connect agents and tools from the GAMS Tools Library.

GDX Service

A collection of tools that operate directly on GAMS Data eXchange (GDX) containers to e.g. compare (GDXDIFF), copy (GDXCOPY), merge (GDXMERGE), label rename (GDXRename) and encoding (GDXEncoding).

Data Transformation

A collection of tools that perform very specific tasks that are awkward or inefficient to implement in GAMS directly. The tools in this category are MessageReceiverWindow, Rank, SCENRED, SCENRED2 and all tools from Linear Algebra (linalg).

Other Tools

A collection of more exotic tools that can become handy in some some special circumstances. The tools in this category are ASK, ENDECRYPT, FINDTHISGAMS, GAMS Posix Utilities, MODEL2TEX, and all tools from Windows Only Tools (win32). Most notably, the collection contains the tool MODEL2TEX to document the model algebra in LaTeX format.

List of Tools

The following table gives an alphabetically sorted list of all available tools.

Tool Description
ASK The utility can be used to get input from an user interactively.
[LINALG.]CHOLESKY Calculates the cholesky decomposition of a symmetric positive definite matrix.
CSV2GDX Reads a CSV file (comma separated values) and writes to a GDX file.
[LINALG.]EIGENVALUE Calculates the Eigenvalues of a symmetric positive definite matrix.
[LINALG.]EIGENVECTOR Calculates the Eigenvalues and Eigenvectors of a symmetric positive definite matrix.
ENDECRYPT A tool to encrypt and decrypt text files.
[DATA.]EXCELDUMP Writes all worksheets of an Excel workbook to GAMS symbols.
[WIN32.]EXCELMERGE Merges the sheets of the source Excel workbook into the destination workbook.
[WIN32.]EXCELTALK Performs command on an Excel workbook specified by filename.
FINDTHISGAMS Windows command line tool for modifying GAMS specific registry entries created by the GAMS installer.
GAMS IDE Classic Integrated Development Environment.
GAMS STUDIO Integrated Development Environment.
GDX2ACCESS Converts GDX data to MS Access tables.
GDX2SQLITE Dumps the complete contents of a GDX file into a SQLite2 database. From Amsterdam Optimization Modeling Group.
GDX2VEDA Translates a GDX file into the VEDA format.
GDX2XLS Converts GDX data into a MS Excel spreadsheet.
GDXCOPY Converts a GDX file into different GDX formats.
GDXDIFF Compares the data of symbols with the same name, type and dimension in two GDX files and writes the differences to a third GDX file.
GDXDUMP Writes scalars, sets and parameters (tables) to standard output formatted as a GAMS program with data statements.
[GDXSERVICE.]GDXENCODING Label encoding conversion.
GDXMERGE Combines multiple GDX files into one file. Symbols with the same name, dimension and type are combined into a single symbol of a higher dimension. The added dimension has the file name of the combined file as its unique element.
GDXMRW A suite of utilities to import/export data between GAMS and MATLAB and to call GAMS models from MATLAB and get results back into MATLAB.
[GDXSERVICE.]GDXRENAME Renames labels in a GDX file.
GDXRRW An interface between GAMS and R. It includes functions to transfer data between GDX and R and a function to call GAMS from R.
GDXVIEWER Views and converts data contained in GDX files.
GDXXRW Preferred utility to read and write MS Excel spreadsheet data.
GMSUNZIP Decompression tool unzip with Debian patches, but renamed to "gmsunzip".
GMSZIP Compression and archiving tool zip with Debian patches, but renamed to "gmszip".
IDECMDS Sends commands to the GAMSIDE.
[LINALG.]INVERT Calculates the inverse of a square matrix A.
MDB2GMS Converts data from an MS Access database into a GAMS readable format.
MESSAGE RECEIVER WINDOW A graphical tool that receives and displays Windows messages.
MODEL2TEX Translates a GAMS model into LaTeX
MPS2GMS Translates an MPS or LP file into an equivalent short generic GAMS program using a GDX file to store data.
[WIN32.]MSAPPAVAIL Checks if a MS Office Application is available.
[LINALG.]OLS Ordinary Least Squares: Estimates the unknown parameters in a linear regression model.
POSIX A collection of POSIX utilities which are usually available for Windows and the different Unix systems and therefore help to write platform independent scripts.
[ALG.]RANK Ranks one-dimensional numeric data.
SCENRED A tool for the reduction of scenarios that model random data processes of a stochastic program. From Humboldt-University Berlin.
SCENRED2 Scenred2 is a fundamental update of Scenred and offers a scenario tree construction algorithm. From Humboldt-University Berlin.
[WIN32.]SHELLEXECUTE Spawns an external program.
SQL2GMS Converts data from an SQL database into a GAMS readable format.
XLS2GMS Converts spreadsheet data from a MS Excel spreadsheet into a GAMS readable format.
XLSDUMP Writes all worksheets of a MS Excel workbook to a GDX file. Unlike gdxxrw, the program does not require that Excel is installed.

Supported Platforms

x86 64bit
MS Windows
x86 64bit
Linux
x86 64bit
macOS
arm 64bit
macOS
ASK ✔ *
[LINALG.]CHOLESKY
CSV2GDX
[LINALG.]EIGENVALUE
[LINALG.]EIGENVECTOR
ENDECRYPT
[DATA.]EXCELDUMP
[WIN32.]EXCELMERGE
[WIN32.]EXCELTALK
FINDTHISGAMS
GAMSIDE ✔ *
GAMSSTUDIO
GDX2ACCESS ✔ *
GDX2SQLITE
GDX2VEDA
GDX2XLS ✔ *
GDXCOPY
GDXDIFF
GDXDUMP
[GDXSERVICE.]GDXENCODING
GDXMERGE
GDXMRW
[GDXSERVICE.]GDXRENAME
GDXRRW
GDXVIEWER ✔ *
GDXXRW ✔ *
GMSUNZIP
GMSZIP
IDECMDS ✔ *
[LINALG.]INVERT
MDB2GMS ✔ *
MSGRWIN
MODEL2TEX
MPS2GMS
[WIN32.]MSAPPAVAIL
[LINALG.]OLS
POSIX** ✔ *
[ALG.]RANK
SCENRED
SCENRED2
[WIN32.]SHELLEXECUTE
SQL2GMS ✔ *
XLS2GMS ✔ *
XLSDUMP ✔ *

* Note that the tool is 32 bit but runs fine on 64 bit Windows.
** awk, cat, cksum, cmp, comm, cp, cut, diff, expr, fold, gdate, grep, gsort, gunzip, gzip, head, join, make, mkdir, mv, od, paste, printf, rm, sed, sleep, tail, tar, tee, test, touch, tr, uniq, wc, xargs

LibInclude Tools Library

In the LibInclude Tools Library, various tools are collected to provide an easy access to complex task. The tools are located in the inclib folder in the GAMS system directory and can be invoked using the $libInclude command.

Note
The default library include directory inclib can be changed with the libIncDir command line parameter. Hence, make sure you point to the correct directory when using $libInclude.

Usage:

$libInclude <library_file> [<tool_name>] [<option(s)>]

Currently the library includes the following tools:

Libinclude file Description
moo Provides methods for multi-objective optimization in GAMS.
pyEmbMI Provide access to a model instance that can be modified and resolved without regenerating the model over and over.
rank Routine for ranking one-dimensional numeric data. Unlike the GAMS tool alg.rank, rank can handle percentile levels.