Tutorials

The tutorials provided in the tutorial directory of the ixmp repository walk through the first steps of working with ixmp. You will learn how to create a ixmp.Scenario as a structured data collection for sets, parameters and the numerical solution to the associated optimization problem.

Dantzig’s transportation problem

We use Dantzig’s transport problem [1], which is also used as the standard GAMS tutorial [4]. This problem finds a least cost shipping schedule that meets demand requirements at markets and supply capacity constraints at multiple factories.

The tutorials are provided as Jupyter notebooks for both Python and R, and are identical as far as possible.

  • Tutorial 1: in Python, or in R.

    This tutorial walks through the following steps:

    1. Launch an ixmp.Platform instance and initialize a new ixmp.Scenario.

    2. Define the sets and parameters in the scenario, and commit the data to the platform.

    3. Check out the scenario and initialize variables and equations (necessary for ixmp to import the solution).

    4. Solve the scenario (export to GAMS input gdx, execute, read solution from output gdx).

    5. Display the solution (variables and equation).

  • Tutorial 2: in Python, or in R.

    This tutorial creates an alternate or ‘counterfactual’ scenario of the transport problem; solves it; and compares the results to the original or reference scenario.

Adapting GAMS models for ixmp

The common example optimization from Dantzig [1] is available in a GAMS implementation from the GAMS website. The file tutorial/transport/transport_ixmp.gms illustrates how an existing GAMS model can be adapted to work with the ix modeling platform. The same, simple procedure can be applied to any GAMS code.

The steps are:

  1. Modify the definitions of GAMS sets (i and j) and parameters (a, b, d, and f) to remove explicit values.

  2. Add lines to read the model input data passed by ixmp.

    The following lines are added before the code that defines and solves the model:

    * These two lines let the model code be run outside of ixmp, if needed
$if not set in  $setglobal in  'ix_transport_data.gdx'
$if not set out $setglobal out 'ix_transport_results.gdx'

$gdxin '%in%'
$load i, j, a, b, d, f
$gdxin

  3. Add a line to write the model output data.

    The following line is added after the model’s solve ...; statement:

    execute_unload '%out%';

ixmp’s GAMSModel class uses command-line options to pass the values of the variables in and out. This causes the model to read its input data from a GDX-format file created by ixmp, and write its output data to a GDX file specified by ixmp. ixmp then automatically retrieves the model solution and other information from the output file, updating the Scenario and storage Backend.