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
.
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.
- clustered_datasklearn.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.time.masks.extreme(data, tech, var='resource', how='max', length='1D', n=1, groupby_length=None, padding=None, normalize=True, **kwargs)[source]¶
Returns timesteps for period of
length
wherevar
for the technologytech
across the given list oflocations
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.
- paddingstr, 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.
- 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.masks.extreme_diff(data, tech0, tech1, var='resource', how='max', length='1D', n=1, groupby_length=None, padding=None, normalize=True, **kwargs)[source]¶
Returns timesteps for period of
length
where the diffence in extreme value forvar
between technologiestech0
andtech1
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.
- paddingstr, 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.
- 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’].
- layout_updatesdict, 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_updatesdict, 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)[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’].
- layout_updatesdict, 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_updatesdict, 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)[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’].
- layout_updatesdict, 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_updatesdict, 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)[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.
- 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-levelimport:
statements are resolved recursively. Ifresolve_imports is False, top-level ``import:
statements are treated like any other key and not further processed. Ifresolve_imports
is a string, such asfoobar
, 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 givenvalue
. 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.
- to_yaml(path=None)[source]¶
Saves the AttrDict to the
path
as a YAML file, or returns a YAML string ifpath
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 inother
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 formthis.that: None
in other will be ignored if subdicts exist in self likethis.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.ModelWarning[source]¶
ModelWarnings should be raised for possible model errors, but where execution can still continue.
- 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