Installation

Most users will have the ix modeling platform installed automatically when installing MESSAGEix.

The sections below cover other use cases:

Contents:

Technical requirements

A high-quality desktop computer or laptop is sufficient for most purposes using the ix modeling platform.

Install GAMS

ixmp requires GAMS.

  1. Download the latest version of GAMS for your operating system; run the installer.

  2. Add GAMS to the PATH environment variable:

    • 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 .bash_profile (Mac) or .bashrc (Linux):

      export PATH=$PATH:/path/to/gams-directory-with-gams-binary

Note

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.

Install ixmp via Anaconda

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).

  1. Install Python via Anaconda. We recommend the latest version, i.e., Python 3.6+.

  2. 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.

  3. Install the ixmp package:

    $ conda install -c conda-forge ixmp

Install ixmp from source

  1. (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.

  2. Clone either the main repository, or your fork; using the Github Desktop client, or the command line:

    $ git clone git@github.com:iiasa/ixmp.git

# or:
$ git clone git@github.com:USER/ixmp.git

  3. Open a command prompt in the ixmp directory and type:

    $ pip install --editable .

    The --editable flag ensures that changes to the source code are picked up every time import ixmp is used in Python code.

  4. (Optional) Run the built-in test suite to check that ixmp functions correctly on your system:

    $ pip install .[tests]
$ py.test

Install rixmp

First, read the rixmp documentation to understand the difference between rixmp and rixmp.legacy.

  1. Install R.

    Warning

    Ensure the 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.

  2. Depending on your platform:

    • (Windows) Run the script install.bat included with ixmp.

    • (Linux and macOS) 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'))"
$ R CMD build .
$ R CMD INSTALL *.tar.gz

  3. (Optional) Install Rtools and add the path to the environment variables.

  4. (Optional) For working with Jupyter notebooks using R, install the IR kernel.

Install development tools

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.

Troubleshooting

For Anaconda users experiencing problems during installation of ixmp, Anaconda might not have been added to the PATH system variable properly. So, if 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.