ixmp core

This page is generated from documentation strings (docstrings) in ixmp\core.py.

See this guide for guidelines on NumPy/SciPy Documentation conventions.

Class ixmp.Platform

class ixmp.Platform(dbprops=None, dbtype=None)

The class ‘Platform’ is the central access point to the ix modeling platform (ixmp). It includes functions for managing and accessing TimeSeries instances (timeseries and reference data) and Scenario instances (structured model input data and results).

Parameters:
  • dbprops (string) – either the name or path/name for a database.properties file (defaults to folder ‘config’, file ‘default.properties’) or the path/name for a local database (if ‘dbtype’ not None)
  • dbtype (string) – the type of the local database (e.g., ‘HSQLDB’) if no ‘dbprops’ is specified, the local database is created/accessed at ‘~/.local/ixmp/localdb/default’
Scenario(model, scen, version=None, scheme=None, annotation=None, cache=False)

Initialize a new ixmp.Scenario (structured input data and solution) or get an existing scenario from the ixmp database instance

Parameters:
  • model (string) – model name
  • scen (string) – scenario name
  • version (string or integer) – initialize a new scenario (if version == ‘new’), or load a specific version from the database (if version is integer)
  • scheme (string) – use an explicit scheme for initializing a new scenario (e.g., ‘MESSAGE’)
  • annotation (string) – a short annotation/comment (when initializing a new scenario)
  • memcache (boolean) – keep all dataframes in memory after first query (default: False)
TimeSeries(model, scen, version=None, annotation=None)

Initialize a new TimeSeries (timeseries or reference data) or get an existing TimeSeries instance from the ixmp database.

Parameters:
  • model (string) – model name
  • scen (string) – scenario name
  • version (string or integer) – initialize a new TimeSeries (if version=’new’), or load a specific version from the database (if version is integer)
  • annotation (string) – a short annotation/comment (when initializing a new TimeSeries)
add_unit(unit, comment='None')

define a unit in the ixmp database instance

Parameters:
  • unit (string) – name of the new unit
  • comment (string, default None) – annotation why this unit was added (timestamp and user are added automatically)
close_db()

close the database connection of the platform instance this is important when working with local database files (‘HSQLDB’)

open_db()

(re-)open the database connection of the platform instance, e.g., to continue working after using ‘close_db()’

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

Get a list of all TimeSeries and Scenario instances initialized in the ixmp database instance

Parameters:
  • default (boolean, default True) – include only default model/scenario version (true) or all versions
  • model (string) – the model name (optional)
  • scen (string) – the scenario name (optional)
units()

returns a list of all units initialized in the ixmp database instance

Class ixmp.TimeSeries

class ixmp.TimeSeries(ix_mp, model, scen, _jobj)

The class ‘TimeSeries’ is a collection of data in timeseries format. It can be used for reference data, results from models submitted using the IAMC template, or as parent-class of the ‘Scenario’ class to store processed model results.

add_timeseries(df, meta=False)

add a timeseries dataframe to the TimeSeries instance

Parameters:
  • df (a Pandas dataframe either) –
    • in tabular form (cols: region, variable, unit, year)
    • in ‘IAMC-style’ format (cols: region, variable, unit, [years])
  • meta (boolean) – indicator whether this timeseries is ‘meta-data’ (special treatment during cloning for MESSAGE-scheme scenarios)
check_out(timeseries_only=False)

check out from the ixmp database instance for making changes

commit(comment)

commit all changes made to the ixmp database instance

discard_changes()

discard all changes, reload from the ixmp database instance

is_default()

check whether this TimeSeries is set as default

last_update()

get the timestamp of the last update/edit of this TimeSeries

run_id()

get the run id of this TimeSeries

set_as_default()

set this instance of a model/scenario as default version

timeseries(iamc=False, regions=None, variables=None, units=None, years=None)

retrieve timeseries data as a pandas.DataFrame

Parameters:
  • iamc (boolean, default True) – returns a pandas.DataFrame either - ‘IAMC-style’ format (cols: region, variable unit, <years>) - in tabular form (cols: region, variable, unit, year)
  • regions (list of strings) – filter by regions
  • variables (list of strings) – filter by variables
  • units (list of strings) – filter by units
  • years (list of integers) – filter by years
version()

get the version number of this TimeSeries

Class ixmp.Scenario

class ixmp.Scenario(ix_mp, model, scen, _jobj, cache=False)

The class ‘Scenario’ is a generic collection of all data for a model instance (sets and parameters), as well as the solution of a model run (levels/marginals of variables and equations).

The class includes functions to make changes to the data, export all data to and import a solution from GAMS gdx, and save the scenario data to an ixmp database instance. All changes are logged for comprehensive version control.

This class inherits all functions of the class ‘TimeSeries’. The timeseries functions can be used to store and retrieve processed model outputs in the IAMC-style format.

add_cat(name, cat, keys, is_unique=False)

add a set element key to the respective category mapping

Parameters:
  • name (string) – name of the set
  • cat (string) – name of the category
  • keys (list of strings) – element keys to be added to the category mapping
add_par(name, key, val=None, unit=None, comment=None)

add elements to a parameter

Parameters:
  • name (string) – name of the parameter
  • key (string, list/range of strings/values, dictionary, dataframe) – element(s) to be added
  • val (values, list/range of values) – element values (only used if ‘key’ is a string or list/range)
  • unit (string, list/range of strings) – element units (only used if ‘key’ is a string or list/range)
  • comment (string, list/range of strings) – comment (optional, only used if ‘key’ is a string or list/range)
add_set(name, key, comment=None)

add elements to a set

Parameters:
  • name (string) – name of the set
  • key (string, list/range of strings/values, dictionary, dataframe) – element(s) to be added
  • comment (string, list/range of strings) – comment (optional, only used if ‘key’ is a string or list/range)
cat(name, cat)

return a list of all set elements mapped to a category

Parameters:
  • name (string) – name of the set
  • cat (string) – name of the category
cat_list(name)

return a list of all categories for a set

Parameters:name (string) – name of the set
change_scalar(name, val, unit, comment=None)

change the value or unit of a scalar

Parameters:
  • name (string) – name of the scalar
  • val (number) – value
  • unit (string) – unit
  • comment (string) – explanatory comment (optional)
clear_cache(name=None)

clear the Python cache of item elements

Parameters:name (string) – item name (default: None, clears entire Python cache)
clone(model=None, scen=None, annotation=None, keep_sol=True, first_model_year=None)

clone the current scenario and return the new scenario

Parameters:
  • model (string) – new model name
  • scen (string) – new scenario name
  • annotation (string) – explanatory comment (optional)
  • keep_sol (boolean, default: True) – indicator whether to include an existing solution in the cloned scenario
  • first_model_year (int, default None) – new first model year in cloned scenario (‘slicing’, only available for MESSAGE-scheme scenarios)
element(ix_type, name, filters=None, cache=None)

internal function to retrieve a dataframe of item elements

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

return a dataframe of (filtered) elements for a specific equation

Parameters:
  • name (string) – name of the equation
  • filters (dictionary) – index names mapped list of index set elements
equ_list()

return a list of equations initialized in the scenario

idx_names(name)

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

Parameters:name (string) – name of the item
idx_sets(name)

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

Parameters:name (string) – name of the item
init_equ(name, idx_sets=None, idx_names=None)

initialize a new equation in the scenario

Parameters:
  • name (string) – name of the item
  • idx_sets (list of strings) – index set list
  • idx_names (list of strings) – index name list (optional, default to ‘idx_sets’)
init_par(name, idx_sets, idx_names=None)

initialize a new parameter in the scenario

Parameters:
  • name (string) – name of the item
  • idx_sets (list of strings) – index set list
  • idx_names (list of strings) – index name list (optional, default to ‘idx_sets’)
init_scalar(name, val, unit, comment=None)

initialize a new scalar

Parameters:
  • name (string) – name of the scalar
  • val (number) – value
  • unit (string) – unit
  • comment (string) – explanatory comment (optional)
init_set(name, idx_sets=None, idx_names=None)

initialize a new set in the scenario

Parameters:
  • name (string) – name of the item
  • idx_sets (list of strings) – index set list
  • idx_names (list of strings) – index name list (optional, default to ‘idx_sets’)
init_var(name, idx_sets=None, idx_names=None)

initialize a new variable in the scenario

Parameters:
  • name (string) – name of the item
  • idx_sets (list of strings) – index set list
  • idx_names (list of strings) – index name list (optional, default to ‘idx_sets’)
item(ix_type, name)

internal function to retrieve the Java instance of an item

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

return a dataframe of (filtered) elements for a specific parameter

Parameters:
  • name (string) – name of the parameter
  • filters (dictionary) – index names mapped list of index set elements
par_list()

return a list of parameters initialized in the scenario

remove_par(name, key=None)

delete a parameter from the scenario or remove an element from a parameter (if key is specified)

Parameters:
  • name (string) – name of the parameter
  • key (dataframe or key list or concatenated string) – elements to be removed
remove_set(name, key=None)

delete a set from the scenario or remove an element from a set (if key is specified)

Parameters:
  • name (string) – name of the set
  • key (dataframe or key list or concatenated string) – elements to be removed
scalar(name)

return a dictionary of the value and unit for a scalar

Parameters:name (string) – name of the scalar
set(name, filters=None, **kwargs)

return a dataframe of (filtered) elements for a specific set

Parameters:
  • name (string) – name of the item
  • filters (dictionary) – index names mapped list of index set elements
set_list()

return a list of sets initialized in the scenario

solve(model, case=None, model_file=None, in_file=None, out_file=None, solve_args=None, comment=None, var_list=None, equ_list=None, check_sol=True)

solve the model (export to gdx, execute GAMS, import the solution)

Parameters:
  • model (string) – model (e.g., MESSAGE) or GAMS file name (excluding ‘.gms’)
  • case (string) – identifier of gdx file names, defaults to ‘model_name_scen_name’
  • model_file (string, optional) – path to GAMS file (including ‘.gms’ extension)
  • in_file (string, optional) – path to GAMS gdx input file (including ‘.gdx’ extension)
  • out_file (string, optional) – path to GAMS gdx output file (including ‘.gdx’ extension)
  • solve_args (string, optional) – arguments to be passed to GAMS (input/output file names, etc.)
  • comment (string, default None) – additional comment added to changelog when importing the solution
  • var_list (list of strings (optional)) – variables to be imported from the solution
  • equ_list (list of strings (optional)) – equations to be imported from the solution
  • check_sol (boolean, default True) – flag whether a non-optimal solution raises an exception (only applies to MESSAGE runs)
to_gdx(path, filename, include_var_equ=False)

write the scenario to GAMS gdx

Parameters:
  • path (string) – path to the folder
  • filename (string) – name of the gdx file
  • include_var_equ (boolean) – indicator whether to include variables/equations in gdx (default: False)
var(name, filters=None, **kwargs)

return a dataframe of (filtered) elements for a specific variable

Parameters:
  • name (string) – name of the variable
  • filters (dictionary) – index names mapped list of index set elements
var_list()

return a list of variables initialized in the scenario

years_active(node, tec, yr_vtg)

return a list of years in which a technology of certain vintage at a specific node can be active

Parameters:
  • node (string) – node name
  • tec (string) – name of the technology
  • yr_vtg (string) – vintage year