API Reference

Contents

API Reference#

Network#

class pypsa.Network(import_name=None, name='', ignore_standard_types=False, override_components=None, override_component_attrs=None, **kwargs)#

Network container for all buses, one-ports and branches.

Parameters:
  • import_name (string, Path) – Path to netCDF file, HDF5 .h5 store or folder of CSV files from which to import network data. The string could be a URL.

  • name (string, default "") – Network name.

  • ignore_standard_types (boolean, default False) – If True, do not read in PyPSA standard types into standard types DataFrames.

  • override_components (pandas.DataFrame) – If you want to override the standard PyPSA components in pypsa.components.components, pass it a DataFrame with index of component name and columns of list_name and description, following the format of pypsa.components.components. See git repository examples/new_components/.

  • override_component_attrs (pypsa.descriptors.Dict of pandas.DataFrame) – If you want to override pypsa.component_attrs, follow its format. See git repository examples/new_components/.

  • kwargs – Any remaining attributes to set

Return type:

None

Examples

>>> nw1 = pypsa.Network("my_store.h5")
>>> nw2 = pypsa.Network("/my/folder")
>>> nw3 = pypsa.Network("https://github.com/PyPSA/PyPSA/raw/master/examples/scigrid-de/scigrid-with-load-gen-trafos.nc")
add(class_name, name, **kwargs)#

Add a single component to the network.

Adds it to component DataFrame.

Any attributes which are not specified will be given the default value from Components.

This method is slow for many components; instead use madd or import_components_from_dataframe (see below).

Parameters:
  • class_name (string) – Component class name in (“Bus”, “Generator”, “Load”, “StorageUnit”, “Store”, “ShuntImpedance”, “Line”, “Transformer”, “Link”).

  • name (string) – Component name

  • kwargs – Component attributes, e.g. x=0.1, length=123

Examples

>>> network.add("Bus", "my_bus_0")
>>> network.add("Bus", "my_bus_1", v_nom=380)
>>> network.add("Line", "my_line_name", bus0="my_bus_0", bus1="my_bus_1", length=34, r=2, x=4)
adjacency_matrix(branch_components=None, investment_period=None, busorder=None, weights=None)#

Construct a sparse adjacency matrix (directed)

Parameters:
  • branch_components (iterable sublist of branch_components) – Buses connected by any of the selected branches are adjacent (default: branch_components (network) or passive_branch_components (sub_network))

  • busorder (pd.Index subset of network.buses.index) – Basis to use for the matrix representation of the adjacency matrix (default: buses.index (network) or buses_i() (sub_network))

  • weights (pd.Series or None (default)) – If given must provide a weight for each branch, multi-indexed on branch_component name and branch name.

Returns:

adjacency_matrix – Directed adjacency matrix

Return type:

sp.sparse.coo_matrix

calculate_dependent_values()#

Calculate per unit impedances and append voltages to lines and shunt impedances.

consistency_check(check_dtypes=False)#

Checks the network for consistency; e.g. that all components are connected to existing buses and that no impedances are singular.

Prints warnings if anything is potentially inconsistent.

Examples

>>> network.consistency_check()
copy(with_time=True, snapshots=None, investment_periods=None, ignore_standard_types=False)#

Returns a deep copy of the Network object with all components and time- dependent data.

Returns:

network

Return type:

pypsa.Network

Parameters:
  • with_time (boolean, default True) – Copy snapshots and time-varying network.component_names_t data too.

  • snapshots (list or index slice) – A list of snapshots to copy, must be a subset of network.snapshots, defaults to network.snapshots

  • ignore_standard_types (boolean, default False) – Ignore the PyPSA standard types.

Examples

>>> network_copy = network.copy()
property crs#

Coordinate reference system of the network’s geometries (n.shapes).

determine_network_topology(investment_period=None, skip_isolated_buses=False)#

Build sub_networks from topology.

For the default case investment_period=None, it is not taken into account whether the branch components are active (based on build_year and lifetime). If the investment_period is specified, the network topology is determined on the basis of the active branches.

df(component_name)#

Return the DataFrame of static components for component_name, i.e. network.component_names.

Parameters:

component_name (string) –

Return type:

pandas.DataFrame

export_to_csv_folder(csv_folder_name, encoding=None, export_standard_types=False)#

Export network and components to a folder of CSVs.

Both static and series attributes of all components are exported, but only if they have non-default values.

If csv_folder_name does not already exist, it is created.

Static attributes are exported in one CSV file per component, e.g. generators.csv.

Series attributes are exported in one CSV file per component per attribute, e.g. generators-p_set.csv.

Parameters:
  • csv_folder_name (string) – Name of folder to which to export.

  • encoding (str, default None) – Encoding to use for UTF when reading (ex. ‘utf-8’). List of Python standard encodings

  • export_standard_types (boolean, default False) – If True, then standard types are exported too (upon reimporting you should then set “ignore_standard_types” when initialising the network).

Examples

>>> network.export_to_csv_folder(csv_folder_name)
export_to_hdf5(path, export_standard_types=False, **kwargs)#

Export network and components to an HDF store.

Both static and series attributes of components are exported, but only if they have non-default values.

If path does not already exist, it is created.

Parameters:
  • path (string) – Name of hdf5 file to which to export (if it exists, it is overwritten)

  • export_standard_types (boolean, default False) – If True, then standard types are exported too (upon reimporting you should then set “ignore_standard_types” when initialising the network).

  • **kwargs – Extra arguments for pd.HDFStore to specify f.i. compression (default: complevel=4)

Examples

>>> network.export_to_hdf5(filename)
export_to_netcdf(path=None, export_standard_types=False, compression=None, float32=False)#

Export network and components to a netCDF file.

Both static and series attributes of components are exported, but only if they have non-default values.

If path does not already exist, it is created.

If no path is passed, no file is exported, but the xarray.Dataset is still returned.

Be aware that this cannot export boolean attributes on the Network class, e.g. network.my_bool = False is not supported by netCDF.

Parameters:
  • path (string|None) – Name of netCDF file to which to export (if it exists, it is overwritten); if None is passed, no file is exported.

  • export_standard_types (boolean, default False) – If True, then standard types are exported too (upon reimporting you should then set “ignore_standard_types” when initialising the network).

  • compression (dict|None) – Compression level to use for all features which are being prepared. The compression is handled via xarray.Dataset.to_netcdf(…). For details see: https://docs.xarray.dev/en/stable/generated/xarray.Dataset.to_netcdf.html An example compression directive is {'zlib': True, 'complevel': 4}. The default is None which disables compression.

  • float32 (boolean, default False) – If True, typecasts values to float32.

Returns:

ds

Return type:

xarray.Dataset

Examples

>>> network.export_to_netcdf("my_file.nc")
get_active_assets(c, investment_period)#

Getter function.

Get True values for elements of component c which are active at a given investment period. These are calculated from lifetime and the build year.

get_committable_i(c)#

Getter function.

Get the index of commitable elements of a given component.

get_extendable_i(c)#

Getter function.

Get the index of extendable elements of a given component.

get_non_extendable_i(c)#

Getter function.

Get the index of non-extendable elements of a given component.

get_switchable_as_dense(component, attr, snapshots=None, inds=None)#

Return a Dataframe for a time-varying component attribute with values for all non-time-varying components filled in with the default values for the attribute.

Parameters:
  • network (pypsa.Network) –

  • component (string) – Component object name, e.g. ‘Generator’ or ‘Link’

  • attr (string) – Attribute name

  • snapshots (pandas.Index) – Restrict to these snapshots rather than network.snapshots.

  • inds (pandas.Index) – Restrict to these components rather than network.components.index

Return type:

pandas.DataFrame

Examples

>>> get_switchable_as_dense(network, 'Generator', 'p_max_pu')
graph(branch_components=None, weight=None, inf_weight=False)#

Build NetworkX graph.

Parameters:
  • network (Network|SubNetwork) –

  • branch_components ([str]) – Components to use as branches. The default are passive_branch_components in the case of a SubNetwork and branch_components in the case of a Network.

  • weight (str) – Branch attribute to use as weight

  • inf_weight (bool|float) – How to treat infinite weights (default: False). True keeps the infinite weight. False skips edges with infinite weight. If a float is given it is used instead.

Returns:

graph – NetworkX graph

Return type:

OrderedGraph

import_components_from_dataframe(dataframe, cls_name)#

Import components from a pandas DataFrame.

If columns are missing then defaults are used.

If extra columns are added, these are left in the resulting component dataframe.

Parameters:
  • dataframe (pandas.DataFrame) – A DataFrame whose index is the names of the components and whose columns are the non-default attributes.

  • cls_name (string) – Name of class of component, e.g. "Line", "Bus", "Generator", "StorageUnit"

Examples

>>> import pandas as pd
>>> buses = ['Berlin', 'Frankfurt', 'Munich', 'Hamburg']
>>> network.import_components_from_dataframe(
        pd.DataFrame({"v_nom" : 380, "control" : 'PV'},
                    index=buses),
                    "Bus")
>>> network.import_components_from_dataframe(
        pd.DataFrame({"carrier" : "solar", "bus" : buses, "p_nom_extendable" : True},
                    index=[b+" PV" for b in buses]),
                    "Generator")
import_from_csv_folder(csv_folder_name, encoding=None, skip_time=False)#

Import network data from CSVs in a folder.

The CSVs must follow the standard form, see pypsa/examples.

Parameters:
  • csv_folder_name (string) – Name of folder

  • encoding (str, default None) –

    Encoding to use for UTF when reading (ex. ‘utf-8’). List of Python standard encodings

  • skip_time (bool, default False) – Skip reading in time dependent attributes

Examples

>>> network.import_from_csv_folder(csv_folder_name)
import_from_hdf5(path, skip_time=False)#

Import network data from HDF5 store at path.

Parameters:
  • path (string, Path) – Name of HDF5 store. The string could be a URL.

  • skip_time (bool, default False) – Skip reading in time dependent attributes

import_from_netcdf(path, skip_time=False)#

Import network data from netCDF file or xarray Dataset at path.

Parameters:
  • path (string|xr.Dataset) – Path to netCDF dataset or instance of xarray Dataset. The string could be a URL.

  • skip_time (bool, default False) – Skip reading in time dependent attributes

import_from_pandapower_net(net, extra_line_data=False, use_pandapower_index=False)#

Import PyPSA network from pandapower net.

Importing from pandapower is still in beta; not all pandapower components are supported.

Unsupported features include: - three-winding transformers - switches - in_service status and - tap positions of transformers

Parameters:
  • net (pandapower network) –

  • extra_line_data (boolean, default: False) – if True, the line data for all parameters is imported instead of only the type

  • use_pandapower_index (boolean, default: False) – if True, use integer numbers which is the pandapower index standard if False, use any net.name as index (e.g. ‘Bus 1’ (str) or 1 (int))

Examples

>>> network.import_from_pandapower_net(net)
OR
>>> import pypsa
>>> import pandapower as pp
>>> import pandapower.networks as pn
>>> net = pn.create_cigre_network_mv(with_der='all')
>>> network = pypsa.Network()
>>> network.import_from_pandapower_net(net, extra_line_data=True)
import_from_pypower_ppc(ppc, overwrite_zero_s_nom=None)#

Import network from PYPOWER PPC dictionary format version 2.

Converts all baseMVA to base power of 1 MVA.

For the meaning of the pypower indices, see also pypower/idx_*.

Parameters:
  • ppc (PYPOWER PPC dict) –

  • overwrite_zero_s_nom (Float or None, default None) –

Examples

>>> from pypower.api import case30
>>> ppc = case30()
>>> network.import_from_pypower_ppc(ppc)
import_series_from_dataframe(dataframe, cls_name, attr)#

Import time series from a pandas DataFrame.

Parameters:
  • dataframe (pandas.DataFrame) – A DataFrame whose index is network.snapshots and whose columns are a subset of the relevant components.

  • cls_name (string) – Name of class of component

  • attr (string) – Name of time-varying series attribute

Examples

>>> import numpy as np
>>> network.set_snapshots(range(10))
>>> network.import_series_from_dataframe(
        pd.DataFrame(np.random.rand(10, 4),
            columns=network.generators.index,
                        index=range(10)),
                    "Generator",
                    "p_max_pu")
incidence_matrix(branch_components=None, busorder=None)#

Construct a sparse incidence matrix (directed)

Parameters:
  • branch_components (iterable sublist of branch_components) – Buses connected by any of the selected branches are adjacent (default: branch_components (network) or passive_branch_components (sub_network))

  • busorder (pd.Index subset of network.buses.index) – Basis to use for the matrix representation of the adjacency matrix (default: buses.index (network) or buses_i() (sub_network))

Returns:

incidence_matrix – Directed incidence matrix

Return type:

sp.sparse.csr_matrix

property investment_period_weightings#

Weightings applied to each investment period during the optimization (LOPF).

  • Objective weightings are multiplied with all cost coefficients in the objective function of the respective investment period (e.g. to include a social discount rate).

  • Years weightings denote the elapsed time until the subsequent investment period (e.g. used for global constraints CO2 emissions).

property investment_periods#

Investment steps during the optimization.

iplot(fig=None, bus_colors='cadetblue', bus_alpha=1, bus_sizes=10, bus_cmap=None, bus_colorbar=None, bus_text=None, line_colors='rosybrown', link_colors='darkseagreen', transformer_colors='orange', line_widths=3, link_widths=3, transformer_widths=3, line_text=None, link_text=None, transformer_text=None, layouter=None, title='', size=None, branch_components=None, iplot=True, jitter=None, mapbox=False, mapbox_style='open-street-map', mapbox_token='', mapbox_parameters={})#

Plot the network buses and lines interactively using plotly.

Parameters:
  • fig (dict, default None) – If not None, figure is built upon this fig.

  • bus_colors (dict/pandas.Series) – Colors for the buses, defaults to “cadetblue”. If bus_sizes is a pandas.Series with a Multiindex, bus_colors defaults to the n.carriers[‘color’] column.

  • bus_alpha (float) – Adds alpha channel to buses, defaults to 1.

  • bus_sizes (float/pandas.Series) – Sizes of bus points, defaults to 10.

  • bus_cmap (plt.cm.ColorMap/str) – If bus_colors are floats, this color map will assign the colors

  • bus_colorbar (dict) – Plotly colorbar, e.g. {‘title’ : ‘my colorbar’}

  • bus_text (pandas.Series) – Text for each bus, defaults to bus names

  • line_colors (str/pandas.Series) – Colors for the lines, defaults to ‘rosybrown’.

  • link_colors (str/pandas.Series) – Colors for the links, defaults to ‘darkseagreen’.

  • transfomer_colors (str/pandas.Series) – Colors for the transfomer, defaults to ‘orange’.

  • line_widths (dict/pandas.Series) – Widths of lines, defaults to 1.5

  • link_widths (dict/pandas.Series) – Widths of links, defaults to 1.5

  • transformer_widths (dict/pandas.Series) – Widths of transformer, defaults to 1.5

  • line_text (pandas.Series) – Text for lines, defaults to line names.

  • link_text (pandas.Series) – Text for links, defaults to link names.

  • tranformer_text (pandas.Series) – Text for transformers, defaults to transformer names.

  • layouter (networkx.drawing.layout function, default None) – Layouting function from networkx which overrules coordinates given in n.buses[['x', 'y']]. See list of available options.

  • title (string) – Graph title

  • size (None|tuple) – Tuple specifying width and height of figure; e.g. (width, heigh).

  • branch_components (list of str) – Branch components to be plotted, defaults to Line and Link.

  • iplot (bool, default True) – Automatically do an interactive plot of the figure.

  • jitter (None|float) – Amount of random noise to add to bus positions to distinguish overlapping buses

  • mapbox (bool, default False) – Switch to use Mapbox.

  • mapbox_style (str, default 'open-street-map') –

    Define the mapbox layout style of the interactive plot. If this is set to a mapbox layout, the argument mapbox_token must be a valid Mapbox API access token.

    Valid open layouts are:

    open-street-map, white-bg, carto-positron, carto-darkmatter, stamen-terrain, stamen-toner, stamen-watercolor

    Valid mapbox layouts are:

    basic, streets, outdoors, light, dark, satellite, satellite-streets

  • mapbox_token (string) – Mapbox API access token. Obtain from https://www.mapbox.com. Can also be included in mapbox_parameters as accesstoken=mapbox_token.

  • mapbox_parameters (dict) – Configuration parameters of the Mapbox layout. E.g. {“bearing”: 5, “pitch”: 10, “zoom”: 1, “style”: ‘dark’}.

Returns:

fig

Return type:

dictionary for plotly figure

lpf(snapshots=None, skip_pre=False)#

Linear power flow for generic network.

Parameters:
  • snapshots (list-like|single snapshot) – A subset or an elements of network.snapshots on which to run the power flow, defaults to network.snapshots

  • skip_pre (bool, default False) – Skip the preliminary steps of computing topology, calculating dependent values and finding bus controls.

Return type:

None

lpf_contingency(snapshots=None, branch_outages=None)#

Computes linear power flow for a selection of branch outages.

Parameters:
  • snapshots (list-like|single snapshot) – A subset or an elements of network.snapshots on which to run the power flow, defaults to network.snapshots NB: currently this only works for a single snapshot

  • branch_outages (list-like) – A list of passive branches which are to be tested for outages. If None, it’s take as all network.passive_branches_i()

Returns:

p0 – num_passive_branch x num_branch_outages DataFrame of new power flows

Return type:

pandas.DataFrame

Examples

>>> network.lpf_contingency(snapshot, branch_outages)
madd(class_name, names, suffix='', **kwargs)#

Add multiple components to the network, along with their attributes.

Make sure when adding static attributes as pandas Series that they are indexed by names. Make sure when adding time-varying attributes as pandas DataFrames that their index is a superset of network.snapshots and their columns are a subset of names.

Any attributes which are not specified will be given the default value from Components.

Parameters:
  • class_name (string) – Component class name in (“Bus”, “Generator”, “Load”, “StorageUnit”, “Store”, “ShuntImpedance”, “Line”, “Transformer”, “Link”).

  • names (list-like or pandas.Index) – Component names

  • suffix (string, default '') – All components are named after names with this added suffix. It is assumed that all Series and DataFrames are indexed by the original names.

  • kwargs – Component attributes, e.g. x=[0.1, 0.2], can be list, pandas.Series of pandas.DataFrame for time-varying

Returns:

new_names – Names of new components (including suffix)

Return type:

pandas.index

Examples

Short Example:

>>> network.madd("Load", ["load 1", "load 2"],
...        bus=["1", "2"],
...        p_set=np.random.rand(len(network.snapshots), 2))

Long Example:

>>> import pandas as pd, numpy as np
>>> buses = range(13)
>>> snapshots = range(7)
>>> n = pypsa.Network()
>>> n.set_snapshots(snapshots)
>>> n.madd("Bus", buses)
>>> # add load as numpy array
>>> n.madd("Load",
...        n.buses.index + " load",
...        bus=buses,
...        p_set=np.random.rand(len(snapshots), len(buses)))
>>> # add wind availability as pandas DataFrame
>>> wind = pd.DataFrame(np.random.rand(len(snapshots), len(buses)),
...        index=n.snapshots,
...        columns=buses)
>>> #use a suffix to avoid boilerplate to rename everything
>>> n.madd("Generator",
...        buses,
...        suffix=' wind',
...        bus=buses,
...        p_nom_extendable=True,
...        capital_cost=1e5,
...        p_max_pu=wind)
merge(other, components_to_skip=None, inplace=False, with_time=True)#

Merge the components of two networks.

Requires disjunct sets of component indices and, if time-dependent data is merged, identical snapshots and snapshot weightings.

If a component in other does not have values for attributes present in network, default values are set.

If a component in other has attributes which are not present in network these attributes are ignored.

Parameters:
  • network (pypsa.Network) – Network to add to.

  • other (pypsa.Network) – Network to add from.

  • components_to_skip (list-like, default None) – List of names of components which are not to be merged e.g. “Bus”

  • inplace (bool, default False) – If True, merge into network in-place, otherwise a copy is made.

  • with_time (bool, default True) – If False, only static data is merged.

Returns:

receiving_n – Merged network, or None if inplace=True

Return type:

pypsa.Network

property meta#

Dictionary of the network meta data.

mremove(class_name, names)#

Removes multiple components from the network.

Removes them from component DataFrames.

Parameters:
  • class_name (string) – Component class name

  • name (list-like) – Component names

Examples

>>> network.mremove("Line", ["line x", "line y"])
pf(snapshots=None, skip_pre=False, x_tol=1e-06, use_seed=False, distribute_slack=False, slack_weights='p_set')#

Full non-linear power flow for generic network.

Parameters:
  • snapshots (list-like|single snapshot) – A subset or an elements of network.snapshots on which to run the power flow, defaults to network.snapshots

  • skip_pre (bool, default False) – Skip the preliminary steps of computing topology, calculating dependent values and finding bus controls.

  • x_tol (float) – Tolerance for Newton-Raphson power flow.

  • use_seed (bool, default False) – Use a seed for the initial guess for the Newton-Raphson algorithm.

  • distribute_slack (bool, default False) – If True, distribute the slack power across generators proportional to generator dispatch by default or according to the distribution scheme provided in slack_weights. If False only the slack generator takes up the slack.

  • slack_weights (dict|str, default 'p_set') – Distribution scheme describing how to determine the fraction of the total slack power (of each sub network individually) a bus of the subnetwork takes up. Default is to distribute proportional to generator dispatch (‘p_set’). Another option is to distribute proportional to (optimised) nominal capacity (‘p_nom’ or ‘p_nom_opt’). Custom weights can be specified via a dictionary that has a key for each subnetwork index (network.sub_networks.index) and a pandas.Series/dict with buses or generators of the corresponding subnetwork as index/keys. When specifying custom weights with buses as index/keys the slack power of a bus is distributed among its generators in proportion to their nominal capacity (p_nom) if given, otherwise evenly.

Returns:

Dictionary with keys ‘n_iter’, ‘converged’, ‘error’ and dataframe values indicating number of iterations, convergence status, and iteration error for each snapshot (rows) and sub_network (columns)

Return type:

dict

plot(margin=0.05, ax=None, geomap=True, projection=None, bus_colors='cadetblue', bus_alpha=1, bus_sizes=0.02, bus_cmap=None, bus_norm=None, bus_split_circles=False, line_colors='rosybrown', link_colors='darkseagreen', transformer_colors='orange', line_alpha=1, link_alpha=1, transformer_alpha=1, line_widths=1.5, link_widths=1.5, transformer_widths=1.5, line_cmap=None, link_cmap=None, transformer_cmap=None, line_norm=None, link_norm=None, transformer_norm=None, flow=None, branch_components=None, layouter=None, title='', boundaries=None, geometry=False, jitter=None, color_geomap=None)#

Plot the network buses and lines using matplotlib and cartopy.

Parameters:
  • margin (float, defaults to 0.05) – Margin at the sides as proportion of distance between max/min x, y Will be ignored if boundaries are given.

  • ax (matplotlib ax, defaults to plt.gca()) – Axis to which to plot the network

  • geomap (bool/str, default True) – Switch to use Cartopy and draw geographical features. If string is passed, it will be used as a resolution argument, valid options are ‘10m’, ‘50m’ and ‘110m’.

  • projection (cartopy.crs.Projection, defaults to None) – Define the projection of your geomap, only valid if cartopy is installed. If None (default) is passed the projection for cartopy is set to cartopy.crs.PlateCarree

  • bus_colors (dict/pandas.Series) – Colors for the buses, defaults to “cadetblue”. If bus_sizes is a pandas.Series with a Multiindex, bus_colors defaults to the n.carriers[‘color’] column.

  • bus_alpha (float) – Adds alpha channel to buses, defaults to 1.

  • bus_sizes (dict/pandas.Series) – Sizes of bus points, defaults to 1e-2. If a multiindexed Series is passed, the function will draw pies for each bus (first index level) with segments of different color (second index level). Such a Series is ob- tained by e.g. n.generators.groupby([‘bus’, ‘carrier’]).p_nom.sum()

  • bus_cmap (plt.cm.ColorMap/str) – If bus_colors are floats, this color map will assign the colors

  • bus_norm (plt.Normalize|matplotlib.colors.*Norm) – The norm applied to the bus_cmap.

  • bus_split_circles (bool, default False) – Draw half circles if bus_sizes is a pandas.Series with a Multiindex. If set to true, the upper half circle per bus then includes all positive values of the series, the lower half circle all negative values. Defaults to False.

  • line_colors (str/pandas.Series) – Colors for the lines, defaults to ‘rosybrown’.

  • link_colors (str/pandas.Series) – Colors for the links, defaults to ‘darkseagreen’.

  • transfomer_colors (str/pandas.Series) – Colors for the transfomer, defaults to ‘orange’.

  • line_alpha (str/pandas.Series) – Alpha for the lines, defaults to 1.

  • link_alpha (str/pandas.Series) – Alpha for the links, defaults to 1.

  • transfomer_alpha (str/pandas.Series) – Alpha for the transfomer, defaults to 1.

  • line_widths (dict/pandas.Series) – Widths of lines, defaults to 1.5

  • link_widths (dict/pandas.Series) – Widths of links, defaults to 1.5

  • transformer_widths (dict/pandas.Series) – Widths of transformer, defaults to 1.5

  • line_cmap (plt.cm.ColorMap/str|dict) – If line_colors are floats, this color map will assign the colors.

  • link_cmap (plt.cm.ColorMap/str|dict) – If link_colors are floats, this color map will assign the colors.

  • transformer_cmap (plt.cm.ColorMap/str|dict) – If transformer_colors are floats, this color map will assign the colors.

  • line_norm (plt.Normalize|matplotlib.colors.*Norm) – The norm applied to the line_cmap.

  • link_norm (plt.Normalize|matplotlib.colors.*Norm) – The norm applied to the link_cmap.

  • transformer_norm (matplotlib.colors.Normalize|matplotlib.colors.*Norm) – The norm applied to the transformer_cmap.

  • flow (snapshot/pandas.Series/function/string) – Flow to be displayed in the plot, defaults to None. If an element of n.snapshots is given, the flow at this timestamp will be displayed. If an aggregation function is given, is will be applied to the total network flow via pandas.DataFrame.agg (accepts also function names). Otherwise flows can be specified by passing a pandas Series with MultiIndex including all necessary branch components. Use the line_widths argument to additionally adjust the size of the flow arrows.

  • layouter (networkx.drawing.layout function, default None) –

    Layouting function from networkx which overrules coordinates given in n.buses[['x', 'y']]. See list of available options.

  • title (string) – Graph title

  • boundaries (list of four floats) – Boundaries of the plot in format [x1, x2, y1, y2]

  • branch_components (list of str) – Branch components to be plotted, defaults to Line and Link.

  • jitter (None|float) – Amount of random noise to add to bus positions to distinguish overlapping buses

  • color_geomap (dict or bool) – Specify colors to paint land and sea areas in. If True, it defaults to {‘ocean’: ‘lightblue’, ‘land’: ‘whitesmoke’}. If no dictionary is provided, colors are white. If False, no geographical features are plotted.

Returns:

bus_collection, branch_collection1, … – Collections for buses and branches.

Return type:

tuple of Collections

pnl(component_name)#

Return the dictionary of DataFrames of varying components for component_name, i.e. network.component_names_t.

Parameters:

component_name (string) –

Return type:

dict of pandas.DataFrame

remove(class_name, name)#

Removes a single component from the network.

Removes it from component DataFrames.

Parameters:
  • class_name (string) – Component class name

  • name (string) – Component name

Examples

>>> network.remove("Line", "my_line 12345")
set_investment_periods(periods)#

Set the investment periods of the network.

If the network snapshots are a pandas.MultiIndex, the investment periods have to be a subset of the first level. If snapshots are a single index, they and all time-series are repeated for all periods. This changes the network snapshots to be a MultiIndex (inplace operation) with the first level being the investment periods and the second level the snapshots.

Parameters:
  • n (pypsa.Network) –

  • periods (list) – List of periods to be selected/initialized.

Return type:

None.

set_snapshots(snapshots: Union[List, Index, MultiIndex, DatetimeIndex], default_snapshot_weightings: float = 1.0, weightings_from_timedelta: bool = False) None#

Set the snapshots/time steps and reindex all time-dependent data.

Snapshot weightings, typically representing the hourly length of each snapshot, is filled with the default_snapshot_weighintgs value, or uses the timedelta of the snapshots if weightings_from_timedelta flag is True, and snapshots are of type pd.DatetimeIndex.

This will reindex all components time-dependent DataFrames (:role:`Network.pnl`); NaNs are filled with the default value for that quantity.

Parameters:
  • snapshots (list, pandas.Index, pd.MultiIndex or pd.DatetimeIndex) – All time steps.

  • default_snapshot_weightings (float) – The default weight for each snapshot. Defaults to 1.0.

  • weightings_from_timedelta (bool) – Wheter to use the timedelta of snapshots as snapshot_weightings if snapshots is of type pd.DatetimeIndex. Defaults to False.

Return type:

None

property snapshot_weightings#

Weightings applied to each snapshots during the optimization (LOPF).

  • Objective weightings multiply the operational cost in the objective function.

  • Generator weightings multiply the impact of all generators in global constraints, e.g. multiplier of GHG emmissions.

  • Store weightings define the elapsed hours for the charge, discharge standing loss and spillage of storage units and stores in order to determine the state of charge.

property snapshots#

Time steps of the network

property srid#

Spatial reference system identifier of the network’s geometries (n.shapes).

to_crs(new)#

Convert the network’s geometries and bus coordinates to a new coordinate reference system.

Sub-Network#

class pypsa.SubNetwork(network, name='')#

Connected network of electric buses (AC or DC) with passive flows or isolated non-electric buses.

Generated by network.determine_network_topology().

adjacency_matrix(branch_components=None, investment_period=None, busorder=None, weights=None)#

Construct a sparse adjacency matrix (directed)

Parameters:
  • branch_components (iterable sublist of branch_components) – Buses connected by any of the selected branches are adjacent (default: branch_components (network) or passive_branch_components (sub_network))

  • busorder (pd.Index subset of network.buses.index) – Basis to use for the matrix representation of the adjacency matrix (default: buses.index (network) or buses_i() (sub_network))

  • weights (pd.Series or None (default)) – If given must provide a weight for each branch, multi-indexed on branch_component name and branch name.

Returns:

adjacency_matrix – Directed adjacency matrix

Return type:

sp.sparse.coo_matrix

calculate_BODF(skip_pre=False)#

Calculate the Branch Outage Distribution Factor (BODF) for sub_network.

Sets sub_network.BODF as a (dense) numpy array.

The BODF is a num_branch x num_branch 2d array.

For the outage of branch l, the new flow on branch k is given in terms of the flow before the outage

f_k^after = f_k^before + BODF_{kl} f_l^before

Note that BODF_{ll} = -1.

Parameters:
  • sub_network (pypsa.SubNetwork) –

  • skip_pre (bool, default False) – Skip the preliminary step of computing the PTDF.

Examples

>>> sub_network.caculate_BODF()
calculate_B_H(skip_pre=False)#

Calculate B and H matrices for AC or DC sub-networks.

calculate_PTDF(skip_pre=False)#

Calculate the Power Transfer Distribution Factor (PTDF) for sub_network.

Sets sub_network.PTDF as a (dense) numpy array.

Parameters:
  • sub_network (pypsa.SubNetwork) –

  • skip_pre (bool, default False) – Skip the preliminary steps of computing topology, calculating dependent values, finding bus controls and computing B and H.

calculate_Y(skip_pre=False)#

Calculate bus admittance matrices for AC sub-networks.

find_bus_controls()#

Find slack and all PV and PQ buses for a sub_network.

This function also fixes sub_network.buses_o, a DataFrame ordered by control type.

find_slack_bus()#

Find the slack bus in a connected sub-network.

graph(branch_components=None, weight=None, inf_weight=False)#

Build NetworkX graph.

Parameters:
  • network (Network|SubNetwork) –

  • branch_components ([str]) – Components to use as branches. The default are passive_branch_components in the case of a SubNetwork and branch_components in the case of a Network.

  • weight (str) – Branch attribute to use as weight

  • inf_weight (bool|float) – How to treat infinite weights (default: False). True keeps the infinite weight. False skips edges with infinite weight. If a float is given it is used instead.

Returns:

graph – NetworkX graph

Return type:

OrderedGraph

incidence_matrix(branch_components=None, busorder=None)#

Construct a sparse incidence matrix (directed)

Parameters:
  • branch_components (iterable sublist of branch_components) – Buses connected by any of the selected branches are adjacent (default: branch_components (network) or passive_branch_components (sub_network))

  • busorder (pd.Index subset of network.buses.index) – Basis to use for the matrix representation of the adjacency matrix (default: buses.index (network) or buses_i() (sub_network))

Returns:

incidence_matrix – Directed incidence matrix

Return type:

sp.sparse.csr_matrix

iterate_components(components=None, skip_empty=True)#

Iterate over components of the subnetwork and extract corresponding data.

Parameters:
  • components (list-like, optional) – List of components (‘Generator’, ‘Line’, etc.) to iterate over, by default None

  • skip_empty (bool, optional) – Whether to skip a components with no assigned assets, by default True

Yields:

Component – Container for component data. See Component class for details.

lpf(snapshots=None, skip_pre=False)#

Linear power flow for connected sub-network.

Parameters:
  • snapshots (list-like|single snapshot) – A subset or an elements of network.snapshots on which to run the power flow, defaults to network.snapshots

  • skip_pre (bool, default False) – Skip the preliminary steps of computing topology, calculating dependent values and finding bus controls.

Return type:

None

pf(snapshots=None, skip_pre=False, x_tol=1e-06, use_seed=False, distribute_slack=False, slack_weights='p_set')#

Non-linear power flow for connected sub-network.

Parameters:
  • snapshots (list-like|single snapshot) – A subset or an elements of network.snapshots on which to run the power flow, defaults to network.snapshots

  • skip_pre (bool, default False) – Skip the preliminary steps of computing topology, calculating dependent values and finding bus controls.

  • x_tol (float) – Tolerance for Newton-Raphson power flow.

  • use_seed (bool, default False) – Use a seed for the initial guess for the Newton-Raphson algorithm.

  • distribute_slack (bool, default False) – If True, distribute the slack power across generators proportional to generator dispatch by default or according to the distribution scheme provided in slack_weights. If False only the slack generator takes up the slack.

  • slack_weights (pandas.Series|str, default 'p_set') – Distribution scheme describing how to determine the fraction of the total slack power a bus of the subnetwork takes up. Default is to distribute proportional to generator dispatch (‘p_set’). Another option is to distribute proportional to (optimised) nominal capacity (‘p_nom’ or ‘p_nom_opt’). Custom weights can be provided via a pandas.Series/dict that has the buses or the generators of the subnetwork as index/keys. When using custom weights with buses as index/keys the slack power of a bus is distributed among its generators in proportion to their nominal capacity (p_nom) if given, otherwise evenly.

Returns:

  • Tuple of three pandas.Series indicating number of iterations,

  • remaining error, and convergence status for each snapshot

Descriptors#

Descriptors for component attributes.

class pypsa.descriptors.Dict#

Dict is a subclass of dict, which allows you to get AND SET items in the dict using the attribute syntax!

Stripped down from addict mewwts/addict .

class pypsa.descriptors.OrderedGraph(incoming_graph_data=None, multigraph_input=None, **attr)#
adjlist_dict_factory#

alias of OrderedDict

node_dict_factory#

alias of OrderedDict

pypsa.descriptors.allocate_series_dataframes(network, series)#

Populate time-varying outputs with default values.

Parameters:
  • network (pypsa.Network) –

  • series (dict) – Dictionary of components and their attributes to populate (see example)

Return type:

None

Examples

>>> allocate_series_dataframes(network, {'Generator': ['p'],
                                         'Load': ['p']})
pypsa.descriptors.expand_series(ser, columns)#

Helper function to quickly expand a series to a dataframe with according column axis and every single column being the equal to the given series.

pypsa.descriptors.get_active_assets(n, c, investment_period)#

Getter function.

Get True values for elements of component c which are active at a given investment period. These are calculated from lifetime and the build year.

pypsa.descriptors.get_activity_mask(n, c, sns=None, index=None)#

Getter function.

Get a boolean array with True values for elements of component c which are active at a specific snapshot. If the network is in multi_investment_period mode (given by n._multi_invest), these are calculated from lifetime and the build year. Otherwise all values are set to True.

pypsa.descriptors.get_bounds_pu(n, c, sns, index=None, attr=None)#

Getter function to retrieve the per unit bounds of a given compoent for given snapshots and possible subset of elements (e.g. non-extendables). Depending on the attr you can further specify the bounds of the variable you are looking at, e.g. p_store for storage units.

Parameters:
  • n (pypsa.Network) –

  • c (string) – Component name, e.g. “Generator”, “Line”.

  • sns (pandas.Index/pandas.DateTimeIndex) – set of snapshots for the bounds

  • index (pd.Index, default None) – Subset of the component elements. If None (default) bounds of all elements are returned.

  • attr (string, default None) – attribute name for the bounds, e.g. “p”, “s”, “p_store”

pypsa.descriptors.get_committable_i(n, c)#

Getter function.

Get the index of commitable elements of a given component.

pypsa.descriptors.get_extendable_i(n, c)#

Getter function.

Get the index of extendable elements of a given component.

pypsa.descriptors.get_non_extendable_i(n, c)#

Getter function.

Get the index of non-extendable elements of a given component.

pypsa.descriptors.get_switchable_as_dense(network, component, attr, snapshots=None, inds=None)#

Return a Dataframe for a time-varying component attribute with values for all non-time-varying components filled in with the default values for the attribute.

Parameters:
  • network (pypsa.Network) –

  • component (string) – Component object name, e.g. ‘Generator’ or ‘Link’

  • attr (string) – Attribute name

  • snapshots (pandas.Index) – Restrict to these snapshots rather than network.snapshots.

  • inds (pandas.Index) – Restrict to these components rather than network.components.index

Return type:

pandas.DataFrame

Examples

>>> get_switchable_as_dense(network, 'Generator', 'p_max_pu')
pypsa.descriptors.get_switchable_as_iter(network, component, attr, snapshots, inds=None)#

Return an iterator over snapshots for a time-varying component attribute with values for all non-time-varying components filled in with the default values for the attribute.

Parameters:
  • network (pypsa.Network) –

  • component (string) – Component object name, e.g. ‘Generator’ or ‘Link’

  • attr (string) – Attribute name

  • snapshots (pandas.Index) – Restrict to these snapshots rather than network.snapshots.

  • inds (pandas.Index) – Restrict to these items rather than all of network.{generators, ..}.index

Return type:

pandas.DataFrame

Examples

>>> get_switchable_as_iter(network, 'Generator', 'p_max_pu', snapshots)
pypsa.descriptors.zsum(s, *args, **kwargs)#

Pandas 0.21.0 changes sum() behavior so that the result of applying sum over an empty DataFrame is NaN.

Meant to be set as pd.Series.zsum = zsum.

Input and Output#

Functions for importing and exporting data.

pypsa.io.export_to_csv_folder(network, csv_folder_name, encoding=None, export_standard_types=False)#

Export network and components to a folder of CSVs.

Both static and series attributes of all components are exported, but only if they have non-default values.

If csv_folder_name does not already exist, it is created.

Static attributes are exported in one CSV file per component, e.g. generators.csv.

Series attributes are exported in one CSV file per component per attribute, e.g. generators-p_set.csv.

Parameters:
  • csv_folder_name (string) – Name of folder to which to export.

  • encoding (str, default None) –

    Encoding to use for UTF when reading (ex. ‘utf-8’). List of Python standard encodings

  • export_standard_types (boolean, default False) – If True, then standard types are exported too (upon reimporting you should then set “ignore_standard_types” when initialising the network).

Examples

>>> network.export_to_csv_folder(csv_folder_name)
pypsa.io.export_to_hdf5(network, path, export_standard_types=False, **kwargs)#

Export network and components to an HDF store.

Both static and series attributes of components are exported, but only if they have non-default values.

If path does not already exist, it is created.

Parameters:
  • path (string) – Name of hdf5 file to which to export (if it exists, it is overwritten)

  • export_standard_types (boolean, default False) – If True, then standard types are exported too (upon reimporting you should then set “ignore_standard_types” when initialising the network).

  • **kwargs – Extra arguments for pd.HDFStore to specify f.i. compression (default: complevel=4)

Examples

>>> network.export_to_hdf5(filename)
pypsa.io.export_to_netcdf(network, path=None, export_standard_types=False, compression=None, float32=False)#

Export network and components to a netCDF file.

Both static and series attributes of components are exported, but only if they have non-default values.

If path does not already exist, it is created.

If no path is passed, no file is exported, but the xarray.Dataset is still returned.

Be aware that this cannot export boolean attributes on the Network class, e.g. network.my_bool = False is not supported by netCDF.

Parameters:
  • path (string|None) – Name of netCDF file to which to export (if it exists, it is overwritten); if None is passed, no file is exported.

  • export_standard_types (boolean, default False) – If True, then standard types are exported too (upon reimporting you should then set “ignore_standard_types” when initialising the network).

  • compression (dict|None) – Compression level to use for all features which are being prepared. The compression is handled via xarray.Dataset.to_netcdf(…). For details see: https://docs.xarray.dev/en/stable/generated/xarray.Dataset.to_netcdf.html An example compression directive is {'zlib': True, 'complevel': 4}. The default is None which disables compression.

  • float32 (boolean, default False) – If True, typecasts values to float32.

Returns:

ds

Return type:

xarray.Dataset

Examples

>>> network.export_to_netcdf("my_file.nc")
pypsa.io.import_components_from_dataframe(network, dataframe, cls_name)#

Import components from a pandas DataFrame.

If columns are missing then defaults are used.

If extra columns are added, these are left in the resulting component dataframe.

Parameters:
  • dataframe (pandas.DataFrame) – A DataFrame whose index is the names of the components and whose columns are the non-default attributes.

  • cls_name (string) – Name of class of component, e.g. "Line", "Bus", "Generator", "StorageUnit"

Examples

>>> import pandas as pd
>>> buses = ['Berlin', 'Frankfurt', 'Munich', 'Hamburg']
>>> network.import_components_from_dataframe(
        pd.DataFrame({"v_nom" : 380, "control" : 'PV'},
                    index=buses),
                    "Bus")
>>> network.import_components_from_dataframe(
        pd.DataFrame({"carrier" : "solar", "bus" : buses, "p_nom_extendable" : True},
                    index=[b+" PV" for b in buses]),
                    "Generator")
pypsa.io.import_from_csv_folder(network, csv_folder_name, encoding=None, skip_time=False)#

Import network data from CSVs in a folder.

The CSVs must follow the standard form, see pypsa/examples.

Parameters:
  • csv_folder_name (string) – Name of folder

  • encoding (str, default None) –

    Encoding to use for UTF when reading (ex. ‘utf-8’). List of Python standard encodings

  • skip_time (bool, default False) – Skip reading in time dependent attributes

Examples

>>> network.import_from_csv_folder(csv_folder_name)
pypsa.io.import_from_hdf5(network, path, skip_time=False)#

Import network data from HDF5 store at path.

Parameters:
  • path (string, Path) – Name of HDF5 store. The string could be a URL.

  • skip_time (bool, default False) – Skip reading in time dependent attributes

pypsa.io.import_from_netcdf(network, path, skip_time=False)#

Import network data from netCDF file or xarray Dataset at path.

Parameters:
  • path (string|xr.Dataset) – Path to netCDF dataset or instance of xarray Dataset. The string could be a URL.

  • skip_time (bool, default False) – Skip reading in time dependent attributes

pypsa.io.import_from_pandapower_net(network, net, extra_line_data=False, use_pandapower_index=False)#

Import PyPSA network from pandapower net.

Importing from pandapower is still in beta; not all pandapower components are supported.

Unsupported features include: - three-winding transformers - switches - in_service status and - tap positions of transformers

Parameters:
  • net (pandapower network) –

  • extra_line_data (boolean, default: False) – if True, the line data for all parameters is imported instead of only the type

  • use_pandapower_index (boolean, default: False) – if True, use integer numbers which is the pandapower index standard if False, use any net.name as index (e.g. ‘Bus 1’ (str) or 1 (int))

Examples

>>> network.import_from_pandapower_net(net)
OR
>>> import pypsa
>>> import pandapower as pp
>>> import pandapower.networks as pn
>>> net = pn.create_cigre_network_mv(with_der='all')
>>> network = pypsa.Network()
>>> network.import_from_pandapower_net(net, extra_line_data=True)
pypsa.io.import_from_pypower_ppc(network, ppc, overwrite_zero_s_nom=None)#

Import network from PYPOWER PPC dictionary format version 2.

Converts all baseMVA to base power of 1 MVA.

For the meaning of the pypower indices, see also pypower/idx_*.

Parameters:
  • ppc (PYPOWER PPC dict) –

  • overwrite_zero_s_nom (Float or None, default None) –

Examples

>>> from pypower.api import case30
>>> ppc = case30()
>>> network.import_from_pypower_ppc(ppc)
pypsa.io.import_series_from_dataframe(network, dataframe, cls_name, attr)#

Import time series from a pandas DataFrame.

Parameters:
  • dataframe (pandas.DataFrame) – A DataFrame whose index is network.snapshots and whose columns are a subset of the relevant components.

  • cls_name (string) – Name of class of component

  • attr (string) – Name of time-varying series attribute

Examples

>>> import numpy as np
>>> network.set_snapshots(range(10))
>>> network.import_series_from_dataframe(
        pd.DataFrame(np.random.rand(10, 4),
            columns=network.generators.index,
                        index=range(10)),
                    "Generator",
                    "p_max_pu")
pypsa.io.merge(network, other, components_to_skip=None, inplace=False, with_time=True)#

Merge the components of two networks.

Requires disjunct sets of component indices and, if time-dependent data is merged, identical snapshots and snapshot weightings.

If a component in other does not have values for attributes present in network, default values are set.

If a component in other has attributes which are not present in network these attributes are ignored.

Parameters:
  • network (pypsa.Network) – Network to add to.

  • other (pypsa.Network) – Network to add from.

  • components_to_skip (list-like, default None) – List of names of components which are not to be merged e.g. “Bus”

  • inplace (bool, default False) – If True, merge into network in-place, otherwise a copy is made.

  • with_time (bool, default True) – If False, only static data is merged.

Returns:

receiving_n – Merged network, or None if inplace=True

Return type:

pypsa.Network

Examples#

This module contains functions for retrieving/loading example networks provided by the PyPSA project.

pypsa.examples.ac_dc_meshed(update=False, from_master=False, remove_link_p_set=True)#

Load the meshed AC-DC network example of pypsa stored in the PyPSA repository.

Parameters:
  • update (bool, optional) – Whether to update the locally stored network data. The default is False.

  • from_master (bool, optional) – Whether to retrieve from the master branch of the pypsa repository.

Return type:

pypsa.Network

pypsa.examples.scigrid_de(update=False, from_master=False)#

Load the SciGrid network example of pypsa stored in the PyPSA repository.

Parameters:

update (bool, optional) – Whether to update the locally stored network data. The default is False.

Return type:

pypsa.Network

pypsa.examples.storage_hvdc(update=False, from_master=False)#

Load the storage network example of pypsa stored in the PyPSA repository.

Parameters:

update (bool, optional) – Whether to update the locally stored network data. The default is False.

Return type:

pypsa.Network

Network Graph#

Graph helper functions, which are attached to network and sub_network.

pypsa.graph.adjacency_matrix(network, branch_components=None, investment_period=None, busorder=None, weights=None)#

Construct a sparse adjacency matrix (directed)

Parameters:
  • branch_components (iterable sublist of branch_components) – Buses connected by any of the selected branches are adjacent (default: branch_components (network) or passive_branch_components (sub_network))

  • busorder (pd.Index subset of network.buses.index) – Basis to use for the matrix representation of the adjacency matrix (default: buses.index (network) or buses_i() (sub_network))

  • weights (pd.Series or None (default)) – If given must provide a weight for each branch, multi-indexed on branch_component name and branch name.

Returns:

adjacency_matrix – Directed adjacency matrix

Return type:

sp.sparse.coo_matrix

pypsa.graph.graph(network, branch_components=None, weight=None, inf_weight=False)#

Build NetworkX graph.

Parameters:
  • network (Network|SubNetwork) –

  • branch_components ([str]) – Components to use as branches. The default are passive_branch_components in the case of a SubNetwork and branch_components in the case of a Network.

  • weight (str) – Branch attribute to use as weight

  • inf_weight (bool|float) – How to treat infinite weights (default: False). True keeps the infinite weight. False skips edges with infinite weight. If a float is given it is used instead.

Returns:

graph – NetworkX graph

Return type:

OrderedGraph

pypsa.graph.incidence_matrix(network, branch_components=None, busorder=None)#

Construct a sparse incidence matrix (directed)

Parameters:
  • branch_components (iterable sublist of branch_components) – Buses connected by any of the selected branches are adjacent (default: branch_components (network) or passive_branch_components (sub_network))

  • busorder (pd.Index subset of network.buses.index) – Basis to use for the matrix representation of the adjacency matrix (default: buses.index (network) or buses_i() (sub_network))

Returns:

incidence_matrix – Directed incidence matrix

Return type:

sp.sparse.csr_matrix

Power Flow#

Power flow functionality.

pypsa.pf.aggregate_multi_graph(sub_network)#

Aggregate branches between same buses and replace with a single branch with aggregated properties (e.g. s_nom is summed, length is averaged).

pypsa.pf.apply_line_types(network)#

Calculate line electrical parameters x, r, b, g from standard types.

pypsa.pf.apply_transformer_t_model(network)#

Convert given T-model parameters to PI-model parameters using wye-delta transformation.

pypsa.pf.apply_transformer_types(network)#

Calculate transformer electrical parameters x, r, b, g from standard types.

pypsa.pf.calculate_B_H(sub_network, skip_pre=False)#

Calculate B and H matrices for AC or DC sub-networks.

pypsa.pf.calculate_PTDF(sub_network, skip_pre=False)#

Calculate the Power Transfer Distribution Factor (PTDF) for sub_network.

Sets sub_network.PTDF as a (dense) numpy array.

Parameters:
  • sub_network (pypsa.SubNetwork) –

  • skip_pre (bool, default False) – Skip the preliminary steps of computing topology, calculating dependent values, finding bus controls and computing B and H.

pypsa.pf.calculate_Y(sub_network, skip_pre=False)#

Calculate bus admittance matrices for AC sub-networks.

pypsa.pf.calculate_dependent_values(network)#

Calculate per unit impedances and append voltages to lines and shunt impedances.

pypsa.pf.find_bus_controls(sub_network)#

Find slack and all PV and PQ buses for a sub_network.

This function also fixes sub_network.buses_o, a DataFrame ordered by control type.

pypsa.pf.find_cycles(sub_network, weight='x_pu')#

Find all cycles in the sub_network and record them in sub_network.C.

networkx collects the cycles with more than 2 edges; then the 2-edge cycles from the MultiGraph must be collected separately (for cases where there are multiple lines between the same pairs of buses).

Cycles with infinite impedance are skipped.

pypsa.pf.find_slack_bus(sub_network)#

Find the slack bus in a connected sub-network.

pypsa.pf.find_tree(sub_network, weight='x_pu')#

Get the spanning tree of the graph, choose the node with the highest degree as a central “tree slack” and then see for each branch which paths from the slack to each node go through the branch.

pypsa.pf.network_batch_lpf(network, snapshots=None)#

Batched linear power flow with numpy.dot for several snapshots.

pypsa.pf.network_lpf(network, snapshots=None, skip_pre=False)#

Linear power flow for generic network.

Parameters:
  • snapshots (list-like|single snapshot) – A subset or an elements of network.snapshots on which to run the power flow, defaults to network.snapshots

  • skip_pre (bool, default False) – Skip the preliminary steps of computing topology, calculating dependent values and finding bus controls.

Return type:

None

pypsa.pf.network_pf(network, snapshots=None, skip_pre=False, x_tol=1e-06, use_seed=False, distribute_slack=False, slack_weights='p_set')#

Full non-linear power flow for generic network.

Parameters:
  • snapshots (list-like|single snapshot) – A subset or an elements of network.snapshots on which to run the power flow, defaults to network.snapshots

  • skip_pre (bool, default False) – Skip the preliminary steps of computing topology, calculating dependent values and finding bus controls.

  • x_tol (float) – Tolerance for Newton-Raphson power flow.

  • use_seed (bool, default False) – Use a seed for the initial guess for the Newton-Raphson algorithm.

  • distribute_slack (bool, default False) – If True, distribute the slack power across generators proportional to generator dispatch by default or according to the distribution scheme provided in slack_weights. If False only the slack generator takes up the slack.

  • slack_weights (dict|str, default 'p_set') – Distribution scheme describing how to determine the fraction of the total slack power (of each sub network individually) a bus of the subnetwork takes up. Default is to distribute proportional to generator dispatch (‘p_set’). Another option is to distribute proportional to (optimised) nominal capacity (‘p_nom’ or ‘p_nom_opt’). Custom weights can be specified via a dictionary that has a key for each subnetwork index (network.sub_networks.index) and a pandas.Series/dict with buses or generators of the corresponding subnetwork as index/keys. When specifying custom weights with buses as index/keys the slack power of a bus is distributed among its generators in proportion to their nominal capacity (p_nom) if given, otherwise evenly.

Returns:

Dictionary with keys ‘n_iter’, ‘converged’, ‘error’ and dataframe values indicating number of iterations, convergence status, and iteration error for each snapshot (rows) and sub_network (columns)

Return type:

dict

pypsa.pf.newton_raphson_sparse(f, guess, dfdx, x_tol=1e-10, lim_iter=100, distribute_slack=False, slack_weights=None)#

Solve f(x) = 0 with initial guess for x and dfdx(x).

dfdx(x) should return a sparse Jacobian. Terminate if error on norm of f(x) is < x_tol or there were more than lim_iter iterations.

pypsa.pf.sub_network_lpf(sub_network, snapshots=None, skip_pre=False)#

Linear power flow for connected sub-network.

Parameters:
  • snapshots (list-like|single snapshot) – A subset or an elements of network.snapshots on which to run the power flow, defaults to network.snapshots

  • skip_pre (bool, default False) – Skip the preliminary steps of computing topology, calculating dependent values and finding bus controls.

Return type:

None

pypsa.pf.sub_network_pf(sub_network, snapshots=None, skip_pre=False, x_tol=1e-06, use_seed=False, distribute_slack=False, slack_weights='p_set')#

Non-linear power flow for connected sub-network.

Parameters:
  • snapshots (list-like|single snapshot) – A subset or an elements of network.snapshots on which to run the power flow, defaults to network.snapshots

  • skip_pre (bool, default False) – Skip the preliminary steps of computing topology, calculating dependent values and finding bus controls.

  • x_tol (float) – Tolerance for Newton-Raphson power flow.

  • use_seed (bool, default False) – Use a seed for the initial guess for the Newton-Raphson algorithm.

  • distribute_slack (bool, default False) – If True, distribute the slack power across generators proportional to generator dispatch by default or according to the distribution scheme provided in slack_weights. If False only the slack generator takes up the slack.

  • slack_weights (pandas.Series|str, default 'p_set') – Distribution scheme describing how to determine the fraction of the total slack power a bus of the subnetwork takes up. Default is to distribute proportional to generator dispatch (‘p_set’). Another option is to distribute proportional to (optimised) nominal capacity (‘p_nom’ or ‘p_nom_opt’). Custom weights can be provided via a pandas.Series/dict that has the buses or the generators of the subnetwork as index/keys. When using custom weights with buses as index/keys the slack power of a bus is distributed among its generators in proportion to their nominal capacity (p_nom) if given, otherwise evenly.

Returns:

  • Tuple of three pandas.Series indicating number of iterations,

  • remaining error, and convergence status for each snapshot

pypsa.pf.sub_network_pf_singlebus(sub_network, snapshots=None, skip_pre=False, distribute_slack=False, slack_weights='p_set', linear=False)#

Non-linear power flow for a sub-network consiting of a single bus.

Parameters:
  • snapshots (list-like|single snapshot) – A subset or an elements of network.snapshots on which to run the power flow, defaults to network.snapshots

  • skip_pre (bool, default False) – Skip the preliminary steps of computing topology, calculating dependent values and finding bus controls.

  • distribute_slack (bool, default False) – If True, distribute the slack power across generators proportional to generator dispatch by default or according to the distribution scheme provided in slack_weights. If False only the slack generator takes up the slack.

  • slack_weights (pandas.Series|str, default 'p_set') – Distribution scheme describing how to determine the fraction of the total slack power a bus of the subnetwork takes up. Default is to distribute proportional to generator dispatch (‘p_set’). Another option is to distribute proportional to (optimised) nominal capacity (‘p_nom’ or ‘p_nom_opt’). Custom weights can be provided via a pandas.Series/dict that has the generators of the single bus as index/keys.

pypsa.pf.wye_to_delta(z1, z2, z3)#

Follows http://home.earthlink.net/~w6rmk/math/wyedelta.htm.

Linopy Optimisation Module#

abstract.py

Build abstracted, extended optimisation problems from PyPSA networks with Linopy.

pypsa.optimization.abstract.optimize_mga(n, snapshots=None, multi_investment_periods=False, weights=None, sense='min', slack=0.05, model_kwargs={}, **kwargs)#

Run modelling-to-generate-alternatives (MGA) on network to find near- optimal solutions.

Parameters:
  • n (pypsa.Network snapshots : list-like) – Set of snapshots to consider in the optimization. The default is None.

  • multi_investment_periods (bool, default False) – Whether to optimise as a single investment period or to optimize in multiple investment periods. Then, snapshots should be a pd.MultiIndex.

  • weights (dict-like) –

    Weights for alternate objective function. The default is None, which minimizes generation capacity. The weights dictionary should be keyed with the component and variable (see pypsa/variables.csv), followed by a float, dict, pd.Series or pd.DataFrame for the coefficients of the objective function. Examples:

    >>> {"Generator": {"p_nom": 1}}
    >>> {"Generator": {"p_nom": pd.Series(1, index=n.generators.index)}}
    >>> {"Generator": {"p_nom": {"gas": 1, "coal": 2}}}
    >>> {"Generator": {"p": pd.Series(1, index=n.generators.index)}
    >>> {"Generator": {"p": pd.DataFrame(1, columns=n.generators.index, index=n.snapshots)}
    

    Weights for non-extendable components are ignored. The dictionary does not need to provide weights for all extendable components.

  • sense (str|int) – Optimization sense of alternate objective function. Defaults to ‘min’. Can also be ‘max’.

  • slack (float) – Cost slack for budget constraint. Defaults to 0.05.

  • model_kwargs (dict) – Keyword arguments used by linopy.Model, such as solver_dir or chunk.

  • **kwargs – Keyword argument used by linopy.Model.solve, such as solver_name,

Returns:

pypsa.optimization.abstract.optimize_security_constrained(n, snapshots=None, branch_outages=None, multi_investment_periods=False, model_kwargs={}, **kwargs)#

Computes Security-Constrained Linear Optimal Power Flow (SCLOPF).

This ensures that no branch is overloaded even given the branch outages.

Parameters:
  • n (pypsa.Network) –

  • snapshots (list-like, optional) – Set of snapshots to consider in the optimization. The default is None.

  • branch_outages (list-like/pandas.Index/pandas.MultiIndex, optional) – Subset of passive branches to consider as possible outages. If a list or a pandas.Index is passed, it is assumed to identify lines. If a multiindex is passed, its first level has to contain the component names, the second the assets. The default None results in all passive branches to be considered.

  • multi_investment_periods (bool, default False) – Whether to optimise as a single investment period or to optimise in multiple investment periods. Then, snapshots should be a pd.MultiIndex.

  • model_kwargs (dict) – Keyword arguments used by linopy.Model, such as solver_dir or chunk.

  • **kwargs – Keyword argument used by linopy.Model.solve, such as solver_name, problem_fn or solver options directly passed to the solver.

Return type:

None

pypsa.optimization.abstract.optimize_transmission_expansion_iteratively(n, snapshots=None, msq_threshold=0.05, min_iterations=1, max_iterations=100, track_iterations=False, line_unit_size=None, link_unit_size=None, line_threshold=0.3, link_threshold=0.3, **kwargs)#

Iterative linear optimization updating the line parameters for passive AC and DC lines. This is helpful when line expansion is enabled. After each successful solving, line impedances and line resistance are recalculated based on the optimization result. If warmstart is possible, it uses the result from the previous iteration to fasten the optimization.

Parameters:
  • snapshots (list or index slice) – A list of snapshots to optimise, must be a subset of network.snapshots, defaults to network.snapshots

  • msq_threshold (float, default 0.05) – Maximal mean square difference between optimized line capacity of the current and the previous iteration. As soon as this threshold is undercut, and the number of iterations is bigger than ‘min_iterations’ the iterative optimization stops

  • min_iterations (integer, default 1) – Minimal number of iteration to run regardless whether the msq_threshold is already undercut

  • max_iterations (integer, default 100) – Maximal number of iterations to run regardless whether msq_threshold is already undercut

  • track_iterations (bool, default False) – If True, the intermediate branch capacities and values of the objective function are recorded for each iteration. The values of iteration 0 represent the initial state.

  • line_unit_size (float, default None) – The unit size for line components. Use None if no discretization is desired.

  • link_unit_size (dict-like, default None) – A dictionary containing the unit sizes for link components, with carrier names as keys. Use None if no discretization is desired.

  • line_threshold (float, default 0.3) – The threshold relative to the unit size for discretizing line components.

  • link_threshold (float, default 0.3) – The threshold relative to the unit size for discretizing link components.

  • **kwargs – Keyword arguments of the n.optimize function which runs at each iteration

pypsa.optimization.abstract.optimize_with_rolling_horizon(n, snapshots=None, horizon=100, overlap=0, **kwargs)#

Optimizes the network in a rolling horizon fashion.

Parameters:
  • n (pypsa.Network) –

  • snapshots (list-like) – Set of snapshots to consider in the optimization. The default is None.

  • horizon (int) – Number of snapshots to consider in each iteration. Defaults to 100.

  • overlap (int) – Number of snapshots to overlap between two iterations. Defaults to 0.

  • **kwargs – Keyword argument used by linopy.Model.solve, such as solver_name,

Return type:

None

common.py

Use common methods for optimization problem definition with Linopy.

pypsa.optimization.common.get_strongly_meshed_buses(n, threshold=45)#

Get the buses which are strongly meshed in the network.

Parameters:
  • n (Network) –

  • threshhold (int) – number of attached components to be counted as strongly meshed

Return type:

pandas series of all meshed buses.

pypsa.optimization.common.reindex(ds, dim, index)#

Index a xarray.DataArray by a pandas.Index while renaming according to the new index name.

Parameters:
  • ds (xr.DataArray) –

  • dim (str) –

  • index (pd.Index) –

Returns:

Reindexed dataarray with renamed dimension.

Return type:

ds

pypsa.optimization.common.set_from_frame(n, c, attr, df)#

Update values in time-dependent attribute from new dataframe.

compat.py

Use compatibility methods for optimization problem definition with Linopy.

This module intends to make the transition from the native pypsa optimization code to the linopy implementation easier.

pypsa.optimization.compat.define_constraints(n, lhs, sense, rhs, name, attr='', axes=None, spec='', mask=None, **kwargs)#

Define a constraint for a given network.

This function mimics the behavior of pypsa.linopt.define_constraints, and was created for compatibility reasons.

Deprecated since version 0.29: This will be removed in 1.0. Use native linopy syntax instead.

pypsa.optimization.compat.define_variables(n, lower, upper, name, attr='', axes=None, spec='', mask=None, **kwargs)#

Define a variable for a given network.

This function mimics the behavior of pypsa.linopt.define_variables, and was created for compatibility reasons.

Deprecated since version 0.29: This will be removed in 1.0. Use native linopy syntax instead.

pypsa.optimization.compat.get_var(n, c, key)#

Get variables directly from network.

Deprecated since version 0.29: This will be removed in 1.0. Use native linopy syntax instead.

pypsa.optimization.compat.join_exprs(arr, **kwargs)#

Sum over linear expression.

This function mimics the behavior of pypsa.linopt.join_exprs, and was created for compatibility reasons.

Deprecated since version 0.29: This will be removed in 1.0. Use native linopy syntax instead.

pypsa.optimization.compat.linexpr(*tuples, as_pandas=True, return_axes=False)#

Define a linear expression.

This function mimics the behavior of pypsa.linopt.linexpr, and was created for compatibility reasons.

Deprecated since version 0.29: This will be removed in 1.0. Use native linopy syntax instead.

constraints.py

Define optimisation constraints from PyPSA networks with Linopy.

pypsa.optimization.constraints.define_fixed_nominal_constraints(n, c, attr)#

Sets constraints for fixing static variables of a given component and attribute to the corresponding values in n.df(c)[attr + ‘_set’].

Parameters:
  • n (pypsa.Network) –

  • c (str) – name of the network component

  • attr (str) – name of the attribute, e.g. ‘p’

pypsa.optimization.constraints.define_fixed_operation_constraints(n, sns, c, attr)#

Sets constraints for fixing time-dependent variables of a given component and attribute to the corresponding values in n.pnl(c)[attr + ‘_set’].

Parameters:
  • n (pypsa.Network) –

  • c (str) – name of the network component

  • attr (str) – name of the attribute, e.g. ‘p’

pypsa.optimization.constraints.define_kirchhoff_voltage_constraints(n, sns)#

Defines Kirchhoff voltage constraints.

pypsa.optimization.constraints.define_modular_constraints(n, c, attr)#

Sets constraints for fixing modular variables of a given component. It allows to define optimal capacity of a component as multiple of the nominal capacity of the single module.

Parameters:
  • n (pypsa.Network) –

  • c (str) – name of the network component

  • attr (str) – name of the variable, e.g. ‘n_opt’

pypsa.optimization.constraints.define_nodal_balance_constraints(n, sns, transmission_losses=0, buses=None, suffix='')#

Defines nodal balance constraints.

pypsa.optimization.constraints.define_nominal_constraints_for_extendables(n, c, attr)#

Sets capacity expansion constraints for extendable assets for a given component and a given attribute.

Note: As GLPK does not like inf values on the right-hand-side we as masking these out.

Parameters:
  • n (pypsa.Network) –

  • c (str) – name of the network component

  • attr (str) – name of the attribute, e.g. ‘p’

pypsa.optimization.constraints.define_operational_constraints_for_committables(n, sns, c)#

Sets power dispatch constraints for committable devices for a given component and a given attribute. The linearized approximation of the unit commitment problem is inspired by Hua et al. (2017) DOI: 10.1109/TPWRS.2017.2735026.

Parameters:
  • n (pypsa.Network) –

  • sns (pd.Index) – Snapshots of the constraint.

  • c (str) – name of the network component

pypsa.optimization.constraints.define_operational_constraints_for_extendables(n, sns, c, attr, transmission_losses)#

Sets power dispatch constraints for extendable devices for a given component and a given attribute.

Parameters:
  • n (pypsa.Network) –

  • sns (pd.Index) – Snapshots of the constraint.

  • c (str) – name of the network component

  • attr (str) – name of the attribute, e.g. ‘p’

pypsa.optimization.constraints.define_operational_constraints_for_non_extendables(n, sns, c, attr, transmission_losses)#

Sets power dispatch constraints for non-extendable and non-commitable assets for a given component and a given attribute.

Parameters:
  • n (pypsa.Network) –

  • sns (pd.Index) – Snapshots of the constraint.

  • c (str) – name of the network component

  • attr (str) – name of the attribute, e.g. ‘p’

pypsa.optimization.constraints.define_ramp_limit_constraints(n, sns, c, attr)#

Defines ramp limits for assets with valid ramplimit.

Parameters:
pypsa.optimization.constraints.define_storage_unit_constraints(n, sns)#

Defines energy balance constraints for storage units. In principal the constraints states:

previous_soc + p_store - p_dispatch + inflow - spill == soc

pypsa.optimization.constraints.define_store_constraints(n, sns)#

Defines energy balance constraints for stores. In principal the constraints states:

previous_e - p == e

global_constraints.py

Define global constraints for optimisation problems with Linopy.

pypsa.optimization.global_constraints.define_growth_limit(n, sns)#

Constraint new installed capacity per investment period.

Parameters:
  • n (pypsa.Network) –

  • sns (list-like) – Set of snapshots to which the constraint should be applied.

pypsa.optimization.global_constraints.define_nominal_constraints_per_bus_carrier(n, sns)#

Set an capacity expansion limit for assets of the same carrier at the same bus (e.g. ‘onwind’ at bus ‘1’). The function searches for columns in the buses dataframe matching the pattern “nom_{min/max}_{carrier}”. In case the constraint should only be defined for one investment period, the column name can be constructed according to “nom_{min/max}_{carrier}_{period}” where period must be in n.investment_periods.

Parameters:
  • n (pypsa.Network) –

  • sns (list-like) – Set of snapshots to which the constraint should be applied.

Return type:

None.

pypsa.optimization.global_constraints.define_operational_limit(n, sns)#

Defines operational limit constraints. It limits the net production of a carrier taking into account generator, storage units and stores.

Parameters:
  • n (pypsa.Network) –

  • sns (list-like) – Set of snapshots to which the constraint should be applied.

Return type:

None.

pypsa.optimization.global_constraints.define_primary_energy_limit(n, sns)#

Defines primary energy constraints. It limits the byproducts of primary energy sources (defined by carriers) such as CO2.

Parameters:
  • n (pypsa.Network) –

  • sns (list-like) – Set of snapshots to which the constraint should be applied.

Return type:

None.

pypsa.optimization.global_constraints.define_tech_capacity_expansion_limit(n, sns)#

Defines per-carrier and potentially per-bus capacity expansion limits.

Parameters:
  • n (pypsa.Network) –

  • sns (list-like) – Set of snapshots to which the constraint should be applied.

Return type:

None.

pypsa.optimization.global_constraints.define_transmission_expansion_cost_limit(n, sns)#

Set a limit for line expansion costs. For the capacity expansion only the carriers ‘AC’ and ‘DC’ are considered.

Parameters:
  • n (pypsa.Network) –

  • sns (list-like) – Set of snapshots to which the constraint should be applied.

Return type:

None.

pypsa.optimization.global_constraints.define_transmission_volume_expansion_limit(n, sns)#

Set a limit for line volume expansion. For the capacity expansion only the carriers ‘AC’ and ‘DC’ are considered.

Parameters:
  • n (pypsa.Network) –

  • sns (list-like) – Set of snapshots to which the constraint should be applied.

Return type:

None.

optimize.py

Build optimisation problems from PyPSA networks with Linopy.

class pypsa.optimization.optimize.OptimizationAccessor(network)#

Optimization accessor for building and solving models using linopy.

add_load_shedding(suffix=' load shedding', buses=None, sign=0.001, marginal_cost=100.0, p_nom=1000000000.0)#

Add load shedding in form of generators to all or a subset of buses.

For more information on load shedding see http://journal.frontiersin.org/article/10.3389/fenrg.2015.00055/full

Parameters:
  • buses (pandas.Index, optional) – Subset of buses where load shedding should be available. Defaults to all buses.

  • sign (float/Series, optional) – Scaling of the load shedding. This is used to scale the price of the load shedding. The default is 1e-3 which translates to a measure in kW instead of MW.

  • marginal_cost (float/Series, optional) – Price of the load shedding. The default is 1e2.

  • p_nom (float/Series, optional) – Maximal load shedding. The default is 1e9 (kW).

assign_duals(assign_all_duals=False)#

Map dual values i.e. shadow prices to network components.

Parameters:
  • n (pypsa.Network) –

  • assign_all_duals (bool, default False) – Whether to assign all dual values or only those that already have a designated place in the network.

assign_solution()#

Map solution to network components.

create_model(snapshots=None, multi_investment_periods=False, transmission_losses=0, linearized_unit_commitment=False, **kwargs)#

Create a linopy.Model instance from a pypsa network.

The model is stored at n.model.

Parameters:
  • n (pypsa.Network) –

  • snapshots (list or index slice) – A list of snapshots to optimise, must be a subset of network.snapshots, defaults to network.snapshots

  • multi_investment_periods (bool, default False) – Whether to optimise as a single investment period or to optimize in multiple investment periods. Then, snapshots should be a pd.MultiIndex.

  • transmission_losses (int, default 0) –

  • linearized_unit_commitment (bool, default False) – Whether to optimise using the linearised unit commitment formulation or not.

  • **kwargs – Keyword arguments used by linopy.Model(), such as solver_dir or chunk.

Return type:

linopy.model

fix_optimal_capacities()#

Fix capacities of extendable assets to optimized capacities.

Use this function when a capacity expansion optimization was already performed and a operational optimization should be done afterwards.

fix_optimal_dispatch()#

Fix dispatch of all assets to optimized values.

Use this function when the optimal dispatch should be used as an starting point for power flow calculation (Network.pf).

optimize_mga(snapshots=None, multi_investment_periods=False, weights=None, sense='min', slack=0.05, model_kwargs={}, **kwargs)#

Run modelling-to-generate-alternatives (MGA) on network to find near- optimal solutions.

Parameters:
  • n (pypsa.Network snapshots : list-like) – Set of snapshots to consider in the optimization. The default is None.

  • multi_investment_periods (bool, default False) – Whether to optimise as a single investment period or to optimize in multiple investment periods. Then, snapshots should be a pd.MultiIndex.

  • weights (dict-like) –

    Weights for alternate objective function. The default is None, which minimizes generation capacity. The weights dictionary should be keyed with the component and variable (see pypsa/variables.csv), followed by a float, dict, pd.Series or pd.DataFrame for the coefficients of the objective function. Examples:

    >>> {"Generator": {"p_nom": 1}}
    >>> {"Generator": {"p_nom": pd.Series(1, index=n.generators.index)}}
    >>> {"Generator": {"p_nom": {"gas": 1, "coal": 2}}}
    >>> {"Generator": {"p": pd.Series(1, index=n.generators.index)}
    >>> {"Generator": {"p": pd.DataFrame(1, columns=n.generators.index, index=n.snapshots)}
    

    Weights for non-extendable components are ignored. The dictionary does not need to provide weights for all extendable components.

  • sense (str|int) – Optimization sense of alternate objective function. Defaults to ‘min’. Can also be ‘max’.

  • slack (float) – Cost slack for budget constraint. Defaults to 0.05.

  • model_kwargs (dict) – Keyword arguments used by linopy.Model, such as solver_dir or chunk.

  • **kwargs – Keyword argument used by linopy.Model.solve, such as solver_name,

Returns:

optimize_security_constrained(snapshots=None, branch_outages=None, multi_investment_periods=False, model_kwargs={}, **kwargs)#

Computes Security-Constrained Linear Optimal Power Flow (SCLOPF).

This ensures that no branch is overloaded even given the branch outages.

Parameters:
  • n (pypsa.Network) –

  • snapshots (list-like, optional) – Set of snapshots to consider in the optimization. The default is None.

  • branch_outages (list-like/pandas.Index/pandas.MultiIndex, optional) – Subset of passive branches to consider as possible outages. If a list or a pandas.Index is passed, it is assumed to identify lines. If a multiindex is passed, its first level has to contain the component names, the second the assets. The default None results in all passive branches to be considered.

  • multi_investment_periods (bool, default False) – Whether to optimise as a single investment period or to optimise in multiple investment periods. Then, snapshots should be a pd.MultiIndex.

  • model_kwargs (dict) – Keyword arguments used by linopy.Model, such as solver_dir or chunk.

  • **kwargs – Keyword argument used by linopy.Model.solve, such as solver_name, problem_fn or solver options directly passed to the solver.

Return type:

None

optimize_transmission_expansion_iteratively(snapshots=None, msq_threshold=0.05, min_iterations=1, max_iterations=100, track_iterations=False, line_unit_size=None, link_unit_size=None, line_threshold=0.3, link_threshold=0.3, **kwargs)#

Iterative linear optimization updating the line parameters for passive AC and DC lines. This is helpful when line expansion is enabled. After each successful solving, line impedances and line resistance are recalculated based on the optimization result. If warmstart is possible, it uses the result from the previous iteration to fasten the optimization.

Parameters:
  • snapshots (list or index slice) – A list of snapshots to optimise, must be a subset of network.snapshots, defaults to network.snapshots

  • msq_threshold (float, default 0.05) – Maximal mean square difference between optimized line capacity of the current and the previous iteration. As soon as this threshold is undercut, and the number of iterations is bigger than ‘min_iterations’ the iterative optimization stops

  • min_iterations (integer, default 1) – Minimal number of iteration to run regardless whether the msq_threshold is already undercut

  • max_iterations (integer, default 100) – Maximal number of iterations to run regardless whether msq_threshold is already undercut

  • track_iterations (bool, default False) – If True, the intermediate branch capacities and values of the objective function are recorded for each iteration. The values of iteration 0 represent the initial state.

  • line_unit_size (float, default None) – The unit size for line components. Use None if no discretization is desired.

  • link_unit_size (dict-like, default None) – A dictionary containing the unit sizes for link components, with carrier names as keys. Use None if no discretization is desired.

  • line_threshold (float, default 0.3) – The threshold relative to the unit size for discretizing line components.

  • link_threshold (float, default 0.3) – The threshold relative to the unit size for discretizing link components.

  • **kwargs – Keyword arguments of the n.optimize function which runs at each iteration

optimize_with_rolling_horizon(snapshots=None, horizon=100, overlap=0, **kwargs)#

Optimizes the network in a rolling horizon fashion.

Parameters:
  • n (pypsa.Network) –

  • snapshots (list-like) – Set of snapshots to consider in the optimization. The default is None.

  • horizon (int) – Number of snapshots to consider in each iteration. Defaults to 100.

  • overlap (int) – Number of snapshots to overlap between two iterations. Defaults to 0.

  • **kwargs – Keyword argument used by linopy.Model.solve, such as solver_name,

Return type:

None

post_processing()#

Post-process the optimized network.

This calculates quantities derived from the optimized values such as power injection per bus and snapshot, voltage angle.

solve_model(extra_functionality=None, solver_name='highs', solver_options={}, assign_all_duals=False, **kwargs)#

Solve an already created model and assign its solution to the network.

Parameters:
  • solver_name (str) – Name of the solver to use.

  • solver_options (dict) – Keyword arguments used by the solver. Can also be passed via **kwargs.

  • assign_all_duals (bool, default False) – Whether to assign all dual values or only those that already have a designated place in the network.

  • **kwargs – Keyword argument used by linopy.Model.solve, such as solver_name, problem_fn or solver options directly passed to the solver.

Returns:

pypsa.optimization.optimize.assign_duals(n, assign_all_duals=False)#

Map dual values i.e. shadow prices to network components.

Parameters:
  • n (pypsa.Network) –

  • assign_all_duals (bool, default False) – Whether to assign all dual values or only those that already have a designated place in the network.

pypsa.optimization.optimize.assign_solution(n)#

Map solution to network components.

pypsa.optimization.optimize.create_model(n, snapshots=None, multi_investment_periods=False, transmission_losses=0, linearized_unit_commitment=False, **kwargs)#

Create a linopy.Model instance from a pypsa network.

The model is stored at n.model.

Parameters:
  • n (pypsa.Network) –

  • snapshots (list or index slice) – A list of snapshots to optimise, must be a subset of network.snapshots, defaults to network.snapshots

  • multi_investment_periods (bool, default False) – Whether to optimise as a single investment period or to optimize in multiple investment periods. Then, snapshots should be a pd.MultiIndex.

  • transmission_losses (int, default 0) –

  • linearized_unit_commitment (bool, default False) – Whether to optimise using the linearised unit commitment formulation or not.

  • **kwargs – Keyword arguments used by linopy.Model(), such as solver_dir or chunk.

Return type:

linopy.model

pypsa.optimization.optimize.define_objective(n, sns)#

Defines and writes out the objective function.

pypsa.optimization.optimize.optimize(n, snapshots=None, multi_investment_periods=False, transmission_losses=0, linearized_unit_commitment=False, model_kwargs={}, extra_functionality=None, assign_all_duals=False, solver_name='highs', solver_options={}, **kwargs)#

Optimize the pypsa network using linopy.

Parameters:
  • n (pypsa.Network) –

  • snapshots (list or index slice) – A list of snapshots to optimise, must be a subset of n.snapshots, defaults to n.snapshots

  • multi_investment_periods (bool, default False) – Whether to optimise as a single investment period or to optimise in multiple investment periods. Then, snapshots should be a pd.MultiIndex.

  • transmission_losses (int, default 0) – Whether an approximation of transmission losses should be included in the linearised power flow formulation. A passed number will denote the number of tangents used for the piecewise linear approximation. Defaults to 0, which ignores losses.

  • linearized_unit_commitment (bool, default False) – Whether to optimise using the linearised unit commitment formulation or not.

  • model_kwargs (dict) – Keyword arguments used by linopy.Model, such as solver_dir or chunk.

  • extra_functionality (callable) – This function must take two arguments extra_functionality(network, snapshots) and is called after the model building is complete, but before it is sent to the solver. It allows the user to add/change constraints and add/change the objective function.

  • assign_all_duals (bool, default False) – Whether to assign all dual values or only those that already have a designated place in the network.

  • solver_name (str) – Name of the solver to use.

  • solver_options (dict) – Keyword arguments used by the solver. Can also be passed via **kwargs.

  • **kwargs – Keyword argument used by linopy.Model.solve, such as solver_name, problem_fn or solver options directly passed to the solver.

Returns:

pypsa.optimization.optimize.post_processing(n)#

Post-process the optimized network.

This calculates quantities derived from the optimized values such as power injection per bus and snapshot, voltage angle.

variables.py

Define optimisation variables from PyPSA networks with Linopy.

pypsa.optimization.variables.define_loss_variables(n, sns, c)#

Initializes variables for transmission losses.

pypsa.optimization.variables.define_modular_variables(n, c, attr)#

Initializes variables ‘attr’ for a given component c to allow a modular expansion of the attribute ‘attr_nom’ It allows to define ‘n_opt’, the optimal number of installed modules.

Parameters:
  • n (pypsa.Network) –

  • c (str) – network component of which the nominal capacity should be defined

  • attr (str) – name of the variable to be handled attached to modular constraints, e.g. ‘p_nom’

pypsa.optimization.variables.define_nominal_variables(n, c, attr)#

Initializes variables for nominal capacities for a given component and a given attribute.

Parameters:
  • n (pypsa.Network) –

  • c (str) – network component of which the nominal capacity should be defined

  • attr (str) – name of the variable, e.g. ‘p_nom’

pypsa.optimization.variables.define_operational_variables(n, sns, c, attr)#

Initializes variables for power dispatch for a given component and a given attribute.

Parameters:
  • n (pypsa.Network) –

  • c (str) – name of the network component

  • attr (str) – name of the attribute, e.g. ‘p’

pypsa.optimization.variables.define_spillage_variables(n, sns)#

Defines the spillage variables for storage units.

Contingency Analysis#

Functionality for contingency analysis, such as branch outages.

pypsa.contingency.calculate_BODF(sub_network, skip_pre=False)#

Calculate the Branch Outage Distribution Factor (BODF) for sub_network.

Sets sub_network.BODF as a (dense) numpy array.

The BODF is a num_branch x num_branch 2d array.

For the outage of branch l, the new flow on branch k is given in terms of the flow before the outage

f_k^after = f_k^before + BODF_{kl} f_l^before

Note that BODF_{ll} = -1.

Parameters:
  • sub_network (pypsa.SubNetwork) –

  • skip_pre (bool, default False) – Skip the preliminary step of computing the PTDF.

Examples

>>> sub_network.caculate_BODF()
pypsa.contingency.network_lpf_contingency(network, snapshots=None, branch_outages=None)#

Computes linear power flow for a selection of branch outages.

Parameters:
  • snapshots (list-like|single snapshot) – A subset or an elements of network.snapshots on which to run the power flow, defaults to network.snapshots NB: currently this only works for a single snapshot

  • branch_outages (list-like) – A list of passive branches which are to be tested for outages. If None, it’s take as all network.passive_branches_i()

Returns:

p0 – num_passive_branch x num_branch_outages DataFrame of new power flows

Return type:

pandas.DataFrame

Examples

>>> network.lpf_contingency(snapshot, branch_outages)

Statistics#

Statistics Accessor.

class pypsa.statistics.Groupers#

Container for all the ‘get_’ methods.

static get_bus_and_carrier(n, c, port='', nice_names=True)#

Get the buses and nice carrier names for a component.

static get_bus_and_carrier_and_bus_carrier(n, c, port='', nice_names=True)#

Get component’s carrier, bus and bus carrier in one combined list.

Used for MultiIndex in energy balance.

static get_bus_unit_and_carrier(n, c, port='', nice_names=True)#

Get the buses and nice carrier names for a component.

static get_carrier(n, c, nice_names=True)#

Get the nice carrier names for a component.

static get_carrier_and_bus_carrier(n, c, port='', nice_names=True)#

Get component carrier and bus carrier in one combined list.

static get_country_and_carrier(n, c, port='', nice_names=True)#

Get component country and carrier.

static get_name_bus_and_carrier(n, c, port='', nice_names=True)#

Get the name, buses and nice carrier names for a component.

class pypsa.statistics.StatisticsAccessor(network)#

Accessor to calculate different statistical values.

capacity_factor(comps=None, aggregate_time='mean', aggregate_groups='sum', at_port=False, groupby=None, bus_carrier=None, nice_names=True)#

Calculate the capacity factor of components in the network.

If bus_carrier is given, only the assets are considered which are connected to buses with carrier bus_carrier.

For information on the list of arguments, see the docs in Network.statistics or pypsa.statistics.StatisticsAccessor.

Parameters:

aggregate_time (str, bool, optional) – Type of aggregation when aggregating time series. Note that for {‘mean’, ‘sum’} the time series are aggregated to using snapshot weightings. With False the time series is given. Defaults to ‘mean’.

capex(comps=None, aggregate_groups='sum', groupby=None, at_port=False, bus_carrier=None, nice_names=True)#

Calculate the capital expenditure of the network in given currency.

If bus_carrier is given, only components which are connected to buses with carrier bus_carrier are considered.

For information on the list of arguments, see the docs in Network.statistics or pypsa.statistics.StatisticsAccessor.

curtailment(comps=None, aggregate_time='sum', aggregate_groups='sum', groupby=None, at_port=False, bus_carrier=None, nice_names=True)#

Calculate the curtailment of components in the network in MWh.

The calculation only considers assets with a p_max_pu time series, which is used to quantify the available power potential.

If bus_carrier is given, only the assets are considered which are connected to buses with carrier bus_carrier.

For information on the list of arguments, see the docs in Network.statistics or pypsa.statistics.StatisticsAccessor.

Parameters:

aggregate_time (str, bool, optional) – Type of aggregation when aggregating time series. Note that for {‘mean’, ‘sum’} the time series are aggregated to MWh using snapshot weightings. With False the time series is given in MW. Defaults to ‘sum’.

dispatch(comps=None, aggregate_time='sum', aggregate_groups='sum', groupby=None, at_port=True, bus_carrier=None, nice_names=True, kind=None)#

Calculate the dispatch of components in the network. Units depend on the regarded bus carrier.

If bus_carrier is given, only the dispatch to and from buses with carrier bus_carrier is calculated.

For information on the list of arguments, see the docs in Network.statistics or pypsa.statistics.StatisticsAccessor.

Parameters:

aggregate_time (str, bool, optional) – Type of aggregation when aggregating time series. Note that for {‘mean’, ‘sum’} the time series are aggregated to MWh using snapshot weightings. With False the time series is given in MW. Defaults to ‘sum’.

Deprecated since version 0.28: This will be removed in 0.29. Use ‘energy_balance’ instead.

energy_balance(comps=None, aggregate_time='sum', aggregate_groups='sum', aggregate_bus=True, groupby=<function get_carrier_and_bus_carrier>, at_port=True, bus_carrier=None, nice_names=True, kind=None)#

Calculate the energy balance of components in the network. Positive values represent a supply and negative a withdrawal. Units depend on the regarded bus carrier.

For information on the list of arguments, see the docs in Network.statistics or pypsa.statistics.StatisticsAccessor.

Additional parameter#

aggregate_bus: bool, optional

Whether to obtain the nodal or carrier-wise energy balance. Default is True, corresponding to the carrier-wise balance.

aggregate_timestr, bool, optional

Type of aggregation when aggregating time series. Note that for {‘mean’, ‘sum’} the time series are aggregated to MWh using snapshot weightings. With False the time series is given in MW. Defaults to ‘sum’.

expanded_capacity(comps=None, aggregate_groups='sum', groupby=None, at_port=False, bus_carrier=None, nice_names=True)#

Calculate the expanded capacity of the network components in MW.

If bus_carrier is given, the capacity is weighed by the output efficiency of components at buses with carrier bus_carrier.

For information on the list of arguments, see the docs in Network.statistics or pypsa.statistics.StatisticsAccessor.

expanded_capex(comps=None, aggregate_groups='sum', groupby=None, at_port=False, bus_carrier=None, nice_names=True)#

Calculate the capex of expanded capacities of the network components in currency.

For information on the list of arguments, see the docs in Network.statistics or pypsa.statistics.StatisticsAccessor.

installed_capacity(comps=None, aggregate_groups='sum', groupby=None, at_port=False, bus_carrier=None, storage=False, nice_names=True)#

Calculate the installed capacity of the network components in MW.

If at_port is True, the capacity is weighed by the output efficiency of components at buses with carrier bus_carrier.

If storage is set to True, only storage capacities of the component Store and StorageUnit are taken into account.

For information on the list of arguments, see the docs in Network.statistics or pypsa.statistics.StatisticsAccessor.

installed_capex(comps=None, aggregate_groups='sum', groupby=None, at_port=False, bus_carrier=None, nice_names=True)#

Calculate the capital expenditure of already built components of the network in given currency.

For information on the list of arguments, see the docs in Network.statistics or pypsa.statistics.StatisticsAccessor.

market_value(comps=None, aggregate_time='mean', aggregate_groups='sum', groupby=None, at_port=True, bus_carrier=None, nice_names=True)#

Calculate the market value of components in the network in given currency/MWh or currency/unit_{bus_carrier} where unit_{bus_carrier} is the unit of the bus carrier.

If bus_carrier is given, only the market value resulting from buses with carrier bus_carrier are calculated.

For information on the list of arguments, see the docs in Network.statistics or pypsa.statistics.StatisticsAccessor.

Parameters:

aggregate_time (str, bool, optional) – Type of aggregation when aggregating time series. Note that for {‘mean’, ‘sum’} the time series are aggregated to using snapshot weightings. With False the time series is given. Defaults to ‘mean’.

opex(comps=None, aggregate_time='sum', aggregate_groups='sum', groupby=None, at_port=False, bus_carrier=None, nice_names=True)#

Calculate the operational expenditure in the network in given currency.

If bus_carrier is given, only components which are connected to buses with carrier bus_carrier are considered.

For information on the list of arguments, see the docs in Network.statistics or pypsa.statistics.StatisticsAccessor.

Parameters:

aggregate_time (str, bool, optional) – Type of aggregation when aggregating time series. Note that for {‘mean’, ‘sum’} the time series are aggregated using snapshot weightings. With False the time series is given. Defaults to ‘sum’.

optimal_capacity(comps=None, aggregate_groups='sum', groupby=None, at_port=False, bus_carrier=None, storage=False, nice_names=True)#

Calculate the optimal capacity of the network components in MW.

If bus_carrier is given, the capacity is weighed by the output efficiency of components at buses with carrier bus_carrier.

If storage is set to True, only storage capacities of the component Store and StorageUnit are taken into account.

For information on the list of arguments, see the docs in Network.statistics or pypsa.statistics.StatisticsAccessor.

revenue(comps=None, aggregate_time='sum', aggregate_groups='sum', groupby=None, at_port=True, bus_carrier=None, nice_names=True, kind=None)#

Calculate the revenue of components in the network in given currency. The revenue is defined as the net revenue of an asset, i.e cost of input - revenue of output. If kind is set to “input” or “output” only the revenue of the input or output is considered.

If bus_carrier is given, only the revenue resulting from buses with carrier bus_carrier is considered.

For information on the list of arguments, see the docs in Network.statistics or pypsa.statistics.StatisticsAccessor.

Parameters:
  • aggregate_time (str, bool, optional) – Type of aggregation when aggregating time series. Note that for {‘mean’, ‘sum’} the time series are aggregated to using snapshot weightings. With False the time series is given. Defaults to ‘sum’.

  • kind (str, optional) – Type of revenue to consider. If ‘input’ only the revenue of the input is considered. If ‘output’ only the revenue of the output is considered. Defaults to None.

supply(comps=None, aggregate_time='sum', aggregate_groups='sum', groupby=None, at_port=True, bus_carrier=None, nice_names=True)#

Calculate the supply of components in the network. Units depend on the regarded bus carrier.

If bus_carrier is given, only the supply to buses with carrier bus_carrier is calculated.

For information on the list of arguments, see the docs in Network.statistics or pypsa.statitics.StatisticsAccessor.

transmission(comps=None, aggregate_time='sum', aggregate_groups='sum', groupby=None, at_port=False, bus_carrier=None, nice_names=True)#

Calculate the transmission of branch components in the network. Units depend on the regarded bus carrier.

If bus_carrier is given, only the flow between buses with carrier bus_carrier is calculated.

For information on the list of arguments, see the docs in Network.statistics or pypsa.statistics.StatisticsAccessor.

Parameters:

aggregate_time (str, bool, optional) – Type of aggregation when aggregating time series. Note that for {‘mean’, ‘sum’} the time series are aggregated to MWh using snapshot weightings. With False the time series is given in MW. Defaults to ‘sum’.

withdrawal(comps=None, aggregate_time='sum', aggregate_groups='sum', groupby=None, at_port=True, bus_carrier=None, nice_names=True)#

Calculate the withdrawal of components in the network. Units depend on the regarded bus carrier.

If bus_carrier is given, only the withdrawal from buses with carrier bus_carrier is calculated.

For information on the list of arguments, see the docs in Network.statistics or pypsa.statitics.StatisticsAccessor.

pypsa.statistics.aggregate_components(n, func, agg='sum', comps=None, groupby=None, at_port=None, bus_carrier=None, nice_names=True)#

Apply a function and group the result for a collection of components.

pypsa.statistics.aggregate_timeseries(df, weights, agg='sum')#

Calculate the weighted sum or average of a DataFrame or Series.

pypsa.statistics.filter_active_assets(n, c, df: [<class 'pandas.core.series.Series'>, <class 'pandas.core.frame.DataFrame'>])#

For static values iterate over periods and concat values.

pypsa.statistics.filter_bus_carrier(n, c, port, bus_carrier, df)#

Filter the DataFrame for components which are connected to a bus with carrier bus_carrier.

pypsa.statistics.get_bus_and_carrier(n, c, port='', nice_names=True)#

Get the buses and nice carrier names for a component.

pypsa.statistics.get_bus_and_carrier_and_bus_carrier(n, c, port='', nice_names=True)#

Get component’s carrier, bus and bus carrier in one combined list.

Used for MultiIndex in energy balance.

pypsa.statistics.get_bus_unit_and_carrier(n, c, port='', nice_names=True)#

Get the buses and nice carrier names for a component.

pypsa.statistics.get_carrier(n, c, nice_names=True)#

Get the nice carrier names for a component.

pypsa.statistics.get_carrier_and_bus_carrier(n, c, port='', nice_names=True)#

Get component carrier and bus carrier in one combined list.

pypsa.statistics.get_country_and_carrier(n, c, port='', nice_names=True)#

Get component country and carrier.

pypsa.statistics.get_name_bus_and_carrier(n, c, port='', nice_names=True)#

Get the name, buses and nice carrier names for a component.

pypsa.statistics.get_operation(n, c)#

Get the operation time series of a component.

pypsa.statistics.get_ports(n, c)#

Get a list of existent ports of a component.

Deprecated since version 0.28: This will be removed in 0.29.

pypsa.statistics.get_transmission_branches(n, bus_carrier=None)#

Get the list of assets which transport between buses of the carrier bus_carrier.

pypsa.statistics.get_transmission_carriers(n, bus_carrier=None)#

Get the carriers which transport between buses of the carrier bus_carrier.

pypsa.statistics.get_weightings(n, c)#

Get the relevant snapshot weighting for a component.

Plotting Networks#

Functions for plotting networks.

class pypsa.plot.HandlerCircle(patch_func=None, **kwargs)#

Legend Handler used to create circles for legend entries.

This handler resizes the circles in order to match the same dimensional scaling as in the applied axis.

create_artists(legend, orig_handle, xdescent, ydescent, width, height, fontsize, trans)#

Return the legend artists generated.

Parameters:
  • legend (~matplotlib.legend.Legend) – The legend for which these legend artists are being created.

  • orig_handle (~matplotlib.artist.Artist or similar) – The object for which these legend artists are being created.

  • xdescent (int) – The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.

  • ydescent (int) – The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.

  • width (int) – The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.

  • height (int) – The rectangle (xdescent, ydescent, width, height) that the legend artists being created should fit within.

  • fontsize (int) – The fontsize in pixels. The legend artists being created should be scaled according to the given fontsize.

  • trans (~matplotlib.transforms.Transform) – The transform that is applied to the legend artists being created. Typically from unit coordinates in the handler box to screen coordinates.

pypsa.plot.add_legend_circles(ax, sizes, labels, srid=4326, patch_kw={}, legend_kw={})#

Add a legend for reference circles.

Parameters:
  • ax (matplotlib ax) –

  • sizes (list-like, float) – Size of the reference circle; for example [3, 2, 1]

  • labels (list-like, str) – Label of the reference circle; for example [“30 GW”, “20 GW”, “10 GW”]

  • patch_kw (defaults to {}) – Keyword arguments passed to matplotlib.patches.Circle

  • legend_kw (defaults to {}) – Keyword arguments passed to ax.legend

pypsa.plot.add_legend_lines(ax, sizes, labels, colors=[], patch_kw={}, legend_kw={})#

Add a legend for lines and links.

Parameters:
  • ax (matplotlib ax) –

  • sizes (list-like, float) – Size of the line reference; for example [3, 2, 1]

  • labels (list-like, str) – Label of the line reference; for example [“30 GW”, “20 GW”, “10 GW”]

  • colors (list-like, str) – Color of the line reference; for example [“red, “green”, “blue”]

  • patch_kw (defaults to {}) – Keyword arguments passed to plt.Line2D

  • legend_kw (defaults to {}) – Keyword arguments passed to ax.legend

pypsa.plot.add_legend_patches(ax, colors, labels, patch_kw={}, legend_kw={})#

Add patches for color references.

Parameters:
  • ax (matplotlib ax) –

  • colors (list-like, float) – Color of the patch; for example [“r”, “g”, “b”]

  • labels (list-like, str) – Label of the patch; for example [“wind”, “solar”, “gas”]

  • patch_kw (defaults to {}) – Keyword arguments passed to matplotlib.patches.Patch

  • legend_kw (defaults to {}) – Keyword arguments passed to ax.legend

pypsa.plot.autogenerate_coordinates(n, assign=False, layouter=None)#

Automatically generate bus coordinates for the network graph according to a layouting function from networkx.

Parameters:
  • n (pypsa.Network) –

  • assign (bool, default False) – Assign generated coordinates to the network bus coordinates at n.buses[['x', 'y']].

  • layouter (networkx.drawing.layout function, default None) –

    Layouting function from networkx. See list of available options. By default coordinates are determined for a planar layout if the network graph is planar, otherwise for a Kamada-Kawai layout.

Returns:

coordinates – DataFrame containing the generated coordinates with buses as index and [‘x’, ‘y’] as columns.

Return type:

pd.DataFrame

Examples

>>> autogenerate_coordinates(network)
>>> autogenerate_coordinates(network, assign=True, layouter=nx.circle_layout)
pypsa.plot.compute_bbox_with_margins(margin, x, y)#

Helper function to compute bounding box for the plot.

pypsa.plot.directed_flow(coords, flow, color, area_factor=1, cmap=None, alpha=1)#

Helper function to generate arrows from flow data.

pypsa.plot.iplot(n, fig=None, bus_colors='cadetblue', bus_alpha=1, bus_sizes=10, bus_cmap=None, bus_colorbar=None, bus_text=None, line_colors='rosybrown', link_colors='darkseagreen', transformer_colors='orange', line_widths=3, link_widths=3, transformer_widths=3, line_text=None, link_text=None, transformer_text=None, layouter=None, title='', size=None, branch_components=None, iplot=True, jitter=None, mapbox=False, mapbox_style='open-street-map', mapbox_token='', mapbox_parameters={})#

Plot the network buses and lines interactively using plotly.

Parameters:
  • fig (dict, default None) – If not None, figure is built upon this fig.

  • bus_colors (dict/pandas.Series) – Colors for the buses, defaults to “cadetblue”. If bus_sizes is a pandas.Series with a Multiindex, bus_colors defaults to the n.carriers[‘color’] column.

  • bus_alpha (float) – Adds alpha channel to buses, defaults to 1.

  • bus_sizes (float/pandas.Series) – Sizes of bus points, defaults to 10.

  • bus_cmap (plt.cm.ColorMap/str) – If bus_colors are floats, this color map will assign the colors

  • bus_colorbar (dict) – Plotly colorbar, e.g. {‘title’ : ‘my colorbar’}

  • bus_text (pandas.Series) – Text for each bus, defaults to bus names

  • line_colors (str/pandas.Series) – Colors for the lines, defaults to ‘rosybrown’.

  • link_colors (str/pandas.Series) – Colors for the links, defaults to ‘darkseagreen’.

  • transfomer_colors (str/pandas.Series) – Colors for the transfomer, defaults to ‘orange’.

  • line_widths (dict/pandas.Series) – Widths of lines, defaults to 1.5

  • link_widths (dict/pandas.Series) – Widths of links, defaults to 1.5

  • transformer_widths (dict/pandas.Series) – Widths of transformer, defaults to 1.5

  • line_text (pandas.Series) – Text for lines, defaults to line names.

  • link_text (pandas.Series) – Text for links, defaults to link names.

  • tranformer_text (pandas.Series) – Text for transformers, defaults to transformer names.

  • layouter (networkx.drawing.layout function, default None) –

    Layouting function from networkx which overrules coordinates given in n.buses[['x', 'y']]. See list of available options.

  • title (string) – Graph title

  • size (None|tuple) – Tuple specifying width and height of figure; e.g. (width, heigh).

  • branch_components (list of str) – Branch components to be plotted, defaults to Line and Link.

  • iplot (bool, default True) – Automatically do an interactive plot of the figure.

  • jitter (None|float) – Amount of random noise to add to bus positions to distinguish overlapping buses

  • mapbox (bool, default False) – Switch to use Mapbox.

  • mapbox_style (str, default 'open-street-map') –

    Define the mapbox layout style of the interactive plot. If this is set to a mapbox layout, the argument mapbox_token must be a valid Mapbox API access token.

    Valid open layouts are:

    open-street-map, white-bg, carto-positron, carto-darkmatter, stamen-terrain, stamen-toner, stamen-watercolor

    Valid mapbox layouts are:

    basic, streets, outdoors, light, dark, satellite, satellite-streets

  • mapbox_token (string) – Mapbox API access token. Obtain from https://www.mapbox.com. Can also be included in mapbox_parameters as accesstoken=mapbox_token.

  • mapbox_parameters (dict) – Configuration parameters of the Mapbox layout. E.g. {“bearing”: 5, “pitch”: 10, “zoom”: 1, “style”: ‘dark’}.

Returns:

fig

Return type:

dictionary for plotly figure

pypsa.plot.plot(n, margin=0.05, ax=None, geomap=True, projection=None, bus_colors='cadetblue', bus_alpha=1, bus_sizes=0.02, bus_cmap=None, bus_norm=None, bus_split_circles=False, line_colors='rosybrown', link_colors='darkseagreen', transformer_colors='orange', line_alpha=1, link_alpha=1, transformer_alpha=1, line_widths=1.5, link_widths=1.5, transformer_widths=1.5, line_cmap=None, link_cmap=None, transformer_cmap=None, line_norm=None, link_norm=None, transformer_norm=None, flow=None, branch_components=None, layouter=None, title='', boundaries=None, geometry=False, jitter=None, color_geomap=None)#

Plot the network buses and lines using matplotlib and cartopy.

Parameters:
  • margin (float, defaults to 0.05) – Margin at the sides as proportion of distance between max/min x, y Will be ignored if boundaries are given.

  • ax (matplotlib ax, defaults to plt.gca()) – Axis to which to plot the network

  • geomap (bool/str, default True) – Switch to use Cartopy and draw geographical features. If string is passed, it will be used as a resolution argument, valid options are ‘10m’, ‘50m’ and ‘110m’.

  • projection (cartopy.crs.Projection, defaults to None) – Define the projection of your geomap, only valid if cartopy is installed. If None (default) is passed the projection for cartopy is set to cartopy.crs.PlateCarree

  • bus_colors (dict/pandas.Series) – Colors for the buses, defaults to “cadetblue”. If bus_sizes is a pandas.Series with a Multiindex, bus_colors defaults to the n.carriers[‘color’] column.

  • bus_alpha (float) – Adds alpha channel to buses, defaults to 1.

  • bus_sizes (dict/pandas.Series) – Sizes of bus points, defaults to 1e-2. If a multiindexed Series is passed, the function will draw pies for each bus (first index level) with segments of different color (second index level). Such a Series is ob- tained by e.g. n.generators.groupby([‘bus’, ‘carrier’]).p_nom.sum()

  • bus_cmap (plt.cm.ColorMap/str) – If bus_colors are floats, this color map will assign the colors

  • bus_norm (plt.Normalize|matplotlib.colors.*Norm) – The norm applied to the bus_cmap.

  • bus_split_circles (bool, default False) – Draw half circles if bus_sizes is a pandas.Series with a Multiindex. If set to true, the upper half circle per bus then includes all positive values of the series, the lower half circle all negative values. Defaults to False.

  • line_colors (str/pandas.Series) – Colors for the lines, defaults to ‘rosybrown’.

  • link_colors (str/pandas.Series) – Colors for the links, defaults to ‘darkseagreen’.

  • transfomer_colors (str/pandas.Series) – Colors for the transfomer, defaults to ‘orange’.

  • line_alpha (str/pandas.Series) – Alpha for the lines, defaults to 1.

  • link_alpha (str/pandas.Series) – Alpha for the links, defaults to 1.

  • transfomer_alpha (str/pandas.Series) – Alpha for the transfomer, defaults to 1.

  • line_widths (dict/pandas.Series) – Widths of lines, defaults to 1.5

  • link_widths (dict/pandas.Series) – Widths of links, defaults to 1.5

  • transformer_widths (dict/pandas.Series) – Widths of transformer, defaults to 1.5

  • line_cmap (plt.cm.ColorMap/str|dict) – If line_colors are floats, this color map will assign the colors.

  • link_cmap (plt.cm.ColorMap/str|dict) – If link_colors are floats, this color map will assign the colors.

  • transformer_cmap (plt.cm.ColorMap/str|dict) – If transformer_colors are floats, this color map will assign the colors.

  • line_norm (plt.Normalize|matplotlib.colors.*Norm) – The norm applied to the line_cmap.

  • link_norm (plt.Normalize|matplotlib.colors.*Norm) – The norm applied to the link_cmap.

  • transformer_norm (matplotlib.colors.Normalize|matplotlib.colors.*Norm) – The norm applied to the transformer_cmap.

  • flow (snapshot/pandas.Series/function/string) – Flow to be displayed in the plot, defaults to None. If an element of n.snapshots is given, the flow at this timestamp will be displayed. If an aggregation function is given, is will be applied to the total network flow via pandas.DataFrame.agg (accepts also function names). Otherwise flows can be specified by passing a pandas Series with MultiIndex including all necessary branch components. Use the line_widths argument to additionally adjust the size of the flow arrows.

  • layouter (networkx.drawing.layout function, default None) –

    Layouting function from networkx which overrules coordinates given in n.buses[['x', 'y']]. See list of available options.

  • title (string) – Graph title

  • boundaries (list of four floats) – Boundaries of the plot in format [x1, x2, y1, y2]

  • branch_components (list of str) – Branch components to be plotted, defaults to Line and Link.

  • jitter (None|float) – Amount of random noise to add to bus positions to distinguish overlapping buses

  • color_geomap (dict or bool) – Specify colors to paint land and sea areas in. If True, it defaults to {‘ocean’: ‘lightblue’, ‘land’: ‘whitesmoke’}. If no dictionary is provided, colors are white. If False, no geographical features are plotted.

Returns:

bus_collection, branch_collection1, … – Collections for buses and branches.

Return type:

tuple of Collections

pypsa.plot.projected_area_factor(ax, original_crs=4326)#

Helper function to get the area scale of the current projection in reference to the default projection.

The default ‘original crs’ is assumed to be 4326, which translates to the cartopy default cartopy.crs.PlateCarree()

Network Clustering#

Functions for computing network clusters.

class pypsa.clustering.spatial.Clustering(network: Any, busmap: pandas.core.series.Series, linemap: pandas.core.series.Series)#
pypsa.clustering.spatial.aggregatebuses(n, busmap, custom_strategies={})#

Aggregate buses in the network based on the given busmap.

Parameters:
  • n (Network) – The network containing the buses.

  • busmap (dict) – A dictionary mapping old bus IDs to new bus IDs.

  • custom_strategies (dict, optional) – Custom aggregation strategies (default is empty dict).

Returns:

df – DataFrame of the aggregated buses.

Return type:

DataFrame

pypsa.clustering.spatial.aggregatelines(n, busmap, line_length_factor=1.0, with_time=True, custom_strategies=None, bus_strategies=None)#

Aggregate lines in the network based on the given busmap.

Parameters:
  • n (Network) – The network containing the lines.

  • busmap (dict) – A dictionary mapping old bus IDs to new bus IDs.

  • line_length_factor (float, optional) – A factor to multiply the length of each line by (default is 1.0).

  • with_time (bool, optional) – Whether to aggregate dynamic data (default is True).

  • custom_strategies (dict, optional) – Custom aggregation strategies (default is empty dict).

  • bus_strategies (dict, optional) – Custom aggregation strategies for buses (default is empty dict).

Returns:

  • df (DataFrame) – DataFrame of the aggregated lines.

  • pnl (dict) – Dictionary of DataFrames of the aggregated dynamic data (if with_time is True).

pypsa.clustering.spatial.aggregateoneport(n, busmap, component, carriers=None, buses=None, with_time=True, custom_strategies={})#

Aggregate one port components in the network based on the given busmap.

Parameters:
  • network (Network) – The network containing the generators.

  • busmap (dict) – A dictionary mapping old bus IDs to new bus IDs.

  • carriers (list, optional) – List of carriers to be considered (default is all carriers).

  • buses (list, optional) – List of buses to be considered (default is all buses).

  • with_time (bool, optional) – Whether to include time-dependent attributes (default is True).

  • custom_strategies (dict, optional) – Custom aggregation strategies (default is empty dict).

Returns:

  • df (DataFrame) – DataFrame of the aggregated generators.

  • pnl (dict) – Dictionary of the aggregated pnl data.

pypsa.clustering.spatial.align_strategies(strategies, keys, component)#

Aligns the given strategies with the given keys.

Parameters:
  • strategies (dict) – The strategies to align.

  • keys (list) – The keys to align the strategies with.

Returns:

The aligned strategies.

Return type:

dict

pypsa.clustering.spatial.busmap_by_greedy_modularity(n, n_clusters, buses_i=None)#

Create a busmap according to Clauset-Newman-Moore greedy modularity maximization [1].

Parameters:
  • n (pypsa.Network) –

  • n_clusters (int) – Final number of clusters desired.

  • buses_i (None | pandas.Index, default=None) – Subset of buses to cluster. If None, all buses are considered.

Returns:

busmap – Mapping of network.buses to clusters (indexed by non-negative integers).

Return type:

pandas.Series

References

pypsa.clustering.spatial.busmap_by_hac(n, n_clusters, buses_i=None, branch_components=None, feature=None, affinity='euclidean', linkage='ward', **kwargs)#

Create a busmap according to Hierarchical Agglomerative Clustering.

Parameters:
  • n (pypsa.Network) –

  • n_clusters (int) – Final number of clusters desired.

  • buses_i (None | pandas.Index, default=None) – Subset of buses to cluster. If None, all buses are considered.

  • branch_components (List, default=None) – Subset of all branch_components in the network. If None, all branch_components are considered.

  • feature (None | pandas.DataFrame, default=None) – Feature to be considered for the clustering. The DataFrame must be indexed with buses_i. If None, all buses have the same similarity.

  • affinity (str or callable, default=’euclidean’) – Metric used to compute the linkage. Can be “euclidean”, “l1”, “l2”, “manhattan”, “cosine”, or “precomputed”. If linkage is “ward”, only “euclidean” is accepted. If “precomputed”, a distance matrix (instead of a similarity matrix) is needed as input for the fit method.

  • linkage (‘ward’, ‘complete’, ‘average’ or ‘single’, default=’ward’) – Which linkage criterion to use. The linkage criterion determines which distance to use between sets of observation. The algorithm will merge the pairs of cluster that minimize this criterion. - ‘ward’ minimizes the variance of the clusters being merged. - ‘average’ uses the average of the distances of each observation of the two sets. - ‘complete’ or ‘maximum’ linkage uses the maximum distances between all observations of the two sets. - ‘single’ uses the minimum of the distances between all observations of the two sets.

  • kwargs – Any remaining arguments to be passed to Hierarchical Clustering (e.g. memory, connectivity).

Returns:

busmap – Mapping of network.buses to clusters (indexed by non-negative integers).

Return type:

pandas.Series

pypsa.clustering.spatial.busmap_by_kmeans(n, bus_weightings, n_clusters, buses_i=None, **kwargs)#

Create a bus map from the clustering of buses in space with a weighting.

Parameters:
  • n (pypsa.Network) – The buses must have coordinates x, y.

  • bus_weightings (pandas.Series) – Series of integer weights for buses, indexed by bus names.

  • n_clusters (int) – Final number of clusters desired.

  • buses_i (None|pandas.Index) – If not None (default), subset of buses to cluster.

  • kwargs – Any remaining arguments to be passed to KMeans (e.g. n_init, n_jobs).

Returns:

busmap – Mapping of network.buses to k-means clusters (indexed by non-negative integers).

Return type:

pandas.Series

pypsa.clustering.spatial.busmap_by_stubs(n, matching_attrs=None)#

Create a busmap by reducing stubs and stubby trees (i.e. sequentially reducing dead-ends).

Parameters:
  • n (pypsa.Network) –

  • matching_attrs (None|[str]) – bus attributes clusters have to agree on

Returns:

busmap – Mapping of network.buses to k-means clusters (indexed by non-negative integers).

Return type:

pandas.Series

pypsa.clustering.spatial.flatten_multiindex(m, join=' ')#

Flatten a multiindex by joining the levels with the given string.

pypsa.clustering.spatial.greedy_modularity_clustering(n, n_clusters, buses_i=None, line_length_factor=1.0)#

Create a busmap according to Clauset-Newman-Moore greedy modularity maximization [1].

Parameters:
  • n (pypsa.Network) –

  • n_clusters (int) – Final number of clusters desired.

  • buses_i (None | pandas.Index, default=None) – Subset of buses to cluster. If None, all buses are considered.

  • line_length_factor (float, default=1.0) – Factor to multiply the spherical distance between two new buses to get new line lengths.

Returns:

Clustering – A named tuple containing network, busmap and linemap.

Return type:

named tuple

References

pypsa.clustering.spatial.hac_clustering(n, n_clusters, buses_i=None, branch_components=None, feature=None, affinity='euclidean', linkage='ward', line_length_factor=1.0, **kwargs)#

Cluster the network using Hierarchical Agglomerative Clustering.

Parameters:
  • n (pypsa.Network) – The buses must have coordinates x, y.

  • buses_i (None | pandas.Index, default=None) – Subset of buses to cluster. If None, all buses are considered.

  • branch_components (List, default=["Line", "Link"]) – Subset of all branch_components in the network.

  • feature (None | pandas.DataFrame, default=None) – Feature to be considered for the clustering. The DataFrame must be indexed with buses_i. If None, all buses have the same similarity.

  • affinity (str or callable, default=’euclidean’) – Metric used to compute the linkage. Can be “euclidean”, “l1”, “l2”, “manhattan”, “cosine”, or “precomputed”. If linkage is “ward”, only “euclidean” is accepted. If “precomputed”, a distance matrix (instead of a similarity matrix) is needed as input for the fit method.

  • linkage (‘ward’, ‘complete’, ‘average’ or ‘single’, default=’ward’) – Which linkage criterion to use. The linkage criterion determines which distance to use between sets of observation. The algorithm will merge the pairs of cluster that minimize this criterion. - ‘ward’ minimizes the variance of the clusters being merged. - ‘average’ uses the average of the distances of each observation of the two sets. - ‘complete’ or ‘maximum’ linkage uses the maximum distances between all observations of the two sets. - ‘single’ uses the minimum of the distances between all observations of the two sets.

  • line_length_factor (float, default=1.0) – Factor to multiply the spherical distance between two new buses in order to get new line lengths.

  • kwargs – Any remaining arguments to be passed to Hierarchical Clustering (e.g. memory, connectivity).

Returns:

Clustering – A named tuple containing network, busmap and linemap

Return type:

named tuple

pypsa.clustering.spatial.kmeans_clustering(n, bus_weightings, n_clusters, line_length_factor=1.0, **kwargs)#

Cluster the network according to k-means clustering of the buses.

Buses can be weighted by an integer in the series bus_weightings.

Note that this clustering method completely ignores the branches of the network.

Parameters:
  • n (pypsa.Network) – The buses must have coordinates x, y.

  • bus_weightings (pandas.Series) – Series of integer weights for buses, indexed by bus names.

  • n_clusters (int) – Final number of clusters desired.

  • line_length_factor (float) – Factor to multiply the spherical distance between new buses in order to get new line lengths.

  • kwargs – Any remaining arguments to be passed to KMeans (e.g. n_init, n_jobs)

Returns:

Clustering – A named tuple containing network, busmap and linemap

Return type:

named tuple

pypsa.clustering.spatial.make_consense(component: str, attr: str) callable#

Returns a function to verify attribute values of a cluster in a component. The values should either be the same or all null.

Parameters:
  • component (str) – The name of the component.

  • attr (str) – The name of the attribute to verify.

Returns:

A function that checks whether all values in the Series are the same or all null.

Return type:

callable

Raises:

AssertionError – If the attribute values in a cluster are not the same or all null.

pypsa.clustering.spatial.normed_or_uniform(x)#

Normalize a series by dividing it by its sum, unless the sum is zero, in which case return a uniform distribution.

Parameters:

x (pandas.Series) – The input series to normalize.

Returns:

The normalized series, or a uniform distribution if the input sum is zero.

Return type:

pandas.Series

Georeferencing Utilities#

Functionality to help with georeferencing and calculate distances/areas.

pypsa.geo.haversine(a, b)#

Compute the distance in km between two sets of points in long/lat.

One dimension of a* should be 2; longitude then latitude. Uses haversine formula.

Parameters:
  • a (array/list of at most 2 dimensions) – One dimension must be 2

  • b (array/list of at most 2 dimensions) – One dimension must be 2

Returns:

distance_km – 2-dimensional array of distances in km between points in a, b

Return type:

array

Examples

>>> haversine([10.1, 52.6], [[10.8, 52.1], [-34, 56.]])
array([[   73.15416698,  2836.6707696 ]])

See also

haversine_pts

Determine pointwise crow-fly distance

pypsa.geo.haversine_pts(a, b)#

Determines crow-flies distance between points in a and b.

ie. distance[i] = crow-fly-distance between a[i] and b[i]

Parameters:
  • a (N x 2 - array of dtype float) – Geographical coordinates in longitude, latitude ordering

  • b (N x 2 - array of dtype float) – Geographical coordinates in longitude, latitude ordering

Returns:

c – Distance in km

Return type:

N - array of dtype float

See also

haversine

Matrix of distances between all pairs in a and b