roseau.load_flow.plotting¶

Plotting functions for roseau.load_flow.

Functions¶

`plot_voltage_phasors`(element, *[, voltage_type, ax])	Plot the voltage phasors of a terminal element or a branch element.
`plot_symmetrical_voltages`(element, *[, axes])	Plot the symmetrical voltages of a terminal element or a branch element.
`plot_interactive_map`(network, *[, style_color, ...])	Plot an electrical network on an interactive map.
`plot_results_interactive_map`(network, *[, ...])	Plot an electrical network on an interactive map with the load flow results.
`voltage_profile`(network, *, mode[, starting_bus_id, ...])	Create a voltage profile of the network.

Module Contents¶

plot_voltage_phasors(element, *, voltage_type='auto', ax=None)¶

Plot the voltage phasors of a terminal element or a branch element.

Parameters:

element (AbstractTerminal) – The bus, load, source, branch side whose voltages to plot.
voltage_type (Literal['pp', 'pn', 'auto']) –
The type of the voltages to plot.
- "auto": Plots the phase-to-neutral voltages if the element has a neutral, otherwise the phase-to-phase voltages. This works for all elements and is the default.
- "pp": Plots the phase-to-phase voltages. Raises an error if the element has only one phase (e.g. “an”).
- "pn": Plots the phase-to-neutral voltages. Raises an error if the element has no neutral.
ax (Axes | None) – The axes to plot on. If None, the currently active axes object is used.

Returns:

The axes with the plot.

Return type:

Axes

plot_symmetrical_voltages(element, *, axes=None)¶

Plot the symmetrical voltages of a terminal element or a branch element.

Parameters:

element (AbstractTerminal) – The bus, load, source, branch side whose voltages to plot. The element must have 'abc' or 'abcn' phases.
axes (Iterable[Axes] | None) – The three axes to plot on for the symmetrical components in the order zero, positive, negative. If None, new axes are created.

Returns:

The three axes with the plots of the symmetrical components in the order zero, positive, negative.

Return type:

tuple[Axes, Axes, Axes]

plot_interactive_map(network, *, style_color=None, highlight_color='#cad40e', style_function=None, highlight_function=None, map_kws=None, add_tooltips=True, add_popups=True, add_search=True, fit_bounds=True)¶

Plot an electrical network on an interactive map.

This function uses the folium library to create an interactive map of the electrical network.

Parameters:

network (ElectricalNetwork) – The electrical network to plot. Buses, lines and transformers are plotted. Buses of source elements are represented with bigger square markers.
style_color (str | StyleColorCallback | None) – A string to use as the default color of all elements, or a callback function in the form (el_type, el_id, /) -> str returning the color of that specific element. el_type is one of "bus", "line", "transformer", "switch". Return None from the callable to use the default color for that element instead. Defaults to ■ #234e83 for buses and lines, ■ #888888 for switches, and ■ #000000 for transformers.
highlight_color (str) – The color of the default style when an element is highlighted. Defaults to ■ #cad40e.
style_function (Callable[[FeatureMap], StyleDict | None] | None) – Function mapping a GeoJson Feature to a style dict. If not provided or when it returns None, the default style is used.
highlight_function (Callable[[FeatureMap], StyleDict | None] | None) – Function mapping a GeoJson Feature to a style dict for mouse events. If not provided or when it returns None, the default highlight style is used.
map_kws (Mapping[str, Any] | None) –
Additional keyword arguments to pass to the folium.Map constructor. The following keywords are passed by default:
- tiles="CartoDB Positron": A light background map that does not obscure network elements.
- location: The centroid of the network geometry if fit_bounds is false. No default value is set otherwise.
- zoom_start: Calculated based on its bounding box if fit_bounds is false. No default value is set otherwise.
add_tooltips (bool) – If True (default), tooltips will be added to the map elements. Tooltips appear when hovering over an element.
add_popups (bool) – If True (default), popups will be added to the map elements. Popups appear when clicking on an element.
add_search (bool) – If True (default), a search bar will be added to the map to search for network elements by their ID.
fit_bounds (bool) – If True (default), the map view will be adjusted to fit all network elements. If False, the initial view is determined by the location and zoom_start parameters in map_kws.

Returns:

The folium.Map object with the network plot.

Return type:

folium.Map

plot_results_interactive_map(network, *, style_color=None, highlight_color='#cad40e', style_function=None, highlight_function=None, map_kws=None, add_tooltips=True, add_popups=True, add_search=True, fit_bounds=True)¶

Plot an electrical network on an interactive map with the load flow results.

This function uses the folium library to create an interactive map of the electrical network with buses colored according to their voltage levels and lines/transformers colored according to their loadings.

Make sure you have defined the geometry of the buses and lines in the network before using this function. You can do this by setting the geometry attribute of the buses and lines. Transformers use the geometry of their HV buses. Also, ensure that the network has valid results by running a load flow calculation before plotting.

Parameters:

network (ElectricalNetwork) – The electrical network to plot. Buses, lines and transformers are plotted. Buses of source elements are represented with bigger square markers.
style_color (str | StyleColorCallback | None) –
A string to use as the default color of all elements, or a callback function in the form (el_type, el_id, /) -> str returning the color of that specific element. el_type is one of "bus", "line", "transformer", "switch". Return None from the callable to use the default color for that element instead. The default colors depend on the element type and its results:

For buses, the default color is determined by their voltage levels:
- blue: U below Umin
- cyan: U close to Umin; specifically, Umin ≤ U < 0.75 * Umin + 0.25
- green: U within Umin and Umax and not close to the limits
- orange: U close to Umax; specifically, 0.75 * Umax + 0.25 < U ≤ Umax
- red: U above Umax
For lines and transformers, the default color depends on their loadings: - green: below 75% of the maximum loading - orange: between 75% and 100% of the maximum loading - red: above 100% of the maximum loading

For switches, the default color is ■ #888888.
highlight_color (str) – The color of the default style when an element is highlighted. Defaults to ■ #cad40e.
style_function (Callable[[FeatureMap], StyleDict | None] | None) – Function mapping a GeoJson Feature to a style dict. If not provided or when it returns None, the default style is used.
highlight_function (Callable[[FeatureMap], StyleDict | None] | None) – Function mapping a GeoJson Feature to a style dict for mouse events. If not provided or when it returns None, the default highlight style is used.
map_kws (Mapping[str, Any] | None) –
Additional keyword arguments to pass to the folium.Map constructor. The following keywords are passed by default:
- tiles="CartoDB Positron": A light background map that does not obscure network elements.
- location: The centroid of the network geometry if fit_bounds is false. No default value is set otherwise.
- zoom_start: Calculated based on its bounding box if fit_bounds is false. No default value is set otherwise.
add_tooltips (bool) – If True (default), tooltips will be added to the map elements. Tooltips appear when hovering over an element.
add_popups (bool) – If True (default), popups will be added to the map elements. Popups appear when clicking on an element.
add_search (bool) – If True (default), a search bar will be added to the map to search for network elements by their ID.
fit_bounds (bool) – If True (default), the map view will be adjusted to fit all network elements. If False, the initial view is determined by the location and zoom_start parameters in map_kws.

Returns:

The folium.Map object with the network plot.

Return type:

folium.Map

voltage_profile(network, *, mode, starting_bus_id=None, traverse_transformers=False, switch_length=None, distance_unit='km')¶

Create a voltage profile of the network.

A voltage profile shows the voltage (in %) of buses in the network as a function of distance from a starting bus. Lines and transformers are also represented, colored according to their loading levels.

The network does not need to have geometries defined for this function to work, as distances are calculated based on line lengths. However, the network must have valid load flow results, and relevant buses must have nominal voltages defined.

Parameters:

network (ElectricalNetwork) – The electrical network to create the voltage profile for.
mode (Literal['min', 'max']) – The aggregation mode to use for bus voltages plots. “min” for the minimum voltage of buses’ phases, “max” for the maximum.
starting_bus_id (Id | None) – The ID of the bus to start the profile from. If None, the bus of the source with the highest voltage is used.
traverse_transformers (bool) – If True, the entire network is traversed including transformers. If False, transformers are not traversed.
switch_length (float | None) – The length in km to assign to switches when calculating distances. If None, it is set to the minimum of 2 meters and the shortest line in the network. Must be non-negative.
distance_unit (str) – The unit to use for distances in the profile. Defaults to “km”.

Returns:

An object containing the voltage profile data for plotting. Use its plotting methods to create plots. E.g., rlf.plotting.voltage_profile(en).plot_matplotlib().

Return type:

_VoltageProfile[ElectricalNetwork, Literal[‘min’, ‘max’]]