roseau.load_flow.plotting

Plotting functions for roseau.load_flow.

Functions

plot_voltage_phasors(→ matplotlib.axes.Axes)

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

plot_symmetrical_voltages(→ tuple[Axes, Axes, Axes])

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

plot_interactive_map(→ folium.Map)

Plot an electrical network on an interactive map.

plot_results_interactive_map(→ folium.Map)

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

voltage_profile(...)

Create a voltage profile of the network.

Module Contents

plot_voltage_phasors(element: AbstractTerminal, *, voltage_type: Literal['pp', 'pn', 'auto'] = 'auto', ax: Axes | None = None) → Axes

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

Parameters:

  • element – The bus, load, source, branch side whose voltages to plot.

  • voltage_type –

    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 – The axes to plot on. If None, the currently active axes object is used.

Returns:

The axes with the plot.

plot_symmetrical_voltages(element: AbstractTerminal, *, axes: Iterable[Axes] | None = None) → tuple[Axes, Axes, Axes]

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

Parameters:

  • element – The bus, load, source, branch side whose voltages to plot. The element must have 'abc' or 'abcn' phases.

  • axes – 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.

plot_interactive_map(network: ElectricalNetwork, *, style_color: str = '#234e83', highlight_color: str = '#cad40e', style_function: Callable[[FeatureMap], StyleDict | None] | None = None, highlight_function: Callable[[FeatureMap], StyleDict | None] | None = None, map_kws: Mapping[str, Any] | None = None, add_tooltips: bool = True, add_popups: bool = True, add_search: bool = True, fit_bounds: bool = True) → folium.Map

Plot an electrical network on an interactive map.

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

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.

Parameters:

  • network – The electrical network to plot. Buses, lines and transformers are plotted. Buses of source elements are represented with bigger square markers.

  • style_color – The color of the default style of an element. Defaults to ■ #234e83.

  • highlight_color – The color of the default style when an element is highlighted. Defaults to ■ #cad40e.

  • style_function – Function mapping a GeoJson Feature to a style dict. If not provided or when it returns None, the default style is used.

  • highlight_function – 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 – Additional keyword arguments to pass to the folium.Map constructor. By default, if fit_bounds is false, location is set to the centroid of the network geometry and zoom_start is calculated based on its bounding box.

  • add_tooltips – If True (default), tooltips will be added to the map elements. Tooltips appear when hovering over an element.

  • add_popups – If True (default), popups will be added to the map elements. Popups appear when clicking on an element.

  • add_search – If True (default), a search bar will be added to the map to search for network elements by their ID.

  • fit_bounds – 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.

plot_results_interactive_map(network: ElectricalNetwork, *, style_color: str = '#234e83', highlight_color: str = '#cad40e', style_function: Callable[[FeatureMap], StyleDict | None] | None = None, highlight_function: Callable[[FeatureMap], StyleDict | None] | None = None, map_kws: Mapping[str, Any] | None = None, add_tooltips: bool = True, add_popups: bool = True, add_search: bool = True, fit_bounds: bool = True) → folium.Map

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 – The electrical network to plot. Buses, lines and transformers are plotted. Buses of source elements are represented with bigger square markers.

  • style_color – The color of the default style of an element. Defaults to ■ #234e83.

  • highlight_color – The color of the default style when an element is highlighted. Defaults to ■ #cad40e.

  • style_function –

    Function mapping a GeoJson Feature to a style dict. If not provided or when it returns None, the default style is used. The default style colors of buses depend on 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

    The default style colors of lines and transformers depend 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

  • highlight_function – 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 – Additional keyword arguments to pass to the folium.Map constructor. By default, if fit_bounds is false, location is set to the centroid of the network geometry and zoom_start is calculated based on its bounding box.

  • add_tooltips – If True (default), tooltips will be added to the map elements. Tooltips appear when hovering over an element.

  • add_popups – If True (default), popups will be added to the map elements. Popups appear when clicking on an element.

  • add_search – If True (default), a search bar will be added to the map to search for network elements by their ID.

  • fit_bounds – 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.

voltage_profile(network: ElectricalNetwork, *, mode: Literal['min', 'max'], starting_bus_id: Id | None = None, traverse_transformers: bool = False, switch_length: float | None = None, distance_unit: str = 'km') → _VoltageProfile[ElectricalNetwork, Literal['min', 'max']]

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 – The electrical network to create the voltage profile for.

  • mode – The aggregation mode to use for bus voltages plots. “min” for the minimum voltage of buses’ phases, “max” for the maximum.

  • starting_bus_id – 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 – If True, the entire network is traversed including transformers. If False, transformers are not traversed.

  • switch_length – 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 – 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().