Python API

The application programming interface (API) for MESSAGEix model developers is implemented in Python. The full API is also available from R; see Usage in R via reticulate.

ixmp package

ixmp provides three classes. These are fully described by the ixmp documentation, which is cross-linked from many places in the MESSAGEix documentation.

Platform([name, backend])

Instance of the modeling platform.

TimeSeries(mp, model, scenario[, version, ...])

Collection of data in time series format.

Scenario(mp, model, scenario[, version, ...])

Collection of model-related data.

ixmp also provides some utility classes and methods:

ixmp.config

Configuration for ixmp.

ixmp.model.MODELS

Mapping from names to available models.

ixmp.model.get_model(name, **model_options)

Return a model for name (or the default) with model_options.

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, scheme=None, **kwargs)

Bases: Scenario

MESSAGEix Scenario.

See ixmp.TimeSeries for the meaning of arguments mp, model, scenario, version, and annotation. The scheme of a newly-created Scenario is always “MESSAGE”.

This class extends ixmp.Scenario and ixmp.TimeSeries and inherits all their methods. Documentation of these inherited methods is included here for convenience. message_ix.Scenario defines additional methods specific to MESSAGEix:

Changed in version 3.0: read_excel() and to_excel() are now methods of ixmp.Scenario, but continue to work with message_ix.Scenario.

add_cat(name, cat, keys[, is_unique])

Map elements from keys to category cat within set name.

add_horizon([year, firstmodelyear, data])

Set the scenario time horizon via year and related categories.

add_macro(data[, scenario, check_convergence])

Add MACRO parametrization to the Scenario and calibrate.

add_spatial_sets(data)

Add sets related to spatial dimensions of the model.

cat(name, cat)

Return a list of all set elements mapped to a category.

cat_list(name)

Return a list of all categories for a mapping set.

equ(name[, filters])

Return equation data.

firstmodelyear

The first model year of the scenario.

par(name[, filters])

Return parameter data.

read_excel(path[, add_units, init_items, ...])

Read a Microsoft Excel file into the Scenario.

rename(name, mapping[, keep])

Rename an element in a set

to_excel(path[, items, filters, max_row])

Write Scenario to a Microsoft Excel file.

var(name[, filters])

Return variable data.

vintage_and_active_years([ya_args, tl_only])

Return matched pairs of vintage and active periods for use in data input.

y0

Alias for firstmodelyear.

years_active(node, tec, yr_vtg)

Return periods in which tec hnology of yr_vtg can be active in node.

ya(node, tec, yr_vtg)

Alias for years_active().

yv_ya([ya_args, tl_only])

Alias for vintage_and_active_years().

add_macro(data, scenario=None, check_convergence=True, **kwargs)

Add MACRO parametrization to the Scenario and calibrate. Notice: existing MACRO calibration data will be overwritten by running this.

Parameters
  • data (dict (str -> DataFrame or Series)) – Dictionary of required data for MACRO calibration.

  • scenario (string, optional, default: None.) – Scenario name for calibrated MESSAGEix scenario.

  • check_convergence (bool, optional, default: True.) – The calibrated scenario solves in one iteration.

  • kwargs – Solve options when solving the calibrated scenario.

See also

Input data file

Warning

MACRO support via add_macro() is experimental in message_ix 3.0 and may not function as expected on all possible MESSAGEix models. See a list of known and pending issues on GitHub.

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_geodata(df: DataFrame) None

Add geodata.

Parameters

df (pandas.DataFrame) –

Data to add. df must have the following columns:

  • region

  • variable

  • subannual

  • unit

  • year

  • value

  • meta

add_horizon(year: Iterable[int] = [], firstmodelyear: Optional[int] = None, data: Optional[dict] = None) None

Set the scenario time horizon via year and related categories.

add_horizon() acts like add_set("year", ...), except with additional conveniences:

  • The firstmodelyear argument can be used to set the first period handled by the MESSAGE optimization. This is equivalent to:

    scenario.add_cat("year", "firstmodelyear", ..., is_unique=True)
    
  • Parameter duration_period is assigned values based on year: The duration of periods is calculated as the interval between successive year elements, and the duration of the first period is set to value that appears most frequently.

See Years, periods, and time slices for a detailed terminology of years and periods in message_ix.

Parameters
  • year (list of int) – The set of periods.

  • firstmodelyear (int, optional) – First period for the model solution. If not given, the first entry of year is used.

  • data (dict) –

    Deprecated since version 3.1: The “year” key corresponds to year and is required. A “firstmodelyear” key corresponds to firstmodelyear and is optional.

Raises

ValueError – If the year set of the Scenario is already populated. Changing the time periods of an existing Scenario can entail complex adjustments to data. For this purpose, adjust each set and parameter individually, or see tools.add_year.

Examples

>>> s = message_ix.Scenario()
# The following are equivalent
>>> s.add_horizon(year=[2020, 2030, 2040], firstmodelyear=2020)
>>> s.add_horizon([2020, 2030, 2040], 2020)
>>> s.add_horizon([2020, 2030, 2040])
add_par(name: str, key_or_data: Optional[Union[str, Sequence[str], Dict, DataFrame]] = None, value=None, unit: Optional[str] = None, comment: Optional[str] = None) None

Set the values of a parameter.

Parameters
  • name (str) – Name of the parameter.

  • key_or_data (str or iterable of str or range or dict or) – pandas.DataFrame Element(s) to be added.

  • value (numeric or iterable of numeric, optional) – Values.

  • unit (str or iterable of str, optional) – Unit symbols.

  • comment (str or iterable of str, optional) – Comment(s) for the added values.

add_set(name: str, key: Union[str, Sequence[str], Dict, DataFrame], comment: Optional[str] = None) None

Add elements to an existing set.

Parameters
  • name (str) – Name of the set.

  • key (str or iterable of str or dict or pandas.DataFrame) – Element(s) to be added. If name exists, the elements are appended to existing elements.

  • comment (str or iterable of str, optional) – Comment describing the element(s). If given, there must be the same number of comments as elements.

Raises
add_spatial_sets(data)

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.

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']}}})
add_timeseries(df: DataFrame, meta: bool = False, year_lim: Tuple[Optional[int], Optional[int]] = (None, None)) None

Add time series data.

Parameters
  • df (pandas.DataFrame) –

    Data to add. df must have the following columns:

    • region or node

    • variable

    • unit

    Additional column names may be either of:

    • year and value—long, or ‘tabular’, format.

    • one or more specific years—wide, or ‘IAMC’ format.

    To support subannual temporal resolution of timeseries data, a column subannual is optional in df. The entries in this column must have been defined in the Platform instance using add_timeslice() beforehand. If no column subannual is included in df, the data is assumed to contain yearly values. See timeslices() for a detailed description of the feature.

  • meta (bool, optional) – If True, store df as metadata. Metadata is treated specially when Scenario.clone() is called for Scenarios created with scheme='MESSAGE'.

  • year_lim (tuple of (int or None, int or None), optional) – Respectively, minimum and maximum years to add from df; data for other years is ignored.

cat(name, cat)

Return a list of all set elements mapped to a category.

Parameters
  • name (str) – Name of the set.

  • cat (str) – Name of the category.

Returns

int is returned if name is ‘year’.

Return type

list of str or list of int

cat_list(name)

Return a list of all categories for a mapping set.

Parameters

name (str) – Name of the set.

change_scalar(name: str, val: Real, unit: str, comment: Optional[str] = None) None

Set the value and unit of a scalar.

Parameters
  • name (str) – Name of the scalar.

  • val (number) – New value of the scalar.

  • unit (str) – New unit of the scalar.

  • comment (str, optional) – Description of the change.

check_out(timeseries_only: bool = False) None

Check out the Scenario.

Raises

ValueError – If has_solution() is True.

See also

TimeSeries.check_out, utils.maybe_check_out

clone(*args, **kwargs)

Clone the current scenario and return the clone.

See ixmp.Scenario.clone() for other parameters.

Parameters
  • keep_solution (bool, optional) – 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().

commit(comment: str) None

Commit all changed data to the database.

If the TimeSeries was newly created (with version='new'), version is updated with a new version number assigned by the backend. Otherwise, commit() does not change the version.

Parameters

comment (str) – Description of the changes being committed.

See also

utils.maybe_commit

delete_meta(*args, **kwargs) None

Remove Metadata for this object.

Deprecated since version 3.1: Use remove_meta().

Parameters

name (str or list of str) – Either single metadata name/identifier, or list of names.

discard_changes() None

Discard all changes and reload from the database.

equ(name, filters=None)

Return equation data.

Same as ixmp.Scenario.equ(), except columns indexed by the MESSAGEix set year are returned with int dtype.

Parameters
  • name (str) – Name of the equation.

  • filters (dict (str -> list of str), optional) – Filters for the dimensions of the equation.

Returns

Filtered elements of the equation.

Return type

pd.DataFrame

equ_list() List[str]

List all defined equations.

property firstmodelyear

The first model year of the scenario.

Return type

int

classmethod from_url(url: str, errors='warn') Tuple[Optional[TimeSeries], Platform]

Instantiate a TimeSeries (or Scenario) given an ixmp:// URL.

The following are equivalent:

from ixmp import Platform, TimeSeries
mp = Platform(name='example')
scen = TimeSeries(mp 'model', 'scenario', version=42)

and:

from ixmp import TimeSeries
scen, mp = TimeSeries.from_url('ixmp://example/model/scenario#42')
Parameters
  • url (str) – See parse_url.

  • errors ('warn' or 'raise') – If ‘warn’, a failure to load the TimeSeries is logged as a warning, and the platform is still returned. If ‘raise’, the exception is raised.

Returns

ts, platform – The TimeSeries and Platform referred to by the URL.

Return type

2-tuple of (TimeSeries, Platform)

get_geodata() DataFrame

Fetch geodata and return it as dataframe.

Returns

Specified data.

Return type

pandas.DataFrame

get_meta(name: Optional[str] = None)

Get Metadata for this object.

Metadata with the given name, attached to this (model name, scenario name, version), is retrieved.

Parameters

name (str, optional) – Metadata name/identifier.

has_equ(name: str) bool

Check whether the scenario has an equation with that name.

has_par(name: str) bool

Check whether the scenario has a parameter with that name.

has_set(name: str) bool

Check whether the scenario has a set name.

has_solution() bool

Return True if the Scenario contains model solution data.

has_var(name: str) bool

Check whether the scenario has a variable with that name.

idx_names(name: str) List[str]

Return the list of index names for an item (set, par, var, equ).

Parameters

name (str) – name of the item

idx_sets(name: str) List[str]

Return the list of index sets for an item (set, par, var, equ).

Parameters

name (str) – name of the item

init_equ(name: str, idx_sets=None, idx_names=None) None

Initialize a new equation.

Parameters
  • name (str) – Name of the equation.

  • idx_sets (sequence of str or str, optional) – Name(s) of index sets for a 1+-dimensional variable.

  • idx_names (sequence of str or str, optional) – Names of the dimensions indexed by idx_sets.

init_par(name: str, idx_sets: Sequence[str], idx_names: Optional[Sequence[str]] = None) None

Initialize a new parameter.

Parameters
  • name (str) – Name of the parameter.

  • idx_sets (sequence of str or str, optional) – Names of sets that index this parameter.

  • idx_names (sequence of str or str, optional) – Names of the dimensions indexed by idx_sets.

init_scalar(name: str, val: Real, unit: str, comment=None) None

Initialize a new scalar.

Parameters
  • name (str) – Name of the scalar

  • val (number) – Initial value of the scalar.

  • unit (str) – Unit of the scalar.

  • comment (str, optional) – Description of the scalar.

init_set(name: str, idx_sets: Optional[Sequence[str]] = None, idx_names: Optional[Sequence[str]] = None) None

Initialize a new set.

Parameters
  • name (str) – Name of the set.

  • idx_sets (sequence of str or str, optional) – Names of other sets that index this set.

  • idx_names (sequence of str or str, optional) – Names of the dimensions indexed by idx_sets.

Raises
  • ValueError – If the set (or another object with the same name) already exists.

  • RuntimeError – If the Scenario is not checked out (see check_out()).

init_var(name: str, idx_sets: Optional[Sequence[str]] = None, idx_names: Optional[Sequence[str]] = None) None

Initialize a new variable.

Parameters
  • name (str) – Name of the variable.

  • idx_sets (sequence of str or str, optional) – Name(s) of index sets for a 1+-dimensional variable.

  • idx_names (sequence of str or str, optional) – Names of the dimensions indexed by idx_sets.

is_default() bool

Return True if the version is the default version.

items(type: ItemType = ItemType.PAR, filters: Optional[Dict[str, Sequence[str]]] = None) Iterable[Tuple[str, Any]]

Iterate over model data items.

Parameters
  • type (ItemType, optional) – Types of items to iterate, e.g. ItemType.PAR for parameters, the only value currently supported.

  • filters (dict, optional) – Filters for values along dimensions; same as the filters argument to par().

Yields

(str, object) – Tuples of item name and data.

last_update() str

Get the timestamp of the last update/edit of this TimeSeries.

load_scenario_data() None

Load all Scenario data into memory.

Raises

ValueError – If the Scenario was instantiated with cache=False.

model: str

Name of the model associated with the TimeSeries.

par(name, filters=None)

Return parameter data.

Same as ixmp.Scenario.par(), except columns indexed by the MESSAGEix set year are returned with int dtype.

Parameters
  • name (str) – Name of the parameter.

  • filters (dict (str -> list of str), optional) – Filters for the dimensions of the parameter.

Returns

Filtered elements of the parameter.

Return type

pd.DataFrame

par_list() List[str]

List all defined parameters.

preload_timeseries() None

Preload timeseries data to in-memory cache. Useful for bulk updates.

read_excel(path: PathLike, add_units: bool = False, init_items: bool = False, commit_steps: bool = False) None

Read a Microsoft Excel file into the Scenario.

Parameters
  • path (os.PathLike) – File to read. Must have suffix ‘.xlsx’.

  • add_units (bool, optional) – Add missing units, if any, to the Platform instance.

  • init_items (bool, optional) – Initialize sets and parameters that do not already exist in the Scenario.

  • commit_steps (bool, optional) – Commit changes after every data addition.

See also

Scenario/model data, TimeSeries.read_file, to_excel

read_file(path: PathLike, firstyear: Optional[int] = None, lastyear: Optional[int] = None) None

Read time series data from a CSV or Microsoft Excel file.

Parameters
  • path (os.PathLike) – File to read. Must have suffix ‘.csv’ or ‘.xlsx’.

  • firstyear (int, optional) – Only read data from years equal to or later than this year.

  • lastyear (int, optional) – Only read data from years equal to or earlier than this year.

remove_geodata(df: DataFrame) None

Remove geodata from the TimeSeries instance.

Parameters

df (pandas.DataFrame) –

Data to remove. df must have the following columns:

  • region

  • variable

  • unit

  • subannual

  • year

remove_meta(name: Union[str, Sequence[str]]) None

Remove Metadata for this object.

Parameters

name (str or list of str) – Either single metadata name/identifier, or list of names.

remove_par(name: str, key=None) None

Remove parameter values or an entire parameter.

Parameters
  • name (str) – Name of the parameter.

  • key (dataframe or key list or concatenated string, optional) – Elements to be removed

remove_set(name: str, key: Optional[Union[str, Sequence[str], Dict, DataFrame]] = None) None

Delete set elements or an entire set.

Parameters
  • name (str) – Name of the set to remove (if key is None) or from which to remove elements.

  • key (pandas.DataFrame or list of str, optional) – Elements to be removed from set name.

remove_solution(first_model_year: Optional[int] = None) None

Remove the solution from the scenario.

This function removes the solution (variables and equations) and timeseries data marked as meta=False from the scenario (see add_timeseries()).

Parameters

first_model_year (int, optional) – If given, timeseries data marked as meta=False is removed only for years from first_model_year onwards.

Raises

ValueError – If Scenario has no solution or if first_model_year is not int.

remove_timeseries(df: DataFrame) None

Remove time series data.

Parameters

df (pandas.DataFrame) –

Data to remove. df must have the following columns:

  • region or node

  • variable

  • unit

  • 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

run_id() int

Get the run id of this TimeSeries.

scalar(name: str) Dict[str, Union[Real, str]]

Return the value and unit of a scalar.

Parameters

name (str) – Name of the scalar.

Returns

{‘value’

Return type

value, ‘unit’: unit}

scenario: str

Name of the scenario associated with the TimeSeries.

scheme = None

Scheme of the Scenario.

set(name, filters=None)

Return elements of a set.

Same as ixmp.Scenario.set(), except columns for multi-dimensional sets indexed by the MESSAGEix set year are returned with int dtype.

Parameters
  • name (str) – Name of the set.

  • filters (dict (str -> list of str), optional) – Mapping of dimension_nameelements, where dimension_name is one of the idx_names given when the set was initialized (see init_set()), and elements is an iterable of labels to include in the return value.

Returns

  • pd.Series – If name is an index set.

  • pd.DataFrame – If name is a set defined over one or more other, index sets.

set_as_default() None

Set the current version as the default.

set_list() List[str]

List all defined sets.

set_meta(name_or_dict: Union[str, Dict[str, Any]], value=None) None

Set Metadata for this object.

Parameters
  • name_or_dict (str or dict) – If dict, a mapping of names/identifiers to values. Otherwise, use the metadata identifier.

  • value (str or number or bool, optional) – Metadata value.

solve(model='MESSAGE', solve_options={}, **kwargs)

Solve MESSAGE or MESSAGE-MACRO for the Scenario.

By default, ixmp.Scenario.solve() is called with ‘MESSAGE’ as the model argument. model may also be overwritten, e.g.:

>>> s.solve(model='MESSAGE-MACRO')
Parameters
  • model ('MESSAGE' or 'MACRO' or 'MESSAGE-MACRO', optional) – Model to solve.

  • solve_options (dict (str -> str), optional) – Name to value mapping to use for GAMS CPLEX solver options file. See the MESSAGE class and DEFAULT_CPLEX_OPTIONS.

  • kwargs – Many other options control the execution of the underlying GAMS code; see the MESSAGE_MACRO class and GAMSModel.

timeseries(region: Optional[Union[Sequence[str], str]] = None, variable: Optional[Union[Sequence[str], str]] = None, unit: Optional[Union[Sequence[str], str]] = None, year: Optional[Union[int, Sequence[int]]] = None, iamc: bool = False, subannual: Union[bool, str] = 'auto') DataFrame

Retrieve time series data.

Parameters
  • iamc (bool, optional) – Return data in wide/’IAMC’ format. If False, return data in long format; see add_timeseries().

  • region (str or list of str, optional) – Regions to include in returned data.

  • variable (str or list of str, optional) – Variables to include in returned data.

  • unit (str or list of str, optional) – Units to include in returned data.

  • year (str or int or list of (str or int), optional) – Years to include in returned data.

  • subannual (bool or 'auto', optional) – Whether to include column for sub-annual specification (if bool); if ‘auto’, include column if sub-annual data (other than ‘Year’) exists in returned data frame.

Raises

ValueError – If subannual is False but Scenario has (filtered) sub-annual data.

Returns

Specified data.

Return type

pandas.DataFrame

to_excel(path: ~os.PathLike, items: ~ixmp.backend.ItemType = ItemType.None, filters: ~typing.Optional[~typing.Dict[str, ~typing.Union[~typing.Sequence[str], ~ixmp.core.scenario.Scenario]]] = None, max_row: ~typing.Optional[int] = None) None

Write Scenario to a Microsoft Excel file.

Parameters
  • path (os.PathLike) – File to write. Must have suffix .xlsx.

  • items (ItemType, optional) – Types of items to write. Either SET | PAR (i.e. only sets and parameters), or MODEL (also variables and equations, i.e. model solution data).

  • filters (dict, optional) – Filters for values along dimensions; same as the filters argument to par().

  • max_row (int, optional) – Maximum number of rows in each sheet. If the number of elements in an item exceeds this number or EXCEL_MAX_ROWS, then an item is written to multiple sheets named, e.g. ‘foo’, ‘foo(2)’, ‘foo(3)’, etc.

transact(message: str = '', condition: bool = True)

Context manager to wrap code in a ‘transaction’.

If condition is True, the TimeSeries (or Scenario) is checked out before the block begins. When the block ends, the object is committed with message. If condition is False, nothing occurs before or after the block.

Example

>>> # `ts` is currently checked in/locked
>>> with ts.transact(message="replace 'foo' with 'bar' in set x"):
>>>    # `ts` is checked out and may be modified
>>>    ts.remove_set("x", "foo")
>>>    ts.add_set("x", "bar")
>>> # Changes to `ts` have been committed
property url: str

URL fragment for the TimeSeries.

This has the format {model name}/{scenario name}#{version}, with the same values passed when creating the TimeSeries instance.

Examples

To form a complete URL (e.g. to use with from_url()), use a configured Platform name:

>>> platform_name = "my-ixmp-platform"
>>> mp = Platform(platform_name)
>>> ts = TimeSeries(mp, "foo", "bar", 34)
>>> ts.url
"foo/bar#34"
>>> f"ixmp://{platform_name}/{ts.url}"
"ixmp://platform_name/foo/bar#34"

Note

Use caution: because Platform configuration is system-specific, other systems must have the same configuration for platform_name in order for the URL to refer to the same TimeSeries/Scenario.

var(name, filters=None)

Return variable data.

Same as ixmp.Scenario.var(), except columns indexed by the MESSAGEix set year are returned with int dtype.

Parameters
  • name (str) – Name of the variable.

  • filters (dict (str -> list of str), optional) – Filters for the dimensions of the variable.

Returns

Filtered elements of the variable.

Return type

pd.DataFrame

var_list() List[str]

List all defined variables.

version = None

Version of the TimeSeries. Immutable for a specific instance.

vintage_and_active_years(ya_args: Optional[Union[Tuple[str, str], Tuple[str, str, Union[int, str]]]] = None, tl_only: bool = True, **kwargs) DataFrame

Return matched pairs of vintage and active periods for use in data input.

Each returned pair of (vintage period \(y^V\), active period \(y\)) satisfies all of the following conditions:

  1. \(y^V, y \in Y\): both vintage and active period are in the year set of the Scenario.

  2. \(y^V \leq y\): a technology cannot be active before it is constructed.

  3. If ya_args (node \(n\), technology \(t\), and optionally \(y^V\)) are given:

    1. \(y^V\) is in the subset of \(Y\) for which \(\text{technical_lifetime}_{n,t,y^V}\) is defined (or the single, specified value).

    2. \(y - y^V + \text{duration_period}_{n,t,y^V} < \text{technical_lifetime}_{n,t,y^V}\): the active period is partly or fully within the technical lifetime defined for that technology, node, and vintage. This is the same condition as years_active().

  4. If ya_args are given and tl_only is True (the default): \(y\) is in the subset of \(Y\) for which \(\text{technical_lifetime}_{n,t,y}\) is defined. 1

  5. (Deprecated) If in_horizon is True: \(y \geq y_0\), the firstmodelyear.

1

note this applies to \(y\), whereas condition 3(a) applies to \(y^V\).

Parameters
  • ya_args (tuple of (node, technology) or (node, technology, year_vtg), optional) – Supplied directly to years_active(). If the third element is omitted, years_active() is called repeatedly, once for each vintage for which a technical lifetime value is set (condition (3)).

  • tl_only (bool, optional) – Condition (4), above.

  • in_horizon (bool, optional) –

    Condition (5), above.

    Deprecated since version 3.6: In message_ix 4.0 or later, in_horizon will be removed, and the default behaviour of vintage_and_active_years() will change to the equivalent of in_horizon = False.

Returns

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

Return type

pandas.DataFrame

Examples

pandas.DataFrame.query() can be used to further manipulate the data in the returned data frame. To limit the vintage periods included:

>>> base = s.vintage_and_active_years(("node", "tech"))
>>> df = base.query("2020 <= year_vtg")

Limit the active periods included:

>>> df = base.query("2040 < year_act")

Limit year_act to the first model year or later (same as deprecated in_horizon argument):

>>> df = base.query(f"{s.firstmodelyear} <= year_act")

More complex expressions and a chained pandas call:

>>> df = s.vintage_and_active_years(
...     ("node", "tech"), tl_only=False
... ).query("2025 <= year_act or year_vtg < 2010")
property y0

Alias for firstmodelyear.

ya(node: str, tec: str, yr_vtg: Union[int, str]) List[int]

Alias for years_active().

years_active(node: str, tec: str, yr_vtg: Union[int, str]) List[int]

Return periods in which tec hnology of yr_vtg can be active in node.

The parameters duration_period and technical_lifetime are used to determine which periods are partly or fully within the lifetime of the technology.

Parameters
  • node (str) – Node name.

  • tec (str) – Technology name.

  • yr_vtg (int or str) – Vintage year.

Return type

list of int

yv_ya(ya_args: Optional[Union[Tuple[str, str], Tuple[str, str, Union[int, str]]]] = None, tl_only: bool = True, **kwargs) DataFrame

Alias for vintage_and_active_years().

Model classes

MESSAGE([name])

Model class for MESSAGE.

MACRO(*args, **kwargs)

Model class for MACRO.

MESSAGE_MACRO(*args, **kwargs)

Model class for MESSAGE_MACRO.

GAMSModel([name])

Extended ixmp.model.gams.GAMSModel for MESSAGE & MACRO.

DEFAULT_CPLEX_OPTIONS

Solver options used by Scenario.solve().

MESSAGE_ITEMS

ixmp items (sets, parameters, variables, and equations) for MESSAGE.

MACRO_ITEMS

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2).

message_ix.models.DEFAULT_CPLEX_OPTIONS = {'advind': 0, 'epopt': 1e-06, 'lpmethod': 4, 'threads': 4}

Solver options used by Scenario.solve().

These configure the GAMS CPLEX solver (or another solver, if selected); see the solver documentation for possible values.

class message_ix.models.GAMSModel(name=None, **model_options)

Extended ixmp.model.gams.GAMSModel for MESSAGE & MACRO.

The MESSAGE, MACRO, and MESSAGE_MACRO child classes encapsulate the GAMS code for the core MESSAGE (or MACRO) mathematical formulation.

The class receives model_options via Scenario.solve(). Some of these are passed on to the parent class ixmp.model.gams.GAMSModel (see there for a list); others are handled as described below.

The “model_dir” option may be set in the user’s ixmp configuration file using the key “message model dir”. If not set, it defaults to “message_ix/model” below the directory where message_ix is installed.

The “solve_options” option may be set in the user’s ixmp configuration file using the key “message solve options”. If not set, it defaults to DEFAULT_CPLEX_OPTIONS.

For example, with the following configuration file:

{
  "platform": {
    "default": "my-platform",
    "my-platform": {"backend": "jdbc", "etc": "etc"},
  },
  "message model dir": "/path/to/custom/gams/source/files",
  "message solve options": {"lpmethod": 4},
}

The following are equivalent:

# Model options given explicitly
scen.solve(
    model_dir="/path/to/custom/gams/source/files",
    solve_options=dict(lpmethod=4),
)

# Model options are read from configuration file
scen.solve()

The following tables list all model options:

Options in message_ix.models.GAMSModel or overridden from ixmp

Option

Usage

Default value

model_dir

Path to GAMS source files.

See above.

model_file

Path to GAMS source file.

'{model_dir}/{model_name}_run.gms'

in_file

Path to write GDX input file.

'{model_dir}/data/MsgData_{case}.gdx'

out_file

Path to read GDX output file.

'{model_dir}/output/MsgOutput_{case}.gdx'

solve_args

Arguments passed directly to GAMS.

[
    '--in="{in_file}"',
    '--out="{out_file}"',
    '--iter="{model_dir}/output/MsgIterationReport_{case}.gdx"'
]

solve_options

Options for the GAMS LP solver.

DEFAULT_CPLEX_OPTIONS

Option defaults inherited from ixmp.model.gams.GAMSModel

Option

Default value

case

'{scenario.model}_{scenario.scenario}'

gams_args

['LogOption=4']

check_solution

True

comment

None

equ_list

None

var_list

None

run(scenario)

Execute the model.

GAMSModel creates a file named cplex.opt in the model directory containing the “solve_options”, as described above.

Warning

GAMSModel can solve Scenarios in two or more Python processes simultaneously; but using different CPLEX options in each process may produce unexpected results.

class message_ix.models.MESSAGE(name=None, **model_options)

Bases: GAMSModel

Model class for MESSAGE.

classmethod initialize(scenario)

Set up scenario with required sets and parameters for MESSAGE.

See also

MESSAGE_ITEMS

class message_ix.models.MACRO(*args, **kwargs)

Bases: GAMSModel

Model class for MACRO.

GAMS_min_version = '24.8.1'

MACRO uses the GAMS break; statement, and thus requires GAMS 24.8.1 or later.

classmethod initialize(scenario, with_data=False)

Initialize the model structure.

name: str = 'MACRO'

Model name.

class message_ix.models.MESSAGE_MACRO(*args, **kwargs)

Bases: MESSAGE, MACRO

Model class for MESSAGE_MACRO.

MESSAGE_MACRO solves the MESSAGE and MACRO models iteratively, connecting changes in technology activity and resource demands (from MESSAGE) to changes in final demands and prices (from MACRO). This iteration continues until the solution converges; i.e. the two models reach a stable point for the values of these parameters.

MESSAGE_MACRO accepts three additional model_options that control the behaviour of this iteration algorithm:

  • max_adjustment (float, default 0.2): the maximum absolute relative change in final demands between iterations. If MACRO returns demands that have changed by more than a factor outside the range (1 - max_adjustment, 1 + max_adjustment) since the previous iteration, then the change is confined to the limits of that range for the next run of MESSAGE.

  • convergence_criterion (float, default 0.01): threshold for model convergence. This option applies to the same value as max_adjustment: the relative change in final demands between two iterations. If the absolute relative change is less than convergence_criterion, the linked model run is complete.

  • max_iteration (int, default 50): the maximum number of iterations between the two models. If the solution does not converge after this many iterations, the linked model run fails and no valid result is produced.

classmethod initialize(scenario, with_data=False)

Set up scenario with required sets and parameters for MESSAGE.

See also

MESSAGE_ITEMS

name: str = 'MESSAGE-MACRO'

Model name.

message_ix.models.MESSAGE_ITEMS = dict(…)

ixmp items (sets, parameters, variables, and equations) for MESSAGE.

Keys are the names of items (sets, parameters, variables, and equations); values are dict specifying their type and dimensionality, with keys ‘ix_type’, ‘idx_sets’, and in some cases ‘idx_names’. These include all items listed in the MESSAGE mathematical specification, i.e. Sets and mappings and Parameter definition.

message_ix.macro.MACRO_ITEMS = dict(…)

All of the ixmp items (sets, parameters, variables, and equations) in the MACRO mathematical formulation.

See also

MESSAGE_ITEMS

Utility methods

message_ix.util.expand_dims(scenario: Scenario, name, **data)

Expand dimensions of parameter name on scenario, filling with data.

This function is for use when an existing parameter name has dimensions that are a subset of those that would be created by make_df(), i.e. those given by MESSAGE_ITEMS.

This can occur when the underlying structure of MESSAGE and the model core is enhanced by adding dimensions to existing parameters. Existing scenario data in users’ databases can not then be automatically updated.

expand_dims() helps users to update this data manually. It:

  1. Retrieves the existing parameter data for name.

  2. Passes this existing data, plus any data given as keyword arguments, to make_df(). The result must be a data frame with no empty values; in other words, data must include all the dimensions to be added to name.

  3. Re-initializes the parameter name on scenario, with the dimensions given by MESSAGE_ITEMS.

  4. Adds the expanded data.

The modifications (steps 3 and 4) are wrapped using transact().

message_ix.util.make_df(name, **data)

Return a data frame for parameter name filled with data.

make_df() always returns a data frame with the columns required by add_par(): the dimensions of the parameter name, plus ‘value’ and ‘unit’. Columns not listed in data are left empty.

The data keyword arguments can be passed in many ways; see the Keyword Arguments and “Function Examples” sections of the Python introductory tutorial, or the examples below.

Examples

>>> make_df(
...    "demand", node=["foo", "bar"], commodity="baz", value=[1.2, 3.4]
... )
  node  commodity  level  year  time  value  unit
0  foo        baz   None  None  None    1.2  None
1  bar        baz   None  None  None    3.4  None

Pass some values as direct keyword arguments, and others by unpacking a dictionary:

>>> common = dict(
...    commodity="light",
...    level="useful",
...    time="year",
...    unit="GWa",
... )
>>> make_df(
...    "demand",
...    node=["Westeros", "Middle-earth"],
...    year=[680, 700],
...    value=[50, 80],
...    # Use values from `common` as additional keyword args:
...    **common,
... )
           node  commodity   level  year  time  value  unit
0      Westeros      light  useful   680  year     50   GWa
1  Middle-earth      light  useful   700  year     50   GWa

Code that uses the deprecated signature, such as:

>>> base = {"year": [2020, 2021, 2022]}
>>> make_df(base, value=1., unit="y")
   year  value  unit
0     1    1.0     y
1     2    1.0     y
2     3    1.0     y

or:

>>> base = dict(
...    node=["Westeros", "Middle-earth"],
...    year=[680, 700],
...    time="year",
...    unit="-",
... )
>>> make_df(base, mode="standard")
           node  year  time  unit      mode
0      Westeros   680  year     -  standard
1  Middle-earth   700  year     -  standard

…can either be adjusted to use the new signature:

>>> make_df("duration_period", **base, value=1., unit="y")

or, emulated using the pandas.DataFrame.assign() method:

>>> pd.DataFrame(base).assign(value=1., unit="y")

The former is recommended, because it will ensure the result has the correct columns for the parameter.

Parameters
  • name (str) – Name of a parameter listed in MESSAGE_ITEMS or MACRO_ITEMS.

  • data (optional) – Contents for dimensions of the parameter, its ‘value’, or ‘unit’. Other keys are ignored.

Return type

pandas.DataFrame

Raises

ValueError – if name is not the name of a MESSAGE or MACRO parameter; if arrays in data have uneven lengths.

Testing utilities

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

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, quiet=True, model_horizon=[700, 710, 720])

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.