Skip to content

flixopt.topology_accessor

Topology accessor for FlowSystem.

This module provides the TopologyAccessor class that enables the flow_system.topology pattern for network structure inspection and visualization.

Attributes

Classes

TopologyAccessor 

TopologyAccessor(flow_system: FlowSystem)

Accessor for network topology inspection and visualization on FlowSystem.

This class provides the topology API for FlowSystem, accessible via flow_system.topology. It offers methods to inspect the network structure and visualize it.

Examples:

Visualize the network:

>>> flow_system.topology.plot()
>>> flow_system.topology.plot(path='my_network.html', show=True)

Interactive visualization:

>>> flow_system.topology.start_app()
>>> # ... interact with the visualization ...
>>> flow_system.topology.stop_app()

Get network structure info:

>>> nodes, edges = flow_system.topology.infos()

Initialize the accessor with a reference to the FlowSystem.

Parameters:

Name Type Description Default
flow_system FlowSystem

The FlowSystem to inspect.

 required

Attributes

carrier_colors property 
carrier_colors: dict[str, str]

Cached mapping of carrier name to hex color.

Returns:

Type Description
dict[str, str]

Dict mapping carrier names (lowercase) to hex color strings.
dict[str, str]

Only carriers with a color defined are included.

Examples:

>>> fs.topology.carrier_colors
{'electricity': '#FECB52', 'heat': '#D62728', 'gas': '#1F77B4'}
component_colors property 
component_colors: dict[str, str]

Cached mapping of component label to hex color.

Returns:

Type Description
dict[str, str]

Dict mapping component labels to hex color strings.
dict[str, str]

Only components with a color defined are included.

Examples:

>>> fs.topology.component_colors
{'Boiler': '#1f77b4', 'CHP': '#ff7f0e', 'HeatPump': '#2ca02c'}
bus_colors property 
bus_colors: dict[str, str]

Cached mapping of bus label to hex color (from carrier).

Bus colors are derived from their associated carrier's color.

Returns:

Type Description
dict[str, str]

Dict mapping bus labels to hex color strings.
dict[str, str]

Only buses with a carrier that has a color defined are included.

Examples:

>>> fs.topology.bus_colors
{'ElectricityBus': '#FECB52', 'HeatBus': '#D62728'}
carrier_units property 
carrier_units: dict[str, str]

Cached mapping of carrier name to unit string.

Returns:

Type Description
dict[str, str]

Dict mapping carrier names (lowercase) to unit strings.
dict[str, str]

Carriers without a unit defined return an empty string.

Examples:

>>> fs.topology.carrier_units
{'electricity': 'kW', 'heat': 'kW', 'gas': 'kW'}
effect_units property 
effect_units: dict[str, str]

Cached mapping of effect label to unit string.

Returns:

Type Description
dict[str, str]

Dict mapping effect labels to unit strings.
dict[str, str]

Effects without a unit defined return an empty string.

Examples:

>>> fs.topology.effect_units
{'costs': '€', 'CO2': 'kg'}

Functions

infos 
infos() -> tuple[dict[str, dict[str, str]], dict[str, dict[str, str]]]

Get network topology information as dictionaries.

Returns node and edge information suitable for visualization or analysis.

Returns:

Type Description
tuple[dict[str, dict[str, str]], dict[str, dict[str, str]]]

Tuple of (nodes_dict, edges_dict) where: - nodes_dict maps node labels to their properties (label, class, infos) - edges_dict maps edge labels to their properties (label, start, end, infos)

Examples:

>>> nodes, edges = flow_system.topology.infos()
>>> print(nodes.keys())  # All component and bus labels
>>> print(edges.keys())  # All flow labels
plot 
plot(colors: ColorType | None = None, show: bool | None = None, **plotly_kwargs: Any) -> PlotResult

Visualize the network structure as a Sankey diagram using Plotly.

Creates a Sankey diagram showing the topology of the flow system, with buses and components as nodes, and flows as links between them. All links have equal width since no solution data is used.

Parameters:

Name Type Description Default
colors ColorType | None

Color specification for nodes (buses). - None: Uses default color palette based on buses. - str: Plotly colorscale name (e.g., 'Viridis', 'Blues'). - list: List of colors to cycle through. - dict: Maps bus labels to specific colors. Links inherit colors from their connected bus.

 None
show bool | None

Whether to display the figure in the browser. - None: Uses default from CONFIG.Plotting.default_show.

 None
**plotly_kwargs Any

Additional arguments passed to Plotly layout.

 {}

Returns:

Type Description
PlotResult

PlotResult containing the Sankey diagram figure and topology data
PlotResult

(source, target, value for each link).

Examples:

>>> flow_system.topology.plot()
>>> flow_system.topology.plot(show=True)
>>> flow_system.topology.plot(colors='Viridis')
>>> flow_system.topology.plot(colors={'ElectricityBus': 'gold', 'HeatBus': 'red'})
Notes

This visualization shows the network structure without optimization results. For visualizations that include flow values, use flow_system.statistics.plot.sankey.flows() after running an optimization.

Hover over nodes and links to see detailed element information.

See Also
  • plot_legacy(): Previous PyVis-based network visualization.
  • statistics.plot.sankey.flows(): Sankey with actual flow values from optimization.
plot_legacy 
plot_legacy(path: bool | str | Path = 'flow_system.html', controls: bool | list[Literal['nodes', 'edges', 'layout', 'interaction', 'manipulation', 'physics', 'selection', 'renderer']] = True, show: bool | None = None) -> pyvis.network.Network | None

Visualize the network structure using PyVis, saving it as an interactive HTML file.

.. deprecated:: Use plot() instead for the new Plotly-based Sankey visualization. This method is kept for backwards compatibility.

Parameters:

Name Type Description Default
path bool | str | Path

Path to save the HTML visualization. - False: Visualization is created but not saved. - str or Path: Specifies file path (default: 'flow_system.html').

 'flow_system.html'
controls bool | list[Literal['nodes', 'edges', 'layout', 'interaction', 'manipulation', 'physics', 'selection', 'renderer']]

UI controls to add to the visualization. - True: Enables all available controls. - List: Specify controls, e.g., ['nodes', 'layout']. - Options: 'nodes', 'edges', 'layout', 'interaction', 'manipulation', 'physics', 'selection', 'renderer'.

 True
show bool | None

Whether to open the visualization in the web browser.

 None

Returns:

Type Description
Network | None

The pyvis.network.Network instance representing the visualization,
Network | None

or None if pyvis is not installed.

Examples:

>>> flow_system.topology.plot_legacy()
>>> flow_system.topology.plot_legacy(show=False)
>>> flow_system.topology.plot_legacy(path='output/network.html', controls=['nodes', 'layout'])
Notes

This function requires pyvis. If not installed, the function prints a warning and returns None. Nodes are styled based on type (circles for buses, boxes for components) and annotated with node information.

start_app 
start_app() -> None

Start an interactive network visualization using Dash and Cytoscape.

Launches a web-based interactive visualization server that allows exploring the network structure dynamically.

Raises:

Type Description
ImportError

If required dependencies are not installed.

Examples:

>>> flow_system.topology.start_app()
>>> # ... interact with the visualization in browser ...
>>> flow_system.topology.stop_app()
Notes

Requires optional dependencies: dash, dash-cytoscape, dash-daq, networkx, flask, werkzeug. Install with: pip install flixopt[network_viz] or pip install flixopt[full]

stop_app 
stop_app() -> None

Stop the interactive network visualization server.

Examples:

>>> flow_system.topology.stop_app()

Functions