The ix modeling platform (ixmp)
The ix modeling platform (ixmp) is a data warehouse for high-powered scenario analysis, with interfaces to Python and R for efficient scientific workflows and effective data pre- and post-processing, and a structured database backend for version-controlled data management.
This repository contains the core and application programming interfaces (API) for the ix modeling platform (ixmp), as well as a number of tutorials and examples for a generic model instance based on Dantzig's transport problem.
Copyright 2017-18 IIASA Energy Program
The platform package is licensed under the Apache License, Version 2.0 (the "License"); you may not use the files in this repository except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
Please refer to the NOTICE for details and the user guidelines.
Documentation and tutorial
Documentation of ixmp and the MESSAGEix framework is automatically created from the documentation of the Python and R API packages. The online documentation is synchronyzed with the contents of the master branch of the repositories www.github.com/iiasa/ixmp and www.github.com/iiasa/message_ix.
There are a number of tutorials to get started with ixmp. You may want to try the tutorial/transport...
Follow the instructions in doc/README for building the ixmp documentation including the scientific programming API manuals on your local machine.
Please cite the following manuscript when using the MESSAGEix framework and/or the ix modeling platform for scientific publications or technical reports:
Daniel Huppmann, Matthew Gidden, Oliver Fricko, Peter Kolp, Clara Orthofer, Michael Pimmer, Nikolay Kushin, Adriano Vinca, Alessio Mastrucci, Keywan Riahi, and Volker Krey.
"The |MESSAGEix| Integrated Assessment Model and the ix modeling platform".
Environmental Modelling & Software 112:143-156, 2019.
electronic pre-print available at pure.iiasa.ac.at/15157/
Install from Conda (New Users)
Install Python via Anaconda. We recommend the latest version, e.g., Python 3.6+.
Install GAMS. Importantly:
- Check the box labeled
Use advanced installation mode
- Check the box labeled
Add GAMS directory to PATH environment variableon the Advanced Options page.
- Check the box labeled
Open a command prompt and type
conda install -c conda-forge ixmp
Install from Source (Advanced Users)
Install the Java Development Kit (Java SE 8) and set the environment variable
JAVA_HOMEper the JDK website instructions; if
JAVA_HOMEdoes not exist, add as new system variable. At this point, ixmp is not compatible with JAVA SE 9.
Update yourDo not overwrite the existing `PATH` environment variable, but add to the list of existing paths.
PATHenvironment variable to point to the JRE binaries and server installation (e.g.,
C:\Program Files\Java\jdk[YOUR JDK VERSION]\jre\bin\,
C:\Program Files\Java\jdk[YOUR JDK VERSION]\jre\bin\server).
Install the latest version of GAMS, otherwise, the export to GDX may not work properly (visit www.gams.com). If you only have a license for an older verson of GAMS, install both versions. Note that for using the integrated MESSAGEix-MACRO model, it is important to install a GAMS version >= 24.8.1.
PATHenvironment variable to point to the GAMS installation (e.g.
C:\GAMS\win64\24.8); again do not overwrite existing
PATHbut rather add to end.
Install some version of Python (2.7 is supported, but 3.6 or higher is recommended). Anaconda is a good choice for users not yet familiar with the language (during installation select add anaconda to PATH system variable)
Install a Windows C++ Compiler
Install a version of
git, (see, e.g., the website)
Additional dependencies for R users
Make sure the R version installed is either 32 OR 64 bit (and >= 3.3.0), consistently with GAMS and Java. Having both 32 and 64 bit generates error.
optparsevia the R package manager
Two alternative options are available:
use the package developed in Python, requires the
reticulateR package (it will allow to install/use
use specific R packages (less available functionalities), requires the
rJavaR package (it will allow to install/use
Install Rtools and add the path to the environment variables
For working with Jupyter notebooks using R, install the IRkernel.
Installing the ix modeling platform
Fork this repository and clone the forked repository (
<user>/ixmp) to your machine. To fork the repository, look for the fork button in the top right at iiasa/ixmp. Add
upstreamto your clone.
We recommend GitKraken for users who prefer a graphical user interface application to work with Github (as opposed to the command line).
Open a command prompt in the new
ixmpdirectory and type:
$ pip install .
(Optional) Run tests to check that
ixmpworks on your system:
$ pip install .[tests] $ py.test tests
Notes and Warnings
For Anaconda users experiencing problems during installation of ixmp, Anaconda might not have been added to the PATH system variable properly. So, if
install.batjust opens and collapses again, check if:
C:\[YOUR ANACONDA LOCATION]\Anaconda3; C:\[YOUR ANACONDA LOCATION]\Anaconda3\Scripts; C:\[YOUR ANACONDA LOCATION]\Anaconda3\Library\bin;
are all part of the PATH system variable. If they are not there, add them.
Install dependencies for the documentation:
$ pip install .[doc]
Navigate to the
docdirectory and build the documentation:
$ cd doc $ make html
The built documentation appears in
doc/build/html/index.html; open this file
using a web browser.