Table of Contents
- Verify Conda Installation
- Create a New Conda Environment
- Install
- macOS Compatibility
- Verify the GAMS API
- Uninstall the GAMS API
- Remove Conda Environment
- Other Useful Conda Commands
- Python Virtual Environment (venv)
- Working with Python and multiple GAMS Installations
- A note on using Python site package
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
andconda
are synonymous – both are package + environment managers – however,conda
comes preloaded with a number of useful data science-related packages. We emphasizeminiconda
because of the smaller install size. The terminal commands we used here apply to bothminiconda
andconda
versions. The remaining documentation will only use the termconda
.
- 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.9 to 3.13.
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., 48.2.0)
The extras
that are available for the GAMS Python API are:
extra | Third-party Dependencies to Install |
---|---|
connect | pandas , pyyaml , openpyxl , sqlalchemy , cerberus , pyodbc , psycopg2-binary , pymysql , pymssql |
control | urllib3 |
core | ply , numpy |
engine | python_dateutil , urllib3 |
magic | ipython , pandas |
tools | pandas |
transfer | pandas , scipy |
all | installs all third-party dependencies for all sub-modules – a complete install |
- Attention
- Users can chain several
extras
together (separated by commas) in onepip
install command to install dependencies from several sub-modules at once.
- Note
- On certain platforms
psycopg2-binary
needs to be built from source (e.g. for Python 3.13 on Windows and for Python 3.9 on macOS on ARM64). This requires additional build dependencies that might need to be installed manually.
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., 48.2.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.
Conda Command | Description |
---|---|
conda env list | List all conda environments |
conda list | List all installed packages in the active environment |
conda deactivate | Deactivate the current Python environment |
conda remove --name XXX --all | Remove the XXX environment, must be deactivated first |
conda install XXX | Install package XXX with the conda system, not all packages can be installed from conda directly |
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.