Most users will have
ixmp installed automatically when installing MESSAGEix.
The sections below cover other use cases.
Ensure you have first read the prerequisites for understanding and using MESSAGEix. These include specific points of knowledge that are necessary to understand these instructions and choose among different installation options.
Use cases for installing ixmp directly include:
Installing ixmp to be used alone (i.e., with models or frameworks other than MESSAGEix). Follow the sections:
Installing ixmp from source, for development purposes, e.g. to be used with a source install of
message_ix. Follow the sections:
Installing the rixmp R package, to use the
ixmp, alone, from R. Again, to use MESSAGEix from R, it is sufficient to install
rmessageix; and not necessary to also/separately install
ixmp requires GAMS.
Run the installer.
Ensure that the
PATHenvironment variable on your system includes the path to the GAMS program:
on Windows, in the GAMS installer…
Check the box labeled “Use advanced installation mode.”
Check the box labeled “Add GAMS directory to PATH environment variable” on the Advanced Options page.
on other platforms (macOS or Linux), add the following line to a file such as
message_ix requires GAMS version 24.8;
ixmp has no minimum requirement per se.
The latest version is recommended.
GAMS is proprietary software and requires a license to solve optimization problems.
To run both the
message_ix tutorials and test suites, a “free demonstration” license is required; the free license is suitable for these small models.
Versions of GAMS up to version 29 include such a license with the installer; since version 30, the free demo license is no longer included, but may be requested via the GAMS website.
If you only have a license for an older version of GAMS, install both the older and the latest versions.
ixmp.reporting.Reporter.visualize() uses Graphviz, a program for graph visualization.
Installing ixmp causes the python
graphviz package to be installed.
If you want to use
visualize() or run the test suite, the Graphviz program itself must also be installed; otherwise it is optional.
If you install
ixmp using Anaconda, Graphviz is installed automatically via its conda-forge package.
For other methods of installation, see the Graphviz download page for downloads and instructions for your system.
After installing GAMS, we recommend that new users install Anaconda, and then use it to install
Advanced users may choose to install
ixmp from source code (next section).
Open a command prompt. We recommend Windows users use the “Anaconda Prompt” to avoid issues with permissions and environment variables when installing and using
ixmp. This program is available in the Windows Start menu after installing Anaconda.
Configure conda to install
ixmpfrom the conda-forge channel 2:
$ conda config --prepend channels conda-forge
Create a new conda enviroment. This step is required if using Anaconda, but optional if using Miniconda. This example uses the name
ixmp_env, but you can use any name of your choice:
$ conda create --name ixmp_env $ conda activate ixmp_env
ixmppackage into the current environment (either
base, or another name from step 7, e.g.
$ conda install -c conda-forge ixmp
See the conda glossary for the differences between Anaconda and Miniconda, and the definitions of the terms ‘channel’ and ‘environment’ here.
The ‘$’ character at the start of these lines indicates that the command text should be entered in the terminal or prompt, depending on the operating system. Do not retype the ‘$’ character itself.
When using Anaconda (not Miniconda), steps (5) through (8) can also be performed using the graphical Anaconda Navigator. See the Anaconda Navigator documentation for how to perform the various steps.
(Optional) If you intend to contribute changes to ixmp, first register a Github account, and fork the ixmp repository. This will create a new repository
<user>/ixmp. (Please also see Contributing to development.)
Clone either the main repository, or your fork; using the Github Desktop client, or the command line:
$ git clone firstname.lastname@example.org:iiasa/ixmp.git # or: $ git clone email@example.com:USER/ixmp.git
Open a command prompt in the
ixmp/directory that is created, and type:
$ pip install --editable .[docs,tests,tutorial]
--editableflag ensures that changes to the source code are picked up every time
import ixmpis used in Python code. The
[docs,tests,tutorial]extra dependencies ensure additional dependencies are installed.
(Optional) Run the built-in test suite to check that
ixmpfunctions correctly on your system:
rixmp is the R interface to
ixmp; see its documentaiton.
You only need to install
rixmp if you intend to use
ixmp from R, rather than from Python.
ixmp from source, per the section above.
Install R. Ensure that your
PATHenvironment variable is configured correctly so that the
Rscriptexecutable is available.
Ensure the the R version installed is either 32- or 64-bit (and >= 3.5.0), consistently with GAMS and Java. Having both 32- and 64-bit versions of R, or mixed 32- and 64-bit versions of different packages, can cause errors.
Open a command prompt in the
ixmp/directory. Type the following commands to build, then install,
rixmpand its dependencies, including reticulate:
$ R CMD build rixmp
Check that there is only one
.zipfile in the folder, then run:
# On Windows $ R CMD INSTALL rixmp_*.zip # Other operating systems $ R CMD INSTALL rixmp_*.tar.gz
(Optional) Install IRKernel, which allows running R code in Jupyter notebooks (see the link for instructions).
(Optional) Check that the R interface works by using the built-in test suite to run the R tutorial notebooks:
$ pytest -m rixmp
ixmp show-versions on the command line to check that you have all dependencies installed, or when reporting issues.
For Anaconda users experiencing problems during installation of ixmp, check that the following paths are part of the
PATH environment variable, and add them if missing:
C:\[YOUR ANACONDA LOCATION]\Anaconda3; C:\[YOUR ANACONDA LOCATION]\Anaconda3\Scripts; C:\[YOUR ANACONDA LOCATION]\Anaconda3\Library\bin;
Developers making changes to the
ixmp source may need one or more of the following tools.
Users developing models using existing functionality should not need these tools.
Use one of:
- Java Development Kit (JDK)
Install the Java Development Kit (JDK) for Java SE version 8 from https://www.oracle.com/technetwork/java/javase/downloads/index.html
At this point, ixmp is not compatible with JAVA SE 9.
Follow the JDK website instructions to set the
JAVA_HOMEenvironment variable; if
JAVA_HOMEdoes not exist, add it as a new system variable.
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).
Do not overwrite the existing
PATHenvironment variable, but add to the list of existing paths.
For installing or modifying some R packages on Windows.