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.7 to 3.11.

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 comes packaged as a wheel and is installed with pip into the conda environment. pip is made available by default whenever a new conda environment is created. It is worth verifying that the user has access to pip via the command line by testing for the version. Just as with conda, the pip version number is not critical and may vary with your installation. If a version number is not returned, then there was an error with the creation of the conda environment – the user should remove the conda environment and recreate.

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.

(gams)$  pip --version
pip 22.2.2 from /Users/gams_user/miniconda3/envs/gams/lib/python3.10/site-packages/pip (python 3.10)

Once pip has been verified, the user can now proceed with the GAMS API installation. To install the GAMS API we must point pip to the directory in the GAMS system that contains all the different wheels (for all supported python versions) – pip will auto-detect the correct wheel to install, there is no need to specify this manually.

Resolving Dependencies

The wheel file was built with the use of extras (i.e., variants of a package that include additional dependencies). These extras enable users to install the third party dependencies for the API tools that they wish to use. The extras that are available for the GAMS Python API are:

Attention

Users can chain several extras together in one pip install command to install dependencies from several sub-module at once.

pip will not install any third-party dependencies if an extra label was not provided.

As an example – to install the transfer data tool (and its dependencies to pandas and scipy) we would need to use the following system command (assuming the standard GAMS installation location):

If users wanted to install the transfer and magic tools we would need to use the following system command (assuming the standard GAMS installation location):

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 42.1.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 gams
Found existing installation: GAMS 42.1.0
Uninstalling GAMS-42.1.0:
  Would remove:
    /Users/gams_user/miniconda3/envs/gams/lib/python3.10/site-packages/GAMS-42.1.0.dist-info/*
    /Users/gams_user/miniconda3/envs/gams/lib/python3.10/site-packages/gams/*
Proceed (Y/n)? y
  Successfully uninstalled GAMS-42.1.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.

Install Source Distribution

The recommended way to install the GAMS Python API is to install from the built distribution (bdist) wheel file. These files are built at GAMS and tested on our system before shipping. However, some users may want to install directly from source (i.e., a source distribution aka sdist) on their system. This type of installation might be of interest to those users who want to experiment with developer releases of Python.

Users should set up a scratch conda environment as previously discussed. Instead of a wheel (.whl) file, users will use pip to install from a .tar.gz file.

It is necessary to first install numpy:

(gams)$  conda install numpy

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.

pip will compile the wheel (.whl) file and then install the package into the environment – uninstalling the API is the same as if it were installed directly from a wheel file. To install we use the following system commands (assuming the standard GAMS installation location):

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, but with the new API structure we recommend that users create a separate python environment and use the .whl files to actually install the GAMS API into the environment. 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 with the new .whl file.