Installation

Install GAMS

MESSAGEix requires GAMS.

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

  2. Add GAMS to the PATH environment variable. This is required in order for MESSAGEix to run the mathematical model core:

    • 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
      

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, 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 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 .
    
  5. (Optional) Run the built-in test suite to check that MESSAGEix functions correctly on your system:

    $ pip install .[tests]
    $ py.test tests
    

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