Users have many options to manage their Python installation; in many cases it is advantageous to create a Python "environment" to sandbox an instance of Python (something which can be done with venv or conda). We recommend that users download a version of miniconda. We direct users to the conda documentation for installation issues. After the user has installed miniconda (or conda) we will:

• Verify that conda is working
• Create a new scratch Python environment
• Enter the new environment and verify the python version
• Install the GAMS API with pip

Note

miniconda and conda are synonymous – both are package + environment managers – however, conda comes preloaded with a number of useful data science-related packages. We emphasize miniconda because of the smaller install size. The terminal commands we used here apply to both miniconda and conda versions. The remaining documentation will only use the term conda.

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.

Verify Conda Installation

To verify that conda is accessible from the terminal we simply need to check for the version number. Your version of conda may differ. The installation of the GAMS API does not depend on the conda version.

$  conda --version
conda 22.9.0

Create a New Conda Environment

Conda can create, manage, and delete Python environments easily – this flexibility allows users to experiment quickly with different tools. If experiments fail, the entire environment can be removed without damaging the rest of the system. In short, each conda environment is an isolated sandbox. We will now create a new conda environment called gams that we will used when installing the GAMS API.

Note

Best practice is to use an environment rather than install into conda's base environment

$  conda create --name gams python=3.10
[verbose conda output]
#
# To activate this environment, use
#
#     $ conda activate gams
#
# To deactivate an active environment, use
#
#     $ conda deactivate
Retrieving notices: ...working... done
$ 

Note

It is necessary to specify the version of Python to install into the new conda environment. The GAMS API currently supports Python 3.8 to 3.12.

We must now "activate" the conda environment (i.e., enter the Python sandbox).

$  conda activate gams
(gams)$ 

Once in the activated environment we should verify the Python version is the one that was specified at creation.

(gams)$  python --version
Python 3.10.8

Install

The GAMS Python API is distributed through the Python Package Index. The gamsapi package comes with several install options (via pip extras) that change how dependencies are resolved. pip will not install any third-party dependencies if an extra label was not provided. For example, to install the transfer data tool (and its dependencies to pandas and scipy).

(gams)$  pip install gamsapi[transfer]==xx.y.z

Note

xx.y.z represents your installed GAMS version number (e.g., 47.6.0)

The extras that are available for the GAMS Python API are:

Attention

Users can chain several extras together (separated by commas) in one pip install command to install dependencies from several sub-modules at once.

macOS Compatibility

The default shell for macOS 10.15+ (Catalina) is zsh. Users that wish to install the gamsapi will need to modify their install syntax slightly (note the quotations).

(gams)$  pip install 'gamsapi[transfer]'==xx.y.z

Note

xx.y.z represents your installed GAMS version number (e.g., 47.6.0)

Apple M1/M2

Apple users that have a M1/M2 (arm) chipset must be careful to match build architectures (i.e., x86 or arm) of both the GAMS system and miniconda (Python). Ideally, M1/M2 users will only install native arm compatible programs. Apple's Rosetta 2 does allow users to install and run x86 compiled programs on M1/M2. However, mixed installations (i.e., an arm GAMS system but a x86 miniconda or vice versa) will fail because the gamsapi will not be able to properly load the necessary shared libraries.

The gams audit tool will return the GAMS build architecture (x86 or arm will be in the returned string):

(gams)$  gams audit
GAMSX            45.1.0 88bbff72 Oct 14, 2023          DAC arm 64bit/macOS

The build architecture of the Python installation is available with the following command:

(gams)$  python -c "import platform; print(platform.processor())"
arm

Attention

The user must reinstall either a GAMS or Python system if these two returns do not match.

Verify the GAMS API

pip provides feedback that suggests that the GAMS API was successfully installed, however, it is still wise to verify this. The best way to test is to actually create a short Python script that imports gams. The following 1 line will run an import operation and, if successful, will output the API version number. The API was not successfully installed if an import error is raised.

(gams)$  python -c "import gams; print(f'API OK -- Version {gams.__version__}')"
API OK -- Version 45.2.0

Attention

Example problems can be found in the [PATH TO GAMS]/api/python/examples folder (organized by sub-module).

Uninstall the GAMS API

Removal of the GAMS API is straightforward with pip:

(gams)$  pip uninstall gamsapi
Found existing installation: gamsapi 45.2.0
Uninstalling gamsapi-45.2.0:
  Would remove:
    /Users/gams_user/miniconda3/envs/gams/lib/python3.10/site-packages/gamsapi-45.2.0.dist-info/*
    /Users/gams_user/miniconda3/envs/gams/lib/python3.10/site-packages/gamsapi/*
Proceed (Y/n)? y
  Successfully uninstalled gamsapi-45.2.0

Remove Conda Environment

Removal of the entire conda environment is also straightforward with the following operations:

(gams)$  conda deactivate
(base)$  conda remove --name gams --all
[verbose conda output]
Proceed ([y]/n)? y

Preparing transaction: done
Verifying transaction: done
Executing transaction: done
(base)$ 

Other Useful Conda Commands

Users are directed to the full conda documentation but some useful commands are provided here as a quick reference.

Python Virtual Environment (venv)

This documentation assumed users will want to use conda to manage their Python environments, but other tools such as venv can be used to manage separate Python environments. The details of the venv setup, activation, deactivation and removal differ from conda, but the pip install commands are the same as in conda. Interested users are referred to the official venv documentation for details on how to create a virtual environment. Users are also directed to additional documentation on: Installing packages using pip and virtual environments.

Working with Python and multiple GAMS Installations

Some users may want to run multiple versions of GAMS on their system – we recommend that users create separate Python environments in order to compare the behavior between versions of the Python API.

A note on using Python site package

Previous API versions could be used by a Python interpreter if the path to the API directory was included in a sitecustomize.py script that resided in the site-packages directory. This type of installation allows customized packages to be found and used, but not necessarily copied into Python's directory structure. Previous versions of the API benefited from this type of installation, we recommend that users create a separate Python environment and actually install the GAMS API into the environment with pip. Users that were using the sitecustomize.py installation method might experience issues with pip installations if their Python finds an old sitecustomize.py file that includes a path to old GAMS API files (pip might report that the requirement is already satisfied). Users can find out where the USER_SITE directory is located by running the following command:

(gams)$  python -m site

Once this directory has been found, it is necessary to remove all paths (in the sitecustomize.py file) that point to previous GAMS API folders and reattempt the pip install process.