The GAMS API is a Python package that contains several sub-modules that enable the control of the GAMS system as well as the movement of data between GAMS and Python. Currently the API supports the Python versions 3.8 to 3.12. The following table gives an overview of all available sub-modules:

Sub-Module	Description
connect (beta)	Used primarily by GMSPython to digest YAML syntax to Extract, Transform and Load (ETL) data into GAMS, but can be used in native Python environments.
control	Enables full control of the GAMS System
core	Core GAMS API tools used to connect to GDX, GMD, GMO and other GAMS objects. Requires expert level knowledge.
engine	GAMS Engine API (OpenAPI compliant), manages jobs with GAMS Engine
magic (beta)	Enables the use of GAMS from within Jupyter notebooks
tools (beta)	Code base for the GAMS tools library
transfer	Data Only API – Allows GAMS data to be maintained outside a GAMS script

Note: Due to compatibility issues the GAMS Python API does not work with the Python interpreter from the Microsoft Store.

To install the API please visit: Getting Started.

Migrate import statements

With the release of GAMS 42 the GAMS Python ecosystem has been restructured – the new structure has many benefits (easier/safer (un)installs, cleaner module namespaces, etc.).

Attention: The new API structure cannot be used to simply "update" previous versions – users should build new python environments from scratch before attempting to install.

Restructuring of the GAMS python API ecosystem was confined to the creation of the new nested structure – class, method and other variables names were not modified. The import statements in legacy code will need to be updated if using the new system. Best practice will be to use the new package structure to import different sub-modules as needed (and avoid from <module_name> import * syntax). We provide a mapping between the old syntax and the new to aid in the transition to the new API structure:

Old `import` statement	New `import` recommendation(s)
`from gams import GamsWorkspace`	`from gams import GamsWorkspace`
`from gams import *`	`import gams`
`from gdxcc import *`	`from gams.core import gdx` -or- `import gams.core.gdx as gdx`
`from optcc import *`	`from gams.core import opt` -or- `import gams.core.opt as opt`
`import gamstransfer as gt`	`from gams import transfer as gt` -or- `import gams.transfer as gt`
`import gams_engine`	‘import gams.engine’

Note: Jupyter users will need to migrate their reload_ext gams_magic -> reload_ext gams.magic and load_ext gams_magic -> load_ext gams.magic

Testing for Old vs New API

Users may be running the same python code with different versions of the Python API. If this is the case, it might be beneficial to include conditional import statements. It is possible to test for the GAMS major version number with the GamsWorkspace.api_major_rel_number property:

from gams import GamsWorkspace
if GamsWorkspace.api_major_rel_number<42:  # old API structure
    import gdxcc as gdx
    from gams import *
    import gamstransfer as gt
else:  # new API structure
    import gams.core.gdx as gdx
    from gams.control import *
    import gams.transfer as gt

Attention: While conditional import statements can be helpful, users are strongly encouraged to modify their code to use the new structure.

GAMS Python API Structure

gams
│
├── connect (previously: gams_connect)
│
├── control (previously: gams)
│
├── core (new)
│    ├── gdx (previously: gdxcc)
│    ├── gmd (previously: gmdcc)
│    ├── opt (previously: optcc)
│    ├── idx (previously: idxcc)
│    ├── dct (previously: dctmcc)
│    ├── gmo (previously: gmomcc)
│    ├── gev (previously: gevmcc)
│    ├── cfg (previously: cfgmcc)
│    ├── emp (previously: emplexer, empyacc)
│    └── embedded (previously: gamsemb)
│
├── engine (previously: gams_engine)
│
├── magic (previously: gams_magic)
│
└── transfer (previously: gamstransfer)