Mapping

For this module, you need to have the optional dependency pyflow-acdc[mapping] installed.

Interactive map

plot_folium(grid, mode='auto', **kwargs)[source]

Choose the folium helper using the same run flags as Grid.reset_run_flags.

mode: ‘auto’ | ‘network’ | ‘ts’ | ‘inv’

  • auto — grid.folium_mode if set to a concrete mode; else prefer a TS loading animation if Time_series_ran and line_loading exist; else an investment timeline map if a MP/Seq results table exists and any of TEP_run, MP_TEP_run, MP_MS_TEP_run, Seq_STEP_run, Seq_MS_STEP_run is true; else static plot_folium_network.

Extra keyword arguments are forwarded to the selected function.

Examples

Animated power flows on a solved grid:

>>> import pyflow_acdc as pyf
>>> grid, res = pyf.cases["NS_MTDC"]()
>>> pyf.optimal_pf(grid)
>>> pyf.plot_folium(grid, ant_path="All", show=False)

Network map (static topology)

plot_folium_network(grid, text='data', name=None, tiles='CartoDB Positron', polygon=None, linestrings=None, ant_path='None', clustering=True, coloring=None, show=True, planar=False, scale_gen=False, base_icon_size=24, plot_load=True, show_all=False, add_marine_regions_wms=False, line_size_factor=1.0)[source]

Create an interactive map visualization using Folium.

Parameters:

  • grid (Grid) – Grid to visualize.

  • text (str, optional) – Hover text format ('data', 'inPu', or 'abs').

  • name (str, optional) – Output file name. Defaults to grid.name.

  • tiles (str, optional) – "OpenStreetMap", "CartoDB Positron", "Cartodb dark_matter", or None.

  • polygon (shapely geometry or list, optional) – Development-area polygon(s) to draw on the map.

  • linestrings (list, optional) – Export-cable linestrings to draw on the map.

  • ant_path (str, optional) – Animated power-flow paths: 'All' (lines above 110 kV), 'Reduced' (HVDC only), or 'None'.

  • clustering (bool, optional) – Enable marker clustering for generators.

  • coloring (str, optional) – Line coloring mode (e.g. 'loss', 'loading', 'ts_max_loading').

  • show (bool, optional) – Open the map in a browser.

  • planar (bool, optional) – Use planar coordinates instead of lon/lat.

  • scale_gen (bool, optional) – Scale generator icons by rating.

  • base_icon_size (int, optional) – Base marker size for generator icons.

  • plot_load (bool, optional) – Plot load nodes on the map.

  • show_all (bool, optional) – Show all components regardless of voltage filters.

  • add_marine_regions_wms (bool, optional) – Add marine-regions WMS overlay.

  • line_size_factor (float, optional) – Scale factor for line thickness.

Notes

The map supports zoom/pan, voltage-level filtering, and component layers for MVAC lines (<110 kV), HVAC lines (<300 kV), EHV lines (<500 kV), UHV lines, DC lines, converters, transformers, and generators by type. Hover information is shown for components. Optional animated power flows are controlled by ant_path.

Examples

>>> import pyflow_acdc as pyf
>>> grid, res = pyf.cases["NS_MTDC"]()
>>> pyf.optimal_pf(grid)
>>> pyf.plot_folium_network(grid, show=False)
Example of the Folium map.
Example of the Folium map.

Time-series and investment maps (under development)

These helpers read solved results already stored on the Grid and build animated Folium maps. The API may change in future releases.

plot_folium_ts_results(grid, name=None, tiles='CartoDB Positron', start=None, end=None, show=True, min_weight=1.5, max_weight=8.0, add_legend=True, legend_position='topright', line_size_factor=1.0)[source]

Build an animated Folium map of line loading from TS-OPF results.

Requires grid.time_series_results['ac_loading'] and/or ['dc_loading'] (populated by ts_acdc_opf()). API under active development.

Line-loading animation from grid.time_series_results (after ts_acdc_opf() or run_ts_opf_for_investment_period()).

plot_folium_inv_results(grid, name=None, source='auto', tiles='CartoDB Positron', planar=False, show=True, min_weight=1.5, max_weight=8.0, show_installed=True, show_decommissioned=True, inv_dropdown_period=False, line_size_factor=1.0)[source]

Build a Folium map of expansion/decommission decisions by investment period.

Reads grid.MP_TEP_results, grid.Seq_STEP_results, or grid.Seq_MS_STEP_results depending on source. API under active development.

Expansion/decommission overlay from grid.MP_TEP_results, grid.Seq_STEP_results, or grid.Seq_MS_STEP_results (source="auto" picks the first non-empty table).