exerpy.visualization¶

The visualization module turns the results of an exergy analysis into diagrams. It requires the optional dependencies of the viz extra:

pip install exerpy[viz]

Sankey¶

Sankey diagram builder for exergy analysis results.

class exerpy.visualization.sankey.SankeyBuilder(analysis: ExergyAnalysis, mode: int = 1, collapse_passthroughs: bool | list[str] = True, groups: dict[str, list[str]] | None = None, node_colors: dict[str, str] | None = None)[source]¶

Bases: object

Builds a Plotly Sankey diagram from a completed ExergyAnalysis result.

Parameters:

analysis (ExergyAnalysis) – Must have had .analyse() called.
mode ({1, 2, 3}) – 1 – total exergy E per link 2 – split material links into E_PH + E_CH (requires chemical_exergy_enabled) 3 – split material links into E_T + E_M + E_CH (requires split_physical_exergy)
collapse_passthroughs (bool or list[str]) – True → collapse CycleCloser nodes (default) False → show every node list → collapse only the listed component type names
groups (dict[str, list[str]], optional) – Visual grouping: {"Group name": ["comp1", "comp2", ...]}. Internal connections are hidden; only boundary-crossing links are shown.

build() → tuple[list[dict], list[dict]][source]¶: Build and return (nodes, links) lists.

to_html(path: str, title: str | None = None) → None[source]¶: Export the Sankey diagram to an HTML file.

to_plotly(title: str | None = None)[source]¶: Return a Plotly Figure containing the Sankey trace.

Waterfall¶

Exergy destruction waterfall diagram.

exerpy.visualization.waterfall.plot_exergy_waterfall(analysis: ExergyAnalysis, title: str | None = None, figsize: tuple[float, float] = (12, 10), exclude_components: list[str] | None = None, colors: dict[str, str] | None = None, show_plot: bool = True)[source]¶

Create an exergy destruction waterfall diagram using Matplotlib.

Visualizes exergy flow through the system as a waterfall chart, showing how exergy is destroyed in each component from the exergetic fuel (100%) down to the exergetic product and losses.

Parameters:

analysis (ExergyAnalysis) – Completed analysis instance (analyse() must be called first).
title (str, optional) – Title for the plot. If None, no title is displayed.
figsize (tuple, optional) – Figure size as (width, height) in inches. Default is (12, 10).
exclude_components (list, optional) – List of component names to exclude from the diagram. By default, all components with NaN E_F (Exergetic Fuel) are excluded, as well as CycleCloser and PowerBus components.
colors (dict, optional) – Override bar colors. Keys: “fuel”, “destruction”, “loss”, “product”. Defaults are taken from exerpy.visualization.colors.WATERFALL_COLORS.
show_plot (bool, optional) – Whether to display the plot immediately. Default is True.

Returns:

fig (matplotlib.figure.Figure) – The figure object containing the waterfall diagram.
ax (matplotlib.axes.Axes) – The axes object of the waterfall diagram.

Raises:

RuntimeError – If the exergy analysis has not been performed yet (analyse() not called).

Notes

The waterfall diagram displays exergy values as percentages of the total fuel exergy.
Components are sorted by their exergy destruction rate (y [%]) in descending order.
Each bar represents the remaining exergy after destruction in that component.
Red bars indicate exergy destruction in components.
Blue bar represents the initial exergetic fuel (100%).
Green bar represents the final exergetic product.

Examples

>>> analysis = ExergyAnalysis.from_tespy(network, Tamb=288.15, pamb=101325)
>>> analysis.analyse(E_F={'inputs': ['fuel']}, E_P={'outputs': ['power']})
>>> fig, ax = analysis.plot_exergy_waterfall(title='Power Plant Exergy Waterfall')
>>> fig.savefig('exergy_waterfall.pdf')

See also

exergy_results: Display tabular exergy analysis results.
print_exergy_summary: Print a text summary of exergy analysis.
plot_exergy_waterfall_plotly: Plotly version of this diagram.

exerpy.visualization.waterfall.plot_exergy_waterfall_plotly(analysis: ExergyAnalysis, title: str | None = None, exclude_components: list[str] | None = None, colors: dict[str, str] | None = None, show_plot: bool = True)[source]¶

Create an exergy destruction waterfall diagram using Plotly.

Interactive version of the waterfall chart. Components are sorted by their exergy destruction rate (y [%]) in descending order.

Parameters:

analysis (ExergyAnalysis) – Completed analysis instance (analyse() must be called first).
title (str, optional) – Title for the plot. If None, a default title is used.
exclude_components (list, optional) – List of component names to exclude from the diagram. By default, all components with NaN E_F (Exergetic Fuel) are excluded, as well as CycleCloser and PowerBus components.
colors (dict, optional) – Override bar colors. Keys: “fuel”, “destruction”, “loss”, “product”. Defaults are taken from exerpy.visualization.colors.WATERFALL_COLORS.
show_plot (bool, optional) – Whether to display the plot immediately. Default is True.

Returns:

fig (plotly.graph_objects.Figure)

Raises:

RuntimeError – If the exergy analysis has not been performed yet (analyse() not called).

Examples

>>> analysis = ExergyAnalysis.from_tespy(network, Tamb=288.15, pamb=101325)
>>> analysis.analyse(E_F={'inputs': ['fuel']}, E_P={'outputs': ['power']})
>>> fig = analysis.plot_exergy_waterfall_plotly(title='Power Plant Exergy Waterfall')
>>> fig.write_html('waterfall.html')

Colors¶

Color utilities for Sankey visualization.

exerpy.visualization.colors.connection_base_color(conn_data: dict) → str[source]¶

exerpy.visualization.colors.fluid_base_color(mass_composition: dict) → str[source]¶

exerpy.visualization.colors.hex_to_rgba(hex_color: str, alpha: float = 0.6) → str[source]¶

exerpy.visualization.colors.pale(color: str, alpha: float = 0.25) → str[source]¶: Return the color at a lower opacity, keeping the identity of the stream.

exerpy.visualization.colors.shade(hex_color: str, factor: float) → str[source]¶: Scale RGB channels by factor (< 1 darkens, > 1 lightens, clamped to 0-255).