edisgo.network.topology

Module Contents

Classes

Topology

Container for all grid topology data of a single MV grid.

class edisgo.network.topology.Topology(**kwargs)

Container for all grid topology data of a single MV grid.

Data may as well include grid topology data of underlying LV grids.

Parameters

config (None or Config) – Provide your configurations if you want to load self-provided equipment data. Path to csv files containing the technical data is set in config_system.cfg in sections system_dirs and equipment. The default is None in which case the equipment data provided by eDisGo is used.

property loads_df

Dataframe with all loads in MV network and underlying LV grids.

Parameters

df (pandas.DataFrame) –

Dataframe with all loads (incl. charging points, heat pumps, etc.) in MV network and underlying LV grids. Index of the dataframe are load names as string. Columns of the dataframe are:

busstr

Identifier of bus load is connected to.

p_setfloat

Peak load or nominal capacity in MW.

typestr

Type of load, e.g. ‘conventional_load’, ‘charging_point’ or ‘heat_pump’ (resistive heaters are as well treated as heat pumps with a COP smaller than 1). This information is for example currently necessary when setting up a worst case analysis, as different types of loads are treated differently.

sectorstr

Further specifies type of load.

In case of conventional loads this attribute is used if demandlib is used to generate sector-specific time series (see function predefined_conventional_loads_by_sector). It is further used when new generators are integrated into the grid in case the LV is not geo-referenced, as e.g. smaller PV rooftop generators are most likely to be located in a household (see function connect_to_lv). The sector needs to either be ‘industrial’, ‘residential’ or ‘cts’.

In case of charging points this attribute is used to define the charging point use case (‘home’, ‘work’, ‘public’ or ‘hpc’) to determine whether a charging process can be flexibilised, as it is assumed that only charging processes at private charging points (‘home’ and ‘work’) can be flexibilised (see function charging_strategy). It is further used when charging points are integrated into the grid, as e.g. ‘home’ charging points are allocated to a household (see function connect_to_lv).

In case of heat pumps it is used when heat pumps are integrated into the grid, as e.g. heat pumps for individual heating are allocated to an existing load (see function connect_to_lv). It is further used to specify, if component is a resistive heater, as resistive heaters are treated as heat pumps. The sector needs to either be ‘individual_heating’, ‘district_heating’, ‘individual_heating_resistive_heater’ or ‘district_heating_resistive_heater’.

building_idint

ID of the building the load is associated with. This is e.g. used to get electricity and heat demand time series as well as information on existing heat pumps and PV rooftop plants for scenarios developed in the eGo^n research project.

annual_consumptionfloat

Annual consumption in MWh.

number_householdsint

Number of households in the building. This information is currently not used in eDisGo.

Returns

Dataframe with all loads in MV network and underlying LV grids. For more information on the dataframe see input parameter df.

Return type

pandas.DataFrame

property generators_df

Dataframe with all generators in MV network and underlying LV grids.

Parameters

df (pandas.DataFrame) –

Dataframe with all generators in MV network and underlying LV grids. Index of the dataframe are generator names as string. Columns of the dataframe are:

busstr

Identifier of bus generator is connected to.

p_nomfloat

Nominal power in MW.

typestr

Type of generator, e.g. ‘solar’, ‘run_of_river’, etc. Is used in case generator type specific time series are provided.

controlstr

Control type of generator used for power flow analysis. In MV and LV grids usually ‘PQ’.

weather_cell_idint

ID of weather cell, that identifies the weather data cell from the weather data set used in the research project open_eGo to determine feed-in profiles of wind and solar generators. Only required when time series of wind and solar generators are assigned using precalculated time series from the OpenEnergy DataBase.

subtypestr

Further specification of type, e.g. ‘solar_roof_mounted’. Currently, not required for any functionality.

Returns

Dataframe with all generators in MV network and underlying LV grids. For more information on the dataframe see input parameter df.

Return type

pandas.DataFrame

property storage_units_df

Dataframe with all storage units in MV grid and underlying LV grids.

Parameters

df (pandas.DataFrame) –

Dataframe with all storage units in MV grid and underlying LV grids. Index of the dataframe are storage names as string. Columns of the dataframe are:

busstr

Identifier of bus storage unit is connected to.

controlstr

Control type of storage unit used for power flow analysis, usually ‘PQ’.

p_nomfloat

Nominal power in MW.

max_hoursfloat

Maximum state of charge capacity in terms of hours at full output capacity p_nom.

Returns

Dataframe with all storage units in MV network and underlying LV grids. For more information on the dataframe see input parameter df.

Return type

pandas.DataFrame

property transformers_df

Dataframe with all MV/LV transformers.

Parameters

df (pandas.DataFrame) –

Dataframe with all MV/LV transformers. Index of the dataframe are transformer names as string. Columns of the dataframe are:

bus0str

Identifier of bus at the transformer’s primary (MV) side.

bus1str

Identifier of bus at the transformer’s secondary (LV) side.

x_pufloat

Per unit series reactance.

r_pufloat

Per unit series resistance.

s_nomfloat

Nominal apparent power in MW.

type_infostr

Type of transformer.

Returns

Dataframe with all MV/LV transformers. For more information on the dataframe see input parameter df.

Return type

pandas.DataFrame

property transformers_hvmv_df

Dataframe with all HV/MV transformers.

Parameters

df (pandas.DataFrame) – Dataframe with all HV/MV transformers, with the same format as transformers_df.

Returns

Dataframe with all HV/MV transformers. For more information on format see transformers_df.

Return type

pandas.DataFrame

property lines_df

Dataframe with all lines in MV network and underlying LV grids.

Parameters

df (pandas.DataFrame) –

Dataframe with all lines in MV network and underlying LV grids. Index of the dataframe are line names as string. Columns of the dataframe are:

bus0str

Identifier of first bus to which line is attached.

bus1str

Identifier of second bus to which line is attached.

lengthfloat

Line length in km.

xfloat

Reactance of line (or in case of multiple parallel lines total reactance of lines) in Ohm.

rfloat

Resistance of line (or in case of multiple parallel lines total resistance of lines) in Ohm.

s_nomfloat

Apparent power which can pass through the line (or in case of multiple parallel lines total apparent power which can pass through the lines) in MVA.

num_parallelint

Number of parallel lines.

type_infostr

Type of line as e.g. given in equipment_data.

kindstr

Specifies whether line is a cable (‘cable’) or overhead line (‘line’).

Returns

Dataframe with all lines in MV network and underlying LV grids. For more information on the dataframe see input parameter df.

Return type

pandas.DataFrame

property buses_df

Dataframe with all buses in MV network and underlying LV grids.

Parameters

df (pandas.DataFrame) –

Dataframe with all buses in MV network and underlying LV grids. Index of the dataframe are bus names as strings. Columns of the dataframe are:

v_nomfloat

Nominal voltage in kV.

xfloat

x-coordinate (longitude) of geolocation.

yfloat

y-coordinate (latitude) of geolocation.

mv_grid_idint

ID of MV grid the bus is in.

lv_grid_idint

ID of LV grid the bus is in. In case of MV buses this is NaN.

in_buildingbool

Signifies whether a bus is inside a building, in which case only components belonging to this house connection can be connected to it.

Returns

Dataframe with all buses in MV network and underlying LV grids.

Return type

pandas.DataFrame

property switches_df

Dataframe with all switches in MV network and underlying LV grids.

Switches are implemented as branches that, when they are closed, are connected to a bus (bus_closed) such that there is a closed ring, and when they are open, connected to a virtual bus (bus_open), such that there is no closed ring. Once the ring is closed, the virtual is a single bus that is not connected to the rest of the grid.

Parameters

df (pandas.DataFrame) –

Dataframe with all switches in MV network and underlying LV grids. Index of the dataframe are switch names as string. Columns of the dataframe are:

bus_openstr

Identifier of bus the switch branch is connected to when the switch is open.

bus_closedstr

Identifier of bus the switch branch is connected to when the switch is closed.

branchstr

Identifier of branch that represents the switch.

typestr

Type of switch, e.g. switch disconnector.

Returns

Dataframe with all switches in MV network and underlying LV grids. For more information on the dataframe see input parameter df.

Return type

pandas.DataFrame

property charging_points_df

Returns a subset of loads_df containing only charging points.

Parameters

type (str) – Load type. Default: “charging_point”

Returns

Pandas DataFrame with all loads of the given type.

Return type

pandas.DataFrame

property id

MV network ID.

Returns

MV network ID.

Return type

int

property mv_grid

Medium voltage network.

The medium voltage network object only contains components (lines, generators, etc.) that are in or connected to the MV grid and does not include any components of the underlying LV grids (also not MV/LV transformers).

Parameters

mv_grid (MVGrid) – Medium voltage network.

Returns

Medium voltage network.

Return type

MVGrid

property lv_grids

Yields generator object with all low voltage grids in network.

Returns

Yields generator object with LVGrid object.

Return type

LVGrid

property grid_district

Dictionary with MV grid district information.

Parameters

grid_district (dict) –

Dictionary with the following MV grid district information:

’population’int

Number of inhabitants in grid district.

’geom’shapely.MultiPolygon

Geometry of MV grid district as (Multi)Polygon.

’srid’int

SRID (spatial reference ID) of grid district geometry.

Returns

Dictionary with MV grid district information. For more information on the dictionary see input parameter grid_district.

Return type

dict

property rings

List of rings in the grid topology.

A ring is represented by the names of buses within that ring.

Returns

List of rings, where each ring is again represented by a list of buses within that ring.

Return type

list(list)

property equipment_data

Technical data of electrical equipment such as lines and transformers.

Returns

Dictionary with pandas.DataFrame containing equipment data. Keys of the dictionary are ‘mv_transformers’, ‘mv_overhead_lines’, ‘mv_cables’, ‘lv_transformers’, and ‘lv_cables’.

Return type

dict

get_lv_grid(name)

Returns LVGrid object for given LV grid ID or name.

Parameters

name (int or str) – LV grid ID as integer or LV grid name (string representation) as string of the LV grid object that should be returned.

Returns

LV grid object with the given LV grid ID or LV grid name (string representation).

Return type

LVGrid

get_connected_lines_from_bus(bus_name)

Returns all lines connected to specified bus.

Parameters

bus_name (str) – Name of bus to get connected lines for.

Returns

Dataframe with connected lines with the same format as lines_df.

Return type

pandas.DataFrame

get_line_connecting_buses(bus_1, bus_2)

Returns information of line connecting bus_1 and bus_2.

Parameters

• bus_1 (str) – Name of first bus.

• bus_2 (str) – Name of second bus.

Returns

Dataframe with information of line connecting bus_1 and bus_2 in the same format as lines_df.

Return type

pandas.DataFrame

get_connected_components_from_bus(bus_name)

Returns dictionary of components connected to specified bus.

Parameters

bus_name (str) – Identifier of bus to get connected components for.

Returns

Dictionary of connected components with keys ‘generators’, ‘loads’, ‘storage_units’, ‘lines’, ‘transformers’, ‘transformers_hvmv’, ‘switches’. Corresponding values are component dataframes containing only components that are connected to the given bus.

Return type

dict of pandas.DataFrame

get_neighbours(bus_name)

Returns a set of neighbour buses of specified bus.

Parameters

bus_name (str) – Identifier of bus to get neighbouring buses for.

Returns

Set of identifiers of neighbouring buses.

Return type

set(str)

add_load(bus, p_set, type='conventional_load', **kwargs)

Adds load to topology.

Load name is generated automatically.

Parameters

• bus (str) – See loads_df for more information.

• p_set (float) – See loads_df for more information.

• type (str) – See loads_df for more information. Default: “conventional_load”

• kwargs – Kwargs may contain any further attributes you want to specify. See loads_df for more information on additional attributes used for some functionalities in edisgo. Kwargs may also contain a load ID (provided through keyword argument load_id as string) used to generate a unique identifier for the newly added load.

Returns

Unique identifier of added load.

Return type

str

add_generator(bus, p_nom, generator_type, control='PQ', **kwargs)

Adds generator to topology.

Generator name is generated automatically.

Parameters

• bus (str) – See generators_df for more information.

• p_nom (float) – See generators_df for more information.

• generator_type (str) – Type of generator, e.g. ‘solar’ or ‘gas’. See ‘type’ in generators_df for more information.

• control (str) – See generators_df for more information. Defaults to ‘PQ’.

• kwargs – Kwargs may contain any further attributes you want to specify. See generators_df for more information on additional attributes used for some functionalities in edisgo. Kwargs may also contain a generator ID (provided through keyword argument generator_id as string) used to generate a unique identifier for the newly added generator.

Returns

Unique identifier of added generator.

Return type

str

add_storage_unit(bus, p_nom, control='PQ', **kwargs)

Adds storage unit to topology.

Storage unit name is generated automatically.

Parameters

• bus (str) – See storage_units_df for more information.

• p_nom (float) – See storage_units_df for more information.

• control (str, optional) – See storage_units_df for more information. Defaults to ‘PQ’.

• kwargs – Kwargs may contain any further attributes you want to specify, e.g. max_hours.

add_line(bus0, bus1, length, **kwargs)

Adds line to topology.

Line name is generated automatically. If type_info is provided, x, r, b and s_nom are calculated.

Parameters

• bus0 (str) – Identifier of connected bus.

• bus1 (str) – Identifier of connected bus.

• length (float) – See lines_df for more information.

• kwargs – Kwargs may contain any further attributes in lines_df. It is necessary to either provide type_info to determine x, r, b and s_nom of the line, or to provide x, r, b and s_nom directly.

add_bus(bus_name, v_nom, **kwargs)

Adds bus to topology.

If provided bus name already exists, a unique name is created.

Parameters

• bus_name (str) – Name of new bus.

• v_nom (float) – See buses_df for more information.

• x (float) – See buses_df for more information.

• y (float) – See buses_df for more information.

• lv_grid_id (int) – See buses_df for more information.

• in_building (bool) – See buses_df for more information.

Returns

Name of bus. If provided bus name already exists, a unique name is created.

Return type

str

remove_load(name)

Removes load with given name from topology.

If no other elements are connected, line and bus are removed as well.

Parameters

name (str) – Identifier of load as specified in index of loads_df.

remove_generator(name)

Removes generator with given name from topology.

If no other elements are connected, line and bus are removed as well.

Parameters

name (str) – Identifier of generator as specified in index of generators_df.

remove_storage_unit(name)

Removes storage with given name from topology.

If no other elements are connected, line and bus are removed as well.

Parameters

name (str) – Identifier of storage as specified in index of storage_units_df.

remove_line(name)

Removes line with given name from topology.

Line is only removed, if it does not result in isolated buses. A warning is raised in that case.

Parameters

name (str) – Identifier of line as specified in index of lines_df.

remove_bus(name)

Removes bus with given name from topology.

Parameters

name (str) – Identifier of bus as specified in index of buses_df.

Notes

Only isolated buses can be deleted from topology. Use respective functions first to delete all connected components (e.g. lines, transformers, loads, etc.). Use function get_connected_components_from_bus() to get all connected components.

update_number_of_parallel_lines(lines_num_parallel)

Changes number of parallel lines and updates line attributes.

When number of parallel lines changes, attributes x, r, b, and s_nom have to be adapted, which is done in this function.

Parameters

lines_num_parallel (pandas.Series) – Index contains identifiers of lines to update as in index of lines_df and values of series contain corresponding new number of parallel lines.

change_line_type(lines, new_line_type)

Changes line type of specified lines to given new line type.

Be aware that this function replaces the lines by one line of the given line type. Lines must all be in the same voltage level and the new line type must be a cable with technical parameters given in equipment parameters.

Parameters

• lines (list(str)) – List of line names of lines to be changed to new line type.

• new_line_type (str) – Specifies new line type of lines. Line type must be a cable with technical parameters given in “mv_cables” or “lv_cables” of equipment data.

sort_buses()

Sorts buses in lines_df such that bus0 is always the upstream bus.

The changes are directly written to lines_df dataframe.

connect_to_mv(edisgo_object, comp_data, comp_type='generator')

Add and connect new component.

Currently, components can be generators, charging points, heat pumps and storage units.

This function creates a new bus the new component is connected to. The new bus is then connected to the grid depending on the specified voltage level (given in comp_data parameter). Components of voltage level 4 are connected to the HV/MV station. Components of voltage level 5 are connected to the nearest MV bus or line. In case the component is connected to a line, the line is split at the point closest to the new component (using perpendicular projection) and a new branch tee is added to connect the new component to.

Parameters

• edisgo_object (EDisGo) –

• comp_data (dict) – Dictionary with all information on component. The dictionary must contain all required arguments of method add_generator, add_storage_unit respectively add_load, except the bus that is assigned in this function, and may contain all other parameters of those methods. Additionally, the dictionary must contain the voltage level to connect in key ‘voltage_level’ and the geolocation in key ‘geom’. The voltage level must be provided as integer, with possible options being 4 (component is connected directly to the HV/MV station) or 5 (component is connected somewhere in the MV grid). The geolocation must be provided as Shapely Point object.

• comp_type (str) – Type of added component. Can be ‘generator’, ‘charging_point’, ‘heat_pump’ or ‘storage_unit’. Default: ‘generator’.

Returns

The identifier of the newly connected component.

Return type

str

connect_to_lv(edisgo_object, comp_data, comp_type='generator', allowed_number_of_comp_per_bus=2)

Add and connect new component to LV grid topology.

This function is used in case the LV grids are not geo-referenced. In case LV grids are geo-referenced function connect_to_lv_based_on_geolocation is used.

Currently, components can be generators, charging points, heat pumps and storage units.

This function connects the new component depending on the voltage level, and information on the MV/LV substation ID, geometry and sector, all provided in the comp_data parameter. It connects

• Components with specified voltage level 6

  • to MV/LV substation (a new bus is created for the new component, unless no geometry data is available, in which case the new component is connected directly to the substation)

• Generators and storage units with specified voltage level 7

  • with a nominal capacity of <=30 kW to LV loads of sector residential, if available

  • with a nominal capacity of >30 kW to LV loads of sector cts, industrial or agricultural, if available

  • to random bus in the LV grid as fallback if no appropriate load is available

• Charging points with specified voltage level 7

  • with sector ‘home’ to LV loads of sector residential, if available

  • with sector ‘work’ to LV loads of sector cts, industrial or agricultural, if available, otherwise

  • with sector ‘public’ or ‘hpc’ to some bus in the grid that is not a house connection

  • to random bus in the LV grid that is not a house connection if no appropriate load is available (fallback)

• Heat pumps with specified voltage level 7

  • with sector ‘individual_heating’ or ‘individual_heating_resistive_heater’ to LV loads

  • with sector ‘district_heating’ or ‘district_heating_resistive_heater’ to some bus in the grid that is not a house connection

  • to random bus in the LV grid that if no appropriate load is available (fallback)

In case no MV/LV substation ID is provided a random LV grid is chosen. In case the provided MV/LV substation ID does not exist (i.e. in case of components in an aggregated load area), the new component is directly connected to the HV/MV station (will be changed once generators in aggregated areas are treated differently in ding0).

The number of components of the same type connected at one load is restricted by the parameter allowed_number_of_comp_per_bus. If every possible load already has more than the allowed number then the new component is directly connected to the MV/LV substation.

Parameters

• edisgo_object (EDisGo) –

• comp_data (dict) – Dictionary with all information on component. The dictionary must contain all required arguments of method add_generator respectively add_load, except the bus that is assigned in this function, and may contain all other parameters of those methods. Additionally, the dictionary must contain the voltage level to connect in key ‘voltage_level’ and may contain the geolocation in key ‘geom’ and the LV grid ID to connect the component in key ‘mvlv_subst_id’. The voltage level must be provided as integer, with possible options being 6 (component is connected directly to the MV/LV substation) or 7 (component is connected somewhere in the LV grid). The geolocation must be provided as Shapely Point object and the LV grid ID as integer.

• comp_type (str) – Type of added component. Can be ‘generator’, ‘charging_point’ or ‘heat_pump’. Default: ‘generator’.

• allowed_number_of_comp_per_bus (int) – Specifies, how many components of the same type are at most allowed to be placed at the same bus. Default: 2.

Returns

The identifier of the newly connected component.

Return type

str

Notes

For the allocation, loads are selected randomly (sector-wise) using a predefined seed to ensure reproducibility.

connect_to_lv_based_on_geolocation(edisgo_object, comp_data, comp_type, max_distance_from_target_bus=0.02)

Add and connect new component to LV grid topology based on its geolocation.

This function is used in case the LV grids are geo-referenced. In case LV grids are not geo-referenced function connect_to_lv is used.

Currently, components can be generators, charging points, heat pumps and storage units.

In case the component is integrated in voltage level 6 it is connected to the closest MV/LV substation; in case it is integrated in voltage level 7 it is connected to the closest LV bus. In contrast to the connection of components to the MV level splitting of a line to connect a new component is not conducted.

A new bus for the new component is only created in case the closest existing bus is farther away than what is specified through parameter max_distance_from_target_bus. Otherwise, the new component is directly connected to the nearest bus.

Parameters

• edisgo_object (EDisGo) –

• comp_data (dict) – Dictionary with all information on component. The dictionary must contain all required arguments of method add_generator, add_storage_unit respectively add_load, except the bus that is assigned in this function, and may contain all other parameters of those methods. Additionally, the dictionary must contain the voltage level to connect to in key ‘voltage_level’ and the geolocation in key ‘geom’. The voltage level must be provided as integer, with possible options being 6 (component is connected directly to the MV/LV substation) or 7 (component is connected somewhere in the LV grid). The geolocation must be provided as Shapely Point object.

• comp_type (str) – Type of new component. Can be ‘generator’, ‘charging_point’, ‘heat_pump’ or ‘storage_unit’.

• max_distance_from_target_bus (int) – Specifies the maximum distance of the component to the target bus in km before a new bus is created. If the new component is closer to the target bus than the maximum specified distance, it is directly connected to that target bus. Default: 0.1.

Returns

The identifier of the newly connected component as in index of generators_df, loads_df or storage_units_df, depending on component type.

Return type

str

to_graph()

Returns graph representation of the grid.

Returns

Graph representation of the grid as networkx Ordered Graph, where lines are represented by edges in the graph, and buses and transformers are represented by nodes.

Return type

networkx.Graph

to_geopandas(mode: str = 'mv')

Returns components as geopandas.GeoDataFrames.

Returns container with geopandas.GeoDataFrames containing all georeferenced components within the grid.

Parameters

mode (str) – Return mode. If mode is “mv” the mv components are returned. If mode is “lv” a generator with a container per lv grid is returned. Default: “mv”

Returns

Data container with GeoDataFrames containing all georeferenced components within the grid(s).

Return type

GeoPandasGridContainer or list(GeoPandasGridContainer)

to_csv(directory)

Exports topology to csv files.

The following attributes are exported:

• ‘loads_df’ : Attribute loads_df is saved to loads.csv.

• ‘generators_df’ : Attribute generators_df is saved to generators.csv.

• ‘storage_units_df’ : Attribute storage_units_df is saved to storage_units.csv.

• ‘transformers_df’ : Attribute transformers_df is saved to transformers.csv.

• ‘transformers_hvmv_df’ : Attribute transformers_df is saved to transformers.csv.

• ‘lines_df’ : Attribute lines_df is saved to lines.csv.

• ‘buses_df’ : Attribute buses_df is saved to buses.csv.

• ‘switches_df’ : Attribute switches_df is saved to switches.csv.

• ‘grid_district’ : Attribute grid_district is saved to network.csv.

Attributes are exported in a way that they can be directly imported to pypsa.

Parameters

directory (str) – Path to save topology to.

from_csv(data_path, edisgo_obj, from_zip_archive=False)

Restores topology from csv files.

Parameters

• data_path (str) – Path to topology csv files or zip archive.

• edisgo_obj (EDisGo) –

• from_zip_archive (bool) – Set to True if data is archived in a zip archive. Default: False.

check_integrity()

Check data integrity.

Checks for duplicated labels and isolated components. Further checks for very small impedances that can cause stability problems in the power flow calculation and large line lengths that might be implausible.

aggregate_lv_grid_at_station(lv_grid_id: int | str) → None

Aggregates all LV grid components to secondary side of the grid’s station.

All lines of the LV grid are dropped, as well as all buses except the station’s secondary side bus. Buses, the loads, generators and storage units are connected to are changed to the station’s secondary side bus. The changes are directly applied to the Topology object.

Parameters

lv_grid_id (int or str) – ID of the LV grid to aggregate.

__repr__()

Return repr(self).