Quick-start guide to running a MESSAGEix-GLOBIOM baseline model

This starting guide is for researchers at IIASA or external collaborators, who are not constant developers of message_ix and related software. It should support running scenarios of different models of the MESSAGEix-GLOBIOM family.

Note

  • This is only a guide, based on some users’ experiences. It is very possible that the following steps for running a scenario will not work directly on your machine.

  • This guide does not cover how to contribute to message_ix_models. If you wish to contribute, please read and understand our contribution guide completely.

Prerequisites

The following prerequisites are necessary to be able to follow the steps of this guide and be able to run scenarios. Most of these prerequisites are analogous to the prerequisites of using message_ix.

Knowledge & skills

Please go through the Prerequisite knowledge & skills in the message_ix documentation. You should understand all of the basic pre-requisites, and most of the advanced pre-requisites. Understanding the concept of virtual environments is especially important. If needed, please educate yourself in the specific areas.

Going through this guide, some error messages might occur. Most of them can be fixed by understanding the error message itself. Understanding the Python Traceback might support with reading and interpreting an error message in Python. If an error message is not directly understandable, a web search is often very helpful. Stack Overflow is a great source of support, and most likely someone else already had the same question on how to solve an error.

If you couldn’t find a solution on the internet, please open an issue on the main repository or another repository of the message_ix software stack, as appropriate.

Installation

Go through the installation process of message_ix_models via Installation.

Tip

If you run into issues related to installing message_ix, please also check Common issues in its installation docs.

Preparation

When using message_ix_models, you will store and access data for distinct scenarios. ixmp provides this storage service via Platforms. Each platform corresponds to a database (DB), either local to your system or remote. To receive the data for a global model, you can either configure access to an existing, remote DB; or download a model ‘snapshot’ file from Zenodo and load it into your local DB.

Configure access to existing DBs

Note

The existing DBs at IIASA facilities are not publicly accessible. If you are interested in collaborating, please reach out to the MESSAGEix team.

Every model variant and project documented with message_ix_models and message_data should contain information about the platform where associated scenarios are stored. (If not, reach out to the person(s) responsible for those variants/projects and ask them.) ixmp keeps track of these platforms. See the message_ix_models Command-line interface, and the ixmp Configuration documentation for how to configure these. [1] To access the IIASA DBs:

  • <Computer> is x8oda.iiasa.ac.at,

  • <PORT> is 1521,

  • <PATH> will be pIXMP2.iiasa.ac.at for most modern DBs, but could also be pIXMP1.iiasa.ac.at on older instances.

Note

If you are a collaborator, but do not know the <USERNAME> and/or <PASSWORD> of the platform you want to use, please reach out to the MESSAGEix Community Manager, currently @glatterf42.

If you do not have access to the IIASA DBs, you need to configure a local DB. This is appropriate for small applications (i.e. less than hundreds of scenarios). Per the ixmp “Configuration” docs linked above, in your call to mix-models config ... you can:

  • replace oracle with hsqldb,

  • replace the URL <COMPUTER>:<PORT>/<PATH> with a path on your system, and

  • omit <USERNAME> and <PASSWORD>.

For more complex modelling needs and required infrastructure, please reach out to the MESSAGEix team.

Download snapshot from Zenodo

The latest version of a MESSAGEix-GLOBIOM baseline model can be found on Zenodo. For convenience, the function snapshot.load() (documented at Load model snapshots (model.snapshot)) automates the following steps, but you can also perform them manually:

  • Fetch the snapshot from Zenodo. To do this manually, do one of the following:

    • Use a CLI command like:

      mix-models fetch snapshot-1

    • Call pooch.fetch().

    • Download it from Zenodo via your browser and extract the .xlsx data file from the .zip archive.

  • Pass the file to read_excel() to read it into a Scenario and store it in a local DB via commit().