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 --editable .[tests]
    $ py.test
    

Install rixmp

See also the rixmp documentation.

  1. Install R.

    Warning

    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.

  2. 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 .
    
  3. Check that there is only one *tar.gz in the folder:

    $ R CMD INSTALL rixmp_*
    
  4. (Optional) Run the built-in test suite to check that ixmp and rixmp functions, as in Install ixmp from source 6. (installing the R devtools package might be a pre-requisite). In the ixmp directory type:

    $ py.test --test-r
    
  5. (Optional) For working with Jupyter notebooks using R, install the IR kernel.

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

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.

  • 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

      Note

      At this point, ixmp is not compatible with JAVA SE 9.

    • Follow the JDK website instructions to set the JAVA_HOME environment variable; if JAVA_HOME does 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).

      Warning

      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.

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.