API Documentation

Model class

class calliope.Model(config, model_data=None, *args, **kwargs)

A Calliope Model.

save_commented_model_yaml(path)

Save a fully built and commented version of the model to a YAML file at the given path. Comments in the file indicate where values were overridden. This is Calliope’s internal representation of a model directly before the model_data xarray.Dataset is built, and can be useful for debugging possible issues in the model formulation.

run(force_rerun=False, **kwargs)

Run the model. If force_rerun is True, any existing results will be overwritten.

Additional kwargs are passed to the backend.

get_formatted_array(var)

Return an xr.DataArray with locs, techs, and carriers as separate dimensions.

Parameters:

var : str

Decision variable for which to return a DataArray.

to_netcdf(path)

Save complete model data (inputs and, if available, results) to a NetCDF file at the given path.

to_csv(path, dropna=True)

Save complete model data (inputs and, if available, results) as a set of CSV files to the given path.

Parameters:

dropna : bool, optional

If True (default), NaN values are dropped when saving, resulting in significantly smaller CSV files.

Time series

calliope.core.time.clustering.get_clusters(data, func, timesteps_per_day, tech=None, timesteps=None, k=None, variables=None, **kwargs)

Run a clustering algorithm on the timeseries data supplied. All timeseries data is reshaped into one row per day before clustering into similar days.

Parameters:

data : xarray.Dataset

Should be normalized

func : str

‘kmeans’ or ‘hierarchical’ for KMeans or Agglomerative clustering, respectively

timesteps_per_day : int

Total number of timesteps in a day

tech : list, optional

list of strings referring to technologies by which clustering is undertaken. If none (default), all technologies within timeseries variables will be used.

timesteps : list or str, optional

Subset of the time domain within which to apply clustering.

k : int, optional

Number of clusters to create. If none (default), will use Hartigan’s rule to infer a reasonable number of clusters.

variables : list, optional

data variables (e.g. resource, energy_eff) by whose values the data will be clustered. If none (default), all timeseries variables will be used.

kwargs : dict

Additional keyword arguments available depend on the func. For available KMeans kwargs see: http://scikit-learn.org/stable/modules/generated/sklearn.cluster.KMeans.html For available hierarchical kwargs see: http://scikit-learn.org/stable/modules/generated/sklearn.cluster.AgglomerativeClustering.html

Returns

——-

clusters : dataframe

Indexed by timesteps and with locations as columns, giving cluster membership for first timestep of each day.

clustered_data : sklearn.cluster object

Result of clustering using sklearn.KMeans(k).fit(X) or sklearn.KMeans(k).AgglomerativeClustering(X). Allows user to access specific attributes, for detailed statistical analysis.

calliope.core.time.masks.extreme(data, tech, var='resource', how='max', length='1D', n=1, groupby_length=None, padding=None, normalize=True, **kwargs)

Returns timesteps for period of length where var for the technology tech across the given list of locations is either minimal or maximal.

Parameters:

data : xarray.Dataset

tech : str

Technology whose var to find extreme for.

var : str, optional

default ‘resource’

how : str, optional

‘max’ (default) or ‘min’.

length : str, optional

Defaults to ‘1D’.

n : int, optional

Number of periods of length to look for, default is 1.

groupby_length : str, optional

Group time series and return n periods of length for each group.

padding : str, optional

Either Pandas frequency (e.g. ‘1D’) or ‘calendar_week’. If Pandas frequency, symmetric padding is undertaken, either side of length If ‘calendar_week’, padding is fit to the calendar week in which the extreme day(s) are found.

normalize : bool, optional

If True (default), data is normalized using normalized_copy().

kwargs : dict, optional

Dimensions of the selected var over which to index. Any remaining dimensions will be flattened by mean

calliope.core.time.masks.extreme_diff(data, tech0, tech1, var='resource', how='max', length='1D', n=1, groupby_length=None, padding=None, normalize=True, **kwargs)

Returns timesteps for period of length where the diffence in extreme value for var between technologies tech0 and tech1 is either a minimum or a maximum.

Parameters:

data : xarray.Dataset

tech0 : str

First technology for which we find the extreme of var

tech1 : str

Second technology for which we find the extreme of var

var : str, optional

default ‘resource’

how : str, optional

‘max’ (default) or ‘min’.

length : str, optional

Defaults to ‘1D’.

n : int, optional

Number of periods of length to look for, default is 1.

groupby_length : str, optional

Group time series and return n periods of length for each group.

padding : str, optional

Either Pandas frequency (e.g. ‘1D’) or ‘calendar_week’. If Pandas frequency, symmetric padding is undertaken, either side of length If ‘calendar_week’, padding is fit to the calendar week in which the extreme day(s) are found.

normalize : bool, optional

If True (default), data is normalized using normalized_copy().

kwargs : dict, optional

Dimensions of the selected var over which to index. Any remaining dimensions will be flattened by mean

calliope.core.time.funcs.resample(data, timesteps, resolution)

Function to resample timeseries data from the input resolution (e.g. 1H), to the given resolution (e.g. 2H)

Parameters:

data : xarray.Dataset

calliope model data, containing only timeseries data variables

timesteps : str or list; optional

If given, apply resampling to a subset of the timeseries data

resolution : str

time resolution of the output data, given in Pandas time frequency format. E.g. 1H = 1 hour, 1W = 1 week, 1M = 1 month, 1T = 1 minute. Multiples allowed.

Analyzing models

class calliope.analysis.plotting.plotting.ModelPlotMethods(model)

timeseries(**kwargs)

Parameters:

array : str or list; default = ‘all’

options: ‘all’, ‘results’, ‘inputs’, the name/list of any energy carrier(s) (e.g. ‘power’), the name/list of any input/output DataArray(s).

User can specify ‘all’ for all input/results timeseries plots, ‘inputs’ for just input timeseries, ‘results’ for just results timeseries, or the name of any data array to plot (in either inputs or results). In all but the last case, arrays can be picked from dropdown in visualisation. In the last case, output can be saved to SVG and a rangeslider can be used.

timesteps_zoom : int, optional

Number of timesteps to show initially on the x-axis (if not given, the full time range is shown by default).

rangeslider : bool, optional

If True, displays a range slider underneath the plot for navigating (helpful primarily in interactive use).

subset : dict, optional

Dictionary by which data is subset (uses xarray loc indexing). Keys any of [‘timeseries’, ‘locs’, ‘techs’, ‘carriers’, ‘costs’].

sum_dims : str, optional

List of dimension names to sum plot variable over.

squeeze : bool, optional

Whether to squeeze out dimensions of length = 1.

html_only : bool, optional; default = False

Returns a html string for embedding the plot in a webpage

to_file : False or str, optional; default = False

Will save plot to file with the given name and extension. to_file=’plot.svg’ to save to SVG, to_file=’plot.png’ for a static PNG image. Allowed file extensions are: [‘png’, ‘jpeg’, ‘svg’, ‘webp’].

layout_updates : dict, optional

The given dict will be merged with the Plotly layout dict generated by the Calliope plotting function, overwriting keys that already exist.

plotly_kwarg_updates : dict, optional

The given dict will be merged with the Plotly plot function’s keyword arguments generated by the Calliope plotting function, overwriting keys that already exist.

capacity(**kwargs)

Parameters:

array : str or list; default = ‘all’

options: ‘all’, ‘results’, ‘inputs’, the name/list of any energy capacity DataArray(s) from inputs/results. User can specify ‘all’ for all input/results capacities, ‘inputs’ for just input capacities, ‘results’ for just results capacities, or the name(s) of any data array(s) to plot (in either inputs or results). In all but the last case, arrays can be picked from dropdown in visualisation. In the last case, output can be saved to SVG.

orient : str, optional

‘h’ for horizontal or ‘v’ for vertical barchart

subset : dict, optional

Dictionary by which data is selected (using xarray indexing loc[]). Keys any of [‘timeseries’, ‘locs’, ‘techs’, ‘carriers’, ‘costs’]).

sum_dims : str, optional

List of dimension names to sum plot variable over.

squeeze : bool, optional

Whether to squeeze out dimensions containing only single values.

html_only : bool, optional; default = False

Returns a html string for embedding the plot in a webpage

to_file : False or str, optional; default = False

Will save plot to file with the given name and extension. to_file=’plot.svg’ to save to SVG, to_file=’plot.png’ for a static PNG image. Allowed file extensions are: [‘png’, ‘jpeg’, ‘svg’, ‘webp’].

layout_updates : dict, optional

The given dict will be merged with the Plotly layout dict generated by the Calliope plotting function, overwriting keys that already exist.

plotly_kwarg_updates : dict, optional

The given dict will be merged with the Plotly plot function’s keyword arguments generated by the Calliope plotting function, overwriting keys that already exist.

transmission(**kwargs)

Parameters:

mapbox_access_token : str, optional

If given and a valid Mapbox API key, a Mapbox map is drawn for lat-lon coordinates, else (by default), a more simple built-in map.

html_only : bool, optional; default = False

Returns a html string for embedding the plot in a webpage

to_file : False or str, optional; default = False

Will save plot to file with the given name and extension. to_file=’plot.svg’ to save to SVG, to_file=’plot.png’ for a static PNG image. Allowed file extensions are: [‘png’, ‘jpeg’, ‘svg’, ‘webp’].

layout_updates : dict, optional

The given dict will be merged with the Plotly layout dict generated by the Calliope plotting function, overwriting keys that already exist.

plotly_kwarg_updates : dict, optional

The given dict will be merged with the Plotly plot function’s keyword arguments generated by the Calliope plotting function, overwriting keys that already exist.

summary(**kwargs)

Plot a summary containing timeseries, installed capacities, and transmission plots. Returns a HTML string by default, returns None if to_file given (and saves the HTML string to file).

Parameters:

to_file : str, optional

Path to output file to save HTML to.

mapbox_access_token : str, optional

(passed to plot_transmission) If given and a valid Mapbox API key, a Mapbox map is drawn for lat-lon coordinates, else (by default), a more simple built-in map.

Pyomo backend interface

class calliope.backend.pyomo.interface.BackendInterfaceMethods(model)

access_model_inputs()

If the user wishes to inspect the parameter values used as inputs in the backend model, they can access a new Dataset of all the backend model inputs, including defaults applied where the user did not specify anything for a loc::tech

update_param(*args, **kwargs)

A Pyomo Param value can be updated without the user directly accessing the backend model.

Parameters:

param : str

Name of the parameter to update

index : tuple of strings

Tuple of dimension indeces, in the order given in model.inputs for the reciprocal parameter

value : int, float, bool, or str

Value to assign to the Pyomo Param at the given index

Returns:

Value will be updated in-place, requiring the user to run the model again to

see the effect on results.

activate_constraint(*args, **kwargs)

Takes a constraint or objective name, finds it in the backend model and sets its status to either active or deactive.

Parameters:

constraint : str

Name of the constraint/objective to activate/deactivate Built-in constraints include ‘_constraint’

active: bool, default=True

status to set the constraint/objective

rerun(*args, **kwargs)

Rerun the Pyomo backend, perhaps after updating a parameter value, (de)activating a constraint/objective or updating run options in the model model_data object (e.g. run.solver).

Returns:

run_data : xarray.Dataset

Raw data from this rerun, including both inputs and results. to filter inputs/results, use run_data.filter_by_attrs(is_result=…) with 0 for inputs and 1 for results.

Utility classes: AttrDict, Exceptions, Logging

class calliope.core.attrdict.AttrDict(source_dict=None)

A subclass of dict with key access by attributes:

d = AttrDict({'a': 1, 'b': 2})
d.a == 1  # True

Includes a range of additional methods to read and write to YAML, and to deal with nested keys.

keys() → a set-like object providing a view on D's keys

values() → an object providing a view on D's values

items() → a set-like object providing a view on D's items

copy()

Override copy method so that it returns an AttrDict

init_from_dict(d)

Initialize a new AttrDict from the given dict. Handles any nested dicts by turning them into AttrDicts too:

d = AttrDict({'a': 1, 'b': {'x': 1, 'y': 2}})
d.b.x == 1  # True

classmethod from_yaml(f, resolve_imports=True)

Returns an AttrDict initialized from the given path or file object f, which must point to a YAML file.

If resolve_imports is True, import: statements are resolved recursively, else they are treated like any other key.

When resolving import statements, anything defined locally overrides definitions in the imported file.

classmethod from_yaml_string(string, resolve_imports=False)

Returns an AttrDict initialized from the given string, which must be valid YAML.

set_key(key, value)

Set the given key to the given value. Handles nested keys, e.g.:

d = AttrDict()
d.set_key('foo.bar', 1)
d.foo.bar == 1  # True

get_key(key, default=<calliope.core.attrdict.__Missing object>)

Looks up the given key. Like set_key(), deals with nested keys.

If default is anything but _MISSING, the given default is returned if the key does not exist.

del_key(key)

Delete the given key. Properly deals with nested keys.

as_dict(flat=False, filtered=True)

Return the AttrDict as a pure dict (with nested dicts if necessary).

get_comments(key)

Get comments for the given key. Returns a dict of the form {'above': ..., 'inline': ..., 'below': ...}.

set_comment(key, comment, kind='inline', exist_ok=False)

Set a comment for the given key. Returns None if successful, KeyError if key does not exist, and ValueError if a comment already exists, unless exist_ok is set to False.

Parameters:

key : str

comment : str

kind : str, optional, default ‘inline’

Can be ‘inline’, ‘above’.

exist_ok : bool, optional, default False

If True, existing comments are overwritten.

del_comments(key)

Remove any comments at the given key. Returns None if successful, KeyError if key has no comments.

to_yaml(path=None)

Saves the AttrDict to the path as a YAML file, or returns a YAML string if path is None.

keys_nested(subkeys_as='list', filtered=True)

Returns all keys in the AttrDict, sorted, including the keys of nested subdicts (which may be either regular dicts or AttrDicts).

If subkeys_as='list' (default), then a list of all keys is returned, in the form ['a', 'b.b1', 'b.b2'].

If subkeys_as='dict', a list containing keys and dicts of subkeys is returned, in the form ['a', {'b': ['b1', 'b2']}].

union(other, allow_override=False, allow_replacement=False, allow_subdict_override_with_none=False)

Merges the AttrDict in-place with the passed other AttrDict. Keys in other take precedence, and nested keys are properly handled.

If allow_override is False, a KeyError is raised if other tries to redefine an already defined key.

If allow_replacement, allow “_REPLACE_” key to replace an entire sub-dict.

If allow_subdict_override_with_none is False (default), a key of the form this.that: None in other will be ignored if subdicts exist in self like this.that.foo: 1, rather than wiping them.

exception calliope.exceptions.ModelError

ModelErrors should stop execution of the model, e.g. due to a problem with the model formulation or input data.

exception calliope.exceptions.BackendError

exception calliope.exceptions.ModelWarning

ModelWarnings should be raised for possible model errors, but where execution can still continue.

exception calliope.exceptions.BackendWarning

calliope.exceptions.print_warnings_and_raise_errors(warnings=None, errors=None)

Print warnings and raise ModelError from errors.

Parameters:

warnings : list, optional

errors : list, optional

calliope.core.util.logging.set_log_level(level)

Set the minimum logging verbosity in a Python console. Higher verbosity levels will include their output and all those of following levels. Level options (in descending order of verbosity):

• ‘DEBUG’

• ‘SOLVER’ -> Calliope custom level, assigned value of 19,

  returns solver (e.g. GLPK) stream

• ‘INFO’ -> default level
• ‘WARNING’
• ‘ERROR’
• ‘CRITICAL’

Previous: Development guide | Next: Index