MESSAGEix requires GAMS.
Run the installer.
Ensure that the
PATHenvironment 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
$ export PATH=$PATH:/path/to/gams-directory-with-gams-binary
MESSAGE-MACRO and MACRO require GAMS 24.8.1 or later (see
The latest version is recommended.
GAMS is proprietary software and requires a license to solve optimization problems.
To run both the
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.
If you only have a license for an older version of GAMS, install both the older and the latest versions.
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.
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).
Open a command prompt. Windows users should use the “Anaconda Prompt” to avoid issues with permissions and environment variables when installing and using MESSAGEix. This program is available in the Windows Start menu after installing Anaconda.
Configure conda to install
message_ixfrom the conda-forge channel 2:
$ conda config --prepend channels conda-forge
Create a new conda enviroment. This step is required if using Anaconda, and optional if using Miniconda. This example uses the name
message, but you can use any name of your choice:
$ conda create --name message $ conda activate message
message-ixpackage into the current environment (either
base, or another name from step 7, e.g.
$ conda install message-ix
Check your install by running some commands from the command-line interface:
# Show versions of message_ix, ixmp, and key dependencies $ message-ix show-versions # Show the contents of the default local Platform (empty on install) $ message-ix --platform=default list
See the conda glossary for the differences between Anaconda and Miniconda, and the definitions of the terms ‘channel’ and ‘environment’ here.
The ‘$’ character at the start of these lines indicates that the command text should be entered in the terminal or prompt, depending on the operating system. Do not retype the ‘$’ character itself.
Notice that conda uses the hyphen (‘-’) in package names, different from the underscore (‘_’) used in Python when importing the package.
Install ixmp from source.
(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.)
Clone either the main repository, or your fork; using the Github Desktop client, or the command line:
$ git clone firstname.lastname@example.org:iiasa/message_ix.git # or: $ git clone email@example.com:USER/message_ix.git
Open a command prompt in the
message_ixdirectory and type:
$ pip install --editable .[docs,reporting,tests,tutorial]
--editableflag ensures that changes to the source code are picked up every time
import message_ixis used in Python code. The
[docs,reporting,tests,tutorial]extra requirements ensure additional dependencies are installed.
(Optional) If you will be using
MESSAGE_master.gmsoutside of Python
message_ixto 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.
(Optional) Run the built-in test suite to check that MESSAGEix functions correctly on your system:
rmessageix is the R interface to MESSAGEix; see R API (rmessageix).
Install MESSAGEix from source, per the previous section. Then:
Open a command prompt in the
message_ix/directory and type the following commands to build, then install,
$ R CMD build rmessageix $ R CMD INSTALL rmessageix_*.zip
(Optional) Install IRkernel, which allows running R code in Jupyter notebooks (see the link for instructions). Check that the R interface works by using the built-in test suite to run the R tutorial notebooks:
$ pytest -m rmessageix
By default, the GAMS files containing the mathematical model core are installed
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