edisgo.tools package¶
edisgo.tools.config module¶
This file is part of eDisGo, a python package for distribution network analysis and optimization.
It is developed in the project open_eGo: https://openegoproject.wordpress.com
eDisGo lives on github: https://github.com/openego/edisgo/ The documentation is available on RTD: http://edisgo.readthedocs.io
Based on code by oemof developing group
This module provides a highlevel layer for reading and writing config files.
-
class
edisgo.tools.config.Config(**kwargs)[source]¶ Bases:
objectContainer for all configurations.
Parameters: config_path (None or strordict) –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.
strIf 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.dictA 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.
Notes
The Config object can be used like a dictionary. See example on how to use it.
Examples
Create Config object from default config files
>>> from edisgo.tools.config import Config >>> config = Config()
Get reactive power factor for generators in the MV network
>>> config['reactive_power_factor']['mv_gen']
-
edisgo.tools.config.load_config(filename, config_dir=None, copy_default_config=True)[source]¶ Loads the specified config file.
Parameters: - filename (
str) – Config file name, e.g. ‘config_grid.cfg’. - config_dir (
str, optional) – Path to config file. If None uses default edisgo config directory specified in config file ‘config_system.cfg’ in section ‘user_dirs’ by subsections ‘root_dir’ and ‘config_dir’. Default: None. - copy_default_config (Boolean) – If True copies a default config file into config_dir if the specified config file does not exist. Default: True.
- filename (
-
edisgo.tools.config.get(section, key)[source]¶ Returns the value of a given key of a given section of the main config file.
Parameters: Returns: The value which will be casted to float, int or boolean. If no cast is successful, the raw string is returned.
Return type:
-
edisgo.tools.config.get_default_config_path()[source]¶ Returns the basic edisgo config path. If it does not yet exist it creates it and copies all default config files into it.
Returns: Path to default edisgo config directory specified in config file ‘config_system.cfg’ in section ‘user_dirs’ by subsections ‘root_dir’ and ‘config_dir’. Return type: str
edisgo.tools.edisgo_run module¶
-
edisgo.tools.edisgo_run.setup_logging(logfilename=None, logfile_loglevel='debug', console_loglevel='info', **logging_kwargs)[source]¶
-
edisgo.tools.edisgo_run.run_edisgo_basic(ding0_filepath, generator_scenario=None, analysis='worst-case', *edisgo_grid)[source]¶ Analyze edisgo network extension cost as reference scenario
ToDo: adapt to refactored code!
Parameters: - ding0_filepath (str) – Path to ding0 data ending typically /path/to/ding0_data/”ding0_grids__” + str(``grid_district`) + “.xxx”`
- analysis (str) – Either ‘worst-case’ or ‘timeseries’
- generator_scenario (None or
str) – If provided defines which scenario of future generator park to use and invokes import of these generators. Possible options are ‘nep2035’ and ‘ego100’.
Returns: - edisgo_grid (
EDisGo) – eDisGo network container - costs (pandas.Dataframe) – Cost of network extension
- grid_issues (dict) – Grids resulting in an error including error message
-
edisgo.tools.edisgo_run.run_edisgo_twice(run_args)[source]¶ Run network analysis twice on same network: once w/ and once w/o new generators
ToDo: adapt to refactored code!
First run without connection of new generators approves sufficient network hosting capacity. Otherwise, network is reinforced. Second run assessment network extension needs in terms of RES integration
Parameters: run_args (list) – Optional parameters for run_edisgo_basic().Returns: - all_costs_before_geno_import (pandas.Dataframe) – Grid extension cost before network connection of new generators
- all_grid_issues_before_geno_import (dict) – Remaining overloading or over-voltage issues in network
- all_costs (pandas.Dataframe) – Grid extension cost due to network connection of new generators
- all_grid_issues (dict) – Remaining overloading or over-voltage issues in network
-
edisgo.tools.edisgo_run.run_edisgo_pool(ding0_file_list, run_args_opt=[None, 'worst-case'], workers=2, worker_lifetime=1)[source]¶ Use python multiprocessing toolbox for parallelization
Several grids are analyzed in parallel.
Parameters: - ding0_file_list (list) – Ding0 network data file names
- run_args_opt (list) – eDisGo options, see
run_edisgo_basic()andrun_edisgo_twice(), has to contain generator_scenario and analysis as entries - workers (int) – Number of parallel process
- worker_lifetime (int) – Bunch of grids sequentially analyzed by a worker
Returns: - all_costs_before_geno_import (list) – Grid extension cost before network connection of new generators
- all_grid_issues_before_geno_import (list) – Remaining overloading or over-voltage issues in network
- all_costs (list) – Grid extension cost due to network connection of new generators
- all_grid_issues (list) – Remaining overloading or over-voltage issues in network
-
edisgo.tools.edisgo_run.run_edisgo_pool_flexible(ding0_id_list, func, func_arguments, workers=2, worker_lifetime=1)[source]¶ Use python multiprocessing toolbox for parallelization
Several grids are analyzed in parallel based on your custom function that defines the specific application of eDisGo.
Parameters: - ding0_id_list (list of int) – List of ding0 network data IDs (also known as HV/MV substation IDs)
- func (any function) – Your custom function that shall be parallelized
- func_arguments (tuple) – Arguments to custom function
func - workers (int) – Number of parallel process
- worker_lifetime (int) – Bunch of grids sequentially analyzed by a worker
Notes
Please note, the following requirements for the custom function which is to be executed in parallel
- It must return an instance of the type
EDisGo. - The first positional argument is the MV network district id (as int). It is
prepended to the tuple of arguments
func_arguments
Returns: containers – Dict of EDisGo instances keyed by its ID Return type: dict of EDisGo
edisgo.tools.geo module¶
-
edisgo.tools.geo.proj2equidistant(srid)[source]¶ Transforms to equidistant projection (epsg:3035).
Parameters: srid (int) – Spatial reference identifier of geometry to transform. Returns: Return type: functools.partial()
-
edisgo.tools.geo.proj2equidistant_reverse(srid)[source]¶ Transforms back from equidistant projection to given projection.
Parameters: srid (int) – Spatial reference identifier of geometry to transform. Returns: Return type: functools.partial()
-
edisgo.tools.geo.proj_by_srids(srid1, srid2)[source]¶ Transforms from specified projection to other specified projection.
Parameters: Returns: Return type: Notes
Projections often used are conformal projection (epsg:4326), equidistant projection (epsg:3035) and spherical mercator projection (epsg:3857).
-
edisgo.tools.geo.calc_geo_lines_in_buffer(grid_topology, bus, grid, buffer_radius=2000, buffer_radius_inc=1000)[source]¶ Determines lines that are at least partly within buffer around given bus.
If there are no lines, the buffer specified in buffer_radius is successively extended by buffer_radius_inc until lines are found.
Parameters: - grid_topology (
Topology) – - bus (pandas.Series) – Data of origin bus the buffer is created around.
Series has same rows as columns of
buses_df. - grid (
Grid) – Grid whose lines are searched. - buffer_radius (float, optional) – Radius in m used to find connection targets. Default: 2000.
- buffer_radius_inc (float, optional) – Radius in m which is incrementally added to buffer_radius as long as no target is found. Default: 1000.
Returns: List of lines in buffer (meaning close to the bus) sorted by the lines’ representatives.
Return type: - grid_topology (
-
edisgo.tools.geo.calc_geo_dist_vincenty(grid_topology, bus_source, bus_target, branch_detour_factor=1.3)[source]¶ Calculates the geodesic distance between two buses in km.
The detour factor in config_grid is incorporated in the geodesic distance.
Parameters: Returns: Distance in km.
Return type:
-
edisgo.tools.geo.find_nearest_bus(point, bus_target)[source]¶ Finds the nearest bus in bus_target to a given point.
Parameters: - point (shapely.Point) – Point to find nearest bus for.
- bus_target (pandas.DataFrame) – Dataframe with candidate buses and their positions given in ‘x’ and ‘y’
columns. The dataframe has the same format as
buses_df.
Returns: Tuple that contains the name of the nearest bus and its distance.
Return type:
-
edisgo.tools.geo.find_nearest_conn_objects(grid_topology, bus, lines, conn_diff_tolerance=0.0001)[source]¶ Searches all lines for the nearest possible connection object per line.
It picks out 1 object out of 3 possible objects: 2 line-adjacent buses and 1 potentially created branch tee on the line (using perpendicular projection). The resulting stack (list) is sorted ascending by distance from bus.
Parameters: - grid_topology (
Topology) – - bus (pandas.Series) – Data of bus to connect.
Series has same rows as columns of
buses_df. - lines (list(str)) – List of line representatives from index of
lines_df. - conn_diff_tolerance (float, optional) – Threshold which is used to determine if 2 objects are at the same position. Default: 0.0001.
Returns: List of connection objects. Each object is represented by dict with representative, shapely object and distance to node.
Return type: - grid_topology (
edisgo.tools.plots module¶
-
edisgo.tools.plots.histogram(data, **kwargs)[source]¶ Function to create histogram, e.g. for voltages or currents.
Parameters: - data (pandas.DataFrame) – Data to be plotted, e.g. voltage or current (v_res or i_res from
network.results.Results). Index of the dataframe must be a pandas.DatetimeIndex. - timeindex (pandas.Timestamp or list(pandas.Timestamp) or None, optional) – Specifies time steps histogram is plotted for. If timeindex is None all time steps provided in data are used. Default: None.
- directory (
stror None, optional) – Path to directory the plot is saved to. Is created if it does not exist. Default: None. - filename (
stror None, optional) – Filename the plot is saved as. File format is specified by ending. If filename is None, the plot is shown. Default: None. - color (
stror None, optional) – Color used in plot. If None it defaults to blue. Default: None. - alpha (
float, optional) – Transparency of the plot. Must be a number between 0 and 1, where 0 is see through and 1 is opaque. Default: 1. - title (
stror None, optional) – Plot title. Default: None. - x_label (
str, optional) – Label for x-axis. Default: “”. - y_label (
str, optional) – Label for y-axis. Default: “”. - normed (
bool, optional) – Defines if histogram is normed. Default: False. - x_limits (
tupleor None, optional) – Tuple with x-axis limits. First entry is the minimum and second entry the maximum value. Default: None. - y_limits (
tupleor None, optional) – Tuple with y-axis limits. First entry is the minimum and second entry the maximum value. Default: None. - fig_size (
strortuple, optional) –- Size of the figure in inches or a string with the following options:
- ’a4portrait’
- ’a4landscape’
- ’a5portrait’
- ’a5landscape’
Default: ‘a5landscape’.
- binwidth (
float) – Width of bins. Default: None.
- data (pandas.DataFrame) – Data to be plotted, e.g. voltage or current (v_res or i_res from
-
edisgo.tools.plots.get_grid_district_polygon(config, subst_id=None, projection=4326)[source]¶ Get MV network district polygon from oedb for plotting.
-
edisgo.tools.plots.mv_grid_topology(edisgo_obj, timestep=None, line_color=None, node_color=None, line_load=None, grid_expansion_costs=None, filename=None, arrows=False, grid_district_geom=True, background_map=True, voltage=None, limits_cb_lines=None, limits_cb_nodes=None, xlim=None, ylim=None, lines_cmap='inferno_r', title='', scaling_factor_line_width=None, curtailment_df=None, **kwargs)[source]¶ Plot line loading as color on lines.
Displays line loading relative to nominal capacity.
Parameters: - edisgo_obj (
EDisGo) – - timestep (pandas.Timestamp) – Time step to plot analysis results for. If timestep is None maximum line load and if given, maximum voltage deviation, is used. In that case arrows cannot be drawn. Default: None.
- line_color (
stror None) –Defines whereby to choose line colors (and implicitly size). Possible options are:
- ’loading’ Line color is set according to loading of the line. Loading of MV lines must be provided by parameter line_load.
- ’expansion_costs’ Line color is set according to investment costs of the line. This option also effects node colors and sizes by plotting investment in stations and setting node_color to ‘storage_integration’ in order to plot storage size of integrated storage units. Grid expansion costs must be provided by parameter grid_expansion_costs.
- None (default) Lines are plotted in black. Is also the fallback option in case of wrong input.
- node_color (
stror None) –Defines whereby to choose node colors (and implicitly size). Possible options are:
- ’technology’ Node color as well as size is set according to type of node (generator, MV station, etc.).
- ’voltage’ Node color is set according to maximum voltage at each node. Voltages of nodes in MV network must be provided by parameter voltage.
- ’voltage_deviation’ Node color is set according to voltage deviation from 1 p.u.. Voltages of nodes in MV network must be provided by parameter voltage.
- ’storage_integration’ Only storage units are plotted. Size of node corresponds to size of storage.
- None (default) Nodes are not plotted. Is also the fallback option in case of wrong input.
- ’curtailment’ Plots curtailment per node. Size of node corresponds to share of curtailed power for the given time span. When this option is chosen a dataframe with curtailed power per time step and node needs to be provided in parameter curtailment_df.
- ’charging_park’ Plots nodes with charging stations in red.
- line_load (pandas.DataFrame or None) – Dataframe with current results from power flow analysis in A. Index of the dataframe is a pandas.DatetimeIndex, columns are the line representatives. Only needs to be provided when parameter line_color is set to ‘loading’. Default: None.
- grid_expansion_costs (pandas.DataFrame or None) – Dataframe with network expansion costs in kEUR. See grid_expansion_costs
in
Resultsfor more information. Only needs to be provided when parameter line_color is set to ‘expansion_costs’. Default: None. - filename (
str) – Filename to save plot under. If not provided, figure is shown directly. Default: None. - arrows (
Boolean) – If True draws arrows on lines in the direction of the power flow. Does only work when line_color option ‘loading’ is used and a time step is given. Default: False. - grid_district_geom (
Boolean) – If True network district polygon is plotted in the background. This also requires the geopandas package to be installed. Default: True. - background_map (
Boolean) – If True map is drawn in the background. This also requires the contextily package to be installed. Default: True. - voltage (pandas.DataFrame) – Dataframe with voltage results from power flow analysis in p.u.. Index of the dataframe is a pandas.DatetimeIndex, columns are the bus representatives. Only needs to be provided when parameter node_color is set to ‘voltage’. Default: None.
- limits_cb_lines (
tuple) – Tuple with limits for colorbar of line color. First entry is the minimum and second entry the maximum value. Only needs to be provided when parameter line_color is not None. Default: None. - limits_cb_nodes (
tuple) – Tuple with limits for colorbar of nodes. First entry is the minimum and second entry the maximum value. Only needs to be provided when parameter node_color is not None. Default: None. - xlim (
tuple) – Limits of x-axis. Default: None. - ylim (
tuple) – Limits of y-axis. Default: None. - lines_cmap (
str) – Colormap to use for lines in case line_color is ‘loading’ or ‘expansion_costs’. Default: ‘inferno_r’. - title (
str) – Title of the plot. Default: ‘’. - scaling_factor_line_width (
floator None) – If provided line width is set according to the nominal apparent power of the lines. If line width is None a default line width of 2 is used for each line. Default: None. - curtailment_df (pandas.DataFrame) – Dataframe with curtailed power per time step and node. Columns of the dataframe correspond to buses and index to the time step. Only needs to be provided if node_color is set to ‘curtailment’.
- legend_loc (str) – Location of legend. See matplotlib legend location options for more information. Default: ‘upper left’.
- edisgo_obj (
edisgo.tools.powermodels_io module¶
-
edisgo.tools.powermodels_io.to_powermodels(pypsa_net)[source]¶ Convert pypsa network to network dictionary format, using the pypower structure as an intermediate steps
powermodels network dictionary: https://lanl-ansi.github.io/PowerModels.jl/stable/network-data/
pypower caseformat: https://github.com/rwl/PYPOWER/blob/master/pypower/caseformat.py
Parameters: pypsa_net – Returns:
-
edisgo.tools.powermodels_io.add_storage_from_edisgo(edisgo_obj, psa_net, pm_dict)[source]¶ Read static storage data (position and capacity) from eDisGo and export to Powermodels dict
-
edisgo.tools.powermodels_io.pypsa2ppc(psa_net)[source]¶ Converter from pypsa data structure to pypower data structure
adapted from pandapower’s pd2ppc converter
-
edisgo.tools.powermodels_io.ppc2pm(ppc, psa_net)[source]¶ converter from pypower datastructure to powermodels dictionary,
adapted from pandapower to powermodels converter: https://github.com/e2nIEE/pandapower/blob/develop/pandapower/converter/powermodels/to_pm.py
Parameters: ppc – Returns:
edisgo.tools.preprocess_pypsa_opf_structure module¶
-
edisgo.tools.preprocess_pypsa_opf_structure.preprocess_pypsa_opf_structure(edisgo_grid, psa_network, hvmv_trafo=False)[source]¶ Prepares pypsa network for OPF problem.
- adds line costs
- adds HV side of HV/MV transformer to network
- moves slack to HV side of HV/MV transformer
Parameters: - edisgo_grid (
EDisGo) – - psa_network (pypsa.Network) –
- hvmv_trafo (
Boolean) – If True, HV side of HV/MV transformer is added to buses and Slack generator is moved to HV side.
-
edisgo.tools.preprocess_pypsa_opf_structure.aggregate_fluct_generators(psa_network)[source]¶ Aggregates fluctuating generators of same type at the same node.
Iterates over all generator buses. If multiple fluctuating generators are attached, they are aggregated by type.
Parameters: psa_network (pypsa.Network) –
edisgo.tools.tools module¶
-
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
- Maximum Residual Load: refers to the point in the time series where the
- (load - generation) achieves its maximum.
- 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_relative_line_load(edisgo_obj, lines=None, timesteps=None)[source]¶ Calculates relative line loading for specified lines and time steps.
Line loading is calculated by dividing the current at the given time step by the allowed current.
Parameters: - edisgo_obj (
EDisGo) – - lines (list(str) or None, optional) – Line names/representatives of lines to calculate line loading for. If None, line loading is calculated for all lines in the network. Default: None.
- timesteps (pandas.Timestamp or list(pandas.Timestamp) or None, optional) – Specifies time steps to calculate line loading for. If timesteps is None, all time steps power flow analysis was conducted for are used. Default: None.
Returns: Dataframe with relative line loading (unitless). Index of the dataframe is a pandas.DatetimeIndex, columns are the line representatives.
Return type: - edisgo_obj (
-
edisgo.tools.tools.calculate_line_reactance(line_inductance_per_km, line_length, num_parallel)[source]¶ Calculates line reactance in Ohm.
Parameters: Returns: Reactance in Ohm
Return type:
-
edisgo.tools.tools.calculate_line_resistance(line_resistance_per_km, line_length, num_parallel)[source]¶ Calculates line resistance in Ohm.
Parameters: Returns: Resistance in Ohm
Return type:
-
edisgo.tools.tools.calculate_apparent_power(nominal_voltage, current, num_parallel)[source]¶ Calculates apparent power in MVA from given voltage and current.
Parameters: Returns: Apparent power in MVA.
Return type:
-
edisgo.tools.tools.drop_duplicated_indices(dataframe, keep='first')[source]¶ Drop rows of duplicate indices in dataframe.
Parameters: - dataframe (pandas.DataFrame) – handled dataframe
- keep (str) – indicator of row to be kept, ‘first’, ‘last’ or False, see pandas.DataFrame.drop_duplicates() method
-
edisgo.tools.tools.drop_duplicated_columns(df, keep='first')[source]¶ Drop columns of dataframe that appear more than once.
Parameters: - df (pandas.DataFrame) – Dataframe of which columns are dropped.
- keep (str) – Indicator of whether to keep first (‘first’), last (‘last’) or none (False) of the duplicated columns. See drop_duplicates() method of pandas.DataFrame.
-
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: 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.assign_feeder(edisgo_obj, mode='mv_feeder')[source]¶ Assigns MV or LV feeder to each bus and line, depending on the mode.
The feeder name is written to a new column mv_feeder or lv_feeder in
Topology’sbuses_dfandlines_df. The MV respectively LV feeder name corresponds to the name of the first bus in the respective feeder.Parameters:
-
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
Topologyclass.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.assign_voltage_level_to_component(edisgo_obj, 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: - edisgo_obj (
EDisGo) – - 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.
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: - edisgo_obj (