# 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:

Launch an

`ixmp.Platform`

instance and initialize a new`ixmp.Scenario`

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

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

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

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:

Modify the definitions of GAMS sets (

`i`

and`j`

) and parameters (`a`

,`b`

,`d`

, and`f`

) to**remove explicit values**.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

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`

.