Installation

Install system dependencies

GAMS (required)

MESSAGEix 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-MACRO and MACRO require GAMS 24.8.1 or later (see MACRO.GAMS_min_version) The latest version is recommended.

GAMS is proprietary software and requires a license to solve optimization problems. To run both the message_ix and ixmp 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 (optional)

reporting.Reporter.visualize() uses Graphviz, a program for graph visualization. Installing message_ix 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 MESSAGEix 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 MESSAGEix via Anaconda

After installing GAMS, we recommend that new users install Anaconda, and then use it to install MESSAGEix. Advanced users may choose to install MESSAGEix 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 MESSAGEix. This program is available in the Windows Start menu after installing Anaconda.

  3. Install the message-ix package:

    $ conda install -c conda-forge message-ix

Install MESSAGEix from source

  1. Install ixmp from source.

  2. (Optional) If you intend to contribute changes to MESSAGEix, first register a Github account, and fork the message_ix repository. This will create a new repository <user>/message_ix. (Please also see Contributing to MESSAGEix development.)

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

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

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

  4. Open a command prompt in the message_ix directory and type:

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

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

  5. (Optional) If you will be using MESSAGE_master.gms outside of Python message_ix to run MESSAGEix, you will likely modify this file, but will not want to commit these changes to Git. Set the Git “assume unchanged” bit for this file:

    $ git update-index --assume-unchanged message_ix/model/MESSAGE_master.gms

    To unset the bit, use --no-assume-unchanged. See the Git documentation for more details.

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

    $ pytest

Common issues

No JVM shared library file (jvm.dll) found

If you get an error containing “No JVM shared library file (jvm.dll) found” when creating a Platform object (e.g. mp = ix.Platform(driver='HSQLDB')), it is likely that you need to set the JAVA_HOME environment variable (see for example these instructions).

Copy GAMS model files for editing

By default, the GAMS files containing the mathematical model core are installed with message_ix (e.g., in your Python site-packages directory). Many users will simply want to run MESSAGEix, or use the Python or R APIs to manipulate data, parameters and scenarios. For these uses, direct editing of the GAMS files is not necessary.

To edit the files directly—to change the mathematical formulation, such as adding new types of parameters, constraints, etc.—use the message-ix command-line program to copy the model files in a directory of your choice:

$ message-ix copy-model /path/for/model/files

You can also set the message model dir configuration key so that this copy of the files is used by default:

$ message-ix config set "message model dir" /path/for/model/files

…or do both in one step:

$ message-ix copy-model --set-default /path/for/model/files