Tutorials

To get started with MESSAGEix, the following tutorials are provided as Jupyter notebooks, which combine code, sample output, and explanatory text.

A static, non-interactive version of each notebook can be viewed online using the links below. In order to execute the tutorial code or make modifications, read the Preparation section, next.

Preparation

Getting tutorial files

If you installed MESSAGEix from source, all notebooks are in the tutorial directory.

If you installed MESSAGEix using Anaconda, download the notebooks using the message-ix command-line program. In a command prompt:

$ message-ix dl /path/to/tutorials

Note

If you installed message_ix into a specific conda environment, that environment must be active in order for your system to find the message-ix command-line program, and also to run the Jupyter notebooks. Activate the environment as described in the conda documentation; for instance, if you used the name message_env:

$ conda activate message_env

Note

By default, the tutorials for your installed version of MESSAGEix are downloaded. To download a different version, add e.g. --tag v1.2.0 to the above command. To download the tutorials from the development version, add --branch master.

Running tutorials

Using Anaconda

The nb_conda package is required. It should be installed by default with Anaconda. If it was not, install it:

$ conda install nb_conda

Open “Jupyter Notebooks” from Anaconda’s “Home” tab (or directly if you have the option).
Choose and open a tutorial notebook.
Each notebook requires a kernel that executes code interactively. Check that the kernel matches your conda environment, and if necessary change kernels with the menu, e.g. Kernel → Change Kernel → Python [conda root].

From the command line

Navigate to the tutorial folder. For instance, if message-ix dl was used above:
```
$ cd /path/to/tutorials
```
Start the Jupyter notebook:
```
$ jupyter notebook
```

Westeros Electrified

This tutorial demonstrates how to model a very simple energy system, and then uses it to illustrate a range of framework features.

Build the baseline model (westeros/westeros_baseline.ipynb).
Add extra detail and constraints to the model
1. Emissions
  1. Introduce emissions and a bound on the emissions (westeros/westeros_emissions_bounds.ipynb).
  2. Introduce taxes on emissions (westeros/westeros_emissions_taxes.ipynb).
2. Renewables
  1. Represent both coal and wind electricity using a “firm capacity” formulation (westeros/westeros_firm_capacity.ipynb): each generation technology can supply some firm capacity, but the variable, renewable technology (wind) supplies less than coal.
  2. Represent coal and wind electricity using a different, “flexibility requirement” formulation (westeros/westeros_flexible_generation.ipynb), wherein wind requires and coal supplies flexibility.
  3. Add a renewable-resource supply curve for the wind power plant, (westeros/westeros_renewable_resource.ipynb).
3. Variablity in energy supply and demand by adding sub-annual time steps, e.g. winter and summer (westeros/westeros_seasonality.ipynb).
4. Using share constraints to depict policies, i.e. require renewables to supply a certain share of total electricity generation (westeros/westeros_share_constraint.ipynb).
5. Add a fossil-resource supply curve for the coal power plant, (westeros/westeros_fossil_resource.ipynb).
6. Add-on technologies: Add the possibility of co-generation for the coal power plant, by allowing it to produce heat via a passout-turbine (westeros/westeros_addon_technologies.ipynb).
7. Build the baseline scenario using data stored in xlsx files to populate sets and parameters.
  1. Export data to and Excel file and import the data to create a new scenario (westeros/westeros_baseline_using_xlsx_import_part1.ipynb).
  2. Import data from multiple excel files to create a new scenario (westeros/westeros_baseline_using_xlsx_import_part2.ipynb).
8. Add soft constraints for activity related dynamic constraints (westeros/westeros_soft_constraints.ipynb
9. Explore historical parameters and their usage (westeros/westeros_historical_new_capacity.ipynb).
After the MESSAGE model has solved, use the message_ix.reporting module to ‘report’ results, e.g. do post-processing, plotting, and other calculations (westeros/westeros_report.ipynb).

Austrian energy system

This tutorial demonstrates a stylized representation of a national electricity sector model, with several fossil and renewable power plant types.

Prepare the base model version, in Python (Austrian_energy_system/austria.ipynb) or in R (Austrian_energy_system/R_austria.ipynb).
Plot results, in Python (Austrian_energy_system/austria_load_scenario.ipynb) or in R (Austrian_energy_system/R_austria_load_scenario.ipynb).
Run a single policy scenario (Austrian_energy_system/austria_single_policy.ipynb).
Run multiple policy scenarios. This tutorial has two notebooks:

an introduction with some exercises (Austrian_energy_system/austria_multiple_policies.ipynb), and

completed code for the exercises (Austrian_energy_system/austria_multiple_policies-answers.ipynb).

Code reference

The module message_ix.util.tutorial contains some helper code used to simplify the tutorials; see also reporting.computations.stacked_bar().

message_ix.util.tutorial.prepare_plots(rep: message_ix.reporting.Reporter, input_costs='$/GWa') → None

Prepare rep to generate plots for tutorial energy models.

Makes available several keys:

plot activity
plot demand
plot extraction
plot fossil supply curve
plot capacity
plot new capacity
plot prices

To control the contents of each plot, use set_filters() on rep.

message_ix.util.tutorial.solve_modified(base: message_ix.core.Scenario, new_name: str)

Context manager for a cloned scenario.

At the end of the block, the modified Scenario yielded by solve_modified() is committed, set as default, and solved. Use in a with: statement to make small modifications and leave a variable in the current scope with the solved scenario.

Examples

>>> with solve_modified(base_scen, "new name") as s:
...     s.add_par( ... )  # Modify the scenario
...     # `s` is solved at the end of the block

Yields: .Scenario – Cloned from base, with the scenario name new_name and no solution.