Installation

A desktop or laptop computer is sufficient for most purposes using ixmp. Most users will have ixmp installed automatically when installing MESSAGEix.

The sections below cover other use cases:

Contents:

Install system dependencies

GAMS

ixmp requires GAMS.

  1. Download GAMS for your operating system; either the latest version or version 29 (see note below).

  2. Run the installer.

  3. Ensure that the PATH environment 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 ~/.bash_profile (macOS), ~/.bashrc, or ~/.profile:

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

Note

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 ixmp and 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.

Note

If you only have a license for an older version of GAMS, install both the older and the latest versions.

Graphviz

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

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; currently Python 3.8.

  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 [email protected]:iiasa/ixmp.git

# or:
$ git clone [email protected]:USER/ixmp.git

  3. Open a command prompt in the ixmp/ directory that is created, and type:

    $ pip install --editable .[docs,tests,tutorial]

    The --editable flag ensures that changes to the source code are picked up every time import ixmp is used in Python code. The [docs,tests,tutorial] extra dependencies ensure additional dependencies are installed.

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

    $ pytest

Install development tools

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.

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.

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 it as a 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.

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, then run:

    $ 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:

    $ pytest -m rixmp

  5. (Optional) To use rixmp in Jupyter notebooks, install the IR kernel.

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

Troubleshooting

Run 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;