Most users will have the ix modeling platform installed automatically when installing MESSAGEix.
The sections below cover other use cases:
- Installing ixmp to be used alone (i.e., with models or frameworks other than MESSAGEix):
- Installing ixmp from source, for development purposes: see Install ixmp from source.
- Installing the R API to ixmp:
A high-quality desktop computer or laptop is sufficient for most purposes using the ix modeling platform.
ixmp requires GAMS.
Download the latest version of GAMS for your operating system; run the installer.
Add GAMS to the
- 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 macOS or Linux, add the following line to your
For using GAMS to solve numerical optimisation problems, you need to install the latest version of GAMS (in particular 24.8 or higher). If you only have a license for an older version, install both the older and the latest version of GAMS.
After installing GAMS, we recommend that new users install Anaconda, and then use it to install ixmp. Advanced users may choose to install ixmp from source code (next section).
Install Python via Anaconda. We recommend the latest version, i.e., Python 3.6+.
Open a command prompt. We recommend Windows users use the “Anaconda Prompt” to avoid permissions issues when installing and using ixmp. This program is available in the Windows Start menu after installing Anaconda.
$ conda install -c conda-forge ixmp
(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
Clone either the main repository, or your fork; using the Github Desktop client, or the command line:
$ git clone email@example.com:iiasa/ixmp.git # or: $ git clone firstname.lastname@example.org:USER/ixmp.git
Open a command prompt in the
ixmpdirectory and type:
$ pip install --editable .
--editableflag ensures that changes to the source code are picked up every time
import ixmpis used in Python code.
(Optional) Run the built-in test suite to check that ixmp functions correctly on your system:
$ pip install --editable .[tests] $ py.test
See also the rixmp documentation.
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.
Enter the directory
rixmp/and use R to build and install the package and its dependencies, including reticulate:
$ cd rixmp $ Rscript -e "install.packages(c('knitr', 'reticulate'), repos='http://cran.rstudio.com/')" $ R CMD build .
Check that there is only one
*tar.gzin the folder:
$ R CMD INSTALL rixmp_*
(Optional) Run the built-in test suite to check that ixmp and rixmp functions, as in Install ixmp from source 6. (installing the R
devtoolspackage might be a pre-requisite). In the
$ py.test --test-r
(Optional) For working with Jupyter notebooks using R, install the IR kernel.
(Optional) Install Rtools and add the path to the environment variables.
Developers making changes to the ixmp source may need one or more of the following tools. Users developing models using existing ixmp functionality should not need these tools.
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 as new system variable.
Update your PATH environment 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 PATH environment variable, but add to the list of existing paths.
Git. Use one of:
In addition, set up an account at https://github.com, and familiarize yourself with forking and cloning repositories, as well as pulling, committing and pushing changes.
For Anaconda users experiencing problems during installation of ixmp,
Anaconda might not have been added to the PATH system variable properly.
install.bat fails, 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.