The MESSAGEix framework

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

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

• message_ix supports creation and use of any energy-system model with the MESSAGE core equations. One specific model is “MESSAGEix-GLOBIOM”, a global model instance used in IIASA ECE Program research and sometimes informally called “MESSAGE”. MESSAGEix-GLOBIOM is documented as part of the separate message_ix_models package, in particular on the page “MESSAGEix-GLOBIOM global model”.

• For peer-reviewed academic literature about MESSAGEix and specific models and applications, see section 2 of the “User guidelines and notice” page, the Usage page, and again the MESSAGEix-GLOBIOM page in the message_ix_models 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 variables and equations in the GAMS implementation of MESSAGE that is included with and used via message_ix.

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