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.

  • 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")
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()

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()
determine_network_topology(investment_period=None)

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, least_significant_digit=None)

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).

  • least_significant_digit – This is passed to the netCDF exporter, but currently makes no difference to file size or float accuracy. We’re working on improving this…

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

  • 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

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

import_from_pandapower_net(net, extra_line_data=False)

Import network from pandapower net.

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

Unsupported features include: - three-winding transformers - switches - in_service status, - shunt impedances, 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

Examples

>>> network.import_from_pandapower_net(net)
OR
>>> import pandapower as pp
>>> import pandapower.networks as pn
>>> net = pn.create_cigre_network_mv(with_der='all')
>>> pp.runpp(net)
>>> 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

lopf(snapshots=None, pyomo=True, solver_name='glpk', solver_options={}, solver_logfile=None, formulation='kirchhoff', keep_files=False, extra_functionality=None, multi_investment_periods=False, **kwargs)

Linear optimal power flow for a group of snapshots.

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

  • pyomo (bool, default True) –

    Whether to use pyomo for building and solving the model, setting this to False saves a lot of memory and time.

    Deprecated since version 0.20: In PyPSA version 0.21 the default will change to pyomo=False.

  • solver_name (string) – Must be a solver name that pyomo recognises and that is installed, e.g. “glpk”, “gurobi”

  • solver_options (dictionary) – A dictionary with additional options that get passed to the solver. (e.g. {‘threads’:2} tells gurobi to use only 2 cpus)

  • solver_logfile (None|string) – If not None, sets the logfile option of the solver.

  • keep_files (bool, default False) – Keep the files that pyomo constructs from OPF problem construction, e.g. .lp file - useful for debugging

  • formulation (string) – Formulation of the linear power flow equations to use; must be one of [“angles”,”cycles”,”kirchhoff”,”ptdf”]

  • extra_functionality (callable function) – 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.

  • 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.

  • ptdf_tolerance (float) – Only taking effect when pyomo is True. Value below which PTDF entries are ignored

  • free_memory (set, default {'pyomo'}) – Only taking effect when pyomo is True. Any subset of {‘pypsa’, ‘pyomo’}. Allows to stash pypsa time-series data away while the solver runs (as a pickle to disk) and/or free pyomo data after the solution has been extracted.

  • solver_io (string, default None) – Only taking effect when pyomo is True. Solver Input-Output option, e.g. “python” to use “gurobipy” for solver_name=”gurobi”

  • skip_pre (bool, default False) – Only taking effect when pyomo is True. Skip the preliminary steps of computing topology, calculating dependent values and finding bus controls.

  • extra_postprocessing (callable function) – Only taking effect when pyomo is True. This function must take three arguments extra_postprocessing(network,snapshots,duals) and is called after the model has solved and the results are extracted. It allows the user to extract further information about the solution, such as additional shadow prices.

  • skip_objective (bool, default False) – Only taking effect when pyomo is False. Skip writing the default objective function. If False, a custom objective has to be defined via extra_functionality.

  • warmstart (bool or string, default False) – Only taking effect when pyomo is False. Use this to warmstart the optimization. Pass a string which gives the path to the basis file. If set to True, a path to a basis file must be given in network.basis_fn.

  • store_basis (bool, default True) – Only taking effect when pyomo is False. Whether to store the basis of the optimization results. If True, the path to the basis file is saved in network.basis_fn. Note that a basis can only be stored if simplex, dual-simplex, or barrier with crossover is used for solving.

  • keep_references (bool, default False) – Only taking effect when pyomo is False. Keep the references of variable and constraint names withing the network. These can be looked up in n.vars and n.cons after solving.

  • keep_shadowprices (bool or list of component names) – Only taking effect when pyomo is False. Keep shadow prices for all constraints, if set to True. If a list is passed the shadow prices will only be parsed for those constraint names. Defaults to [‘Bus’, ‘Line’, ‘GlobalConstraint’]. After solving, the shadow prices can be retrieved using pypsa.linopt.get_dual() with corresponding name

  • solver_dir (str, default None) – Only taking effect when pyomo is False. Path to directory where necessary files are written, default None leads to the default temporary directory used by tempfile.mkstemp().

Returns

  • status (str) – Status of optimization. Either “ok” if solution is optimal, or “warning” if not.

  • termination_condition (str) – More information on how the solver terminated. One of “optimal”, “suboptimal” (in which case a solution is still provided), “infeasible”, “infeasible or unbounded”, or “other”.

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)
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"])
opf(snapshots=None)

Optimal power flow for snapshots.

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, line_colors='rosybrown', link_colors='darkseagreen', transformer_colors='orange', 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.

  • 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_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")
sclopf(snapshots=None, branch_outages=None, solver_name='glpk', pyomo=True, skip_pre=False, extra_functionality=None, solver_options={}, keep_files=False, formulation='kirchhoff', ptdf_tolerance=0.0)

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

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

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

  • 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()

  • solver_name (string) – Must be a solver name that pyomo recognises and that is installed, e.g. “glpk”, “gurobi”

  • pyomo (bool, default True) –

    Whether to use pyomo for building and solving the model, setting this to False saves a lot of memory and time.

    Deprecated since version 0.20: In PyPSA version 0.21 the default will change to pyomo=False.

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

  • extra_functionality (callable function) – 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.

  • solver_options (dictionary) – A dictionary with additional options that get passed to the solver. (e.g. {‘threads’:2} tells gurobi to use only 2 cpus)

  • keep_files (bool, default False) – Keep the files that pyomo constructs from OPF problem construction, e.g. .lp file - useful for debugging

  • formulation (string, default "kirchhoff") – Formulation of the linear power flow equations to use; must be one of [“angles”,”cycles”,”kirchoff”,”ptdf”]

  • ptdf_tolerance (float) –

Return type

None

Examples

>>> network.sclopf(network, branch_outages)
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(value)

Set the snapshots and reindex all time-dependent data.

This will reindex all pandas.Panels of time-dependent data; NaNs are filled with the default value for that quantity.

Parameters

snapshots (list or pandas.Index) – All time steps.

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

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 https://github.com/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)

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=slice(None, None, 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, least_significant_digit=None)

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).

  • least_significant_digit – This is passed to the netCDF exporter, but currently makes no difference to file size or float accuracy. We’re working on improving this…

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

  • 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

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

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

Import network from pandapower net.

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

Unsupported features include: - three-winding transformers - switches - in_service status, - shunt impedances, 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

Examples

>>> network.import_from_pandapower_net(net)
OR
>>> import pandapower as pp
>>> import pandapower.networks as pn
>>> net = pn.create_cigre_network_mv(with_der='all')
>>> pp.runpp(net)
>>> 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")

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)

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.

Optimisation Module

Tools for fast Linear Problem file writing. This module contains.

  • io functions for writing out variables, constraints and objective into a lp file.

  • functions to create lp format based linear expression

  • solver functions which read the lp file, run the problem and return the solution

This module supports the linear optimal power flow calculation without using pyomo (see module linopt.py)

pypsa.linopt.align_with_static_component(n, c, attr)

Alignment of time-dependent variables with static components.

If c is a pypsa.component name, it will sort the columns of the variable according to the static component.

pypsa.linopt.broadcasted_axes(*dfs)

Helper function which, from a collection of arrays, series, frames and other values, retrieves the axes of series and frames which result from broadcasting operations.

It checks whether index and columns of given series and frames, repespectively, are aligned. Using this function allows to subsequently use pure numpy operations and keep the axes in the background.

pypsa.linopt.define_binaries(n, axes, name, attr='', spec='', mask=None)

Defines binary-variable(s) for pypsa-network. The variables are stored in the network object under n.vars with key of the variable name. For each entry for the pd.Series of pd.DataFrame spanned by the axes argument the function defines a binary.

Parameters
  • n (pypsa.Network) –

  • axes (pd.Index or tuple of pd.Index objects) – Specifies the axes and therefore the shape of the variables.

  • name (str) –

    general name of the variable (or component which the variable is referring to). The variable will then be stored under:

    • n.vars[name].pnl if the variable is two-dimensional

    • n.vars[name].df if the variable is one-dimensional

  • attr (str default '') – Specifying name of the variable, defines under which name the variable(s) are stored in n.vars[name].pnl if two-dimensional or in n.vars[name].df if one-dimensional

  • mask (pd.DataFrame/np.array) – Boolean mask with False values for variables which are skipped. The shape of the mask has to match the shape given by axes.

See also

define_variables

pypsa.linopt.define_constraints(n, lhs, sense, rhs, name, attr='', axes=None, spec='', mask=None)

Defines constraint(s) for pypsa-network with given left hand side (lhs), sense and right hand side (rhs). The constraints are stored in the network object under n.cons with key of the constraint name. If multiple constraints are defined at ones, only using np.arrays, then the axes argument can be used for defining the axes for the constraints (this is especially recommended for time-dependent constraints). If one of lhs, sense and rhs is a pd.Series/pd.DataFrame the axes argument is not necessary.

Parameters
  • n (pypsa.Network) –

  • lhs (pd.Series/pd.DataFrame/np.array/str/float) – left hand side of the constraint(s), created with pypsa.linot.linexpr().

  • sense (pd.Series/pd.DataFrame/np.array/str/float) – sense(s) of the constraint(s)

  • rhs (pd.Series/pd.DataFrame/np.array/str/float) – right hand side of the constraint(s), must only contain pure constants, no variables

  • name (str) –

    general name of the constraint (or component which the constraint is referring to). The constraint will then be stored under:

    • n.cons[name].pnl if the constraint is two-dimensional

    • n.cons[name].df if the constraint is one-dimensional

  • attr (str default '') – Specifying name of the constraint, defines under which name the constraint(s) are stored in n.cons[name].pnl if two-dimensional or in n.cons[name].df if one-dimensional

  • axes (pd.Index or tuple of pd.Index objects, default None) – Specifies the axes if all of lhs, sense and rhs are np.arrays or single strings or floats.

  • mask (pd.DataFrame/np.array) – Boolean mask with False values for constraints which are skipped. The shape of the mask has to match the shape of the array that come out when combining lhs, sense and rhs.

Example

Let’s say we want to constraint all gas generators to a maximum of 100 MWh during the first 10 snapshots. We then firstly get all operational variables for this subset and constraint there sum to less equal 100.

>>> from pypsa.linopt import get_var, linexpr, define_constraints
>>> gas_i = n.generators.query('carrier == "Natural Gas"').index
>>> gas_vars = get_var(n, 'Generator', 'p').loc[n.snapshots[:10], gas_i]
>>> lhs = linexpr((1, gas_vars)).sum().sum()
>>> define_constraints(n, lhs, '<=', 100, 'Generator', 'gas_power_limit')

Now the constraint references can be accessed by pypsa.linopt.get_con() using

>>> cons = get_var(n, 'Generator', 'gas_power_limit')

Under the hood they are stored in n.cons.Generator.pnl.gas_power_limit. For retrieving their shadow prices add the general name of the constraint to the keep_shadowprices argument.

Note that this is useful for the extra_functionality argument.

pypsa.linopt.define_variables(n, lower, upper, name, attr='', axes=None, spec='', mask=None)

Defines variable(s) for pypsa-network with given lower bound(s) and upper bound(s). The variables are stored in the network object under n.vars with key of the variable name. If multiple variables are defined at ones, at least one of lower and upper has to be an array (including pandas) of shape > (1,) or axes have to define the dimensions of the variables.

Parameters
  • n (pypsa.Network) –

  • lower (pd.Series/pd.DataFrame/np.array/str/float) – lower bound(s) for the variable(s)

  • upper (pd.Series/pd.DataFrame/np.array/str/float) – upper bound(s) for the variable(s)

  • name (str) –

    general name of the variable (or component which the variable is referring to). The variable will then be stored under:

    • n.vars[name].pnl if the variable is two-dimensional

    • n.vars[name].df if the variable is one-dimensional

    but can easily be accessed with get_var(n, name, attr)()

  • attr (str default '') – Specifying name of the variable, defines under which name the variable(s) are stored in n.vars[name].pnl if two-dimensional or in n.vars[name].df if one-dimensional

  • axes (pd.Index or tuple of pd.Index objects, default None) – Specifies the axes and therefore the shape of the variables if bounds are single strings or floats. This is helpful when multiple variables have the same upper and lower bound.

  • mask (pd.DataFrame/np.array) – Boolean mask with False values for variables which are skipped. The shape of the mask has to match the shape the added variables.

Example

Let’s say we want to define a demand-side-managed load at each bus of network n, which has a minimum of 0 and a maximum of 10. We then define lower bound (lb) and upper bound (ub) and pass it to define_variables

>>> from pypsa.linopt import define_variables, get_var
>>> lb = pd.DataFrame(0, index=n.snapshots, columns=n.buses.index)
>>> ub = pd.DataFrame(10, index=n.snapshots, columns=n.buses.index)
>>> define_variables(n, lb, ub, 'DSM', 'variableload')

Now the variables can be accessed by pypsa.linopt.get_var() using

>>> variables = get_var(n, 'DSM', 'variableload')

Note that this is usefull for the extra_functionality argument.

pypsa.linopt.get_con(n, c, attr, pop=False)

Retrieves constraint references for a given static or time-depending attribute of a give component.

Parameters
  • n (pypsa.Network) –

  • c (str) – component name to which the constraint belongs

  • attr (str) – attribute name of the constraints

Example

get_con(n, ‘Generator’, ‘mu_upper’)

pypsa.linopt.get_dual(n, name, attr='')

Retrieves shadow price for a given constraint. Note that for retrieving shadow prices of a custom constraint, its name has to be passed to keep_references in the lopf, or keep_references has to be set to True. Note that a lookup of all stored shadow prices is given in n.dualvalues.

Parameters
  • n (pypsa.Network) –

  • c (str) – constraint name to which the constraint belongs

  • attr (str) – attribute name of the constraints

Example

get_dual(n, ‘Generator’, ‘mu_upper’)

pypsa.linopt.get_sol(n, name, attr='')

Retrieves solution for a given variable. Note that a lookup of all stored solutions is given in n.solutions.

Parameters
  • n (pypsa.Network) –

  • c (str) – general variable name (or component name if variable is attached to a component)

  • attr (str) – attribute name of the variable

Example

get_dual(n, ‘Generator’, ‘mu_upper’)

pypsa.linopt.get_var(n, c, attr, pop=False)

Retrieves variable references for a given static or time-depending attribute of a given component. The function looks into n.variables to detect whether the variable is a time-dependent or static.

Parameters
  • n (pypsa.Network) –

  • c (str) – component name to which the constraint belongs

  • attr (str) – attribute name of the constraints

Example

>>> get_var(n, 'Generator', 'p')
pypsa.linopt.join_exprs(df)

Helper function to join arrays, series or frames of strings together.

pypsa.linopt.linexpr(*tuples, as_pandas=True, return_axes=False)

Elementwise concatenation of tuples in the form (coefficient, variables). Coefficient and variables can be arrays, series or frames. Per default returns a pandas.Series or pandas.DataFrame of strings. If return_axes is set to True the return value is split into values and axes, where values are the numpy.array and axes a tuple containing index and column if present.

Parameters
  • tuples (tuple of tuples) –

    Each tuple must of the form (coeff, var), where

    • coeff is a numerical value, or a numerical array, series, frame

    • var is a str or a array, series, frame of variable strings

  • as_pandas (bool, default True) – Whether to return to resulting array as a series, if 1-dimensional, or a frame, if 2-dimensional. Supersedes return_axes argument.

  • return_axes (Boolean, default False) – Whether to return index and column (if existent)

Example

Initialize coefficients and variables

>>> coeff1 = 1
>>> var1 = pd.Series(['a1', 'a2', 'a3'])
>>> coeff2 = pd.Series([-0.5, -0.3, -1])
>>> var2 = pd.Series(['b1', 'b2', 'b3'])

Create the linear expression strings

>>> linexpr((coeff1, var1), (coeff2, var2))
0    +1.0 a1 -0.5 b1
1    +1.0 a2 -0.3 b2
2    +1.0 a3 -1.0 b3
dtype: object

For a further step the resulting frame can be used as the lhs of pypsa.linopt.define_constraints()

For retrieving only the values:

>>> linexpr((coeff1, var1), (coeff2, var2), as_pandas=False)
array(['+1.0 a1 -0.5 b1', '+1.0 a2 -0.3 b2', '+1.0 a3 -1.0 b3'], dtype=object)
pypsa.linopt.run_and_read_cbc(n, problem_fn, solution_fn, solver_logfile, solver_options, warmstart=None, store_basis=True)

Solving function. Reads the linear problem file and passes it to the cbc solver. If the solution is successful it returns variable solutions and constraint dual values.

For more information on the solver options, run ‘cbc’ in your shell

pypsa.linopt.run_and_read_cplex(n, problem_fn, solution_fn, solver_logfile, solver_options, warmstart=None, store_basis=True)

Solving function.

Reads the linear problem file and passes it to the cplex solver. If the solution is successful it returns variable solutions and constraint dual values. Cplex must be installed for using this function

pypsa.linopt.run_and_read_glpk(n, problem_fn, solution_fn, solver_logfile, solver_options, warmstart=None, store_basis=True)

Solving function. Reads the linear problem file and passes it to the glpk solver. If the solution is successful it returns variable solutions and constraint dual values.

For more information on the glpk solver options: https://kam.mff.cuni.cz/~elias/glpk.pdf

pypsa.linopt.run_and_read_gurobi(n, problem_fn, solution_fn, solver_logfile, solver_options, warmstart=None, store_basis=True)

Solving function. Reads the linear problem file and passes it to the gurobi solver. If the solution is successful it returns variable solutions and constraint dual values. Gurobipy must be installed for using this function.

For more information on solver options: https://www.gurobi.com/documentation/{gurobi_verion}/refman/parameter_descriptions.html

pypsa.linopt.run_and_read_highs(n, problem_fn, solution_fn, solver_logfile, solver_options={}, warmstart=None, store_basis=True)

Highs solver function. Reads a linear problem file and passes it to the highs solver. If the solution is feasible the function returns the objective, solution and dual constraint variables. Highs must be installed for usage. Documentation: https://www.maths.ed.ac.uk/hall/HiGHS/

Notes

The script might only work for version HiGHS 1.1.1. Installation steps::

sudo apt-get install cmake # if not installed git clone git@github.com:ERGO-Code/HiGHS.git cd HiGHS git checkout 95342daa73543cc21e5b27db3e0fbf7330007541 # moves to HiGHS 1.1.1 mkdir build cd build cmake .. make ctest

Then in .bashrc add paths of executables and library ::

export PATH=”${PATH}:/foo/HiGHS/build/bin” export LD_LIBRARY_PATH=”${LD_LIBRARY_PATH}:/foo/HiGHS/build/lib” source .bashrc

Now when typing highs in the terminal you should see something like ::

Running HiGHS 1.1.1 [date: 2021-11-14, git hash: 95342daa]

The function reads and execute (i.e. subprocess.Popen,…) terminal commands of the solver. Meaning the command can be also executed at your command window/terminal if HiGHs is installed. Executing the commands on your local terminal helps to identify the raw outputs that are useful for developing the interface further.

All functions below the “process = …” do only read and save the outputs generated from the HiGHS solver. These parts are solver specific and depends on the solver output.

Solver options are read by the 1) command window and the 2) option_file.txt

1) An example list of solver options executable by the command window is given here: Examples: –model_file arg File of model to solve. –presolve arg Presolve: “choose” by default - “on”/”off” are alternatives. –solver arg Solver: “choose” by default - “simplex”/”ipm” are alternatives. –parallel arg Parallel solve: “choose” by default - “on”/”off” are alternatives. –time_limit arg Run time limit (double). –options_file arg File containing HiGHS options. -h, –help Print help.

2) The options_file.txt gives some more options, see a full list here: https://www.maths.ed.ac.uk/hall/HiGHS/HighsOptions.set By default, we insert a couple of options for the ipm solver. The dictionary can be overwritten by simply giving the new values. For instance, you could write a dictionary replacing some of the default values or adding new options:

``` solver_options = {

name: highs, method: ipm, parallel: “on”, <option_name>: <value>,

Note, the <option_name> and <value> must be equivalent to the name convention of HiGHS. Some function exist that are not documented, check their GitHub file: https://github.com/ERGO-Code/HiGHS/blob/master/src/lp_data/HighsOptions.h

Returns

  • status (string,) – “ok” or “warning”

  • termination_condition (string,) – Contains “optimal”, “infeasible”,

  • variables_sol (series)

  • constraints_dual (series)

  • objective (float)

pypsa.linopt.run_and_read_xpress(n, problem_fn, solution_fn, solver_logfile, solver_options, keep_files, warmstart=None, store_basis=True)

Solving function. Reads the linear problem file and passes it to the Xpress solver. If the solution is successful it returns variable solutions and constraint dual values. The xpress module must be installed for using this function.

For more information on solver options: https://www.fico.com/fico-xpress-optimization/docs/latest/solver/GUID-ACD7E60C-7852-36B7-A78A-CED0EA291CDD.html

pypsa.linopt.set_conref(n, constraints, c, attr, spec='')

Sets constraint references to the network. One-dimensional constraint references will be collected at n.cons[c].df, two-dimensional in n.cons[c].pnl For example:

  • constraints for nominal capacity variables for generators are stored in n.cons.Generator.df.mu_upper

  • operational capacity limits for generators are stored in n.cons.Generator.pnl.mu_upper

pypsa.linopt.set_varref(n, variables, c, attr, spec='')

Sets variable references to the network. One-dimensional variable references will be collected at n.vars[c].df, two-dimensional varaibles in n.vars[c].pnl. For example:

  • nominal capacity variables for generators are stored in n.vars.Generator.df.p_nom

  • operational variables for generators are stored in n.vars.Generator.pnl.p

pypsa.linopt.to_pandas(array, *axes)

Convert a numpy array to pandas.Series if 1-dimensional or to a pandas.DataFrame if 2-dimensional.

Provide index and columns if needed

pypsa.linopt.write_binary(n, axes, mask=None)

Writer function for writing out multiple binary-variables at a time.

According to the axes it writes out binaries for each entry the pd.Series or pd.DataFrame spanned by axes. Returns a series or frame with variable references.

pypsa.linopt.write_bound(n, lower, upper, axes=None, mask=None)

Writer function for writing out multiple variables at a time.

If lower and upper are floats it demands to give pass axes, a tuple of (index, columns) or (index), for creating the variable of same upper and lower bounds. Return a series or frame with variable references.

pypsa.linopt.write_constraint(n, lhs, sense, rhs, axes=None, mask=None)

Writer function for writing out multiple constraints to the corresponding constraints file.

If lower and upper are numpy.ndarrays it axes must not be None but a tuple of (index, columns) or (index). Return a series or frame with constraint references.

pypsa.linopt.write_objective(n, terms)

Writer function for writing out one or multiple objective terms.

Parameters
  • n (pypsa.Network) –

  • terms (str/numpy.array/pandas.Series/pandas.DataFrame) – String or array of strings which represent new objective terms, built with linexpr()

Power System Optimisation

Build optimisation problems from PyPSA networks without Pyomo.

Originally retrieved from nomopyomo ( -> ‘no more Pyomo’).

pypsa.linopf.assign_solution(n, sns, variables_sol, constraints_dual, keep_references=False, keep_shadowprices=None)

Map solution to network components.

Helper function. Assigns the solution of a succesful optimization to the network.

pypsa.linopf.define_dispatch_for_extendable_and_committable_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.linopf.define_dispatch_for_extendable_constraints(n, sns, c, attr)

Sets power dispatch constraints for extendable devices 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.linopf.define_dispatch_for_non_extendable_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.linopf.define_fixed_variable_constraints(n, sns, c, attr, pnl=True)

Sets constraints for fixing variables of a given component and attribute to the corresponding values in n.df(c)[attr + ‘_set’] if pnl is True, or 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’

  • pnl (bool, default True) – Whether variable which should be fixed is time-dependent

pypsa.linopf.define_global_constraints(n, sns)

Defines global constraints for the optimization. Possible types are.

  1. primary_energy

    Use this to constraint the byproducts of primary energy sources as CO2

  2. transmission_volume_expansion_limit

    Use this to set a limit for line volume expansion. Possible carriers are ‘AC’ and ‘DC’

  3. transmission_expansion_cost_limit

    Use this to set a limit for line expansion costs. Possible carriers are ‘AC’ and ‘DC’

  4. tech_capacity_expansion_limit

    Use this to se a limit for the summed capacitiy of a carrier (e.g. ‘onwind’) for each investment period at choosen nodes. This limit could e.g. represent land resource/ building restrictions for a technology in a certain region. Currently, only the capacities of extendable generators have to be below the set limit.

pypsa.linopf.define_growth_limit(n, sns, c, attr)

Constraint new installed capacity per investment period.

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.linopf.define_kirchhoff_constraints(n, sns)

Defines Kirchhoff voltage constraints.

pypsa.linopf.define_nodal_balance_constraints(n, sns)

Defines nodal balance constraint.

pypsa.linopf.define_nominal_for_extendable_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.linopf.define_objective(n, sns)

Defines and writes out the objective function.

pypsa.linopf.define_ramp_limit_constraints(n, sns, c)

Defines ramp limits for a given component with valid ramplimit.

pypsa.linopf.define_storage_unit_constraints(n, sns)

Defines state of charge (soc) constraints for storage units. In principal the constraints states:

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

pypsa.linopf.define_store_constraints(n, sns)

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

previous_e - p == e

pypsa.linopf.ilopf(n, snapshots=None, msq_threshold=0.05, min_iterations=1, max_iterations=100, track_iterations=False, **kwargs)

Iterative linear optimization updating the line parameters for passive AC and DC lines. This is helpful when line expansion is enabled. After each sucessful 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.

  • **kwargs – Keyword arguments of the lopf function which runs at each iteration

pypsa.linopf.network_lopf(n, snapshots=None, solver_name='cbc', solver_logfile=None, extra_functionality=None, multi_investment_periods=False, skip_objective=False, skip_pre=False, extra_postprocessing=None, formulation='kirchhoff', keep_references=False, keep_files=False, keep_shadowprices=['Bus', 'Line', 'Transformer', 'Link', 'GlobalConstraint'], solver_options=None, warmstart=False, store_basis=False, solver_dir=None)

Linear optimal power flow for a group of snapshots.

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

  • solver_name (string) – Must be a solver name that pyomo recognises and that is installed, e.g. “glpk”, “gurobi”

  • solver_logfile (None|string) – If not None, sets the logfile option of the solver.

  • solver_options (dictionary) – A dictionary with additional options that get passed to the solver. (e.g. {‘threads’:2} tells gurobi to use only 2 cpus)

  • solver_dir (str, default None) – Path to directory where necessary files are written, default None leads to the default temporary directory used by tempfile.mkstemp().

  • keep_files (bool, default False) – Keep the files that pyomo constructs from OPF problem construction, e.g. .lp file - useful for debugging

  • formulation (string) – Formulation of the linear power flow equations to use; must be one of [“angles”,”cycles”,”kirchhoff”,”ptdf”]

  • extra_functionality (callable function) – 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.

  • skip_pre (bool, default False) – Skip the preliminary steps of computing topology.

  • skip_objective (bool, default False) – Skip writing the default objective function. If False, a custom objective has to be defined via extra_functionality.

  • extra_postprocessing (callable function) – This function must take three arguments extra_postprocessing(network,snapshots,duals) and is called after the model has solved and the results are extracted. It allows the user to extract further information about the solution, such as additional shadow prices.

  • warmstart (bool or string, default False) – Use this to warmstart the optimization. Pass a string which gives the path to the basis file. If set to True, a path to a basis file must be given in network.basis_fn.

  • store_basis (bool, default False) – Whether to store the basis of the optimization results. If True, the path to the basis file is saved in network.basis_fn. Note that a basis can only be stored if simplex, dual-simplex, or barrier with crossover is used for solving.

  • keep_references (bool, default False) – Keep the references of variable and constraint names withing the network. These can be looked up in n.vars and n.cons after solving.

  • keep_shadowprices (bool or list of component names) – Keep shadow prices for all constraints, if set to True. If a list is passed the shadow prices will only be parsed for those constraint names. Defaults to [‘Bus’, ‘Line’, ‘GlobalConstraint’]. After solving, the shadow prices can be retrieved using pypsa.linopt.get_dual() with corresponding name

pypsa.linopf.prepare_lopf(n, snapshots=None, keep_files=False, skip_objective=False, extra_functionality=None, solver_dir=None)

Sets up the linear problem and writes it out to a lp file.

Returns

  • Tuple (fdp, problem_fn) indicating the file descriptor and the file name of

  • the lp file

Pyomo Optimisation Module

Tools for fast Pyomo linear problem building.

Essentially this library replaces Pyomo expressions with more strict objects with a pre-defined affine structure.

class pypsa.opt.LConstraint(lhs=None, sense='==', rhs=None)

Constraint of optimisation variables.

Linear constraint of the form:

lhs sense rhs

Parameters
class pypsa.opt.LExpression(variables=None, constant=0.0)

Affine expression of optimisation variables.

Affine expression of the form:

constant + coeff1*var1 + coeff2*var2 + ….

Parameters
  • variables (list of tuples of coefficients and variables) – e.g. [(coeff1,var1),(coeff2,var2),…]

  • constant (float) –

pypsa.opt.l_constraint(model, name, constraints, *args)

A replacement for pyomo’s Constraint that quickly builds linear constraints.

Instead of

model.name = Constraint(index1,index2,…,rule=f)

call instead

l_constraint(model,name,constraints,index1,index2,…)

where constraints is a dictionary of constraints of the form:

constraints[i] = LConstraint object

OR using the soon-to-be-deprecated list format:

constraints[i] = [[(coeff1,var1),(coeff2,var2),…],sense,constant_term]

i.e. the first argument is a list of tuples with the variables and their coefficients, the second argument is the sense string (must be one of “==”,”<=”,”>=”,”><”) and the third argument is the constant term (a float). The sense “><” allows lower and upper bounds and requires constant_term to be a 2-tuple.

Variables may be repeated with different coefficients, which pyomo will sum up.

Parameters
  • model (pyomo.environ.ConcreteModel) –

  • name (string) – Name of constraints to be constructed

  • constraints (dict) – A dictionary of constraints (see format above)

  • *args – Indices of the constraints

pypsa.opt.l_objective(model, objective=None, sense=1)

A replacement for pyomo’s Objective that quickly builds linear objectives.

Instead of

model.objective = Objective(expr=sum(vars[i]*coeffs[i] for i in index)+constant)

call instead

l_objective(model,objective,sense)

where objective is an LExpression.

Variables may be repeated with different coefficients, which pyomo will sum up.

Parameters
  • model (pyomo.environ.ConcreteModel) –

  • objective (LExpression) –

  • sense (minimize / maximize) –

Pyomo Power System Optimisation

Optimal Power Flow functions.

pypsa.opf.define_nodal_balances(network, snapshots)

Construct the nodal balance for all elements except the passive branches.

Store the nodal balance expression in network._p_balance.

pypsa.opf.define_passive_branch_flows_with_kirchhoff(network, snapshots, skip_vars=False)

define passive branch flows with the kirchoff method.

pypsa.opf.define_sub_network_cycle_constraints(subnetwork, snapshots, passive_branch_p, attribute)

Constructs cycle_constraints for a particular subnetwork.

pypsa.opf.network_lopf(network, snapshots=None, solver_name='glpk', solver_io=None, skip_pre=False, extra_functionality=None, multi_investment_periods=False, solver_logfile=None, solver_options={}, keep_files=False, formulation='angles', ptdf_tolerance=0.0, free_memory={}, extra_postprocessing=None)

Linear optimal power flow for a group of snapshots.

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

  • solver_name (string) – Must be a solver name that pyomo recognises and that is installed, e.g. “glpk”, “gurobi”

  • solver_io (string, default None) – Solver Input-Output option, e.g. “python” to use “gurobipy” for solver_name=”gurobi”

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

  • extra_functionality (callable function) – 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.

  • solver_logfile (None|string) – If not None, sets the logfile option of the solver.

  • solver_options (dictionary) – A dictionary with additional options that get passed to the solver. (e.g. {‘threads’:2} tells gurobi to use only 2 cpus)

  • keep_files (bool, default False) – Keep the files that pyomo constructs from OPF problem construction, e.g. .lp file - useful for debugging

  • formulation (string) – Formulation of the linear power flow equations to use; must be one of [“angles”,”cycles”,”kirchhoff”,”ptdf”]

  • ptdf_tolerance (float) – Value below which PTDF entries are ignored

  • free_memory (set, default {'pyomo'}) – Any subset of {‘pypsa’, ‘pyomo’}. Allows to stash pypsa time-series data away while the solver runs (as a pickle to disk) and/or free pyomo data after the solution has been extracted.

  • extra_postprocessing (callable function) – This function must take three arguments extra_postprocessing(network,snapshots,duals) and is called after the model has solved and the results are extracted. It allows the user to extract further information about the solution, such as additional shadow prices.

Return type

None

pypsa.opf.network_lopf_build_model(network, snapshots=None, skip_pre=False, formulation='angles', ptdf_tolerance=0.0)

Build pyomo model for linear optimal power flow for a group of snapshots.

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

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

  • formulation (string) – Formulation of the linear power flow equations to use; must be one of [“angles”,”cycles”,”kirchhoff”,”ptdf”]

  • ptdf_tolerance (float) – Value below which PTDF entries are ignored

Return type

network.model

pypsa.opf.network_lopf_prepare_solver(network, solver_name='glpk', solver_io=None)

Prepare solver for linear optimal power flow.

Parameters
  • solver_name (string) – Must be a solver name that pyomo recognises and that is installed, e.g. “glpk”, “gurobi”

  • solver_io (string, default None) – Solver Input-Output option, e.g. “python” to use “gurobipy” for solver_name=”gurobi”

Return type

None

pypsa.opf.network_lopf_solve(network, snapshots=None, formulation='angles', solver_options={}, solver_logfile=None, keep_files=False, free_memory={'pyomo'}, extra_postprocessing=None)

Solve linear optimal power flow for a group of snapshots and extract results.

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

  • formulation (string) – Formulation of the linear power flow equations to use; must be one of [“angles”,”cycles”,”kirchhoff”,”ptdf”]; must match formulation used for building the model.

  • solver_options (dictionary) – A dictionary with additional options that get passed to the solver. (e.g. {‘threads’:2} tells gurobi to use only 2 cpus)

  • solver_logfile (None|string) – If not None, sets the logfile option of the solver.

  • keep_files (bool, default False) – Keep the files that pyomo constructs from OPF problem construction, e.g. .lp file - useful for debugging

  • free_memory (set, default {'pyomo'}) – Any subset of {‘pypsa’, ‘pyomo’}. Allows to stash pypsa time-series data away while the solver runs (as a pickle to disk) and/or free pyomo data after the solution has been extracted.

  • extra_postprocessing (callable function) – This function must take three arguments extra_postprocessing(network,snapshots,duals) and is called after the model has solved and the results are extracted. It allows the user to extract further information about the solution, such as additional shadow prices.

Return type

None

pypsa.opf.network_opf(network, snapshots=None)

Optimal power flow for snapshots.

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)
pypsa.contingency.network_sclopf(network, snapshots=None, branch_outages=None, solver_name='glpk', pyomo=True, skip_pre=False, extra_functionality=None, solver_options={}, keep_files=False, formulation='kirchhoff', ptdf_tolerance=0.0)

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

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

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

  • 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()

  • solver_name (string) – Must be a solver name that pyomo recognises and that is installed, e.g. “glpk”, “gurobi”

  • pyomo (bool, default True) –

    Whether to use pyomo for building and solving the model, setting this to False saves a lot of memory and time.

    Deprecated since version 0.20: In PyPSA version 0.21 the default will change to pyomo=False.

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

  • extra_functionality (callable function) – 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.

  • solver_options (dictionary) – A dictionary with additional options that get passed to the solver. (e.g. {‘threads’:2} tells gurobi to use only 2 cpus)

  • keep_files (bool, default False) – Keep the files that pyomo constructs from OPF problem construction, e.g. .lp file - useful for debugging

  • formulation (string, default "kirchhoff") – Formulation of the linear power flow equations to use; must be one of [“angles”,”cycles”,”kirchoff”,”ptdf”]

  • ptdf_tolerance (float) –

Return type

None

Examples

>>> network.sclopf(network, branch_outages)

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.

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, 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”]

  • 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)

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, line_colors='rosybrown', link_colors='darkseagreen', transformer_colors='orange', 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.

  • 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_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.networkclustering.Clustering(network, busmap, linemap, linemap_positive, linemap_negative)
busmap

Alias for field number 1

linemap

Alias for field number 2

linemap_negative

Alias for field number 4

linemap_positive

Alias for field number 3

network

Alias for field number 0

pypsa.networkclustering.busmap_by_greedy_modularity(network, n_clusters, buses_i=None)

Create a busmap according to Clauset-Newman-Moore greedy modularity maximization [1].

Parameters
  • network (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

1

Clauset, A., Newman, M. E., & Moore, C. “Finding community structure in very large networks.” Physical Review E 70(6), 2004.

pypsa.networkclustering.busmap_by_hac(network, n_clusters, buses_i=None, branch_components=None, feature=None, affinity='euclidean', linkage='ward', **kwargs)

Create a busmap according to Hierarchical Agglomerative Clustering.

Parameters
  • network (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.networkclustering.busmap_by_kmeans(network, bus_weightings, n_clusters, buses_i=None, **kwargs)

Create a bus map from the clustering of buses in space with a weighting.

Parameters
  • network (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.networkclustering.busmap_by_stubs(network, matching_attrs=None)

Create a busmap by reducing stubs and stubby trees (i.e. sequentially reducing dead-ends).

Parameters
  • network (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.networkclustering.greedy_modularity_clustering(network, n_clusters, buses_i=None, line_length_factor=1.0)

Create a busmap according to Clauset-Newman-Moore greedy modularity maximization [1].

Parameters
  • network (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

1

Clauset, A., Newman, M. E., & Moore, C. “Finding community structure in very large networks.” Physical Review E 70(6), 2004.

pypsa.networkclustering.hac_clustering(network, 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
  • network (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.networkclustering.kmeans_clustering(network, 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
  • network (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

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