EDisGo class

class edisgo.EDisGo(**kwargs)[source]

Provides the top-level API for invocation of data import, power flow analysis, network reinforcement, flexibility measures, etc..

Parameters:
  • ding0_grid (str) – Path to directory containing csv files of network to be loaded.
  • generator_scenario (None or str, optional) – If None, the generator park of the imported grid is kept as is. Otherwise defines which scenario of future generator park to use and invokes grid integration of these generators. Possible options are ‘nep2035’ and ‘ego100’. These are scenarios from the research project open_eGo (see final report for more information on the scenarios). See import_generators for further information on how generators are integrated and what further options there are. Default: None.
  • worst_case_analysis (None or str, optional) –

    If not None time series for feed-in and load will be generated according to the chosen worst case analysis. Possible options are:

    • ’worst-case’

      Feed-in and load for the two worst-case scenarios feed-in case and load case are generated.

    • ’worst-case-feedin’

      Feed-in and load for the worst-case scenario feed-in case is generated.

    • ’worst-case-load’

      Feed-in and load for the worst-case scenario load case is generated.

    Worst case scaling factors for loads and generators are specified in the config section worst_case_scale_factor.

    Be aware that if you choose to conduct a worst-case analysis your input for all other time series parameters (e.g. timeseries_generation_fluctuating, timeseries_generation_dispatchable, timeseries_load) will not be used. As eDisGo is designed to work with time series but worst cases are not time specific, a random time index 1/1/1970 is used.

    Default: None.

  • timeseries_generation_fluctuating (str or pandas.DataFrame or None, optional) –

    Parameter used to obtain time series for active power feed-in of fluctuating renewables wind and solar. Possible options are:

    • ’oedb’

      Hourly time series for the year 2011 are obtained from the OpenEnergy DataBase. See edisgo.io.timeseries_import.import_feedin_timeseries() for more information.

    • pandas.DataFrame

      DataFrame with time series for active power feed-in, normalized to a capacity of 1 MW.

      Time series can either be aggregated by technology type or by type and weather cell ID. In the first case columns of the DataFrame are ‘solar’ and ‘wind’; in the second case columns need to be a pandas.MultiIndex with the first level containing the type and the second level the weather cell ID.

      Index needs to be a pandas.DatetimeIndex.

      When importing a ding0 grid and/or using predefined scenarios of the future generator park (see parameter generator_scenario), each generator has an assigned weather cell ID that identifies the weather data cell from the weather data set used in the research project open_eGo to determine feed-in profiles. The weather cell ID can be retrieved from column weather_cell_id in generators_df and could be overwritten to use own weather cells.

    Default: None.

  • timeseries_generation_dispatchable (pandas.DataFrame or None, optional) –

    DataFrame with time series for active power of each type of dispatchable generator, normalized to a capacity of 1 MW.

    Index needs to be a pandas.DatetimeIndex.

    Columns represent generator type (e.g. ‘gas’, ‘coal’, ‘biomass’). All in the current grid existing generator types can be retrieved from column type in generators_df. Use ‘other’ if you don’t want to explicitly provide every possible type.

    Default: None.

  • timeseries_generation_reactive_power (pandas.DataFrame or None, optional) –

    Dataframe with time series of normalized reactive power (normalized by the rated nominal active power) per technology and weather cell. Index needs to be a pandas.DatetimeIndex. Columns represent generator type and can be a MultiIndex containing the weather cell ID in the second level. If the technology doesn’t contain weather cell information, i.e. if it is not a solar or wind generator, this second level can be left as a numpy Nan or a None.

    If no time series for the technology or technology and weather cell ID is given, reactive power will be calculated from power factor and power factor mode in the config sections reactive_power_factor and reactive_power_mode and a warning will be raised.

    Default: None.

  • timeseries_load (str or pandas.DataFrame or None, optional) –

    Parameter used to obtain time series of active power of loads. Possible options are:

    • ’demandlib’

      Time series for the year specified in input parameter timeindex are generated using standard electric load profiles from the oemof demandlib.

    • pandas.DataFrame

      DataFrame with load time series of each type of load normalized with corresponding annual energy demand. Index needs to be a pandas.DatetimeIndex. Columns represent load type. The in the current grid existing load types can be retrieved from column sector in loads_df. In ding0 grids the differentiated sectors are ‘residential’, ‘retail’, ‘industrial’, and ‘agricultural’.

    Default: None.

  • timeseries_load_reactive_power (pandas.DataFrame or None, optional) –

    Dataframe with time series of normalized reactive power (normalized by annual energy demand) per load sector.

    Index needs to be a pandas.DatetimeIndex.

    Columns represent load type. The in the current grid existing load types can be retrieved from column sector in loads_df. In ding0 grids the differentiated sectors are ‘residential’, ‘retail’, ‘industrial’, and ‘agricultural’.

    If no time series for the load sector is given, reactive power will be calculated from power factor and power factor mode in the config sections reactive_power_factor and reactive_power_mode and a warning will be raised.

    Default: None.

  • timeindex (None or pandas.DatetimeIndex, optional) – Can be used to select time ranges of the feed-in and load time series that will be used in the power flow analysis. Also defines the year load time series are obtained for when choosing the ‘demandlib’ option to generate load time series.
  • config_path (None or str or dict) –

    Path to the config directory. Options are:

    • None

      If config_path is None, configs are loaded from the edisgo default config directory ($HOME$/.edisgo). If the directory does not exist it is created. If config files don’t exist the default config files are copied into the directory.

    • str

      If config_path is a string, configs will be loaded from the directory specified by config_path. If the directory does not exist it is created. If config files don’t exist the default config files are copied into the directory.

    • dict

      A dictionary can be used to specify different paths to the different config files. The dictionary must have the following keys:

      • ’config_db_tables’
      • ’config_grid’
      • ’config_grid_expansion’
      • ’config_timeseries’

      Values of the dictionary are paths to the corresponding config file. In contrast to the other two options, the directories and config files must exist and are not automatically created.

    Default: None.
topology

The topology is a container object holding the topology of the grids.

Type:Topology
timeseries

Container for component time series.

Type:TimeSeries
results

This is a container holding all calculation results from power flow analyses, curtailment, storage integration, etc.

Type:Results
config

eDisGo configuration data.

Returns:Config object with configuration data from config files.
Return type:Config
import_ding0_grid(path)[source]

Import ding0 topology data from csv files in the format as Ding0 provides it.

Parameters:path (str) – Path to directory containing csv files of network to be loaded.
to_pypsa(**kwargs)[source]

Convert to PyPSA network representation.

A network topology representation based on pandas.DataFrame. The overall container object of this data model, the pypsa.Network, is set up.

Parameters:kwargs – See to_pypsa() for further information.
Returns:PyPSA network representation.
Return type:pypsa.Network
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:networkx.Graph
import_generators(generator_scenario=None, **kwargs)[source]

Gets generator park for specified scenario and integrates them into the grid.

Currently, the only supported data source is scenario data generated in the research project open_eGo. You can choose between two scenarios: ‘nep2035’ and ‘ego100’. You can get more information on the scenarios in the final report.

The generator data is retrieved from the open energy platform from tables for conventional power plants and renewable power plants.

When the generator data is retrieved, the following steps are conducted:

  • Step 1: Update capacity of existing generators if ` update_existing` is True, which it is by default.
  • Step 2: Remove decommissioned generators if remove_decommissioned is True, which it is by default.
  • Step 3: Integrate new MV generators.
  • Step 4: Integrate new LV generators.

For more information on how generators are integrated, see connect_to_mv and connect_to_lv.

After the generator park is changed there may be grid issues due to the additional in-feed. These are not solved automatically. If you want to have a stable grid without grid issues you can invoke the automatic grid expansion through the function reinforce.

Parameters:generator_scenario (str) – Scenario for which to retrieve generator data. Possible options are ‘nep2035’ and ‘ego100’.
Other Parameters:
 kwargs – See edisgo.io.generators_import.oedb().
analyze(mode=None, timesteps=None, **kwargs)[source]

Conducts a static, non-linear power flow analysis

Conducts a static, non-linear power flow analysis using PyPSA and writes results (active, reactive and apparent power as well as current on lines and voltages at buses) to Results (e.g. v_res for voltages). See to_pypsa() for more information.

Parameters:
  • mode (str) – Allows to toggle between power flow analysis (PFA) on the whole network topology (default: None), only MV (‘mv’ or ‘mvlv’) or only LV (‘lv’). Defaults to None which equals power flow analysis for MV + LV.
  • timesteps (pandas.DatetimeIndex or pandas.Timestamp) – Timesteps specifies for which time steps to conduct the power flow analysis. It defaults to None in which case the time steps in timeindex are used.
reinforce(**kwargs)[source]

Reinforces the network and calculates network expansion costs.

See edisgo.flex_opt.reinforce_grid.reinforce_grid() for more information.

perform_mp_opf(timesteps, storage_series=[], **kwargs)[source]

Run optimal power flow with julia.

Parameters:
  • timesteps (list) – List of timesteps to perform OPF for.
  • kwargs – See run_mp_opf() for further information.
Returns:

Status of optimization.
Return type:

str
aggregate_components(mode='by_component_type', aggregate_generators_by_cols=['bus'], aggregate_loads_by_cols=['bus'], aggregate_charging_points_by_cols=['bus'])[source]

Aggregates generators, loads and charging points at the same bus.

There are several options how to aggregate. By default all components of the same type are aggregated separately. You can specify further columns to consider in the aggregation, such as the generator type or the load sector.

Be aware that by aggregating components you lose some information e.g. on load sector or charging point use case.

Parameters:
  • mode (str) – Valid options are ‘by_component_type’ and ‘by_load_and_generation’. In case of aggregation ‘by_component_type’ generators, loads and charging points are aggregated separately, by the respectively specified columns, given in aggregate_generators_by_cols, aggregate_loads_by_cols, and aggregate_charging_points_by_cols. In case of aggregation ‘by_load_and_generation’, all loads and charging points at the same bus are aggregated. Input in aggregate_loads_by_cols and aggregate_charging_points_by_cols is ignored. Generators are aggregated by the columns specified in aggregate_generators_by_cols.
  • aggregate_generators_by_cols (list(str)) – List of columns to aggregate generators at the same bus by. Valid columns are all columns in generators_df.
  • aggregate_loads_by_cols (list(str)) – List of columns to aggregate loads at the same bus by. Valid columns are all columns in loads_df.
  • aggregate_charging_points_by_cols (list(str)) – List of columns to aggregate charging points at the same bus by. Valid columns are all columns in charging_points_df.
plot_mv_grid_topology(technologies=False, **kwargs)[source]

Plots plain MV network topology and optionally nodes by technology type (e.g. station or generator).

For more information see edisgo.tools.plots.mv_grid_topology().

Parameters:technologies (Boolean) – If True plots stations, generators, etc. in the topology in different colors. If False does not plot any nodes. Default: False.
plot_mv_voltages(**kwargs)[source]

Plots voltages in MV network on network topology plot.

For more information see edisgo.tools.plots.mv_grid_topology().

plot_mv_line_loading(**kwargs)[source]

Plots relative line loading (current from power flow analysis to allowed current) of MV lines.

For more information see edisgo.tools.plots.mv_grid_topology().

plot_mv_grid_expansion_costs(**kwargs)[source]

Plots grid expansion costs per MV line.

For more information see edisgo.tools.plots.mv_grid_topology().

plot_mv_storage_integration(**kwargs)[source]

Plots storage position in MV topology of integrated storage units.

For more information see edisgo.tools.plots.mv_grid_topology().

plot_mv_grid(**kwargs)[source]

General plotting function giving all options of function edisgo.tools.plots.mv_grid_topology().

histogram_voltage(timestep=None, title=True, **kwargs)[source]

Plots histogram of voltages.

For more information on the histogram plot and possible configurations see edisgo.tools.plots.histogram().

Parameters:
  • timestep (pandas.Timestamp or list(pandas.Timestamp) or None, optional) – Specifies time steps histogram is plotted for. If timestep is None all time steps voltages are calculated for are used. Default: None.
  • title (str or bool, optional) – Title for plot. If True title is auto generated. If False plot has no title. If str, the provided title is used. Default: True.
histogram_relative_line_load(timestep=None, title=True, voltage_level='mv_lv', **kwargs)[source]

Plots histogram of relative line loads.

For more information on how the relative line load is calculated see edisgo.tools.tools.get_line_loading_from_network(). For more information on the histogram plot and possible configurations see edisgo.tools.plots.histogram().

Parameters:
  • timestep (pandas.Timestamp or list(pandas.Timestamp) or None, optional) – Specifies time step(s) histogram is plotted for. If timestep is None all time steps currents are calculated for are used. Default: None.
  • title (str or bool, optional) – Title for plot. If True title is auto generated. If False plot has no title. If str, the provided title is used. Default: True.
  • voltage_level (str) – Specifies which voltage level to plot voltage histogram for. Possible options are ‘mv’, ‘lv’ and ‘mv_lv’. ‘mv_lv’ is also the fallback option in case of wrong input. Default: ‘mv_lv’
save(directory, save_results=True, save_topology=True, save_timeseries=True, **kwargs)[source]

Saves EDisGo object to csv.

It can be chosen if results, topology and timeseries should be saved. For each one, a separate directory is created.

Parameters:
  • directory (str) – Main directory to save EDisGo object to.
  • save_results (bool, optional) – Indicates whether to save Results object. Per default it is saved. See to_csv for more information.
  • save_topology (bool, optional) – Indicates whether to save Topology. Per default it is saved. See to_csv for more information.
  • save_timeseries (bool, optional) – Indicates whether to save Timeseries. Per default it is saved. See to_csv for more information.
Other Parameters:
 
  • reduce_memory (bool, optional) – If True, size of dataframes containing time series in Results and TimeSeries is reduced. See reduce_memory and reduce_memory for more information. Type to convert to can be specified by providing to_type as keyword argument. Further parameters of reduce_memory functions cannot be passed here. Call these functions directly to make use of further options. Default: False.
  • to_type (str, optional) – Data type to convert time series data to. This is a tradeoff between precision and memory. Default: “float32”.
add_component(comp_type, add_ts=True, ts_active_power=None, ts_reactive_power=None, **kwargs)[source]

Adds single component to network topology.

Components can be lines or buses as well as generators, loads, charging points or storage units.

Parameters:
  • comp_type (str) – Type of added component. Can be ‘Bus’, ‘Line’, ‘Load’, ‘Generator’, ‘StorageUnit’, ‘Transformer’ or ‘ChargingPoint’.
  • add_ts (bool) – Indicator if time series for component are added as well.
  • ts_active_power (pandas.Series) – Active power time series of added component. Index of the series must contain all time steps in timeindex. Values are active power per time step in MW.
  • ts_reactive_power (pandas.Series) – Reactive power time series of added component. Index of the series must contain all time steps in timeindex. Values are reactive power per time step in MVA.
  • **kwargs (dict) – Attributes of added component. See respective functions for required entries. For ‘Load’, ‘Generator’ and ‘StorageUnit’ the boolean add_ts determines whether a time series is created for the new component or not.
  • Todo (change into add_components to allow adding of several components) – at a time, change topology.add_load etc. to add_loads, where lists of parameters can be inserted
integrate_component(comp_type, geolocation, voltage_level=None, add_ts=True, ts_active_power=None, ts_reactive_power=None, **kwargs)[source]

Adds single component to topology based on geolocation.

Currently components can be generators or charging points.

Parameters:
  • comp_type (str) – Type of added component. Can be ‘Generator’ or ‘ChargingPoint’.
  • geolocation (shapely.Point or tuple) – Geolocation of the new component. In case of tuple, the geolocation must be given in the form (longitude, latitude).
  • voltage_level (int, optional) –

    Specifies the voltage level the new component is integrated in. Possible options are 4 (MV busbar), 5 (MV grid), 6 (LV busbar) or 7 (LV grid). If no voltage level is provided the voltage level is determined based on the nominal power p_nom (given as kwarg) as follows:

    • voltage level 4 (MV busbar): nominal power between 4.5 MW and 17.5 MW
    • voltage level 5 (MV grid) : nominal power between 0.3 MW and 4.5 MW
    • voltage level 6 (LV busbar): nominal power between 0.1 MW and 0.3 MW
    • voltage level 7 (LV grid): nominal power below 0.1 MW
  • add_ts (bool, optional) – Indicator if time series for component are added as well. Default: True.
  • ts_active_power (pandas.Series, optional) – Active power time series of added component. Index of the series must contain all time steps in timeindex. Values are active power per time step in MW. Currently, if you want to add time series (if add_ts is True), you must provide a time series. It is not automatically retrieved.
  • ts_reactive_power (pandas.Series, optional) – Reactive power time series of added component. Index of the series must contain all time steps in timeindex. Values are reactive power per time step in MVA. Currently, if you want to add time series (if add_ts is True), you must provide a time series. It is not automatically retrieved.
Other Parameters:
 

kwargs – Attributes of added component. See add_generator respectively add_charging_point methods for more information on required and optional parameters of generators and charging points.
remove_component(comp_type, comp_name, drop_ts=True)[source]

Removes single component from respective DataFrame. If drop_ts is set to True, timeseries of elements are deleted as well.

Parameters:
  • comp_type (str) – Type of removed component. Can be ‘Bus’, ‘Line’, ‘Load’, ‘Generator’, ‘StorageUnit’, ‘Transformer’.
  • comp_name (str) – Name of component to be removed.
  • drop_ts (Boolean) – Indicator if timeseries for component are removed as well. Defaults to True.
  • Todo (change into remove_components, when add_component is changed into) – add_components, to allow removal of several components at a time
reduce_memory(**kwargs)[source]

Reduces size of dataframes containing time series to save memory.

Per default, float data is stored as float64. As this precision is barely needed, this function can be used to convert time series data to a data subtype with less memory usage, such as float32.

Other Parameters:
 
  • to_type (str, optional) – Data type to convert time series data to. This is a tradeoff between precision and memory. Default: “float32”.
  • results_attr_to_reduce (list(str), optional) – See attr_to_reduce parameter in reduce_memory for more information.
  • timeseries_attr_to_reduce (list(str), optional) – See attr_to_reduce parameter in reduce_memory for more information.