Table of Contents
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, CSVRead and SqliteWrite.
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
orgamstool 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, SqliteWrite, MDB2GMS, SQL2GMS). There are also tools for specialized systems like SqliteWrite, MDB2GMS, and SQL2GMS. 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, 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 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).
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. scenred ScenRed is a tool for the reduction of scenarios and scenario tree construction modeling the random data processes of a stochastic program. From Humboldt-University Berlin.
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, MessageReceiverWindow, 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 tables give alphabetically sorted lists of all available tools. The tables are organized into executable tools, GAMS tools and libInclude tools.
Executable Tool | Description |
---|---|
ASK | The utility can be used to get input from an user interactively. |
CSV2GDX | Reads a CSV file (comma separated values) and writes to a GDX file. |
ENDECRYPT | A tool to encrypt and decrypt text files. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
GAMS Tool | Description |
---|---|
[ALG.]RANK | Ranks one-dimensional numeric data. |
[DATA.]EXCELDUMP | Writes all worksheets of an Excel workbook to GAMS symbols. |
[DATA.]CSVREAD | Writes data from a CSV file to a GAMS symbol. |
[DATA.]SQLITEWRITE | Exports GAMS symbols to a SQLite database file. |
[GDXSERVICE.]GDXENCODING | Label encoding conversion. |
[GDXSERVICE.]GDXRENAME | Renames labels in a GDX file. |
[LINALG.]CHOLESKY | Calculates the cholesky decomposition of a symmetric positive definite matrix. |
[LINALG.]EIGENVALUE | Calculates the Eigenvalues of a symmetric positive definite matrix. |
[LINALG.]EIGENVECTOR | Calculates the Eigenvalues and Eigenvectors of a symmetric positive definite matrix. |
[LINALG.]INVERT | Calculates the inverse of a square matrix A. |
[LINALG.]OLS | Ordinary Least Squares: Estimates the unknown parameters in a linear regression model. |
[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. |
[WIN32.]MSAPPAVAIL | Checks if a MS Office Application is available. |
[WIN32.]SHELLEXECUTE | Spawns an external program. |
libInclude Tool | Description |
---|---|
moo | Provides methods for multi-objective optimization in GAMS. |
pyEmbMI | Provides 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. |
scenred | Tool for the reduction of scenarios and scenario tree construction modeling the random data processes of a stochastic program. From Humboldt-University Berlin. |
Supported Platforms
x86 64bit MS Windows | x86 64bit Linux | x86 64bit macOS | arm 64bit macOS | |
---|---|---|---|---|
[ALG.]RANK | ✔ | ✔ | ✔ | ✔ |
ASK | ✔ * | |||
CSV2GDX | ✔ | ✔ | ✔ | ✔ |
[DATA.]EXCELDUMP | ✔ | ✔ | ✔ | ✔ |
[DATA.]CSVREAD | ✔ | ✔ | ✔ | ✔ |
[DATA.]SQLITEWRITE | ✔ | ✔ | ✔ | ✔ |
ENDECRYPT | ✔ | ✔ | ✔ | ✔ |
FINDTHISGAMS | ✔ | |||
GAMSIDE | ✔ * | |||
GAMSSTUDIO | ✔ | ✔ | ✔ | ✔ |
GDX2ACCESS | ✔ * | |||
GDX2VEDA | ✔ | ✔ | ✔ | ✔ |
GDX2XLS | ✔ * | |||
GDXCOPY | ✔ | ✔ | ✔ | ✔ |
GDXDIFF | ✔ | ✔ | ✔ | ✔ |
GDXDUMP | ✔ | ✔ | ✔ | ✔ |
GDXMERGE | ✔ | ✔ | ✔ | ✔ |
[GDXSERVICE.]GDXENCODING | ✔ | ✔ | ✔ | ✔ |
[GDXSERVICE.]GDXRENAME | ✔ | ✔ | ✔ | ✔ |
GDXVIEWER | ✔ * | |||
GDXXRW | ✔ * | |||
GMSUNZIP | ✔ | ✔ | ✔ | ✔ |
GMSZIP | ✔ | ✔ | ✔ | ✔ |
IDECMDS | ✔ * | |||
[LINALG.]CHOLESKY | ✔ | ✔ | ✔ | ✔ |
[LINALG.]EIGENVALUE | ✔ | ✔ | ✔ | ✔ |
[LINALG.]EIGENVECTOR | ✔ | ✔ | ✔ | ✔ |
[LINALG.]INVERT | ✔ | ✔ | ✔ | ✔ |
[LINALG.]OLS | ✔ | ✔ | ✔ | ✔ |
MDB2GMS | ✔ * | |||
moo | ✔ | ✔ | ✔ | ✔ |
MSGRWIN | ✔ | |||
MODEL2TEX | ✔ | ✔ | ✔ | ✔ |
MPS2GMS | ✔ | ✔ | ✔ | ✔ |
POSIX** | ✔ * | |||
pyEmbMI | ✔ | ✔ | ✔ | ✔ |
rank | ✔ | ✔ | ✔ | ✔ |
ScenRed | ✔ | ✔ | ✔ | ✔ |
SQL2GMS | ✔ * | |||
[WIN32.]EXCELMERGE | ✔ | |||
[WIN32.]EXCELTALK | ✔ | |||
[WIN32.]MSAPPAVAIL | ✔ | |||
[WIN32.]SHELLEXECUTE | ✔ | |||
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