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.9 to 3.13. The following table gives an overview of all available sub-modules:
Sub-Module | Description |
---|---|
connect | 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
andload_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:
- 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)