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.
To support a variety of complex use-cases, the MESSAGEix stack takes configuration and inputs from several places:
ixmp keeps track of named Platforms and their associated databases, and stores information in its
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]/[SERVICENAME] [USERNAME] [PASSWORD]
You may also want to make this the default platform.
Unless told otherwise,
Platform objects without any arguments (
mp = ixmp.Platform()); this loads the default platform.
Set the default:
$ ixmp platform add default [PLATFORMNAME]
message_ix stores only one configuration value in
'message model dir', the path to the GAMS model files.
MESSAGEix-GLOBIOM uses the GAMS model files from the current
master branch, so you should not set this, or unset it when using
message_ix_models will use the
"message_local_data" for local data, if it is set and not overridden.
[COMPUTER]is in this case either the hostname or the IP address.
Some code responds to environment variables.
For example, ixmp responds to
IXMP_DATA, which tells it where to find the file
message_ix_models responds to
MESSAGE_LOCAL_DATA; see the discussion of local data.
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:
--opt0is an option that (potentially) affects any command, including the subcommands
arg1are an option and mandatory argument to the command
cmd1. They might not have any relevance to other
cmd3are distinct subcommands of
They may respond to
arg1, and to
--opt0; at least, they must not contradict them.
They each may have their own options and arguments, which can be distinct.
--help for any (sub)command to read about its behaviour.
If the help text does not make the behaviour clear, file an issue.
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.
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.
mix-models --help describes these:
$ mix-models --help 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, e.g.: mix-models cd-links --help mix-models cd-links run --help The top-level options --platform, --model, and --scenario are used by commands that access specific message_ix scenarios; these can also be specified with --url. For more information, see https://docs.messageix.org/projects/models2/en/latest/cli.html Options: --url ixmp://PLATFORM/MODEL/SCENARIO[#VERSION] Scenario URL. --platform PLATFORM Configured platform name. --model MODEL Model name for some commands. --scenario SCENARIO Scenario name for some commands. --version INTEGER Scenario version. --local-data PATH Base path for local data. -v, --verbose Print DEBUG-level log messages. --help Show this message and exit. Commands: cd-links CD-LINKS project. dl Retrieve data from primary sources. engage ENGAGE project. iiasapp Import power plant capacity. material Model with materials accounting. prep-submission Prepare scenarios for submission to database. report Postprocess results. res MESSAGE-GLOBIOM reference energy system (RES). techs Export data from data/technology.yaml to CSV. transport MESSAGEix-Transport variant.
To explain further:
By default, message_data connects to the default ixmp Platform. These options direct it to work with a different Platform.
--model MODEL --scenario SCENARIOor
Many commands use an existing
Scenarioas 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
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
This option is a counterpart to the top-level
--url/--model/--scenariooptions. 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-modelgives the model name.
Current code generates a variety of fixed (non-configurable) scenario names; use
--helpfor each command to see which.
To employ these in new code, refer to the example of existing code.