# API Documentation¶

## Model class¶

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

A Calliope Model.

save_commented_model_yaml(path)[source]

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)[source]

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, index_format='index')[source]

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

Parameters
varstr

Decision variable for which to return a DataArray.

index_formatstr, default = ‘index’

‘index’ to return the loc_tech(_carrier) dimensions as individual indexes, ‘multiindex’ to return them as a MultiIndex. The latter has the benefit of having a smaller memory footprint, but you cannot undertake dimension specific operations (e.g. formatted_array.sum(‘locs’))

to_netcdf(path)[source]

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

to_csv(path, dropna=True)[source]

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

Parameters
dropnabool, optional

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

to_lp(path)[source]

Save built model to LP format at the given path. If the backend model has not been built yet, it is built prior to saving.

## Time series¶

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

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

Should be normalized

funcstr

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

timesteps_per_dayint

Total number of timesteps in a day

techlist, optional

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

timestepslist or str, optional

Subset of the time domain within which to apply clustering.

kint, optional

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

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

kwargsdict

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
——-
clustersdataframe

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

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.

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

Parameters
dataxarray.Dataset
techstr

Technology whose var to find extreme for.

varstr, optional

default ‘resource’

howstr, optional

‘max’ (default) or ‘min’.

lengthstr, optional

Defaults to ‘1D’.

nint, optional

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

groupby_lengthstr, optional

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

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.

normalizebool, optional

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

kwargsdict, optional

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

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
dataxarray.Dataset
tech0str

First technology for which we find the extreme of var

tech1str

Second technology for which we find the extreme of var

varstr, optional

default ‘resource’

howstr, optional

‘max’ (default) or ‘min’.

lengthstr, optional

Defaults to ‘1D’.

nint, optional

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

groupby_lengthstr, optional

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

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.

normalizebool, optional

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

kwargsdict, optional

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

calliope.time.funcs.resample(data, timesteps, resolution)[source]

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

Parameters
dataxarray.Dataset

calliope model data, containing only timeseries data variables

timestepsstr or list; optional

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

resolutionstr

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.postprocess.plotting.plotting.ModelPlotMethods(model)[source]
timeseries(**kwargs)[source]
Parameters
arraystr 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_zoomint, optional

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

rangesliderbool, optional

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

subsetdict, optional

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

sum_dimsstr, optional

List of dimension names to sum plot variable over.

squeezebool, optional

Whether to squeeze out dimensions of length = 1.

html_onlybool, optional; default = False

Returns a html string for embedding the plot in a webpage

to_fileFalse 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’].

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

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)[source]
Parameters
arraystr 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.

orientstr, optional

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

subsetdict, optional

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

sum_dimsstr, optional

List of dimension names to sum plot variable over.

squeezebool, optional

Whether to squeeze out dimensions containing only single values.

html_onlybool, optional; default = False

Returns a html string for embedding the plot in a webpage

to_fileFalse 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’].

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

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)[source]
Parameters
mapbox_access_tokenstr, 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_onlybool, optional; default = False

Returns a html string for embedding the plot in a webpage

to_fileFalse 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’].

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

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)[source]

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_filestr, optional

Path to output file to save HTML to.

mapbox_access_tokenstr, 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)[source]
access_model_inputs()[source]

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)[source]

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

Parameters
paramstr

Name of the parameter to update

update_dictdict

keys are parameter indeces (either strings or tuples of strings, depending on whether there is one or more than one dimension). Values are the new values being assigned to the parameter at the given indeces.

Returns
Value(s) will be updated in-place, requiring the user to run the model again to
see the effect on results.
activate_constraint(*args, **kwargs)[source]

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

Parameters
constraintstr

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)[source]

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

New calliope model, including both inputs and results, but no backend interface.

## Utility classes: AttrDict, Exceptions, Logging¶

class calliope.core.attrdict.AttrDict(source_dict=None)[source]

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.

copy()[source]

Override copy method so that it returns an AttrDict

init_from_dict(d)[source]

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)[source]

Returns an AttrDict initialized from the given path or file object f, which must point to a YAML file. The path can be a string or a pathlib.Path.

Parameters
fstr or pathlib.Path
resolve_importsbool or str, optional

If resolve_imports is True, top-level import: statements are resolved recursively. If resolve_imports is False, top-level import: statements are treated like any other key and not further processed. If resolve_imports is a string, such as foobar, import statements underneath that key are resolved, i.e. foobar.import:. When resolving import statements, anything defined locally overrides definitions in the imported file.

classmethod from_yaml_string(string, resolve_imports=True)[source]

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

set_key(key, value)[source]

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>)[source]

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)[source]

Delete the given key. Properly deals with nested keys.

as_dict(flat=False)[source]

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

to_yaml(path=None)[source]

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

keys_nested(subkeys_as='list')[source]

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)[source]

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[source]

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

exception calliope.exceptions.BackendError[source]
exception calliope.exceptions.ModelWarning[source]

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

exception calliope.exceptions.BackendWarning[source]
calliope.exceptions.print_warnings_and_raise_errors(warnings=None, errors=None)[source]

Print warnings and raise ModelError from errors.

Parameters
warningslist, optional
errorslist, optional
calliope.core.util.logging.set_log_verbosity(verbosity='info', include_solver_output=True, capture_warnings=True)[source]

Set the verbosity of logging and setup the root logger to log to console (stdout) with timestamp output formatting.

Parameters
verbositystr, default ‘info’

Logging level to display across all of Calliope. Can be one of ‘debug’, ‘info’, ‘warning’, ‘error’, or ‘critical’.

include_solver_outputbool, default True

If True, the logging level for just the backend model is set to DEBUG, which turns on display of solver output.

capture_warningsbool, default True

If True, also capture all warnings and log them to the WARNING level. This results in more consistent output when running interactively.

Previous: Development guide | Next: Index