edisgo.network.topology
¶
Module Contents¶
Classes¶
Container for all grid topology data of a single MV grid. |
- class edisgo.network.topology.Topology(**kwargs)[source]¶
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 functionconnect_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 functionconnect_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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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).
- property lv_grids¶
Yields generator object with all low voltage grids in network.
- 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
- property rings¶
List of rings in the grid topology.
A ring is represented by the names of buses within that ring.
- 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
- get_connected_lines_from_bus(bus_name)[source]¶
Returns all lines connected to specified bus.
- get_line_connecting_buses(bus_1, bus_2)[source]¶
Returns information of line connecting bus_1 and bus_2.
- Parameters
- Returns
Dataframe with information of line connecting bus_1 and bus_2 in the same format as
lines_df
.- Return type
- get_connected_components_from_bus(bus_name)[source]¶
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
- add_load(bus, p_set, type='conventional_load', **kwargs)[source]¶
Adds load to topology.
Load name is generated automatically.
- Parameters
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
- add_generator(bus, p_nom, generator_type, control='PQ', **kwargs)[source]¶
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
- add_storage_unit(bus, p_nom, control='PQ', **kwargs)[source]¶
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)[source]¶
Adds line to topology.
Line name is generated automatically. If type_info is provided, x, r, b and s_nom are calculated.
- add_bus(bus_name, v_nom, **kwargs)[source]¶
Adds bus to topology.
If provided bus name already exists, a unique name is created.
- Parameters
- Returns
Name of bus. If provided bus name already exists, a unique name is created.
- Return type
- remove_load(name)[source]¶
Removes load with given name from topology.
If no other elements are connected, line and bus are removed as well.
- remove_generator(name)[source]¶
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)[source]¶
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)[source]¶
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.
- remove_bus(name)[source]¶
Removes bus with given name from topology.
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)[source]¶
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)[source]¶
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.
- sort_buses()[source]¶
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')[source]¶
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
respectivelyadd_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
- connect_to_lv(edisgo_object, comp_data, comp_type='generator', allowed_number_of_comp_per_bus=2)[source]¶
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
respectivelyadd_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
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)[source]¶
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
respectivelyadd_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
orstorage_units_df
, depending on component type.- Return type
- to_graph()[source]¶
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
- to_geopandas(mode: str = 'mv')[source]¶
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
- to_csv(directory)[source]¶
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.
- check_integrity()[source]¶
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 [source]¶
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.