The MESSAGEix framework

MESSAGEix is a versatile, dynamic systems-optimization modelling framework developed by the IIASA Energy, Climate, and Environment (ECE) Program [1] since the 1980s.

This is the documentation for message_ix, a Python package that ties together all components of the framework. message_ix and ixmp are free and open source software, licensed under the `APACHE 2.0 license`_.

• For the scientific reference of the framework, see Huppmann et al. (2019) [3].

• For an overview and recent publications related to the specific MESSAGEix-GLOBIOM global model instance used at the IIASA ECE Program, see the MESSAGEix-GLOBIOM documentation.

Getting started

Modeling using MESSAGEix requires domain knowledge, understanding of certain research methods, and scientific computing skills.

• Prerequisite knowledge & skills gives a list of these items for formal and self-guided learning.

Then, continue with the:

• MESSAGEix model & framework detailed description and feature list.

• Installation of the software and essential dependencies.

• Tutorials for new users that demonstrate the basic features of the framework.

• Usage of MESSAGEix in academic publications, research projects, and derived tools.

Features of ixmp, message_ix, and related packages [3]

Mathematical specification

These pages provide comprehensive description of the variables and equations in the core MESSAGEix mathematical implementation.

• Sets and mappings

• Years, periods, and time slices

• Parameter definition

• MESSAGE core formulation

• Solve statement workflow

• Standard output reports

• Auxiliary investment parameters

• MACRO core formulation

Developing MESSAGEix models

Everyone is encouraged to use MESSAGEix to develop energy system and integrated assessment models! Developing a valid, scientific model requires careful use of the framework features. This section provides guidelines for how to make some common model design choices.

• Efficiency - output- vs. input defined technologies

• Add model years to an existing Scenario

• Postprocessing and reporting

• Debugging and data validation

• Calibrate and tune MESSAGE-MACRO

• User guidelines and notice describes how to cite the framework and software in published research.

• Sharing publications, projects, and tools explains how to add your MESSAGEix applications to the Usage page in these docs.

Reference and development

• Python API

• Usage in R via reticulate

• What’s New —release history and migration/upgrade notes.

• Contributing to development —we welcome enhancements to the framework itself that enable new features across all models. You can learn more about how we handle these contributions in GOVERNANCE.md (on GitHub or included with the source code) [2]

• References

Community and support

We aim to maintain a healthy community for developers and users of MESSAGEix; thus we expect everyone to follow our Code of Conduct, which you can find in CODE_OF_CONDUCT.md (on GitHub or included with the source code). [2]

You can also:

• Read or join existing discussions on GitHub, or start a new one with your MESSAGEix usage question.

• Search current issues, or open a new one to report a bug in the code.

• Subscribe to the MESSAGEix Community Newsletter by filling this form and ticking the box for “MESSAGEix-Community”. At least once a year, we update all subscribers on the latest research and ongoing projects regarding MESSAGEix and invite you to our annual Community Meeting.

• See our security policy in SECURITY.md (on GitHub or included with the source code). [2]

• Read answers to some not-so-‘frequently’ asked questions.

• Check the older message_ix Google Group, either online or via e-mail at <message_ix@googlegroups.com>.

[1]

Known as the “Energy Program” until 2020-12-31.

[2] (1,2,3)

Our usage of files like CODE_OF_CONDUCT, GOVERNANCE, SECURITY, and SUPPORT follows the Open Source Guides recommendations.