message_ix package

MESSAGEix models are created using the message_ix.Scenario class. Several utility methods are also provided in the module message_ix.utils.

class message_ix.Scenario(mp, model, scenario=None, version=None, annotation=None, cache=False, clone=None, **kwargs)

MESSAGEix Scenario.

This class extends ixmp.Scenario and inherits all its methods. It defines additional methods specific to MESSAGEix.

add_cat(name, cat, keys, is_unique=False)

Map elements from keys to category cat within set name.

  • name (str) – Name of the set.
  • cat (str) – Name of the category.
  • keys (str or list of str) – Element keys to be added to the category mapping.
  • is_unique (bool, optional) – If True, then cat must have only one element. An exception is raised if cat already has an element, or if len(keys) > 1.

Add sets related to temporal dimensions of the model.

Parameters:data (dict-like) – Year sets. “year” is a required key. “firstmodelyear” is optional; if not provided, the first element of “year” is used.


>>> s = message_ix.Scenario()
>>> s.add_horizon({'year': [2010, 2020]})
>>> s.add_horizon({'year': [2010, 2020], 'firstmodelyear': 2020})

Add sets related to spatial dimensions of the model.

Parameters:data (dict) –

Mapping of levelmember. Each member may be:

  • A single label for elements.
  • An iterable of labels for elements.
  • A recursive dict following the same convention, defining sub-levels and their members.


>>> s = message_ix.Scenario()
>>> s.add_spatial_sets({'country': 'Austria'})
>>> s.add_spatial_sets({'country': ['Austria', 'Germany']})
>>> s.add_spatial_sets({'country': {
...     'Austria': {'state': ['Vienna', 'Lower Austria']}}})
cat(name, cat)

return a list of all set elements mapped to a category

  • name (string) – name of the set
  • cat (string) – name of the category

return a list of all categories for a set

Parameters:name (string) – name of the set
clone(model=None, scenario=None, annotation=None, keep_solution=True, first_model_year=None, **kwargs)

clone the current scenario and return the new scenario

  • model (string) – new model name
  • scenario (string) – new scenario name
  • annotation (string) – explanatory comment (optional)
  • keep_solution (boolean, default, True) – indicator whether to include an existing solution in the cloned scenario
  • first_model_year (int, default None) – new first model year in cloned scenario (‘slicing’, only available for MESSAGE-scheme scenarios)

Returns True if scenario currently has a solution

read_excel(fname, add_units=False, commit_steps=False)

Read Excel file data and load into the scenario.

  • fname (string) – path to file
  • add_units (bool) – add missing units, if any, to the platform instance. default: False
  • commit_steps (bool) – commit changes after every data addition. default: False
rename(name, mapping, keep=False)

Rename an element in a set

  • name (str) – name of the set to change (e.g., ‘technology’)
  • mapping (str) – mapping of old (current) to new set element names
  • keep (bool, optional, default: False) – keep the old values in the model
solve(model='MESSAGE', **kwargs)

Solve the Scenario.

By default, ixmp.Scenario.solve() is called with “MESSAGE” as the model argument; see the documentation of that method for other arguments. model may also be overwritten, e.g.:

>>> s.solve(model='MESSAGE-MACRO')

Save a scenario as an Excel file. NOTE: Cannot export solution currently (only model data) due to limitations in excel sheet names (cannot have multiple sheet names which are identical except for upper/lower case).

Parameters:fname (string) – path to file
vintage_and_active_years(ya_args=None, in_horizon=True)

Return sets of vintage and active years for use in data input.

For a valid pair (year_vtg, year_act), the following conditions are satisfied:

  1. Both the vintage year (year_vtg) and active year (year_act) are in the model’s year set.
  2. year_vtg <= year_act.
  3. year_act <= the model’s first year or year_act is in the smaller subset ixmp.Scenario.years_active() for the given ya_args.
  • ya_args (tuple of (node, technology, year_vtg), optional) – Arguments to ixmp.Scenario.years_active().
  • in_horizon (bool, optional) – Restrict years returned to be within the current model horizon.

with columns, “year_vtg” and “year_act”, in which each row is a valid pair.

Return type:


Utility methods

message_ix.utils.make_df(base, **kwargs)

Extend or overwrite base with new values from kwargs.


base modified with kwargs.

Return type:



Scalar values in base or kwargs are broadcast. The number of rows in the returned pandas.DataFrame equals the length of the longest item in either argument.

>>> base = {'foo': 'bar'}
>>> make_df(base, baz=[42, 43, 44])
    foo     baz
0   bar     42
1   bar     43
2   bar     44
message_ix.utils.make_ts(df, time_col, value_col, metadata={})

The function groups the dataframe by the year specified in year_col_name (year_act Vs. year_vtg). It then reshapes the dataframe df to reseble the timeseries requirements: sets the unit, the variable name, and the value column to the one specified in value_col_name. it further drops all all additional columns.

message_ix.utils.matching_rows(df, row, match_columns=[])

The function finds all the columns in a dataframe that are specified in the match columns list.

message_ix.utils.multiply_df(df1, column1, df2, column2)

The function merges dataframe df1 with df2 and multiplies column1 with column2. The function returns the new merged dataframe with the result of the muliplication in the column ‘product’.