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.

core.DEFAULT_SOLVE_OPTIONS = {'advind': 0, 'epopt': 1e-06, 'lpmethod': 2, 'threads': 4}

Solver options used by message_ix.Scenario.solve(). These configure the GAMS CPLEX solver (or another solver, if selected); see the solver documentation for possible values.

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

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.

Parameters:
  • 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_horizon(data)

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.

Examples

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

Add sets related to spatial dimensions of the model.

Parameters:data (dict) –

Mapping of level → member. 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.

Examples

>>> 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

Parameters:
  • name (string) – name of the set
  • cat (string) – name of the category
cat_list(name)

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, shift_first_model_year=None, platform=None)

Clone the current scenario and return the clone.

If the (model, scenario) given already exist on the Platform, the version for the cloned Scenario follows the last existing version. Otherwise, the version for the cloned Scenario is 1.

Note

clone() does not set or alter default versions. This means that a clone to new (model, scenario) names has no default version, and will not be returned by Platform.scenario_list() unless default=False is given.

Parameters:
  • model (str, optional) – New model name. If not given, use the existing model name.
  • scenario (str, optional) – New scenario name. If not given, use the existing scenario name.
  • annotation (str, optional) – Explanatory comment for the clone commit message to the database.
  • keep_solution (bool, default True) – If True, include all timeseries data and the solution (vars and equs) from the source scenario in the clone. Otherwise, only timeseries data marked as meta=True (see TimeSeries.add_timeseries()) or prior to first_model_year (see TimeSeries.add_timeseries()) are cloned.
  • shift_first_model_year (int, optional) – If given, the values of the solution are transfered to parameters historical_*, parameter resource_volume is updated, and the first_model_year is shifted. The solution is then discarded, see TimeSeries.remove_solution().
  • platform (Platform, optional) – Platform to clone to (default: current platform)
firstmodelyear

Returns the first model year of the scenario.

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

Read Excel file data and load into the scenario.

Parameters:
  • 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
remove_solution()

Remove the solution from the scenario

Delete the model solution (variables and equations) and timeseries data marked as meta=False (see TimeSeries.add_timeseries()) prior to the first model year.

rename(name, mapping, keep=False)

Rename an element in a set

Parameters:
  • 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', solve_options={}, **kwargs)

Solve the model for 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')
Parameters:
  • model (str, optional) – Type of model to solve, e.g. ‘MESSAGE’ or ‘MESSAGE-MACRO’.
  • solve_options (dict, optional) – name, value pairs to use for GAMS solver optfile. See message_ix.DEFAULT_SOLVE_OPTIONS for defaults and https://www.gams.com/latest/docs/S_CPLEX.html for possible keys.
to_excel(fname)

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.
Parameters:
  • 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.
Returns:

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

pandas.DataFrame

Utility methods

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

Extend or overwrite base with new values from kwargs.

Parameters:
Returns:

base modified with kwargs.
Return type:

pandas.DataFrame

Examples

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’.

message_ix.testing.make_dantzig(mp, solve=False, multi_year=False)

Return an message_ix.Scenario for Dantzig’s canning problem.

Parameters:
  • mp (ixmp.Platform) – Platform on which to create the scenario.
  • solve (bool, optional) – If True, the scenario is solved.
  • multi_year (bool, optional) – If True, the scenario has years 1963–1965 inclusive. Otherwise, the scenario has the single year 1963.
message_ix.testing.make_westeros(mp, emissions=False, solve=False)

Return an message_ix.Scenario for the Westeros model.

This is the same model used in the westeros_baseline.ipynb tutorial.

Parameters:
  • mp (ixmp.Platform) – Platform on which to create the scenario.
  • emissions (bool, optional) – If True, the emissions_factor parameter is also populated for CO2.
  • solve (bool, optional) – If True, the scenario is solved.