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.
Getting tutorial files
If you installed MESSAGEix from source, all notebooks are in the
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
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
$ conda activate message_env
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,
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 dlwas used above:
$ cd /path/to/tutorials
Start the Jupyter notebook:
$ jupyter notebook
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
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.
Represent coal and wind electricity using a different, “flexibility requirement” formulation (westeros/westeros_flexible_generation.ipynb), wherein wind requires and coal supplies flexibility.
Add a renewable-resource supply curve for the wind power plant, (westeros/westeros_renewable_resource.ipynb).
Variablity in energy supply and demand by adding sub-annual time steps, e.g. winter and summer (westeros/westeros_seasonality.ipynb).
Using share constraints to depict policies, i.e. require renewables to supply a certain share of total electricity generation (westeros/westeros_share_constraint.ipynb).
Add a fossil-resource supply curve for the coal power plant, (westeros/westeros_fossil_resource.ipynb).
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).
Build the baseline scenario using data stored in xlsx files to populate sets and parameters.
Export data to and Excel file and import the data to create a new scenario (westeros/westeros_baseline_using_xlsx_import_part1.ipynb).
Import data from multiple excel files to create a new scenario (westeros/westeros_baseline_using_xlsx_import_part2.ipynb).
Add soft constraints for activity related dynamic constraints (westeros/westeros_soft_constraints.ipynb
Explore historical parameters and their usage (westeros/westeros_historical_new_capacity.ipynb).
Austrian energy system
This tutorial demonstrates a stylized representation of a national electricity sector model, with several fossil and renewable power plant types.
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).
- 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 fossil supply curve
plot new capacity
To control the contents of each plot, use
- 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.
>>> with solve_modified(base_scen, "new name") as s: ... s.add_par( ... ) # Modify the scenario ... # `s` is solved at the end of the block
.Scenario – Cloned from base, with the scenario name new_name and no solution.