Command-line interface

This page describes how to use the mix-models command-line interface (CLI) to perform common tasks. mix-models is organized into commands and subcommands, sometimes in multiple levels. Our goal is that the semantics of all commands are similar, so that interacting with each command feels similar.

Controlling CLI behaviour

To support a variety of complex use-cases, the MESSAGEix stack takes configuration and inputs from several places:

ixmp configuration file: config.json

ixmp keeps track of named Platforms and their associated databases, and stores information in its config.json file. See Configuration in the documentation. List existing platforms:

$ ixmp platform list

To add a specific database, you can use the ixmp CLI [1]:

$ ixmp platform add <PLATFORMNAME> jdbc oracle <COMPUTER>:<PORT>/<PATH> <USERNAME> <PASSWORD>

You may also want to make this the default platform. Unless told otherwise, message_ix_models creates Platform objects without any arguments (mp = ixmp.Platform()); this loads the default platform. Set the default:

$ ixmp platform add default <PLATFORMNAME>

message_ix recognizes the following config.json value:

message_model_dir

Path to the GAMS model files. Most code in MESSAGEix-GLOBIOM expects the GAMS model files from the current message_ix main branch, so you should not set this, or unset it when using message_ix_models.

message_ix_models recognizes the following 2 config.json values:

message_local_data

Path to local data, if it is set and not overridden.

no_message_data

If not set or False, then the CLI displays a warning message if the private message_data package is not installed:

Warning: message_data is not installed or cannot be imported; see the documentation via --help

If set to True, then the message is suppressed:

$ mix-models config set no_message_data true

Environment variables

Some code responds to environment variables. For example, ixmp responds to IXMP_DATA, which tells it where to find the file config.json.

message_ix_models responds to MESSAGE_LOCAL_DATA; see the discussion of local data.

CLI parameters (arguments and options)

Each command has zero or more arguments and options. Arguments are mandatory and follow the command name in a certain order. Options, as the name implies, are not required. If an option is omitted, a default value is used; the code and --help text make clear what the default behaviour is.

Arguments and options are hierarchical. Consider the following examples:

$ mix-data --opt0=foo cmd1 --opt1=bar arg1 cmd2 --opt2=baz arg2
$ mix-data --opt0=foo cmd1            arg1 cmd3 --opt3=baz arg3a arg3b

In these examples:

  • --opt0 is an option that (potentially) affects any command, including the subcommands cmd2 or cmd3.

  • --opt1 and arg1 are an option and mandatory argument to the command cmd1. They might not have any relevance to other mix-models commands.

  • cmd2 and cmd3 are distinct subcommands of cmd1.

    • They may respond to --opt1 and arg1, and to --opt0; at least, they must not contradict them.

    • They each may have their own options and arguments, which can be distinct.

Tip

Use --help for any (sub)command to read about its behaviour. If the help text does not make the behaviour clear, file an issue.

Configuration files and metadata

For some features of the code, the default behaviour is very elaborate and serves for most uses; but we also provide the option to override it. This default behaviour or optional behaviour is defined by reading an input file. These are stored in the package data directory.

For example, mix-models report loads reporting configuration from message_ix_models/data/report/global.yaml, a YAML file with hundreds of lines. Optionally, a different file can be used:

$ mix-models report --config other

…looks for a file other.yaml in the local data directory or current working directory. Or:

$ mix-models report --config /path/to/another/file.yaml

…can be used to point to a file in a different directory.

Important CLI options and commands

Top-level options and commands

mix-models --help describes these:

Usage: mix-models [OPTIONS] COMMAND [ARGS]...

  Command-line interface for MESSAGEix-GLOBIOM model tools.

  Every tool and script in this repository is accessible through this CLI.
  Scripts are grouped into commands and sub-commands. For help on specific
  (sub)commands, use --help, for instance:

          mix-models report --help
          mix-models ssp gen-structures --help

  The top-level options --platform, --model, and --scenario are used by
  commands that access specific MESSAGEix scenarios in a specific ixmp
  platform/database; these can also be specified with --url.

  For complete documentation, see
  https://docs.messageix.org/projects/models/en/latest/cli.html

Options:
  --url ixmp://PLATFORM/MODEL/SCENARIO[#VERSION]
                                  Scenario URL.
  --platform PLATFORM             ixmp platform name.
  --model MODEL                   Model name for some commands.
  --scenario SCENARIO             Scenario name for some commands.
  --version INTEGER               Scenario version for some commands.
  --local-data PATH               Base path for local data.
  -v, --verbose                   Print DEBUG-level log messages.
  --help                          Show this message and exit.

Commands:
  buildings         MESSAGEix-Buildings model.
  cd-links          CD-LINKS project.
  config            Get and set configuration keys.
  covid             COVID project.
  engage            ENGAGE project.
  export-test-data  Prepare data for testing.
  fetch             Retrieve data from primary sources.
  iiasapp           Import power plant capacity.
  last-log          Show the location of the last log file, if any.
  material          Model with materials accounting.
  model             MESSAGEix-GLOBIOM reference energy system (RES).
  navigate          NAVIGATE project.
  prep-submission   Prepare scenarios for submission to an IIASA Scenario...
  report            Postprocess results.
  res               MESSAGEix-GLOBIOM reference energy system (RES).
  ssp               Shared Socioeconomic Pathways (SSP) project.
  techs             Export metadata to technology.csv.
  testing           Manipulate test data.
  transport         MESSAGEix-Transport variant.
  water-ix          MESSAGEix-Water and Nexus variant.

Further information about the top-level options:

--platform PLATFORM or --url

By default, message_data connects to the default ixmp Platform. These options direct it to work with a different Platform.

--model MODEL --scenario SCENARIO or --url

Many commands use an existing Scenario as a starting point, and begin by cloning that Scenario to a new (model name, scenario name). For any such command, these top-level options define the starting point/initial Scenario to clone/‘baseline’.

In contrast, see --output-model, below.

Common options

Since message_ix_models.model and message_ix_models.project codes often perform similar tasks, their CLI options and arguments are provided in util.click for easy re-use. These include:

SSP argument

This takes one of the values ‘SSP1’, ‘SSP2’, or ‘SSP3’.

Commands that will not work for one or more of the SSPs should check the argument value given by the user and raise NotImplementedError.

--output-model NAME option

This option is a counterpart to the top-level --url, --model, or --scenario options. A command that starts from one Scenario, and builds one or more Scenarios from it will clone to a new (model name, scenario name); --output-model gives the model name.

Current code generates a variety of fixed (non-configurable) scenario names; use --help for each command to see which.

To employ these in new code, refer to the example of existing code.