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: ixmp.core.scenario.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, in_horizon])

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

years_active(node, tec, yr_vtg)

Return years in which tec of yr_vtg can be active in node.

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

Add MACRO parametrization to the Scenario and calibrate.

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: pandas.core.frame.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=[], firstmodelyear=None, data=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, pandas.core.frame.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, pandas.core.frame.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: pandas.core.frame.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: numbers.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[ixmp.core.timeseries.TimeSeries], ixmp.core.platform.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() pandas.core.frame.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: numbers.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: ixmp.backend.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.

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: os.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: os.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: pandas.core.frame.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, pandas.core.frame.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: pandas.core.frame.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[numbers.Real, str]]

Return the value and unit of a scalar.

Parameters

name (str) – Name of the scalar.

Returns

{‘value’

Return type

value, ‘unit’: unit}

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[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') pandas.core.frame.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
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.

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, tec, yr_vtg), optional) – Arguments to years_active().

  • in_horizon (bool, optional) – Only return years within the model horizon (firstmodelyear or later).

Returns

with columns ‘year_vtg’ and ‘year_act’, in which each row is a valid pair.

Return type

pandas.DataFrame

years_active(node, tec, yr_vtg)

Return years in which tec 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

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.MESSAGE(name=None, **model_options)

Bases: message_ix.models.GAMSModel

Model class for MESSAGE.

The MESSAGE Python class encapsulates the GAMS code for the core MESSAGE mathematical formulation. The model_options arguments are received from Scenario.solve(), and—except for solve_options—are passed on to the parent class GAMSModel; see there for a full list of options.

name = 'MESSAGE'

Model name.

defaults = dict(...)

Default model options.

The paths to MESSAGE GAMS source files use the MODEL_PATH configuration setting. MODEL_PATH, in turn, defaults to “message_ix/model” inside the directory where message_ix is installed.

Key

Value

MESSAGE defaults

model_file

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

in_file

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

out_file

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

solve_args

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

Inherited from GAMSModel

case

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

gams_args

['LogOption=4']

check_solution

True

comment

None

equ_list

None

var_list

None

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: message_ix.models.GAMSModel

Model class for MACRO.

name = '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.

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

Bases: message_ix.models.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.

name = 'MESSAGE-MACRO'

Model name.

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

Bases: ixmp.model.gams.GAMSModel

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

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 options in DEFAULT_CPLEX_OPTIONS, or any overrides passed to solve().

Warning

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

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.

message_ix.macro.MACRO_ITEMS = dict(…)

ixmp items (sets, parameters, variables, and equations) in MACRO.

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.

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

Code that uses the deprecated signature:

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

can either be adjusted to use the new signature:

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

or, emulated using the built-in pandas method assign():

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