The Application Programing Interfaces (APIs) to GAMS allow the seamless integration of GAMS into an application. The APIs by provides appropriate classes for the interaction with GAMS. The GAMSDatabase class for in-memory representation of data can be used for convenient exchange of input data and model results. Models written in GAMS can be run with the GAMSJob class and by using the GAMSModelInstance class a sequence of closely related model instances can be solved in the most efficient way. Note that the GAMS object-oriented API was not designed to offer modeling capability. The model needs to be formulated in GAMS and passed on to the GAMSJob class.

Five versions of object-oriented GAMS APIs :

• .NET API with Target Framework Version 4.6.2,
• C++ API works with C++17 or later,
• Java API works with Java SE 11 or later. The non-mainstream version of Java API that works with Java SE 8 is still available with maintenance support, but the functionality that is newer than GAMS 43 will be not available in this version. See Java Release Notes and Java Tutorial for more details.
• Python API works with Python 3.8 to 3.12.
• Matlab API works with Matlab 2017b (or later) and Octave 5.2 (or later).

In addition to the object-oriented GAMS APIs, there exist an R API and expert-level (or low-level) GAMS APIs in which its usage requires advanced knowledge of GAMS component libraries.

See Executing GAMS from other Environments if you want to execute GAMS directly from an application without using APIs.

Object-oriented APIs

The Reference Manuals give an overview of the features provides by GAMS APIs, release notes, and a list of all classes with descriptions. The Tutorials provide an overview of the basic functionality of the GAMS APIs and the Examples provides a list of examples available with GAMS distribution with detailed description. See also Release Notes and Supported Platforms.

Reference Manuals

The GAMS APIs reference manuals give an overview of the features provides by GAMS APIs, release notes, and a list of all classes with descriptions.

• .NET API  
• C++ API
• Java API
• Python API
• Matlab API

Tutorials

GAMS API Tutorials provide an overview of basic functionalities of GAMS APIs and allow a user to get started to work with the GAMS API.

• .NET API Tutorial
• C++ API Tutorial
• Java API Tutorial
• Python API Tutorial
• Matlab API Tutorial

Examples

There are several examples avaiable for the different programming languages: .NET, C++, Java, and Python. Below we give a description of each example together with its link to the detailed page in different languages.

These examples are available with the GAMS distribution in [Path/To/GAMS]/apifiles/ directory. In that directory, the file readme.txt describes how to build and execute these examples. A GAMS script to compile and execute each example is available in [Path/To/GAMS]/apilib_ml/ directory with a table of contents.

Alias

The Object-oriented API does not have the concept of a GAMS alias. An alias cannot be entered into a GAMSDatabase by API methods. Nevertheless, if the GAMSDatabase is loaded from a GDX container (e.g. the GAMSJob.OutDB), the database can contain aliases. Such an alias can be retrieved as a GAMSSet and consists of the elements of the aliased set. The method to find out if a GAMSSet in a GAMSDatabase is indeed an alias is to check if the symbol name is different from the lookup name (i.e. bool isAlias = db.GetSet("ii").Name != "ii"). This example model goes through the logic of how aliases are handled in the Object-oriented API.

See Alias example in [.NET, Java, Python].

Benders2Stage

This example implements a simple Benders decomposition method for a stochastic linear program. The underlying model implements a simple distribution system with stochastic demand data. This example actually consists of two programs: A sequential and a parallel implementation. In the sequential version, the master and the subproblems are implemented with the GAMSModelInstance object which allows resolving the model with modified input without regenerating the model. A GAMSModelInstance has a fixed model rim, so this provides a challenge for Benders master problem because every iteration adds new constraints (the Benders cuts) to the master. We get around this limitation of GAMSModelInstance by initializing the GAMSModelInstance of the master with a fixed number of empty (i.e. non-binding) placeholders constraints and during the run of the algorithm turn these placeholder constraints into valid Benders cuts. The parallel version extends the Benders2Stage example by solving the independent subproblems in parallel. For that we need to instantiate a separate GAMSModelInstance for each parallel worker. We use the efficient GAMSModelInstance. CopyInstance method to accomplish this in the most effective way. The number of demand scenarios can be larger than the number of parallel workers. The distribution of work is handles through a work queue. The parallel execution of the subproblems is done in separate threads (the MT in the name of the example stands for Multi Threading), so there is very little overhead from disk activity.

See Bender2Stage example in [.NET, Java, Python] and Bender2StageMT example in [.NET, Java, Python].

Clad

This example demonstrates how to implement a complex termination criterion for a difficult MIP using GAMS/Cplex. We would like to achieve a globally optimal solution (relative gap 0%) but if solution time becomes larger than n1 seconds, we can compromise for a 10% gap, and if this is not achieved after n2 seconds, we compromise for a 20% gap, and again if this is not accomplished in n3 seconds we take whatever the solver has done so far and terminate the solve. This is implemented by executing GAMSJob.run in an independent thread and providing new tolerances for the relative gap in the main thread by supplying new GAMS/Cplex option files and triggers the processing of the new tolerance option by GAMS/Cplex through the GAMSJob.Interrupt method.

See Clad example in [.NET, Java, Python].

CutStock

This example contains two programs that implement a column generation approach to solve the cutting stock problem. In the program SimpleCutsock, the column generation scheme has been implemented in GAMS. Moreover the GAMS model with the input and output data has been wrapped in a class that separates all interaction with GAMS from the driving application. In the second example, the column generation approach has been entirely implemented in the program using GAMSJob for the master and GAMSModelInstance for the pricing problem. GAMS is used to build the master and pricing problems. The logic of the column generation method is in the application program.

See Cutstock Model example in [.NET, Java, Python], SimpleCustock example in [.NET, Java, Python], and Custock example in [.NET, Java, Python].

Domain Checking

Enforcing referential integrity also known in the GAMS lingo as domain checking is an essential and important part of GAMS. The Object-oriented API does a delayed domain checking of symbols. So you can add records to a domain controlled parameter (e.g. p(i)) even though the GAMSSet i does not contain the label (yet). The user can trigger an explicit check of the referential integrity by calling the GAMSDatabase.CheckDomains (or GAMSSymbol.CheckDomains). The Object-oriented API provides methods to access the records that violate the referential integrity (see GAMSDatabaseDomainViolation for details). Domain checking is implicitly done when the GAMSDatabase is exported to a GDX file via the GAMSDatabase.Export method or for databases provided in the GAMSJob.Run method. The implicit domain check can be suppressed (and left to GAMS when importing data) via the GAMSDatabase.SuppressAutoDomainChecking property. This example demonstrates how to trigger domain checking and how to access the records that violate the referential integrity.

See Domain checking example in [.NET, C++, Java, Python].

GUI Examples

Modern development frameworks like Microsoft's Visual Studio, Python, and Java allow to quickly build graphical user interfaces. Every example consists of a simple GUI that provides data entry, executing of a GAMSJob and graphically represents the results of a GAMS model.

• CutstockGUI: This example allows to either load data from a database or to enter data manually. A cutting stock problem is solved by using both the GAMSJob and the GAMSModelInstance class in order to implement a decomposition approach. See also CutStock Example. See this example in [.NET].
• InterruptGUI: This small example demonstrates how to run a GAMS model in a graphical user interface. This has all rudimentary features we know from the GAMS IDE: starting a job, capture the GAMS log in a window, and providing a button to interrupt. The underlying mechanism to interrupt the job is similar to the Interrupt Example (GAMSJob.Interrupt), but the trigger mechanism is very different. See this example in [.NET, Java, Python].
• FarmGUI: For this farming model, the input data can be entered directly into several tables. The GAMS model itself is executed by using one single GAMSJob instance. Results are displayed in different charts and tables. See this example in [ .NET].
• TransportGUI: In this example a series of transportation problems is solved using GAMSModelInstance. Data can be entered into tables or can be loaded from a database. When data is entered into a table, related tables are updated automatically. Results are shown in tables and/or a bar chart. See also Transport Model Sequence Example. See this example in [.NET, Java].

GAMS Remote Object

This example demonstrates how to implement a simple GAMS Server. The example has two parts: GAMSServer and GAMSClient. The example is configured to run the client and server on the same machine, but can easily be altered to run on different machines. Both client and server need access to the GAMSRemoteClass that implements the server. The method to communicate is very simple. The client sets up the ingredients for a GAMSJob (model text, GDX input, parameters) and sends them serialized (via a byte representation of the GDX and parameter file) to the server. The server recreates the GAMS objects from the serialized representations, runs the model, and ships GAMSJob.OutDB serialized back to the client for further processing.

See GAMSServer example in [.NET] and GAMSClient in [.NET].

Interrupt

Ctrl-C in a regular console application results in the interrupt of the entire job. GAMS users are used to the fact that Ctrl-C interrupts a solve but then continues with the execution of the remaining GAMS job. The example demonstrates how to alter some console properties to get this behavior of Ctrl-C.

See Interrupt example in [ .NET, Java, Python ].

Markowitz

This is a small graphical program that plots the efficient frontier of Markowitz' portfolio selection problem with the two objectives return and risk. The example utilizes the GAMSModelInstance class to solve the parameterized objective max lambda*return - (1-lambda)*risk in the most efficient way.

See Markowitz example in [ .NET, Python ].

MessageReceiver Window

The little example demonstrates how to implement a custom visual log. From GAMS one can send messages to the form started by this program via the put_utility "winmsg". The form also understands some commands (a message that starts with @) to save the content of the form, to put the content into the clipboard, or to terminate the program. The MessageReceiverWindow is also distributed as an executable in the GAMS system directory ready to be used. The model mrw01 in the GAMS Test Library demonstrates the use of the program.

See MessageReceiver Window example in [.NET].

Special Values

This example shows how special values of the programming language (e.g. infinity) percolate down to GAMS. Infinity and NaN (not a number) are well defined. The GAMS Undefined and EPS need special considerations.

See Special Values example in [.NET, Java, Python].

Transport Model Sequence

This set of examples demonstrates the use of the Object-oriented API on the simple transport model trnsport.gms : A Transportation Problem [trnsport]. The detailed description of the various examples is provided in the Object-oriented API tutorials in the GAMS documentation.

See Transport Model example in [.NET, C++, Java, Python].

Traveling Salesman Problem

This example demonstrates how to use a GAMSModelInstance to implement the subtour elimination algorithm for the Traveling Salesman Problem (TSP) problem. Similar to Benders2Stage example, we have a placeholder for the subtour elimination constraint that gets generated in each iteration of the algorithm. In contrast to the Benders example, here we regenerate the GAMSModelInstance if the original number of placeholders was not big enough. We continue this process until all subtours are eliminated.

See Traveling Salesman Problem example in [.NET, Java, Python].

Unit Test

This example contains all the unit tests we run on the .Net Object-oriented API. See Unit Test example in [.NET].

Warehouse

This example demonstrates how to solve a simple GAMS model to assign stores to warehouses for different data sets in parallel. The model has been parameterized. The data can be derived from a few numbers namely the number of warehouses, stores, and some fixed cost scalar. The results of the model are written into a single result database that is protected across the parallel threads via a mutex.

See Warehouse example in [.NET, C++, Java, Python].

Release Notes

GAMS API Release Notes provide an overview of changes to the GAMS APIs in releases of the GAMS distribution.

• Java API Release Notes

Supported Platforms

Expert-Level APIs

In addition to the object-oriented GAMS API, there exist expert-level (or low-level) APIs to some component libraries of the GAMS system. These APIs are used internally in GAMS for a long time and help in the deployment of GAMS models. While they offer high performance and flexibility, they also require advanced knowledge and it is recommended that the object-oriented GAMS API is used if possible. The expert-level APIs are offered for C, C#, Delphi, Fortran, Java, Python, and Visual Basic.

The DCT, GEV, and GMO components are mainly used to build solver links to GAMS (see, e.g., the GAMSLinks project. In fact, all professional GAMS solver links are based on these components. They provide access to an instance of a model generated by a solve statement. If you plan to build advanced algorithms for models or need to solve a sequence of very similar models these components might represent an alternative to an implementing using the GAMS language.

While we also strive for backward compatibility with our component libraries, but programming interfaces are commonly subject to change, so programs based on these APIs might require adjustment when updating to a new GAMS version. The Release Notes have a section on these API changes.

Overviews of the exported function in pseudo code are available in the following summary pages:

• CFG API (GAMS Configuration Object)

• DCT API (GAMS Dictionary Object)

• GDX API (GAMS Data Exchange Object) which is also available as open source project on GitHub. The official documentation can be found here.

• GEV API (GAMS Environment Object) with additional GAMS Environment Object Options.

• GMO API (GAMS Modeling Object) with additional information on philosophy and design.

• IDX API (GAMS IDX Object)

• OPT API (GAMS Option Object)

• PAL API (GAMS Auditing and Licensing Object)

Note

Without having a GAMS system directory in the PATH environment variable, the xyzCreateD functions (e.g. gdxCreateD, optCreateD, ...) might cause some issues finding libraries that are only in the GAMS system directory on Windows.

Supported Platforms

* Fortran API files are based on C code to load dynamic libraries. For Windows pure Fortran API files for Intel and Lahey Fortran compilers are included