edisgo.tools.tools

Module Contents

Functions

select_worstcase_snapshots(edisgo_obj)

Select two worst-case snapshots from time series

calculate_line_reactance(line_inductance_per_km, ...)

Calculates line reactance in Ohm.

calculate_line_resistance(line_resistance_per_km, ...)

Calculates line resistance in Ohm.

calculate_line_susceptance(line_capacitance_per_km, ...)

Calculates line shunt susceptance in Siemens.

calculate_apparent_power(nominal_voltage, current, ...)

Calculates apparent power in MVA from given voltage and current.

drop_duplicated_indices(dataframe[, keep])

Drop rows of duplicate indices in dataframe.

drop_duplicated_columns(df[, keep])

Drop columns of dataframe that appear more than once.

select_cable(edisgo_obj, level, apparent_power)

Selects suitable cable type and quantity using given apparent power.

get_path_length_to_station(edisgo_obj)

Determines path length from each bus to HV-MV station.

get_downstream_buses(edisgo_obj, comp_name[, comp_type])

Returns all buses downstream (farther away from station) of the given bus or line.

assign_voltage_level_to_component(df, buses_df)

Adds column with specification of voltage level component is in.

determine_grid_integration_voltage_level(...)

Gives voltage level component should be integrated into based on its nominal power.

determine_bus_voltage_level(edisgo_object, bus_name)

Gives voltage level as integer from 4 to 7 of given bus.

get_weather_cells_intersecting_with_grid_district(→ set)

Get all weather cells that intersect with the grid district.

get_directory_size(start_dir)

Calculates the size of all files within the start path.

get_files_recursive(path[, files])

Recursive function to get all files in a given path and its sub directories.

calculate_impedance_for_parallel_components(...[, pu])

Method to calculate parallel impedance and power of parallel elements.

add_line_susceptance(edisgo_obj[, mode])

Adds line susceptance information in Siemens to lines in existing grids.

aggregate_district_heating_components(edisgo_obj[, ...])

Aggregate PtH components that feed into the same district heating network.

reduce_timeseries_data_to_given_timeindex(edisgo_obj, ...)

Reduces timeseries data in EDisGo object to given time index.

resample(object, freq_orig[, method, freq, ...])

Resamples time series data to a desired resolution.

reduce_memory_usage(→ pandas.DataFrame)

Function to automatically check if columns of a pandas DataFrame can

get_year_based_on_timeindex(edisgo_obj)

Checks if timeindex is already set and

get_year_based_on_scenario(scenario)

Returns the year the given scenario was set up for.

hash_dataframe(→ str)

Get hash of dataframe.

edisgo.tools.tools.select_worstcase_snapshots(edisgo_obj)[source]

Select two worst-case snapshots from time series

Two time steps in a time series represent worst-case snapshots. These are

  1. Maximum Residual Load: refers to the point in the time series where the

    (load - generation) achieves its maximum.

  2. Minimum Residual Load: refers to the point in the time series where the

    (load - generation) achieves its minimum.

These two points are identified based on the generation and load time series. In case load or feed-in case don’t exist None is returned.

Parameters:

edisgo_obj (EDisGo) –

Returns:

Dictionary with keys ‘min_residual_load’ and ‘max_residual_load’. Values are corresponding worst-case snapshots of type pandas.Timestamp.

Return type:

dict

edisgo.tools.tools.calculate_line_reactance(line_inductance_per_km, line_length, num_parallel)[source]

Calculates line reactance in Ohm.

Parameters:
  • line_inductance_per_km (float or array-like) – Line inductance in mH/km.

  • line_length (float) – Length of line in km.

  • num_parallel (int) – Number of parallel lines.

Returns:

Reactance in Ohm

Return type:

float

edisgo.tools.tools.calculate_line_resistance(line_resistance_per_km, line_length, num_parallel)[source]

Calculates line resistance in Ohm.

Parameters:
  • line_resistance_per_km (float or array-like) – Line resistance in Ohm/km.

  • line_length (float) – Length of line in km.

  • num_parallel (int) – Number of parallel lines.

Returns:

Resistance in Ohm

Return type:

float

edisgo.tools.tools.calculate_line_susceptance(line_capacitance_per_km, line_length, num_parallel)[source]

Calculates line shunt susceptance in Siemens.

Parameters:
  • line_capacitance_per_km (float) – Line capacitance in uF/km.

  • line_length (float) – Length of line in km.

  • num_parallel (int) – Number of parallel lines.

Returns:

Shunt susceptance in Siemens.

Return type:

float

edisgo.tools.tools.calculate_apparent_power(nominal_voltage, current, num_parallel)[source]

Calculates apparent power in MVA from given voltage and current.

Parameters:
  • nominal_voltage (float or array-like) – Nominal voltage in kV.

  • current (float or array-like) – Current in kA.

  • num_parallel (int or array-like) – Number of parallel lines.

Returns:

Apparent power in MVA.

Return type:

float

edisgo.tools.tools.drop_duplicated_indices(dataframe, keep='last')[source]

Drop rows of duplicate indices in dataframe.

Be aware that this function changes the dataframe inplace. To avoid this behavior provide a copy of the dataframe to this function.

Parameters:
  • dataframe (pandas.DataFrame) – Dataframe to drop indices from.

  • keep (str) – Indicator of whether to keep first (“first”), last (“last”) or none (False) of the duplicated indices. See pandas.DataFrame.duplicated for more information. Default: “last”.

edisgo.tools.tools.drop_duplicated_columns(df, keep='last')[source]

Drop columns of dataframe that appear more than once.

Be aware that this function changes the dataframe inplace. To avoid this behavior provide a copy of the dataframe to this function.

Parameters:
  • df (pandas.DataFrame) – Dataframe to drop columns from.

  • keep (str) – Indicator of whether to keep first (“first”), last (“last”) or none (False) of the duplicated columns. See pandas.DataFrame.duplicated for more information. Default: “last”.

edisgo.tools.tools.select_cable(edisgo_obj, level, apparent_power)[source]

Selects suitable cable type and quantity using given apparent power.

Cable is selected to be able to carry the given apparent_power, no load factor is considered. Overhead lines are not considered in choosing a suitable cable.

Parameters:
  • edisgo_obj (EDisGo) –

  • level (str) – Grid level to get suitable cable for. Possible options are ‘mv’ or ‘lv’.

  • apparent_power (float) – Apparent power the cable must carry in MVA.

Returns:

  • pandas.Series – Series with attributes of selected cable as in equipment data and cable type as series name.

  • int – Number of necessary parallel cables.

edisgo.tools.tools.get_path_length_to_station(edisgo_obj)[source]

Determines path length from each bus to HV-MV station.

The path length is written to a new column path_length_to_station in buses_df dataframe of Topology class.

Parameters:

edisgo_obj (EDisGo) –

Returns:

Series with bus name in index and path length to station as value.

Return type:

pandas.Series

edisgo.tools.tools.get_downstream_buses(edisgo_obj, comp_name, comp_type='bus')[source]

Returns all buses downstream (farther away from station) of the given bus or line.

In case a bus is given, returns all buses downstream of the given bus plus the given bus itself. In case a line is given, returns all buses downstream of the bus that is closer to the station (thus only one bus of the line is included in the returned buses).

Parameters:
  • edisgo_obj (EDisGo object) –

  • comp_name (str) – Name of bus or line (as in index of buses_df or lines_df) to get downstream buses for.

  • comp_type (str) – Can be either ‘bus’ or ‘line’. Default: ‘bus’.

Returns:

List of buses (as in index of buses_df) downstream of the given component incl. the initial bus.

Return type:

list(str)

edisgo.tools.tools.assign_voltage_level_to_component(df, buses_df)[source]

Adds column with specification of voltage level component is in.

The voltage level (‘mv’ or ‘lv’) is determined based on the nominal voltage of the bus the component is connected to. If the nominal voltage is smaller than 1 kV, voltage level ‘lv’ is assigned, otherwise ‘mv’ is assigned.

Parameters:
  • df (pandas.DataFrame) – Dataframe with component names in the index. Only required column is column ‘bus’, giving the name of the bus the component is connected to.

  • buses_df (pandas.DataFrame) – Dataframe with bus information. Bus names are in the index. Only required column is column ‘v_nom’, giving the nominal voltage of the voltage level the bus is in.

Returns:

Same dataframe as given in parameter df with new column ‘voltage_level’ specifying the voltage level the component is in (either ‘mv’ or ‘lv’).

Return type:

pandas.DataFrame

edisgo.tools.tools.determine_grid_integration_voltage_level(edisgo_object, power)[source]

Gives voltage level component should be integrated into based on its nominal power.

The voltage level is specified through an integer value from 4 to 7 with 4 = MV busbar, 5 = MV grid, 6 = LV busbar and 7 = LV grid.

The voltage level is determined using upper limits up to which capacity a component is integrated into a certain voltage level. These upper limits are set in the config section grid_connection through the parameters ‘upper_limit_voltage_level_{4:7}’.

Parameters:
  • edisgo_object (EDisGo) –

  • power (float) – Nominal power of component in MW.

Returns:

Voltage level component should be integrated into. Possible options are 4 (MV busbar), 5 (MV grid), 6 (LV busbar) or 7 (LV grid).

Return type:

int

edisgo.tools.tools.determine_bus_voltage_level(edisgo_object, bus_name)[source]

Gives voltage level as integer from 4 to 7 of given bus.

The voltage level is specified through an integer value from 4 to 7 with 4 = MV busbar, 5 = MV grid, 6 = LV busbar and 7 = LV grid.

Buses that are directly connected to a station and not part of a longer feeder or half-ring, i.e. they are only part of one line, are as well considered as voltage level 4 or 6, depending on if they are connected to an HV/MV station or MV/LV station.

Parameters:
Returns:

Voltage level of bus. Possible options are 4 (MV busbar), 5 (MV grid), 6 (LV busbar) or 7 (LV grid).

Return type:

int

edisgo.tools.tools.get_weather_cells_intersecting_with_grid_district(edisgo_obj: edisgo.EDisGo, engine: sqlalchemy.engine.base.Engine | None = None) set[source]

Get all weather cells that intersect with the grid district.

Parameters:
  • edisgo_obj (EDisGo) –

  • engine (sqlalchemy.Engine) – Database engine. Only needed when using new egon_data data.

Returns:

Set with weather cell IDs.

Return type:

set(int)

edisgo.tools.tools.get_directory_size(start_dir)[source]

Calculates the size of all files within the start path.

Walks through all files and sub-directories within a given directory and calculate the sum of size of all files in the directory. See also stackoverflow.

Parameters:

start_dir (str) – Start path.

Returns:

Size of the directory.

Return type:

int

edisgo.tools.tools.get_files_recursive(path, files=None)[source]

Recursive function to get all files in a given path and its sub directories.

Parameters:
  • path (str) – Directory to start from.

  • files (list, optional) – List of files to start with. Default: None.

edisgo.tools.tools.calculate_impedance_for_parallel_components(parallel_components, pu=False)[source]

Method to calculate parallel impedance and power of parallel elements.

edisgo.tools.tools.add_line_susceptance(edisgo_obj, mode='mv_b')[source]

Adds line susceptance information in Siemens to lines in existing grids.

Parameters:
  • edisgo_obj (EDisGo) – EDisGo object to which line susceptance information is added.

  • mode (str) –

    Defines how the susceptance is added:

    • ’no_b’

      Susceptance is set to 0 for all lines.

    • ’mv_b’ (Default)

      Susceptance is for the MV lines set according to the equipment parameters and for the LV lines it is set to zero.

    • ’all_b’

      Susceptance is for the MV lines set according to the equipment parameters and for the LV lines 0.25 uF/km is chosen.

Return type:

EDisGo

edisgo.tools.tools.aggregate_district_heating_components(edisgo_obj, feedin_district_heating=None)[source]

Aggregate PtH components that feed into the same district heating network.

Besides aggregating PtH components, feed-in from other heat supply sources can be specified, which is subtracted from the heat demand in the district heating network in order to determine the heat demand that needs to be covered by the PtH units.

Concerning the aggregated components, rated power of the single components is added up and COP for combined component is calculated from COP of all components weighed with their rated power. If active and reactive power time series were previously set for the PtH units they are overwritten.

Parameters:
  • edisgo_obj (EDisGo) –

  • feedin_district_heating (pandas.DataFrame) – Other thermal feed-in into district heating per district heating area (in columns) and time step (in index) in MW.

edisgo.tools.tools.reduce_timeseries_data_to_given_timeindex(edisgo_obj, timeindex, freq='1H', timeseries=True, electromobility=True, save_ev_soc_initial=True, heat_pump=True, dsm=True, overlying_grid=True)[source]

Reduces timeseries data in EDisGo object to given time index.

Parameters:
  • edisgo_obj (EDisGo) –

  • timeindex (pandas.DatetimeIndex) – Time index to set.

  • freq (str or pandas.Timedelta, optional) – Frequency of time series data. This is only needed if it cannot be inferred from the given timeindex and if electromobility data and/or overlying grid data is reduced, as the initial SoC is tried to be set using the time step before the first time step in the given timeindex. Offset aliases can be found here: https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases. Default: ‘1H’.

  • timeseries (bool) – Indicates whether timeseries in TimeSeries are reduced to given time index. Default: True.

  • electromobility (bool) – Indicates whether timeseries in Electromobility are reduced to given time index. Default: True.

  • save_ev_soc_initial (bool) – Indicates whether to save initial EV SOC from timestep before first timestep of given time index. Default: True.

  • heat_pump (bool) – Indicates whether timeseries in HeatPump are reduced to given time index. Default: True.

  • dsm (bool) – Indicates whether timeseries in DSM are reduced to given time index. Default: True.

  • overlying_grid (bool) – Indicates whether timeseries in OverlyingGrid are reduced to given time index. Default: True.

edisgo.tools.tools.resample(object, freq_orig, method: str = 'ffill', freq: str | pandas.Timedelta = '15min', attr_to_resample=None)[source]

Resamples time series data to a desired resolution.

Both up- and down-sampling methods are possible.

Parameters:
  • object (TimeSeries or HeatPump) – Object of which to resample time series data.

  • freq_orig (pandas.Timedelta) – Frequency of original time series data.

  • method (str, optional) – See method parameter in resample_timeseries for more information.

  • freq (str, optional) – See freq parameter in resample_timeseries for more information.

  • attr_to_resample (list(str), optional) – List of attributes to resample. Per default, all attributes specified in respective object’s _attributes are resampled.

edisgo.tools.tools.reduce_memory_usage(df: pandas.DataFrame, show_reduction: bool = False) pandas.DataFrame[source]

Function to automatically check if columns of a pandas DataFrame can be reduced to a smaller data type.

Source: https://mikulskibartosz.name/how-to-reduce-memory-usage-in-pandas

Parameters:
  • df (pandas.DataFrame) – DataFrame to reduce memory usage for.

  • show_reduction (bool) – If True, print amount of memory reduced.

Returns:

DataFrame with decreased memory usage.

Return type:

pandas.DataFrame

edisgo.tools.tools.get_year_based_on_timeindex(edisgo_obj)[source]

Checks if timeindex is already set and if so, returns the year of the time index.

Parameters:

edisgo_object (EDisGo) –

Returns:

If a time index is available returns the year of the time index, otherwise it returns None.

Return type:

int or None

edisgo.tools.tools.get_year_based_on_scenario(scenario)[source]

Returns the year the given scenario was set up for.

Parameters:

scenario (str) – Scenario for which to set year. Possible options are ‘eGon2035’ and ‘eGon100RE’.

Returns:

Returns the year of the scenario (2035 in case of the ‘eGon2035’ scenario and 2045 in case of the ‘eGon100RE’ scenario). If another scenario name is provided it returns None.

Return type:

int or None

edisgo.tools.tools.hash_dataframe(df: pandas.DataFrame) str[source]

Get hash of dataframe.

Can be used to check if dataframes have the same content.

Parameters:

df (pandas.DataFrame) – DataFrame to hash.

Returns:

Hash of dataframe as string.

Return type:

str