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
message_ix package
Model classes
Utility methods
Testing utilities

`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

KeyError – If the set name does not exist. init_set() must be called before add_set().
ValueError – For invalid forms or combinations of key and comment.

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']}}})

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.

See also

Scenario.read_excel

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_name → elements, 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[str, Sequence[str]]] = None, variable: Optional[Union[str, Sequence[str]]] = None, unit: Optional[Union[str, Sequence[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.

See also

Scenario/model data, read_excel

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:

\(y^V, y \in Y\): both vintage and active period are in the year set of the Scenario.
\(y^V \leq y\): a technology cannot be active before it is constructed.
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().
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]_
(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 `message_ix.Scenario.solve()`.
`MESSAGE_ITEMS`	List of ixmp items for MESSAGE.

message_ix.models.DEFAULT_CPLEX_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.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`

static enforce(scenario): Enforce data consistency in scenario.

classmethod initialize(scenario): Set up scenario with required sets and parameters for MESSAGE.

See also

MESSAGE_ITEMS

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.

name: str = 'MESSAGE': Model name.

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.

name: str = 'MACRO': Model name.

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.

See also

Scenario.add_macro()

name: str = 'MESSAGE-MACRO': Model name.

name: str = 'MESSAGE-MACRO': Model name.

message_ix.models.MESSAGE_ITEMS = dict(…)

List of ixmp items 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.

See also

MESSAGE.initialize(), MACRO_ITEMS

message_ix.macro.MACRO_ITEMS = dict(…)

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)

All of the items in the MACRO mathematical formulation.

See also

MESSAGE_ITEMS

Utility methods 

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

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.

Python API

ixmp package

message_ix package

Model classes

Utility methods

Testing utilities

`ixmp` package 

`message_ix` package 

Model classes 

Utility methods 

Testing utilities 