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

The tutorials refer to terms and concepts from energy systems research (i.e. how they are measured and modeled mathematically) and to scientific programming languages and tools (i.e. Python/R language syntax and popular packages in either language)—however, they do not provide a full introduction to these. Read the pre-requisite knowledge documentation page for an outline of things you should learn first, in order to fully understand the tutorials.

Getting tutorial files

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

If you installed MESSAGEix using Anaconda or pip, 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 matching 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 main.

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

  1. Open “Jupyter Notebooks” from Anaconda’s “Home” tab (or directly if you have the option).

  2. Choose and open a tutorial notebook.

  3. 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

  1. Navigate to the tutorial folder. For instance, if message-ix dl was used above:

    $ cd /path/to/tutorials

  2. Start the Jupyter notebook:

    $ jupyter notebook

Westeros Electrified

The Westeros Electrified tutorial series demonstrates how to:

  • create a minimal model that represents a very simple energy system,

  • add extra detail / constraints to this representation, and

  • post-process (analyze, visualize, or ‘report’) the results.

The following list groups the tutorials by topic. For new or beginner users, the following sequence of six tutorials (also marked with ⭐, below) requires the lowest amount of background knowledge and is sufficient for a basic introduction:

1 — 2.1 — 2.2 — 3.1 — 3.2.1

The remaining tutorials require deeper energy systems knowledge; greater scientific programming skills; and/or relate to more advanced uses of the framework, such as used in global research applications of MESSAGEix.

  1. ⭐ Build the baseline model (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/westeros/westeros_baseline.ipynb).

  2. Add extra detail and constraints to the model:

    1. ⭐ Emissions:

      1. Introduce emissions and a bound on the emissions (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/westeros/westeros_emissions_bounds.ipynb).

      2. Introduce taxes on emissions (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/westeros/westeros_emissions_taxes.ipynb).

    2. ⭐ Supply of resources:

      Add a fossil-resource supply curve for the coal power plant, (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/westeros/westeros_fossil_resource.ipynb).

    3. Renewables and integration constraints:

      1. Represent both coal and wind electricity using a “firm capacity” formulation (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/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 (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/westeros/westeros_flexible_generation.ipynb), wherein wind requires and coal supplies flexibility.

      3. Add a renewable-resource supply curve for the wind power plant, (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/westeros/westeros_renewable_resource.ipynb).

    4. Sub-annual time resolution:

      Represent variability in energy supply and demand by adding sub-annual time resolution, e.g. winter and summer (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/westeros/westeros_seasonality.ipynb).

    5. Constraints:

      1. Using share constraints to depict policies, i.e. require renewables to supply a certain share of total electricity generation (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/westeros/westeros_share_constraint.ipynb).

      2. Add soft constraints for activity related dynamic constraints (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/westeros/westeros_soft_constraints.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 (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/westeros/westeros_addon_technologies.ipynb).

    7. Use parameters to represent the historical characteristics of the energy system (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/westeros/westeros_historical_new_capacity.ipynb).

    8. Modeling of a multi-node energy system and representing trade between nodes (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/westeros/westeros_multinode_energy_trade.ipynb).

  3. Use other features of message_ix and ixmp:

    1. ⭐ After the MESSAGE model has solved, use the message_ix.report module to ‘report’ results, e.g. do post-processing, plotting, and other calculations (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/westeros/westeros_report.ipynb).

    2. Build the baseline scenario using data stored in Excel files to populate sets and parameters:

      1. ⭐ Export data to file and import the data to create a new scenario (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/westeros/westeros_baseline_using_xlsx_import_part1.ipynb).

      2. Import and combine data from multiple files to create a new scenario (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/westeros/westeros_baseline_using_xlsx_import_part2.ipynb).

Austrian energy system

These tutorials demonstrate a stylized representation of a national electricity sector model, with several fossil and renewable power plant types.

  1. Prepare the base model version, in Python (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/Austrian_energy_system/austria.ipynb) or in R (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/Austrian_energy_system/R_austria.ipynb).

  2. Plot results, in Python (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/Austrian_energy_system/austria_load_scenario.ipynb) or in R (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/Austrian_energy_system/R_austria_load_scenario.ipynb).

  3. Run a single policy scenario (https://github.com/iiasa/message_ix/blob/v3.9.0/tutorial/Austrian_energy_system/austria_single_policy.ipynb).

  4. Run multiple policy scenarios. This tutorial has two notebooks:

Code reference

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

message_ix.util.tutorial.prepare_plots(rep: Reporter, input_costs='$/GWa') → None[source]

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: Scenario, new_name: str)[source]

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.