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:

  1. A back end for storing data such as model inputs and outputs.
  2. 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.
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)

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.
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_defaultTrue if the version is the default version for the (model, scenario).
  • is_lockedTrue 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)

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:

  1. model: the name of a model used to perform calculations between input and output data.

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

  3. 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 for modification.
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 for modification.

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.
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.
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, cache=False, **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 for initializing a new scenario.
  • cache (bool, optional) – Store data in memory and return cached values instead of repeatedly querying the backend.

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().
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 metadata.
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, value) Set scenario metadata.
solve([model, callback, cb_kwargs]) Solve the model and store output.
to_excel(path[, items]) 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:
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 for modification.

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

Parameters:name (str, optional) – metadata attribute 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:
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.
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_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_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:

Return type:

pandas.DataFrame

set_list()

List all defined sets.

set_meta(name, value)

Set scenario metadata.

Parameters:
  • name (str) – metadata attribute name
  • value (str or number or bool) – metadata attribute 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:

  1. Data from the Scenario are written to a model input file.
  2. Code or an external program is invoked to perform calculations or optimizations, solving the model.
  3. 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:

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

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

Configuration

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

  1. The directory given by the environment variable IXMP_DATA, if defined,
  2. ${XDG_DATA_HOME}/ixmp, if the environment variable is defined, or
  3. $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.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_attrs]) Assert that Quantity objects a and b have numerically close values.
    assert_qty_equal(a, b[, 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, kernel]) Execute a Jupyter notebook via nbconvert and collect output.
    get_cell_output(nb, name_or_index) Retrieve a cell from nb according to its metadata name_or_index:
ixmp.testing.assert_logs(caplog, message_or_messages=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.
ixmp.testing.assert_qty_allclose(a, b, check_attrs=True, **kwargs)

Assert that Quantity objects a and b have numerically close values.

When Quantity is AttrSeries, a and b are first passed through as_quantity().

ixmp.testing.assert_qty_equal(a, b, check_attrs=True, **kwargs)

Assert that Quantity objects a and b are equal.

When Quantity is AttrSeries, a and b are first passed through as_quantity().

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)

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.

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.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.run_notebook(nb_path, tmp_path, env=None, kernel=None)

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