Table of Contents
- Object-oriented APIs
- Expert-Level APIs to GAMS Component Libraries
- Supported Platforms
The Application Programing Interfaces (APIs) to GAMS allow the seamless integration of GAMS into an application. There are three versions of object-oriented GAMS APIs : .NET, Java, and Python. 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 avaiable with GAMS distribution with detailed description.
In addition to the object-oriented GAMS APIs, there exist 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.
See Support Platforms for platform availabilities of all GAMS APIs.
The GAMS object-oriented API allows the seamless integration of GAMS into an application by providing 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. The three versions of the object-oriented GAMS API: .NET, Java, Python work with .NET framework 4 (Visual Studio 2010), Java SE 5 and up, and Python 2.7 accordingly.
- 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
The GAMS APs reference manuals give an overview of the features provides by GAMS APIs, release notes, and a list of all classes with descriptions.
GAMS API Tutorials provide an overview of basic functionalities of GAMS APIs and alllow a user to get started to work with the GAMS API.
There are several examples avaiable for the different programming languages: .NET, 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.
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.
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.
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.
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.
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.
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, 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 a bar chart. See also Transport Model Sequence Example. See this example in [.NET].
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.
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.
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.
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].
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.
This set of examples demonstrates the use of the Object-oriented API on the simple transport model [trnsport] from the GAMS Model Library. The detailed description of the various examples is provided in the Object-oriented API tutorials in the GAMS documentation.
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.
This example contains all the unit tests we run on the .Net Object-oriented API. See Unit Test example in [.NET].
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.
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++, 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 at COIN-OR for the interfaces to Bonmin, Cbc, Couenne, Ipopt, and SCIP). 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 GAMS 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)
- GAMSx API (GAMS Execution Object)
- GDX API (GAMS Data Exchange Object) with additional information available as PDF and CHM.
- GEV API (GAMS Environment Object)
- GMO API (GAMS Modeling Object) with additional information on philosophy and design.
- IDX API (GAMS IDX Object)
- OPT API (GAMS Option Object)
|APIs/Platform availability - 24.8|
Mac OS X
|IBM Power 64bit
|GAMS Python||2.7 and 3.4 only|
|Python||2.7, 3.4 and src only||src only||src only||src only|