# The MESSAGEix framework¶

Key features of the ix modeling platform (source: [1])

## Overview and scope¶

MESSAGEix is a versatile, open-source, dynamic systems-optimization model. It was developed for strategic energy planning and integrated assessment of energy-engineering-economy-environment systems (E4). It can be applied to analyse scenarios of the energy system transformation under technical-engineering constraints and political-societal considerations. The optimization model can be linked to the general-economy MACRO model to incorporate feedback between prices and demand levels for energy and commodities. The equations are implemented in the mathematical programming system GAMS for numerical solution of a model instance.

The MESSAGEix framework is fully integrated with IIASA’s ix modeling platform (ixmp), a data warehouse for high-powered numerical scenario analysis. The platform supports an efficient workflow between original input data sources, the implementation of the mathematical model formulation, and the analysis of numerical results. The platform can be accessed via a web-based user interface and application programming interfaces (API) to the scientific programming languages Python and R. The platform also includes a generic data exchange API to GAMS for numerical computation.

This documentation provides an introduction and the mathematical formulation of the MESSAGEix equations and auxiliary functions. For the scientific reference of the framework, see Huppmann et al. (submitted) [1]. The formulation of MESSAGEix is a re-implementation and extension of ‘MESSAGE V’ (Messner and Strubegger, 1995 [5]), the Integrated Assessment model developed at IIASA since the 1980s. For an overview of the MESSAGEix model used at the IIASA Energy Program and a list of recent publications, please refer to the MESSAGE-GLOBIOM documentation website.

MESSAGEix and the ix modeling platform are licensed under an APACHE 2.0 open-source license. See the LICENSE file for the full text.

Please read the NOTICE included in this repository and other documents referenced below for the user guidelines and further information.

The community mailing list for questions and discussions on new features is hosted using Googlegroups. Please join at groups.google.com/d/forum/message_ix and use <message_ix@googlegroups.com> to send an email to the MESSAGEix user community.

## Features of the MESSAGEix model¶

The MESSAGEix implementation includes:

• A comprehensive implementation of ‘technologies’ to represent a reference energy system (i.e., the fuel supply chain, conversion technologies from primary to secondary energy forms, transmissions and distribution, and final demand for energy services)
• Vintaging of capacity and explicit possibility for early retirement/decommissioning of technologies
• Explicit formulations for the system integration of variable renewable energy sources based on Sullivan et al., 2013 [6] and Johnson et al., 2016 [2].
• A direct implementation of the ‘soft’ relaxations of dynamic constraints on new capacity and activity (see Keppo and Strubegger, 2010 [3])
• Implementation of perfect-foresight and dynamic-recursive (myopic) solution approaches

## Documentation¶

The mathematical model description and other documentation pages are built from the documentation comments in the GAMS code and the Python and R interface bindings. The documentation available on MESSAGEix.iiasa.ac.at is synchronized with the GitHub repository. It is built from the latest master branch at github.com/iiasa/message_ix upon every update.

## Getting started¶

### Installation¶

For new users, we recommend to install Anaconda (Python 3.6 or higher) and GAMS. Importantly, when installing GAMS, check the box labeled Use advanced installation mode select Add GAMS directory to PATH environment variable on the Advanced Options page.

Then, open a command prompt and type

 conda install -c conda-forge message-ix 

### Tutorials¶

To get started with a stylized energy system model implemented in MESSAGEix, look at the tutorials included in this repository at tutorial/README.

### Running the MESSAGEix model¶

There are three methods to run the MESSAGEix model:

• Via the scientific programming APIs using the packages/libraries ixmp and message_ix, calling the method solve() of the ixmp.Scenario class (see the tutorials).

• Using the file MESSAGE_master.gms, where the scenario name (i.e., the gdx input file), the optimization horizon (perfect foresight or myopic/rolling-horizon version), and other options can be defined explicitly.

This approach is recommended for users who prefer to work via GAMS IDE or other text editors to set the model specifications.

• Directly from the command line calling the file MESSAGE_run.gms (see the auto-doc page). The scenario name and other options can be passed as command line parameters, e.g. gams MESSAGE_run.gms --in="<data-file>" --out="<output-file>".

## Overview of model structure and includes files¶

The pages listed below provide a comprehensive documentation of the equations and the workflow when solving a MESSAGEix model instance. The documentation is generated to a large extent from mark-up comments in the GAMS code.

## Scientific programming API documentation¶

For a comprehensive documentation of the scientific programming APIs, please see the documentation of the ixmp package at software.ene.iiasa.ac.at/ixmp.