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:
-
add_unit
(unit, comment='None')¶ define a unit in the ixmp database instance
Parameters:
-
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:
-
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)
- df (a Pandas dataframe either) –
-
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:
-
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:
-
cat
(name, cat)¶ return a list of all set elements mapped to a category
Parameters:
-
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:
-
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:
-
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:
-
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
-