Magic (Jupyter Notebooks)
Note
This feature is currently in beta status.

Introduction

GAMS Jupyter Notebooks allow to use notebook technology in combination with GAMS. If you just want to learn GAMS there are probably better ways doing this. Notebooks allow you to combine GAMS and Python. The former works great with well structured data and optimization models, while the latter is very rich in features to retrieve, manipulate, and visualize data that comes in all sort of ways. Combining GAMS and Python in a notebook it is relatively easy to tell an optimization story with text, data, graphs, math, and models.

Getting Started

The first step in getting started with GAMS Jupyter Notebooks is to make your Python 3 installation aware of the GAMS Python API described in the Getting Started section of the API tutorial. We recommend to follow the steps below which are specifically tailored for getting started with GAMS Jupyter notebooks. While any Python 3.9 to 3.13 installation is supported, we recommend the use of miniconda Python distributions.

Attention
All core third party dependencies will be installed if the user supplies the optional pip syntax (pip install gamsapi[magic]).

In addition to the GAMS Python API collection (and the core magic dependencies), the examples located in [PATH TO GAMS]/api/python/examples/magic will require the additional packages: jupyterlab, matplotlib, and tabulate. The following code section shows how to create and set up a conda environment for GAMS Jupyter notebooks:

$ conda create --name gams python=3.10

$ conda activate gams

(gams)$ pip install gamsapi[magic] --find-links [PATH TO GAMS]\api\python\bdist

$ conda install jupyter

(gams)$ jupyter notebook

$ conda create --name gams python=3.10

$ conda activate gams

(gams)$ pip install gamsapi[magic] --find-links /Library/Frameworks/GAMS.framework/Versions/[GAMS MAJOR VERSION]/Resources/api/python/bdist

$ conda install jupyter

(gams)$ jupyter notebook

$ conda create --name gams python=3.10

$ conda activate gams

(gams)$ pip install gamsapi[transfer,magic] --find-links [PATH TO GAMS]/api/python/bdist

$ conda install jupyter

(gams)$ jupyter notebook

The notebooks Millco.ipynb and Introduction.ipynb located in api/python/examples/magic are good starting points to get familiar with Jupyter notebooks and GAMS. The remainder of this section gives the dialog of the Introduction.ipynb notebook. Please see also the other notebook examples:

Tutorial

Introduction

Converting GAMS Jupyter Notebooks into Python Scripts

Sometimes it can be useful to execute the logic of a GAMS Jupyter notebook in a standalone Python script. This can be achieved by using the gams.magic.GamsInteractive class which implements the back-end logic of gams.magic and does require neither IPython nor jupyter. Translating GAMS magic commands into Python method equivalents is stright forward. First, the Python equivalent of %reload_ext gams.magic needs to be added to the beginning of a Python script:

from gams.magic import GamsInteractive
gams = GamsInteractive()

Afterwards, each magic command or method available in GAMS Jupyter notebooks has an equivalent in GamsInteractive with the same name. GAMS magic commands like %gams or %gams_reset can be translated into methods of the exact same name - in this case GamsInteractive.gams() and GamsInteractive.gams_reset(). Methods and properties which are accessed directly (without GAMS magic command) in a Jupyter notebook like gams.exchange_container or gams.activate() can be used in the exact same way from within GamsInteractive. Options and parameters of GAMS magic commands can be used with corresponding arguments of the equivalent methods.

While GAMS magic commands can be translated very easily, certain interactive functionality like chart plotting might require a different mechanism when being translated. Also display() might need to be changed into print() or similar to be working in a standalone Python script. In addition, Jupyter notebooks display data which is returned by the last command of a Python cell. In Python we need to use another print() of the return value to get it as output.

For a complete example of a translated GAMS Jupyter notebook see [PATH TO GAMS]/api/python/examples/magic/millco.py which is a translation of the Millco.ipynb notebook.