flixOpt.results

This module contains the Results functionality of the flixOpt framework. It provides high level functions to analyze the results of a calculation. It leverages the plotting.py module to plot the results. The results can also be analyzed without this module, as the results are stored in a widely supported format.

Classes

CalculationResults

CalculationResults(calculation_name: str, folder: str)

Functions

to_dataframe

to_dataframe(label: str, variable_name: str = 'flow_rate', input_factor: Optional[Literal[1, -1]] = -1, output_factor: Optional[Literal[1, -1]] = 1, threshold: Optional[float] = 1e-05, with_last_time_step: bool = True) -> pd.DataFrame

Convert results of a specified element to a DataFrame.

Parameters:

Name	Type	Description	Default
label	str	The label of the element (Component, Bus, or Flow) to retrieve data for.	required
variable_name	str	The name of the variable to extract from the element's data.	'flow_rate'
input_factor	Optional[Literal[1, -1]]	Factor to apply to input values.	-1
output_factor	Optional[Literal[1, -1]]	Factor to apply to output values.	1
threshold	Optional[float]	Minimum absolute value for data inclusion in the DataFrame.	1e-5
with_last_time_step	bool	Whether to include the last time step in the DataFrame index.	True

Returns:

Type	Description
DataFrame	A DataFrame containing the specified variable's data with a datetime index. Dataframe is empty (no index), if no values are left after filtering.

Raises:

Type	Description
ValueError	If no data is found for the specified variable.

plot_operation

plot_operation(label: str, mode: Literal['bar', 'line', 'area', 'heatmap'] = 'area', variable_name: str = 'flow_rate', heatmap_periods: Literal['YS', 'MS', 'W', 'D', 'h', '15min', 'min'] = 'D', heatmap_steps_per_period: Literal['W', 'D', 'h', '15min', 'min'] = 'h', colors: Union[str, List[str]] = 'viridis', engine: Literal['plotly', 'matplotlib'] = 'plotly', invert: bool = True, show: bool = True, save: bool = False, path: Union[str, Path, Literal['auto']] = 'auto') -> Union[go.Figure, Tuple[plt.Figure, plt.Axes]]

Plots the operation results for a specified Element using the chosen plotting engine and mode.

Parameters:

Name	Type	Description	Default
label	str	The label of the element to plot (e.g., a component or bus).	required
mode	(bar, line, area, heatmap)	The type of plot to generate.	'bar'
variable_name	str	The variable to plot from the element's data.	'flow_rate'
heatmap_periods	(YS, MS, W, D, h, '15min', min)	The period for heatmap plotting.	'YS'
heatmap_steps_per_period	(W, D, h, '15min', min)	The steps per period for heatmap plotting.	'W'
colors	str or List[str]	The colors or colorscale to use for the plot.	'viridis'
engine	(plotly, matplotlib)	The plotting engine to use.	'plotly'
invert	bool	Whether to invert the input and output factors.	False
show	bool	Whether to display the plot immediately. (This includes saving the plot to file when engine='plotly')	True
save	bool	Whether to save the plot to a file.	False
path	Union[str, Path, Literal['auto']]	The path to save the plot to. If 'auto', the plot is saved to an automatically named file.	'auto'

Returns:

Type	Description
Union[Figure, Tuple[Figure, Axes]]	The generated plot object, either a Plotly figure or a Matplotlib figure and axes.

Raises:

Type	Description
ValueError	If an invalid engine or color configuration is provided for heatmap mode.

plot_storage

plot_storage(label: str, variable_name: str = 'flow_rate', mode: Literal['bar', 'line', 'area'] = 'area', colors: Union[str, List[str]] = 'viridis', invert: bool = True, show: bool = True, save: bool = False, path: Union[str, Path, Literal['auto']] = 'auto')

Plots the storage operation results for a specified Storage Element, including its charge state.

Parameters:

Name	Type	Description	Default
label	str	The label of the Storage to plot	required
variable_name	str	The variable to plot from the element's data.	'flow_rate'
mode	(bar, line, area)	The type of plot to generate.	'bar'
colors	str or List[str]	The colors or colorscale to use for the plot.	'viridis'
invert	bool	Whether to invert the input and output factors.	True
show	bool	Whether to display the plot immediately. (This includes saving the plot to file when engine='plotly')	True
save	bool	Whether to save the plot to a file.	False
path	Union[str, Path, Literal['auto']]	The path to save the plot to. If 'auto', the plot is saved to an automatically named file.	'auto'

Returns:

Type	Description
Figure	The generated Plotly figure object with the storage operation plot.

visualize_network

visualize_network(path: Union[bool, str, Path] = 'results/network.html', controls: Union[bool, List[Literal['nodes', 'edges', 'layout', 'interaction', 'manipulation', 'physics', 'selection', 'renderer']]] = True, show: bool = True) -> Optional[pyvis.network.Network]

Visualizes the network structure of a FlowSystem using PyVis, saving it as an interactive HTML file.

Parameters:

Name	Type	Description	Default
path	Union[bool, str, Path]	Path to save the HTML visualization. If False, the visualization is created but not saved.	'results/network.html'
controls	Union[bool, List[str]]	UI controls to add to the visualization. True enables all available controls, or specify a list of controls.	True
show	bool	Whether to open the visualization in the web browser.	True

Returns:

Type	Description
Optional[Network]	The Network instance representing the visualization, or None if pyvis is not installed.

Notes

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

Functions

extract_single_result

extract_single_result(results_data: dict[str, Dict[str, Union[int, float, ndarray, dict]]], keys: List[str]) -> Optional[Union[int, float, np.ndarray]]

Goes through a nested dictionary with the given keys. Returns the value if found. Else returns None

extract_results

extract_results(results_data: dict[str, Dict[str, Union[int, float, ndarray, dict]]], keys: List[str], keep_none: bool = False) -> Dict[str, Union[int, float, np.ndarray]]

For each item in a dictionary, goes through its sub dictionaries. Returns the value if found. Else returns None. If specified, removes all None values

flatten_dict

flatten_dict(d, parent_key='', sep='__')

Recursively flattens a nested dictionary.

Parameters: d (dict): The dictionary to flatten. parent_key (str): The base key for the current recursion level. sep (str): The separator to use when concatenating keys.

Returns: dict: A flattened dictionary.