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, licensed under the APACHE 2.0 open-source 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

Developing a valid, scientific MESSAGEix 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

Using, getting help, and contributing

Everyone is encouraged to use the framework to develop energy system and integrated assessment models!

Everyone is required to please follow our Code of Conduct, which you can find on GitHub or in CODE_OF_CONDUCT.md included with the source code.

• Python API

• Usage in R via reticulate

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

• User guidelines and notice —including how to properly cite the framework and software in scientific research.

• 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 your contributions on GitHub or in GOVERNANCE.md included with the source code.

• Sharing publications, projects, and tools—we invite the sharing of the usage of the MESSAGEix framework.

• See our Security Policy on GitHub or in .github/SECURITY.md included with the source code.

• Frequently asked questions

• References

Have a question? Check…

• …on GitHub:

  • Join an existing discussion or start a new one with your question.

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

• …the Frequently asked questions.

• …the 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.