Python (`ixmp` package)¶

The ix modeling platform application programming interface (API) is organized around three classes:

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

Platform¶

class ixmp.Platform(name=None, backend=None, **backend_args)¶

Instance of the modeling platform.

A Platform connects two key components:

A back end for storing data such as model inputs and outputs.
One or more model(s); codes in Python or other languages or frameworks that run, via Scenario.solve(), on the data stored in the Platform.

The Platform parameters control these components. TimeSeries and Scenario objects tied to a single Platform; to move data between platforms, see Scenario.clone().

Parameters

name (str) – Name of a specific configured backend.
backend ('jdbc') – Storage backend type. ‘jdbc’ corresponds to the built-in JDBCBackend; see BACKENDS.
backend_args – Keyword arguments to specific to the backend. See JDBCBackend.

Platforms have the following methods:

`add_region`(region, hierarchy[, parent])	Define a region including a hierarchy level and a ‘parent’ region.
`add_region_synonym`(region, mapped_to)	Define a synonym for a region.
`add_unit`(unit[, comment])	Define a unit.
`check_access`(user, models[, access])	Check access to specific models.
`regions`()	Return all regions defined for the IAMC-style timeseries format including known synonyms.
`scenario_list`([default, model, scen])	Return information about TimeSeries and Scenarios on the Platform.
`set_log_level`(level)	Set log level for the Platform and its storage `Backend`.
`units`()	Return all units defined on the Platform.

The following backend methods are available via Platform too:

`backend.base.Backend.add_model_name`(name)	Add (register) new model name.
`backend.base.Backend.add_scenario_name`(name)	Add (register) new scenario name.
`backend.base.Backend.close_db`()	OPTIONAL: Close database connection(s).
`backend.base.Backend.get_doc`(domain[, name])	Read documentation from database
`backend.base.Backend.get_meta`(model, …)	Retrieve meta indicators.
`backend.base.Backend.get_model_names`()	List existing model names.
`backend.base.Backend.get_scenario_names`()	List existing scenario names.
`backend.base.Backend.open_db`()	OPTIONAL: (Re-)open database connection(s).
`backend.base.Backend.remove_meta`(categories, …)	Remove meta categories.
`backend.base.Backend.set_doc`(domain, docs)	Save documentation to database
`backend.base.Backend.set_meta`(meta, model, …)	Set meta categories.

These methods can be called like normal Platform methods, e.g.:

$ platform_instance.close_db()

add_region(region, hierarchy, parent='World')¶

Define a region including a hierarchy level and a ‘parent’ region.

Tip

On a Platform backed by a shared database, a region may already exist with a different spelling. Use regions() first to check, and consider calling add_region_synonym() instead.

Parameters

region (str) – Name of the region.
parent (str, default 'World') – Assign a ‘parent’ region.
hierarchy (str) – Hierarchy level of the region (e.g., country, R11, basin)

add_region_synonym(region, mapped_to)¶

Define a synonym for a region.

When adding timeseries data using the synonym in the region column, it will be converted to mapped_to.

Parameters

region (str) – Name of the region synonym.
mapped_to (str) – Name of the region to which the synonym should be mapped.

add_timeslice(name, category, duration)¶

Define a subannual timeslice including a category and duration.

See timeslices() for a detailed description of timeslices.

Parameters

name (str) – Unique name of the timeslice.
category (str) – Timeslice category (e.g. ‘common’, ‘month’, etc).
duration (float) – Duration of timeslice as fraction of year.

add_unit(unit, comment='None')¶

Define a unit.

Parameters

unit (str) – Name of the unit.
comment (str, optional) – Annotation describing the unit or why it was added. The current database user and timestamp are appended automatically.

check_access(user, models, access='view')¶

Check access to specific models.

Parameters

user (str) – Registered user name
models (str or list of str) – Model(s) name
access (str, optional) – Access type - view or edit

Returns

Return type

bool or dict of bool

export_timeseries_data(path, default=True, model=None, scenario=None, variable=None, unit=None, region=None)¶

Export timeseries data to CSV file across multiple scenarios.

Refer add_timeseries() of Timeseries to get more information about adding timeseries data to scenario.

Parameters

path (os.PathLike) –
File name to export data to; must have the suffix ‘.csv’.

Result file will contain the following columns:
- model
- scenario
- version
- variable
- unit
- region
- meta
- subannual
- year
- value
default (bool, optional) – True to include only TimeSeries versions marked as default.
model (str, optional) – Only return data for this model name.
scenario (str, optional) – Only return data for this scenario name.
variable (list of str, optional) – Only return data for variable name(s) in this list.
unit (list of str, optional) – Only return data for unit name(s) in this list.
region (list of str, optional) – Only return data for region(s) in this list.

Returns

Return type

None

get_log_level()¶

Return log level of the storage Backend, if any.

Returns: Name of a Python logging level.
Return type: str

regions()¶

Return all regions defined for the IAMC-style timeseries format including known synonyms.

Returns
Return type: pandas.DataFrame

scenario_list(default=True, model=None, scen=None)¶

Return information about TimeSeries and Scenarios on the Platform.

Parameters

default (bool, optional) – Return only the default version of each TimeSeries/Scenario (see TimeSeries.set_as_default()). Any (model, scenario) without a default version is omitted. If False, return all versions.
model (str, optional) – A model name. If given, only return information for model.
scen (str, optional) – A scenario name. If given, only return information for scen.

Returns

Scenario information, with the columns:

model, scenario, version, and scheme—Scenario identifiers; see Scenario.
is_default—True if the version is the default version for the (model, scenario).
is_locked—True if the Scenario has been locked for use.
cre_user and cre_date—database user that created the Scenario, and creation time.
upd_user and upd_date—user and time for last modification of the Scenario.
lock_user and lock_date—user that locked the Scenario and lock time.
annotation: description of the Scenario or changelog.

Return type

pandas.DataFrame

set_log_level(level)¶

Set log level for the Platform and its storage Backend.

Parameters: level (str) – Name of a Python logging level.

timeslices()¶

Return all subannual timeslices defined in this Platform instance.

Timeslices are a way to represent subannual temporal resolution in timeseries data. A timeslice consists of a name (e.g., ‘january’, ‘summer’), a category (e.g., ‘months’, ‘seasons’), and a duration given relative to a full year.

The category and duration do not have any functional relevance within the ixmp framework, but they may be useful for pre- or post-processing. For example, they can be used to filter all timeslices of a certain category (e.g., all months) from the pandas.DataFrame returned by this function or to aggregate subannual data to full-year results.

A timeslice is related to the index set ‘time’ in a message_ix.Scenario to indicate a subannual temporal dimension. Alas, timeslices and set elements of time have to be initialized/defined independently.

See add_timeslice() to initialize additional timeslices in the Platform instance.

Returns: DataFrame of timeslices, categories and duration
Return type: pandas.DataFrame

units()¶

Return all units defined on the Platform.

Returns
Return type: numpy.ndarray of str

TimeSeries¶

class ixmp.TimeSeries(mp, model, scenario, version=None, annotation=None, **kwargs)¶

Collection of data in time series format.

TimeSeries is the parent/super-class of Scenario.

Parameters

mp (Platform) – ixmp instance in which to store data.
model (str) – Model name.
scenario (str) – Scenario name.
version (int or str, optional) – If omitted and a default version of the (model, scenario) has been designated (see set_as_default()), load that version. If int, load a specific version. If 'new', create a new TimeSeries.
annotation (str, optional) – A short annotation/comment used when version='new'.

A TimeSeries is uniquely identified on its Platform by three values:

model: the name of a model used to perform calculations between input and output data.
- In TimeSeries storing non-model data, arbitrary strings can be used.
- In a Scenario, the model is a reference to a GAMS program registered to the Platform that can be solved with Scenario.solve(). See ixmp.model.MODELS.
scenario: the name of a specific, coherent description of the real- world system being modeled. Any model may be used to represent multiple alternate, or ‘counter-factual’, scenarios.
version: an integer identifying a specific iteration of a (model, scenario). A new version is created by:
- Instantiating a new TimeSeries with the same model and scenario as an existing TimeSeries.
- Calling Scenario.clone().
Optionally, one version may be set as a default version. See set_as_default().

TimeSeries objects have the following methods:

`add_geodata`(df)	Add geodata (layers) to the TimeSeries.
`add_timeseries`(df[, meta, year_lim])	Add data to the TimeSeries.
`check_out`([timeseries_only])	Check out the TimeSeries.
`commit`(comment)	Commit all changed data to the database.
`discard_changes`()	Discard all changes and reload from the database.
`get_geodata`()	Fetch geodata and return it as dataframe.
`is_default`()	Return `True` if the `version` is the default version.
`last_update`()	Get the timestamp of the last update/edit of this TimeSeries.
`preload_timeseries`()	Preload timeseries data to in-memory cache.
`read_file`(path[, firstyear, lastyear])	Read time series data from a CSV or Microsoft Excel file.
`remove_geodata`(df)	Remove geodata from the TimeSeries instance.
`remove_timeseries`(df)	Remove timeseries data from the TimeSeries instance.
`run_id`()	Get the run id of this TimeSeries.
`set_as_default`()	Set the current `version` as the default.
`timeseries`([region, variable, unit, year, …])	Retrieve timeseries data.

add_geodata(df)¶

Add geodata (layers) to the TimeSeries.

Parameters

df (pandas.DataFrame) –

Data to add. df must have the following columns:

region
variable
subannual
unit
year
value
meta

add_timeseries(df, meta=False, year_lim=None, None)¶

Add data to the TimeSeries.

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.

check_out(timeseries_only=False)¶

Check out the TimeSeries.

Data in the TimeSeries can only be modified when it is in a checked-out state.

See also

utils.maybe_check_out()

commit(comment)¶

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

discard_changes()¶: Discard all changes and reload from the database.

get_geodata()¶

Fetch geodata and return it as dataframe.

Returns: Specified data.
Return type: pandas.DataFrame

is_default()¶: Return True if the version is the default version.

last_update()¶: Get the timestamp of the last update/edit of this TimeSeries.

model = None¶: Name of the model associated with the TimeSeries

preload_timeseries()¶: Preload timeseries data to in-memory cache. Useful for bulk updates.

read_file(path, firstyear=None, lastyear=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)¶

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_timeseries(df)¶

Remove timeseries data from the TimeSeries instance.

Parameters

df (pandas.DataFrame) –

Data to remove. df must have the following columns:

region or node
variable
unit
year

run_id()¶: Get the run id of this TimeSeries.

scenario = None¶: Name of the scenario associated with the TimeSeries

set_as_default()¶: Set the current version as the default.

timeseries(region=None, variable=None, unit=None, year=None, iamc=False, subannual='auto')¶

Retrieve timeseries data.

Parameters

iamc (bool, optional) – Return data in wide/’IAMC’ format. If False, return data in long/’tabular’ 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 dataframe.

Raises

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

Returns

Specified data.

Return type

pandas.DataFrame

version = None¶: Version of the TimeSeries. Immutable for a specific instance.

Scenario¶

class ixmp.Scenario(mp, model, scenario, version=None, scheme=None, annotation=None, **model_init_args)¶

Bases: ixmp.core.TimeSeries

Collection of model-related data.

See TimeSeries for the meaning of parameters mp, model, scenario, version, and annotation.

Parameters: scheme (str, optional) – Use an explicit scheme to initialize the new scenario. The initialize() method of the corresponding Model subclass in MODELS is used to initialize items in the Scenario.

A Scenario is a TimeSeries associated with a particular model that can be run on the current Platform by calling solve(). The Scenario also stores the output, or ‘solution’ of a model run; this includes the ‘level’ and ‘marginal’ values of GAMS equations and variables.

Data in a Scenario are closely related to different types in the GAMS data model:

A set is a named collection of labels. See init_set(), add_set(), and set(). There are two types of sets:
1. Sets that are lists of labels.
2. Sets that are ‘indexed’ by one or more other set(s). For this type of set, each member is an ordered tuple of the labels in the index sets.
A scalar is a named, single, numerical value. See init_scalar(), change_scalar(), and scalar().
Parameters, variables, and equations are multi-dimensional arrays of values that are indexed by one or more sets (i.e. with dimension 1 or greater). The Scenario methods for handling these types are very similar; they mainly differ in how they are used within GAMS models registered with ixmp:
- Parameters are generic data that can be defined before a model run. They may be altered by the model solution. See init_par(), remove_par(), par_list(), add_par(), and par().
- Variables are calculated during or after a model run by GAMS code, so they cannot be modified by a Scenario. See init_var(), var_list(), and var().
- Equations describe fundamental relationships between other types (parameters, variables, and scalars) in a model. They are defined in GAMS code, so cannot be modified by a Scenario. See init_equ(), equ_list(), and equ().

Deprecated since version 3.0: The cache keyword argument to Scenario has no effect and raises a warning. Use cache as one of the backend_args to Platform to disable/enable caching for storage backends that support it. Use load_scenario_data() to load all data in the Scenario into an in-memory cache.

`add_par`(name[, key_or_data, value, unit, …])	Set the values of a parameter.
`add_set`(name, key[, comment])	Add elements to an existing set.
`change_scalar`(name, val, unit[, comment])	Set the value and unit of a scalar.
`clone`([model, scenario, annotation, …])	Clone the current scenario and return the clone.
`equ`(name[, filters])	Return a dataframe of (filtered) elements for a specific equation.
`equ_list`()	List all defined equations.
`get_meta`([name])	Get scenario meta.
`has_equ`(name)	Check whether the scenario has an equation with that name.
`has_par`(name)	Check whether the scenario has a parameter with that name.
`has_set`(name)	Check whether the scenario has a set name.
`has_solution`()	Return `True` if the Scenario has been solved.
`has_var`(name)	Check whether the scenario has a variable with that name.
`idx_names`(name)	Return the list of index names for an item (set, par, var, equ).
`idx_sets`(name)	Return the list of index sets for an item (set, par, var, equ).
`init_equ`(name[, idx_sets, idx_names])	Initialize a new equation.
`init_par`(name, idx_sets[, idx_names])	Initialize a new parameter.
`init_scalar`(name, val, unit[, comment])	Initialize a new scalar.
`init_set`(name[, idx_sets, idx_names])	Initialize a new set.
`init_var`(name[, idx_sets, idx_names])	Initialize a new variable.
`load_scenario_data`()	Load all Scenario data into memory.
`par`(name[, filters])	Return parameter data.
`par_list`()	List all defined parameters.
`read_excel`(path[, add_units, init_items, …])	Read a Microsoft Excel file into the Scenario.
`remove_par`(name[, key])	Remove parameter values or an entire parameter.
`remove_set`(name[, key])	Delete set elements or an entire set.
`remove_solution`([first_model_year])	Remove the solution from the scenario
`scalar`(name)	Return the value and unit of a scalar.
`set`(name[, filters])	Return the (filtered) elements of a set.
`set_list`()	List all defined sets.
`set_meta`(name_or_dict[, value])	Set scenario meta.
`solve`([model, callback, cb_kwargs])	Solve the model and store output.
`to_excel`(path[, items, filters, max_row])	Write Scenario to a Microsoft Excel file.
`var`(name[, filters])	Return a dataframe of (filtered) elements for a specific variable.
`var_list`()	List all defined variables.

add_par(name, key_or_data=None, value=None, unit=None, comment=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, key, comment=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.

change_scalar(name, val, unit, comment=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=False)¶

Check out the Scenario.

Raises: ValueError – If has_solution() is True.

clone(model=None, scenario=None, annotation=None, keep_solution=True, shift_first_model_year=None, platform=None)¶

Clone the current scenario and return the clone.

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

Note

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

Parameters

model (str, optional) – New model name. If not given, use the existing model name.
scenario (str, optional) – New scenario name. If not given, use the existing scenario name.
annotation (str, optional) – Explanatory comment for the clone commit message to the database.
keep_solution (bool, optional) – If True, include all timeseries data and the solution (vars and equs) from the source scenario in the clone. If False, only include timeseries data marked meta=True (see TimeSeries.add_timeseries()).
shift_first_model_year (int, optional) – If given, all timeseries data in the Scenario is omitted from the clone for years from first_model_year onwards. Timeseries data with the meta flag (see TimeSeries.add_timeseries()) are cloned for all years.
platform (Platform, optional) – Platform to clone to (default: current platform)

delete_meta(*args, **kwargs)¶

Remove scenario meta.

Deprecated since version 3.1: Use remove_meta().

Parameters: name (str or list of str) – Either single meta key or list of keys.

equ(name, filters=None, **kwargs)¶

Return a dataframe of (filtered) elements for a specific equation.

Parameters

name (str) – name of the equation
filters (dict) – index names mapped list of index set elements

equ_list()¶: List all defined equations.

classmethod from_url(url, errors='warn')¶

Instantiate a Scenario given an ixmp-scheme URL.

The following are equivalent:

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

and:

from ixmp import Scenario
scen, mp = Scenario.from_url('ixmp://example/model/scenario#42')

Parameters

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

Returns

scenario, platform – The Scenario and Platform referred to by the URL.

Return type

2-tuple of (Scenario, Platform)

get_meta(name=None)¶

Get scenario meta.

Parameters: name (str, optional) – meta category name

has_equ(name)¶: Check whether the scenario has an equation with that name.

has_par(name)¶: Check whether the scenario has a parameter with that name.

has_set(name)¶: Check whether the scenario has a set name.

has_solution()¶

Return True if the Scenario has been solved.

If has_solution() == True, model solution data exists in the db.

has_var(name)¶: Check whether the scenario has a variable with that name.

idx_names(name)¶

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

Parameters: name (str) – name of the item

idx_sets(name)¶

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

Parameters: name (str) – name of the item

init_equ(name, idx_sets=None, idx_names=None)¶

Initialize a new equation.

Parameters

name (str) – Name of the equation.
idx_sets (list of str or str, optional) – Name(s) of index sets for a 1+-dimensional variable.
idx_names (list of str or str, optional) – Names of the dimensions indexed by idx_sets.

init_par(name, idx_sets, idx_names=None)¶

Initialize a new parameter.

Parameters

name (str) – Name of the parameter.
idx_sets (list of str or str, optional) – Names of sets that index this parameter.
idx_names (list of str or str, optional) – Names of the dimensions indexed by idx_sets.

init_scalar(name, val, unit, comment=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, idx_sets=None, idx_names=None)¶

Initialize a new set.

Parameters

name (str) – Name of the set.
idx_sets (list of str or str, optional) – Names of other sets that index this set.
idx_names (list 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, idx_sets=None, idx_names=None)¶

Initialize a new variable.

Parameters

name (str) – Name of the variable.
idx_sets (list of str or str, optional) – Name(s) of index sets for a 1+-dimensional variable.
idx_names (list of str or str, optional) – Names of the dimensions indexed by idx_sets.

items(type=<ItemType.PAR: 4>, filters=None)¶

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.

load_scenario_data()¶

Load all Scenario data into memory.

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

par(name, filters=None, **kwargs)¶

Return parameter data.

If filters is provided, only a subset of data, matching the filters, is returned.

Parameters

name (str) – Name of the parameter
filters (dict (str -> list of str), optional) – Index names mapped to lists of index set elements. Elements not appearing in the respective index set(s) are silently ignored.

par_list()¶: List all defined parameters.

read_excel(path, add_units=False, init_items=False, commit_steps=False)¶

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.

remove_meta(name)¶

Remove scenario meta.

Parameters: name (str or list of str) – Either single meta key or list of keys.

remove_par(name, key=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, key=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=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 TimeSeries.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.

scalar(name)¶

Return the value and unit of a scalar.

Parameters: name (str) – Name of the scalar.
Returns: {‘value’
Return type: value, ‘unit’: unit}

scheme = None¶: Scheme of the Scenario.

set(name, filters=None, **kwargs)¶

Return the (filtered) elements of a set.

Parameters

name (str) – Name of the set.
filters (dict) – 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

Return type

pandas.DataFrame

set_list()¶: List all defined sets.

set_meta(name_or_dict, value=None)¶

Set scenario meta.

Parameters

name_or_dict (str or dict) – If the argument is dict, it used as a mapping of meta categories (names) to values. Otherwise, use the argument as the meta category name.
value (str or number or bool, optional) – Meta category value.

solve(model=None, callback=None, cb_kwargs={}, **model_options)¶

Solve the model and store output.

ixmp ‘solves’ a model by invoking the run() method of a Model subclass—for instance, GAMSModel.run(). Depending on the underlying model code, different steps are taken; see each model class for details. In general:

Data from the Scenario are written to a model input file.
Code or an external program is invoked to perform calculations or optimizations, solving the model.
Data representing the model outputs or solution are read from a model output file and stored in the Scenario.

If the optional argument callback is given, then additional steps are performed:

Execute the callback with the Scenario as an argument. The Scenario has an iteration attribute that stores the number of times the underlying model has been solved (#2).
If the callback returns False or similar, iterate by repeating from step #1. Otherwise, exit.

Parameters

model (str) – model (e.g., MESSAGE) or GAMS file name (excluding ‘.gms’)
callback (callable, optional) – Method to execute arbitrary non-model code. Must accept a single argument: the Scenario. Must return a non-False value to indicate convergence.
cb_kwargs (dict, optional) – Keyword arguments to pass to callback.
model_options – Keyword arguments specific to the model. See GAMSModel.

Warns

UserWarning – If callback is given and returns None. This may indicate that the user has forgotten a return statement, in which case the iteration will continue indefinitely.

Raises

ValueError – If the Scenario has already been solved.

to_excel(path, items=<ItemType.PAR|SET: 6>, filters=None, max_row=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()

var(name, filters=None, **kwargs)¶

Return a dataframe of (filtered) elements for a specific variable.

Parameters

name (str) – name of the variable
filters (dict) – index names mapped list of index set elements

var_list()¶: List all defined variables.

ixmp.backend.io.EXCEL_MAX_ROWS = 1048576¶: Maximum number of rows supported by the Excel file format. See to_excel() and Scenario/model data.

Configuration¶

When imported, ixmp reads configuration from the first file named config.json found in one of the following directories:

The directory given by the environment variable IXMP_DATA, if defined,
${XDG_DATA_HOME}/ixmp, if the environment variable is defined, or
$HOME/.local/share/ixmp.

Tip

For most users, #2 or #3 is a sensible default; platform information for many local and remote databases can be stored in config.json and retrieved by name.

Advanced users wishing to use a project-specific config.json can set IXMP_DATA to the directory containing this file.

To manipulate the configuration file, use the platform command in the ixmp command-line interface:

# Add a platform named 'p1' backed by a local HSQL database
$ ixmp platform add p1 jdbc hsqldb /path/to/database/files

# Add a platform named 'p2' backed by a remote Oracle database
$ ixmp platform add p2 jdbc oracle \
       database.server.example.com:PORT:SCHEMA username password

# Make 'p2' the default Platform
$ ixmp platform add default p2

…or, use the methods of ixmp.config.

ixmp.config¶: An instance of Config.

class ixmp._config.Config(read=True)¶

Configuration for ixmp.

Config stores two kinds of data: simple keys with a single value, and structured Platform information.

ixmp has no built-in simple keys; however, it can store keys for other packages that build on ixmp, such as message_ix.

Parameters: read (bool) – Read config.json on startup.

add_platform(name, *args, **kwargs)¶

Add or overwrite information about a platform.

Parameters

name (str) – New or existing platform name.
args – Positional arguments. If name is ‘default’, args must be a single string: the name of an existing configured Platform. Otherwise, the first of args specifies one of the BACKENDS, and the remaining args are specific to that backend.
kwargs – Keyword arguments. These differ according to backend.

clear()¶

Clear all configuration keys by setting empty or default values.

clear() also sets the default local platform:

{
  "platform": {
    "default": "local",
    "local": {
      "class": "jdbc",
      "driver": "hsqldb",
      "path": "~/.local/share/ixmp/localdb/default"
    },
}

get(key)¶: Return the value of a configuration key.

get_platform_info(name)¶

Return information on configured Platform name.

Parameters: name (str) – Existing platform. If name is ‘default’, then the information for the default platform is returned.
Returns: The ‘class’ key specifies one of the BACKENDS. Other keys vary by backend class.
Return type: dict
Raises: KeyError – If name is not configured as a platform.

path = None¶: Full-resolved path of the config.json file.

read()¶

Try to read configuration keys from file.

If successful, the attribute path is set to the path of the file.

register(name, type, default=None)¶

Register a new configuration key.

Parameters

name (str) – Name of the new key; must not already exist.
type (object) – Type of the key’s value, such as str or pathlib.Path.
default (any, optional) – Default value for the key. If not supplied, the type is called to supply the default, value, e.g. str().

remove_platform(name)¶: Remove the configuration for platform name.

save()¶

Write configuration keys to file.

config.json is created in the first of the ixmp configuration directories that exists. Only non-null values are written.

set(name, value)¶: Set configuration key to value.

Utilities¶

ixmp.utils.format_scenario_list(platform, model=None, scenario=None, match=None, default_only=False, as_url=False)¶

Return a formatted list of TimeSeries on platform.

Parameters

platform (Platform) –
model (str, optional) – Model name to restrict results. Passed to scenario_list().
scenario (str, optional) – Scenario name to restrict results. Passed to scenario_list().
match (str, optional) – Regular expression to restrict results. Only results where the model or scenario name matches are returned.
default_only (bool, optional) – Only return TimeSeries where a default version has been set with TimeSeries.set_as_default().
as_url (bool, optional) – Format results as ixmp URLs.

Returns

If as_url is False, also include summary information.

Return type

list of str

ixmp.utils.maybe_check_out(timeseries, state=None)¶

Check out timeseries depending on state.

If state is None, then check_out() is called.

Returns

True – if state was None and a check out was performed, i.e. timeseries was previously in a checked-in state.
False – if state was None and no check out was performed, i.e. timeseries was already in a checked-out state.
state – if state was not None and no check out was attempted.

Raises

ValueError – If timeseries is a Scenario object and has_solution() is True.

ixmp.utils.maybe_commit(timeseries, condition, message)¶

Commit timeseries with message if condition is True.

Returns

True – if a commit is performed.
False – if any exception is raised during the attempted commit. The exception is logged with level INFO.

See also

TimeSeries.commit()

ixmp.utils.parse_url(url)¶

Parse url and return Platform and Scenario information.

A URL (Uniform Resource Locator), as the name implies, uniquely identifies a specific scenario and (optionally) version of a model, as well as (optionally) the database in which it is stored. ixmp URLs take forms like:

ixmp://PLATFORM/MODEL/SCENARIO[#VERSION]
MODEL/SCENARIO[#VERSION]

where:

The PLATFORM is a configured platform name; see ixmp.config.
MODEL may not contain the forward slash character (‘/’); SCENARIO may contain any number of forward slashes. Both must be supplied.
VERSION is optional but, if supplied, must be an integer.

Returns

platform_info (dict) – Keyword argument ‘name’ for the Platform constructor.
scenario_info (dict) – Keyword arguments for a Scenario on the above platform: ‘model’, ‘scenario’ and, optionally, ‘version’.

Raises

ValueError – For malformed URLs.

ixmp.utils.update_par(scenario, name, data)¶

Update parameter name in scenario using data, without overwriting.

Only values which do not already appear in the parameter data are added.

Testing utilities¶

Utilities for testing ixmp.

These include:

pytest hooks, fixtures:

`ixmp_cli`	A CliRunner object that invokes the ixmp command-line interface.
`tmp_env`	Return the os.environ dict with the IXMP_DATA variable set.
`test_mp`	An empty ixmp.Platform connected to a temporary, in-memory database.

…and assertions:

`assert_logs`(caplog[, message_or_messages, …])	Assert that message_or_messages appear in logs.
`assert_qty_allclose`(a, b[, check_type, …])	Assert that Quantity objects a and b have numerically close values.
`assert_qty_equal`(a, b[, check_type, check_attrs])	Assert that Quantity objects a and b are equal.

Methods for setting up and populating test ixmp databases:

`make_dantzig`(mp[, solve])	Return `ixmp.Scenario` of Dantzig’s canning/transport problem.
`create_test_platform`(tmp_path, data_path, …)	Create a Platform for testing using specimen files ‘name.*’.
`populate_test_platform`(platform)	Populate platform with data for testing.

Methods to run and retrieve values from Jupyter notebooks:

`run_notebook`(nb_path, tmp_path[, env, …])	Execute a Jupyter notebook via `nbconvert` and collect output.
`get_cell_output`(nb, name_or_index[, kind])	Retrieve a cell from nb according to its metadata name_or_index:

ixmp.testing.MemInfo(arr, cls=<class 'float'>)¶: Return a namedtuple for array, with values as cls.

ixmp.testing.add_random_model_data(scenario, length)¶

Add a set and parameter with given length to scenario.

The set is named ‘random_set’. The parameter is named ‘random_par’, and has two dimensions indexed by ‘random_set’.

ixmp.testing.assert_logs(caplog, message_or_messages=None, at_level=None)¶

Assert that message_or_messages appear in logs.

Use assert_logs as a context manager for a statement that is expected to trigger certain log messages. assert_logs checks that these messages are generated.

Example

def test_foo(caplog):

with assert_logs(caplog, ‘a message’):: logging.getLogger(__name__).info(‘this is a message!’)

Parameters

caplog (object) – The pytest caplog fixture.
message_or_messages (str or list of str) – String(s) that must appear in log messages.
at_level (int, optional) – Messages must appear on ‘ixmp’ or a sub-logger with at least this level.

ixmp.testing.bool_param_id(name)¶

Parameter ID callback for pytest.mark.parametrize().

This formats a boolean value as ‘name0’ (False) or ‘name1’ (True) for easier selection with e.g. pytest -k 'name0'.

ixmp.testing.create_test_platform(tmp_path, data_path, name, **properties)¶

Create a Platform for testing using specimen files ‘name.*’.

Any of the following files from data_path are copied to tmp_path:

name.lobs, name.script, i.e. the contents of a JDBCBackend HyperSQL database.
name.properties.

The contents of name.properties (if it exists) are formatted using the properties keyword arguments.

Returns: the path to the .properties file, if any, else the .lobs file without suffix.
Return type: pathlib.Path

ixmp.testing.get_cell_output(nb, name_or_index, kind='data')¶

Retrieve a cell from nb according to its metadata name_or_index:

The Jupyter notebook format allows specifying a document-wide unique ‘name’ metadata attribute for each cell:

https://nbformat.readthedocs.io/en/latest/format_description.html #cell-metadata

Return the cell matching name_or_index if a string; or the cell at the int index; or raise ValueError.

Parameters: kind (str, optional) – Kind of cell output to retrieve. For ‘data’, the data in format ‘text/plain’ is run through eval(). To retrieve an exception message, use ‘evalue’.

ixmp.testing.ixmp_cli(tmp_env)¶: A CliRunner object that invokes the ixmp command-line interface.

ixmp.testing.make_dantzig(mp, solve=False)¶

Return ixmp.Scenario of Dantzig’s canning/transport problem.

Parameters

mp (ixmp.Platform) – Platform on which to create the scenario.
solve (bool or os.PathLike) – If not False, then solve is interpreted as a path to a directory, and the model transport_ixmp.gms in the directory is run for the scenario.

See also

DantzigModel()

ixmp.testing.memory_usage(message='', reset=False)¶

Profile memory usage from within a test function.

The Python package memory_profiler and jpype are used to report memory usage. A message is logged at the DEBUG level, similar to:

DEBUG    ixmp.testing:testing.py:527  42 <message>
MemInfo(profiled=' 533.76', max_rss=' 534.19', jvm_total=' 213.50',
        jvm_free='  79.22', jvm_used=' 134.28', python='399.48')
MemInfo(profiled='   0.14', max_rss='   0.00', jvm_total='   0.00',
        jvm_free=' -37.75', jvm_used='  37.75', python=' -37.61')

Parameters

message (str, optional) – A string added to the log message, to aid in identifying points in profiled code.
reset (bool, optional) – If True, start profiling anew.

Returns

A MemInfo tuple with the following fields, all in MiB:

profiled: the instantaneous memory usage reported by memory_profiler.
max_rss: the maximum resident set size (i.e. the maximum over the entire life of the process) reported by resource.getrusage().
jvm_total: total memory allocated for the Java Virtual Machine (JVM) underlying JPype, used by JDBCBackend; the same as java.lang.Runtime.getRuntime().totalMemory().
jvm_free: memory allocated to the JVM that is free.
jvm_used: memory used by the JVM, i.e. jvm_total minus jvm_free.
python: a rough estimate of Python memory usage, i.e. profiled minus jvm_used. This may not be accurate.

Return type

collections.namedtuple

ixmp.testing.parametrize_quantity_class(request)¶: Fixture to run tests twice, for both reporting Quantity classes.

ixmp.testing.populate_test_platform(platform)¶

Populate platform with data for testing.

Many of the tests in test_core.py depend on this set of data.

The data consist of:

3 versions of the Dantzig cannery/transport Scenario.
- Version 2 is the default.
- All have HIST_DF and TS_DF as time-series data.
1 version of a TimeSeries with model name ‘Douglas Adams’ and scenario name ‘Hitchhiker’, containing 2 values.

ixmp.testing.protect_pint_app_registry()¶

Protect pint’s application registry.

Use this fixture on tests which invoke code that calls pint.set_application_registry(). It ensures that the environment for other tests is not altered.

ixmp.testing.random_model_data(length)¶: Random (set, parameter) data with at least length elements.

See also

add_random_model_data()

ixmp.testing.random_ts_data(length)¶

A pandas.DataFrame of time series data with length rows.

Suitable for passage to TimeSeries.add_timeseries().

ixmp.testing.resource_limit(request)¶

A fixture that limits Python resources.

See the documentation (pytest --help) for the --resource-limit command-line option that selects (1) the specific resource and (2) the level of the limit.

The original limit, if any, is reset after the test function in which the fixture is used.

ixmp.testing.run_notebook(nb_path, tmp_path, env=None, kernel=None, allow_errors=False)¶

Execute a Jupyter notebook via nbconvert and collect output.

Modified from https://blog.thedataincubator.com/2016/06/testing-jupyter-notebooks/

Parameters

nb_path (path-like) – The notebook file to execute.
tmp_path (path-like) – A directory in which to create temporary output.
env (dict-like, optional) – Execution environment for nbconvert. If not supplied, os.environ is used.
kernel (str, optional) – Jupyter kernel to use. Default: ‘python2’ or ‘python3’, matching the current Python version.
allow_errors (bool, optional) – Whether to pass the --allow-errors option to nbconvert. If True, the execution always succeeds, and cell output contains exception information.

Returns

nb (nbformat.NotebookNode) – Parsed and executed notebook.
errors (list) – Any execution errors.

ixmp.testing.test_mp(request, tmp_env, test_data_path)¶: An empty ixmp.Platform connected to a temporary, in-memory database.

ixmp.testing.tmp_env(tmp_path_factory)¶

Return the os.environ dict with the IXMP_DATA variable set.

IXMP_DATA will point to a temporary directory that is unique to the test session. ixmp configuration (i.e. the ‘config.json’ file) can be written and read in this directory without modifying the current user’s configuration.

Python (ixmp package)¶

Platform¶

TimeSeries¶

Scenario¶

Configuration¶

Utilities¶

Testing utilities¶

Python (`ixmp` package)¶