flixopt 2.2.0b0__py3-none-any.whl → 3.0.0__py3-none-any.whl

flixopt/results.py

@@ -1,12 +1,13 @@
+from __future__ import annotations
+
 import datetime
 import json
 import logging
 import pathlib
 import warnings
-from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional, Tuple, Union
+from typing import TYPE_CHECKING, Any, Literal
 
 import linopy
-import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
 import plotly
@@ -15,13 +16,14 @@ import yaml
 
 from . import io as fx_io
 from . import plotting
-from .core import DataConverter, TimeSeriesCollection
 from .flow_system import FlowSystem
 
 if TYPE_CHECKING:
+    import matplotlib.pyplot as plt
     import pyvis
 
     from .calculation import Calculation, SegmentedCalculation
+    from .core import FlowSystemDimensions
 
 
 logger = logging.getLogger('flixopt')
@@ -29,59 +31,100 @@ logger = logging.getLogger('flixopt')
 
 class _FlowSystemRestorationError(Exception):
     """Exception raised when a FlowSystem cannot be restored from dataset."""
+
     pass
 
 
 class CalculationResults:
-    """Results container for Calculation results.
-
-    This class is used to collect the results of a Calculation.
-    It provides access to component, bus, and effect
-    results, and includes methods for filtering, plotting, and saving results.
-
-    The recommended way to create instances is through the class methods
-    `from_file()` or `from_calculation()`, rather than direct initialization.
+    """Comprehensive container for optimization calculation results and analysis tools.
+
+    This class provides unified access to all optimization results including flow rates,
+    component states, bus balances, and system effects. It offers powerful analysis
+    capabilities through filtering, plotting, and export functionality, making it
+    the primary interface for post-processing optimization results.
+
+    Key Features:
+        **Unified Access**: Single interface to all solution variables and constraints
+        **Element Results**: Direct access to component, bus, and effect-specific results
+        **Visualization**: Built-in plotting methods for heatmaps, time series, and networks
+        **Persistence**: Save/load functionality with compression for large datasets
+        **Analysis Tools**: Filtering, aggregation, and statistical analysis methods
+
+    Result Organization:
+        - **Components**: Equipment-specific results (flows, states, constraints)
+        - **Buses**: Network node balances and energy flows
+        - **Effects**: System-wide impacts (costs, emissions, resource consumption)
+        - **Solution**: Raw optimization variables and their values
+        - **Metadata**: Calculation parameters, timing, and system configuration
 
     Attributes:
-        solution (xr.Dataset): Dataset containing optimization results.
-        flow_system_data (xr.Dataset): Dataset containing the flow system.
-        summary (Dict): Information about the calculation.
-        name (str): Name identifier for the calculation.
-        model (linopy.Model): The optimization model (if available).
-        folder (pathlib.Path): Path to the results directory.
-        components (Dict[str, ComponentResults]): Results for each component.
-        buses (Dict[str, BusResults]): Results for each bus.
-        effects (Dict[str, EffectResults]): Results for each effect.
-        timesteps_extra (pd.DatetimeIndex): The extended timesteps.
-        hours_per_timestep (xr.DataArray): Duration of each timestep in hours.
-
-    Example:
-        Load results from saved files:
-
-        >>> results = CalculationResults.from_file('results_dir', 'optimization_run_1')
-        >>> element_result = results['Boiler']
-        >>> results.plot_heatmap('Boiler(Q_th)|flow_rate')
-        >>> results.to_file(compression=5)
-        >>> results.to_file(folder='new_results_dir', compression=5)  # Save the results to a new folder
+        solution: Dataset containing all optimization variable solutions
+        flow_system_data: Dataset with complete system configuration and parameters. Restore the used FlowSystem for further analysis.
+        summary: Calculation metadata including solver status, timing, and statistics
+        name: Unique identifier for this calculation
+        model: Original linopy optimization model (if available)
+        folder: Directory path for result storage and loading
+        components: Dictionary mapping component labels to ComponentResults objects
+        buses: Dictionary mapping bus labels to BusResults objects
+        effects: Dictionary mapping effect names to EffectResults objects
+        timesteps_extra: Extended time index including boundary conditions
+        hours_per_timestep: Duration of each timestep for proper energy calculations
+
+    Examples:
+        Load and analyze saved results:
+
+        ```python
+        # Load results from file
+        results = CalculationResults.from_file('results', 'annual_optimization')
+
+        # Access specific component results
+        boiler_results = results['Boiler_01']
+        heat_pump_results = results['HeatPump_02']
+
+        # Plot component flow rates
+        results.plot_heatmap('Boiler_01(Natural_Gas)|flow_rate')
+        results['Boiler_01'].plot_node_balance()
+
+        # Access raw solution dataarrays
+        electricity_flows = results.solution[['Generator_01(Grid)|flow_rate', 'HeatPump_02(Grid)|flow_rate']]
+
+        # Filter and analyze results
+        peak_demand_hours = results.filter_solution(variable_dims='time')
+        costs_solution = results.effects['cost'].solution
+        ```
+
+        Advanced filtering and aggregation:
+
+        ```python
+        # Filter by variable type
+        scalar_results = results.filter_solution(variable_dims='scalar')
+        time_series = results.filter_solution(variable_dims='time')
+
+        # Custom data analysis leveraging xarray
+        peak_power = results.solution['Generator_01(Grid)|flow_rate'].max()
+        avg_efficiency = (
+            results.solution['HeatPump(Heat)|flow_rate'] / results.solution['HeatPump(Electricity)|flow_rate']
+        ).mean()
+        ```
+
+    Design Patterns:
+        **Factory Methods**: Use `from_file()` and `from_calculation()` for creation or access directly from `Calculation.results`
+        **Dictionary Access**: Use `results[element_label]` for element-specific results
+        **Lazy Loading**: Results objects created on-demand for memory efficiency
+        **Unified Interface**: Consistent API across different result types
+
     """
 
     @classmethod
-    def from_file(cls, folder: Union[str, pathlib.Path], name: str):
-        """Create CalculationResults instance by loading from saved files.
-
-        This method loads the calculation results from previously saved files,
-        including the solution, flow system, model (if available), and metadata.
+    def from_file(cls, folder: str | pathlib.Path, name: str) -> CalculationResults:
+        """Load CalculationResults from saved files.
 
         Args:
-            folder: Path to the directory containing the saved files.
-            name: Base name of the saved files (without file extensions).
+            folder: Directory containing saved files.
+            name: Base name of saved files (without extensions).
 
         Returns:
-            CalculationResults: A new instance containing the loaded data.
-
-        Raises:
-            FileNotFoundError: If required files cannot be found.
-            ValueError: If files exist but cannot be properly loaded.
+            CalculationResults: Loaded instance.
         """
         folder = pathlib.Path(folder)
         paths = fx_io.CalculationResultsPaths(folder, name)
@@ -94,7 +137,7 @@ class CalculationResults:
             except Exception as e:
                 logger.critical(f'Could not load the linopy model "{name}" from file ("{paths.linopy_model}"): {e}')
 
-        with open(paths.summary, 'r', encoding='utf-8') as f:
+        with open(paths.summary, encoding='utf-8') as f:
             summary = yaml.load(f, Loader=yaml.FullLoader)
 
         return cls(
@@ -107,25 +150,18 @@ class CalculationResults:
         )
 
     @classmethod
-    def from_calculation(cls, calculation: 'Calculation'):
-        """Create CalculationResults directly from a Calculation object.
-
-        This method extracts the solution, flow system, and other relevant
-        information directly from an existing Calculation object.
+    def from_calculation(cls, calculation: Calculation) -> CalculationResults:
+        """Create CalculationResults from a Calculation object.
 
         Args:
-            calculation: A Calculation object containing a solved model.
+            calculation: Calculation object with solved model.
 
         Returns:
-            CalculationResults: A new instance containing the results from
-                the provided calculation.
-
-        Raises:
-            AttributeError: If the calculation doesn't have required attributes.
+            CalculationResults: New instance with extracted results.
         """
         return cls(
             solution=calculation.model.solution,
-            flow_system_data=calculation.flow_system.as_dataset(constants_in_dataset=True),
+            flow_system_data=calculation.flow_system.to_dataset(),
             summary=calculation.summary,
             model=calculation.model,
             name=calculation.name,
@@ -137,19 +173,21 @@ class CalculationResults:
         solution: xr.Dataset,
         flow_system_data: xr.Dataset,
         name: str,
-        summary: Dict,
-        folder: Optional[pathlib.Path] = None,
-        model: Optional[linopy.Model] = None,
+        summary: dict,
+        folder: pathlib.Path | None = None,
+        model: linopy.Model | None = None,
         **kwargs,  # To accept old "flow_system" parameter
     ):
-        """
+        """Initialize CalculationResults with optimization data.
+        Usually, this class is instantiated by the Calculation class, or by loading from file.
+
         Args:
-            solution: The solution of the optimization.
-            flow_system_data: The flow_system that was used to create the calculation as a datatset.
-            name: The name of the calculation.
-            summary: Information about the calculation,
-            folder: The folder where the results are saved.
-            model: The linopy model that was used to solve the calculation.
+            solution: Optimization solution dataset.
+            flow_system_data: Flow system configuration dataset.
+            name: Calculation name.
+            summary: Calculation metadata.
+            folder: Results storage folder.
+            model: Linopy optimization model.
         Deprecated:
             flow_system: Use flow_system_data instead.
         """
@@ -175,15 +213,13 @@ class CalculationResults:
 
         self.buses = {label: BusResults(self, **infos) for label, infos in self.solution.attrs['Buses'].items()}
 
-        self.effects = {
-            label: EffectResults(self, **infos) for label, infos in self.solution.attrs['Effects'].items()
-        }
+        self.effects = {label: EffectResults(self, **infos) for label, infos in self.solution.attrs['Effects'].items()}
 
         if 'Flows' not in self.solution.attrs:
             warnings.warn(
                 'No Data about flows found in the results. This data is only included since v2.2.0. Some functionality '
                 'is not availlable. We recommend to evaluate your results with a version <2.2.0.',
-            stacklevel=2,
+                stacklevel=2,
             )
             self.flows = {}
         else:
@@ -192,7 +228,7 @@ class CalculationResults:
             }
 
         self.timesteps_extra = self.solution.indexes['time']
-        self.hours_per_timestep = TimeSeriesCollection.calculate_hours_per_timestep(self.timesteps_extra)
+        self.hours_per_timestep = FlowSystem.calculate_hours_per_timestep(self.timesteps_extra)
         self.scenarios = self.solution.indexes['scenario'] if 'scenario' in self.solution.indexes else None
 
         self._effect_share_factors = None
@@ -201,10 +237,9 @@ class CalculationResults:
         self._flow_rates = None
         self._flow_hours = None
         self._sizes = None
-        self._effects_per_component = {'operation': None, 'invest': None, 'total': None}
-        self._flow_network_info_ = None
+        self._effects_per_component = None
 
-    def __getitem__(self, key: str) -> Union['ComponentResults', 'BusResults', 'EffectResults', 'FlowResults']:
+    def __getitem__(self, key: str) -> ComponentResults | BusResults | EffectResults:
         if key in self.components:
             return self.components[key]
         if key in self.buses:
@@ -216,25 +251,30 @@ class CalculationResults:
         raise KeyError(f'No element with label {key} found.')
 
     @property
-    def storages(self) -> List['ComponentResults']:
-        """All storages in the results."""
+    def storages(self) -> list[ComponentResults]:
+        """Get all storage components in the results."""
         return [comp for comp in self.components.values() if comp.is_storage]
 
     @property
     def objective(self) -> float:
-        """The objective result of the optimization."""
-        return self.summary['Main Results']['Objective']
+        """Get optimization objective value."""
+        # Deprecated. Fallback
+        if 'objective' not in self.solution:
+            logger.warning('Objective not found in solution. Fallback to summary (rounded value). This is deprecated')
+            return self.summary['Main Results']['Objective']
+
+        return self.solution['objective'].item()
 
     @property
     def variables(self) -> linopy.Variables:
-        """The variables of the optimization. Only available if the linopy.Model is available."""
+        """Get optimization variables (requires linopy model)."""
         if self.model is None:
             raise ValueError('The linopy model is not available.')
         return self.model.variables
 
     @property
     def constraints(self) -> linopy.Constraints:
-        """The constraints of the optimization. Only available if the linopy.Model is available."""
+        """Get optimization constraints (requires linopy model)."""
         if self.model is None:
             raise ValueError('The linopy model is not available.')
         return self.model.constraints
@@ -243,39 +283,38 @@ class CalculationResults:
     def effect_share_factors(self):
         if self._effect_share_factors is None:
             effect_share_factors = self.flow_system.effects.calculate_effect_share_factors()
-            self._effect_share_factors = {'operation': effect_share_factors[0],
-                                          'invest': effect_share_factors[1]}
+            self._effect_share_factors = {'temporal': effect_share_factors[0], 'periodic': effect_share_factors[1]}
         return self._effect_share_factors
 
     @property
-    def flow_system(self) -> 'FlowSystem':
-        """ The restored flow_system that was used to create the calculation.
+    def flow_system(self) -> FlowSystem:
+        """The restored flow_system that was used to create the calculation.
         Contains all input parameters."""
         if self._flow_system is None:
+            old_level = logger.level
+            logger.level = logging.CRITICAL
             try:
-                from . import FlowSystem
-                current_logger_level = logger.getEffectiveLevel()
-                logger.setLevel(logging.CRITICAL)
                 self._flow_system = FlowSystem.from_dataset(self.flow_system_data)
                 self._flow_system._connect_network()
-                logger.setLevel(current_logger_level)
             except Exception as e:
-                logger.critical(f'Not able to restore FlowSystem from dataset. Some functionality is not availlable. {e}')
+                logger.critical(
+                    f'Not able to restore FlowSystem from dataset. Some functionality is not availlable. {e}'
+                )
                 raise _FlowSystemRestorationError(f'Not able to restore FlowSystem from dataset. {e}') from e
+            finally:
+                logger.level = old_level
         return self._flow_system
 
     def filter_solution(
         self,
-        variable_dims: Optional[Literal['scalar', 'time', 'scenario', 'timeonly', 'scenarioonly']] = None,
-        element: Optional[str] = None,
-        timesteps: Optional[pd.DatetimeIndex] = None,
-        scenarios: Optional[pd.Index] = None,
-        contains: Optional[Union[str, List[str]]] = None,
-        startswith: Optional[Union[str, List[str]]] = None,
+        variable_dims: Literal['scalar', 'time', 'scenario', 'timeonly', 'scenarioonly'] | None = None,
+        element: str | None = None,
+        timesteps: pd.DatetimeIndex | None = None,
+        scenarios: pd.Index | None = None,
+        contains: str | list[str] | None = None,
+        startswith: str | list[str] | None = None,
     ) -> xr.Dataset:
-        """
-        Filter the solution to a specific variable dimension and element.
-        If no element is specified, all elements are included.
+        """Filter solution by variable dimension and/or element.
 
         Args:
             variable_dims: The dimension of which to get variables from.
@@ -307,26 +346,30 @@ class CalculationResults:
             startswith=startswith,
         )
 
-    def effects_per_component(self, mode: Literal['operation', 'invest', 'total'] = 'total') -> xr.Dataset:
-        """Returns a dataset containing effect totals for each components (including their flows).
-
-        Args:
-            mode: Which effects to contain. (operation, invest, total)
+    @property
+    def effects_per_component(self) -> xr.Dataset:
+        """Returns a dataset containing effect results for each mode, aggregated by Component
 
         Returns:
             An xarray Dataset with an additional component dimension and effects as variables.
         """
-        if mode not in ['operation', 'invest', 'total']:
-            raise ValueError(f'Invalid mode {mode}')
-        if self._effects_per_component[mode] is None:
-            self._effects_per_component[mode] = self._create_effects_dataset(mode)
-        return self._effects_per_component[mode]
+        if self._effects_per_component is None:
+            self._effects_per_component = xr.Dataset(
+                {
+                    mode: self._create_effects_dataset(mode).to_dataarray('effect', name=mode)
+                    for mode in ['temporal', 'periodic', 'total']
+                }
+            )
+            dim_order = ['time', 'period', 'scenario', 'component', 'effect']
+            self._effects_per_component = self._effects_per_component.transpose(*dim_order, missing_dims='ignore')
+
+        return self._effects_per_component
 
     def flow_rates(
         self,
-        start: Optional[Union[str, List[str]]] = None,
-        end: Optional[Union[str, List[str]]] = None,
-        component: Optional[Union[str, List[str]]] = None,
+        start: str | list[str] | None = None,
+        end: str | list[str] | None = None,
+        component: str | list[str] | None = None,
     ) -> xr.DataArray:
         """Returns a DataArray containing the flow rates of each Flow.
 
@@ -347,17 +390,19 @@ class CalculationResults:
         """
         if self._flow_rates is None:
             self._flow_rates = self._assign_flow_coords(
-                xr.concat([flow.flow_rate.rename(flow.label) for flow in self.flows.values()],
-                          dim=pd.Index(self.flows.keys(), name='flow'))
+                xr.concat(
+                    [flow.flow_rate.rename(flow.label) for flow in self.flows.values()],
+                    dim=pd.Index(self.flows.keys(), name='flow'),
+                )
             ).rename('flow_rates')
         filters = {k: v for k, v in {'start': start, 'end': end, 'component': component}.items() if v is not None}
         return filter_dataarray_by_coord(self._flow_rates, **filters)
 
     def flow_hours(
         self,
-        start: Optional[Union[str, List[str]]] = None,
-        end: Optional[Union[str, List[str]]] = None,
-        component: Optional[Union[str, List[str]]] = None,
+        start: str | list[str] | None = None,
+        end: str | list[str] | None = None,
+        component: str | list[str] | None = None,
     ) -> xr.DataArray:
         """Returns a DataArray containing the flow hours of each Flow.
 
@@ -387,9 +432,9 @@ class CalculationResults:
 
     def sizes(
         self,
-        start: Optional[Union[str, List[str]]] = None,
-        end: Optional[Union[str, List[str]]] = None,
-        component: Optional[Union[str, List[str]]] = None
+        start: str | list[str] | None = None,
+        end: str | list[str] | None = None,
+        component: str | list[str] | None = None,
     ) -> xr.DataArray:
         """Returns a dataset with the sizes of the Flows.
         Args:
@@ -406,56 +451,49 @@ class CalculationResults:
         """
         if self._sizes is None:
             self._sizes = self._assign_flow_coords(
-                xr.concat([flow.size.rename(flow.label) for flow in self.flows.values()],
-                          dim=pd.Index(self.flows.keys(), name='flow'))
+                xr.concat(
+                    [flow.size.rename(flow.label) for flow in self.flows.values()],
+                    dim=pd.Index(self.flows.keys(), name='flow'),
+                )
             ).rename('flow_sizes')
         filters = {k: v for k, v in {'start': start, 'end': end, 'component': component}.items() if v is not None}
         return filter_dataarray_by_coord(self._sizes, **filters)
 
     def _assign_flow_coords(self, da: xr.DataArray):
         # Add start and end coordinates
-        da = da.assign_coords({
-            'start': ('flow', [flow.start for flow in self.flows.values()]),
-            'end': ('flow', [flow.end for flow in self.flows.values()]),
-            'component': ('flow', [flow.component for flow in self.flows.values()]),
-        })
+        da = da.assign_coords(
+            {
+                'start': ('flow', [flow.start for flow in self.flows.values()]),
+                'end': ('flow', [flow.end for flow in self.flows.values()]),
+                'component': ('flow', [flow.component for flow in self.flows.values()]),
+            }
+        )
 
         # Ensure flow is the last dimension if needed
         existing_dims = [d for d in da.dims if d != 'flow']
         da = da.transpose(*(existing_dims + ['flow']))
         return da
 
-    def _get_flow_network_info(self) -> Dict[str, Dict[str, str]]:
-        flow_network_info = {}
-
-        for flow in self.flows.values():
-            flow_network_info[flow.label] = {
-                'label': flow.label,
-                'start': flow.start,
-                'end': flow.end,
-            }
-        return flow_network_info
-
     def get_effect_shares(
         self,
         element: str,
         effect: str,
-        mode: Optional[Literal['operation', 'invest']] = None,
-        include_flows: bool = False
+        mode: Literal['temporal', 'periodic'] | None = None,
+        include_flows: bool = False,
     ) -> xr.Dataset:
         """Retrieves individual effect shares for a specific element and effect.
-        Either for operation, investment, or both modes combined.
+        Either for temporal, investment, or both modes combined.
         Only includes the direct shares.
 
         Args:
             element: The element identifier for which to retrieve effect shares.
             effect: The effect identifier for which to retrieve shares.
-            mode: Optional. The mode to retrieve shares for. Can be 'operation', 'invest',
+            mode: Optional. The mode to retrieve shares for. Can be 'temporal', 'periodic',
                 or None to retrieve both. Defaults to None.
 
         Returns:
             An xarray Dataset containing the requested effect shares. If mode is None,
-            returns a merged Dataset containing both operation and investment shares.
+            returns a merged Dataset containing both temporal and investment shares.
 
         Raises:
             ValueError: If the specified effect is not available or if mode is invalid.
@@ -464,25 +502,38 @@ class CalculationResults:
             raise ValueError(f'Effect {effect} is not available.')
 
         if mode is None:
-            return xr.merge([self.get_effect_shares(element=element, effect=effect, mode='operation', include_flows=include_flows),
-                             self.get_effect_shares(element=element, effect=effect, mode='invest', include_flows=include_flows)])
+            return xr.merge(
+                [
+                    self.get_effect_shares(
+                        element=element, effect=effect, mode='temporal', include_flows=include_flows
+                    ),
+                    self.get_effect_shares(
+                        element=element, effect=effect, mode='periodic', include_flows=include_flows
+                    ),
+                ]
+            )
 
-        if mode not in ['operation', 'invest']:
-            raise ValueError(f'Mode {mode} is not available. Choose between "operation" and "invest".')
+        if mode not in ['temporal', 'periodic']:
+            raise ValueError(f'Mode {mode} is not available. Choose between "temporal" and "periodic".')
 
         ds = xr.Dataset()
 
         label = f'{element}->{effect}({mode})'
         if label in self.solution:
-            ds =  xr.Dataset({label: self.solution[label]})
+            ds = xr.Dataset({label: self.solution[label]})
 
         if include_flows:
             if element not in self.components:
                 raise ValueError(f'Only use Components when retrieving Effects including flows. Got {element}')
-            flows = [label.split('|')[0] for label in self.components[element].inputs + self.components[element].outputs]
+            flows = [
+                label.split('|')[0] for label in self.components[element].inputs + self.components[element].outputs
+            ]
             return xr.merge(
-                [ds] + [self.get_effect_shares(element=flow, effect=effect, mode=mode, include_flows=False)
-                        for flow in flows]
+                [ds]
+                + [
+                    self.get_effect_shares(element=flow, effect=effect, mode=mode, include_flows=False)
+                    for flow in flows
+                ]
             )
 
         return ds
@@ -491,7 +542,7 @@ class CalculationResults:
         self,
         element: str,
         effect: str,
-        mode: Literal['operation', 'invest', 'total'] = 'total',
+        mode: Literal['temporal', 'periodic', 'total'] = 'total',
         include_flows: bool = False,
     ) -> xr.DataArray:
         """Calculates the total effect for a specific element and effect.
@@ -503,10 +554,9 @@ class CalculationResults:
             element: The element identifier for which to calculate total effects.
             effect: The effect identifier to calculate.
             mode: The calculation mode. Options are:
-                'operation': Returns operation-specific effects.
-                'invest': Returns investment-specific effects.
-                'total': Returns the sum of operation effects (across all timesteps)
-                    and investment effects. Defaults to 'total'.
+                'temporal': Returns temporal effects.
+                'periodic': Returns investment-specific effects.
+                'total': Returns the sum of temporal effects and periodic effects. Defaults to 'total'.
             include_flows: Whether to include effects from flows connected to this element.
 
         Returns:
@@ -521,18 +571,22 @@ class CalculationResults:
             raise ValueError(f'Effect {effect} is not available.')
 
         if mode == 'total':
-            operation = self._compute_effect_total(element=element, effect=effect, mode='operation', include_flows=include_flows)
-            invest = self._compute_effect_total(element=element, effect=effect, mode='invest', include_flows=include_flows)
-            if invest.isnull().all() and operation.isnull().all():
+            temporal = self._compute_effect_total(
+                element=element, effect=effect, mode='temporal', include_flows=include_flows
+            )
+            periodic = self._compute_effect_total(
+                element=element, effect=effect, mode='periodic', include_flows=include_flows
+            )
+            if periodic.isnull().all() and temporal.isnull().all():
                 return xr.DataArray(np.nan)
-            if operation.isnull().all():
-                return invest.rename(f'{element}->{effect}')
-            operation = operation.sum('time')
-            if invest.isnull().all():
-                return operation.rename(f'{element}->{effect}')
-            if 'time' in operation.indexes:
-                operation = operation.sum('time')
-            return invest + operation
+            if temporal.isnull().all():
+                return periodic.rename(f'{element}->{effect}')
+            temporal = temporal.sum('time')
+            if periodic.isnull().all():
+                return temporal.rename(f'{element}->{effect}')
+            if 'time' in temporal.indexes:
+                temporal = temporal.sum('time')
+            return periodic + temporal
 
         total = xr.DataArray(0)
         share_exists = False
@@ -552,8 +606,9 @@ class CalculationResults:
             if include_flows:
                 if element not in self.components:
                     raise ValueError(f'Only use Components when retrieving Effects including flows. Got {element}')
-                flows = [label.split('|')[0] for label in
-                         self.components[element].inputs + self.components[element].outputs]
+                flows = [
+                    label.split('|')[0] for label in self.components[element].inputs + self.components[element].outputs
+                ]
                 for flow in flows:
                     label = f'{flow}->{target_effect}({mode})'
                     if label in self.solution:
@@ -564,40 +619,60 @@ class CalculationResults:
             total = xr.DataArray(np.nan)
         return total.rename(f'{element}->{effect}({mode})')
 
-    def _create_effects_dataset(self, mode: Literal['operation', 'invest', 'total'] = 'total') -> xr.Dataset:
+    def _create_effects_dataset(self, mode: Literal['temporal', 'periodic', 'total']) -> xr.Dataset:
         """Creates a dataset containing effect totals for all components (including their flows).
         The dataset does contain the direct as well as the indirect effects of each component.
 
         Args:
-            mode: The calculation mode ('operation', 'invest', or 'total').
+            mode: The calculation mode ('temporal', 'periodic', or 'total').
 
         Returns:
             An xarray Dataset with components as dimension and effects as variables.
         """
-        # Create an empty dataset
         ds = xr.Dataset()
+        all_arrays = {}
+        template = None  # Template is needed to determine the dimensions of the arrays. This handles the case of no shares for an effect
 
-        # Add each effect as a variable to the dataset
+        components_list = list(self.components)
+
+        # First pass: collect arrays and find template
         for effect in self.effects:
-            # Create a list of DataArrays, one for each component
-            component_arrays = [
-                self._compute_effect_total(element=component, effect=effect, mode=mode, include_flows=True).expand_dims(
-                    component=[component]
-                )  # Add component dimension to each array
-                for component in list(self.components)
-            ]
+            effect_arrays = []
+            for component in components_list:
+                da = self._compute_effect_total(element=component, effect=effect, mode=mode, include_flows=True)
+                effect_arrays.append(da)
+
+                if template is None and (da.dims or not da.isnull().all()):
+                    template = da
+
+            all_arrays[effect] = effect_arrays
+
+        # Ensure we have a template
+        if template is None:
+            raise ValueError(
+                f"No template with proper dimensions found for mode '{mode}'. "
+                f'All computed arrays are scalars, which indicates a data issue.'
+            )
+
+        # Second pass: process all effects (guaranteed to include all)
+        for effect in self.effects:
+            dataarrays = all_arrays[effect]
+            component_arrays = []
+
+            for component, arr in zip(components_list, dataarrays, strict=False):
+                # Expand scalar NaN arrays to match template dimensions
+                if not arr.dims and np.isnan(arr.item()):
+                    arr = xr.full_like(template, np.nan, dtype=float).rename(arr.name)
 
-            # Combine all components into one DataArray for this effect
-            if component_arrays:
-                effect_array = xr.concat(component_arrays, dim='component', coords='minimal')
-                # Add this effect as a variable to the dataset
-                ds[effect] = effect_array
+                component_arrays.append(arr.expand_dims(component=[component]))
+
+            ds[effect] = xr.concat(component_arrays, dim='component', coords='minimal', join='outer').rename(effect)
 
         # For now include a test to ensure correctness
         suffix = {
-            'operation': '(operation)|total_per_timestep',
-            'invest': '(invest)|total',
-            'total': '|total',
+            'temporal': '(temporal)|per_timestep',
+            'periodic': '(periodic)',
+            'total': '',
         }
         for effect in self.effects:
             label = f'{effect}{suffix[mode]}'
@@ -616,11 +691,11 @@ class CalculationResults:
         heatmap_timeframes: Literal['YS', 'MS', 'W', 'D', 'h', '15min', 'min'] = 'D',
         heatmap_timesteps_per_frame: Literal['W', 'D', 'h', '15min', 'min'] = 'h',
         color_map: str = 'portland',
-        save: Union[bool, pathlib.Path] = False,
+        save: bool | pathlib.Path = False,
         show: bool = True,
         engine: plotting.PlottingEngine = 'plotly',
-        scenario: Optional[Union[str, int]] = None,
-    ) -> Union[plotly.graph_objs.Figure, Tuple[plt.Figure, plt.Axes]]:
+        indexer: dict[FlowSystemDimensions, Any] | None = None,
+    ) -> plotly.graph_objs.Figure | tuple[plt.Figure, plt.Axes]:
         """
         Plots a heatmap of the solution of a variable.
 
@@ -632,19 +707,40 @@ class CalculationResults:
             save: Whether to save the plot or not. If a path is provided, the plot will be saved at that location.
             show: Whether to show the plot or not.
             engine: The engine to use for plotting. Can be either 'plotly' or 'matplotlib'.
-            scenario: The scenario to plot. Defaults to the first scenario. Has no effect without scenarios present
+            indexer: Optional selection dict, e.g., {'scenario': 'base', 'period': 2024}.
+                 If None, uses first value for each dimension.
+                 If empty dict {}, uses all values.
+
+        Examples:
+            Basic usage (uses first scenario, first period, all time):
+
+            >>> results.plot_heatmap('Battery|charge_state')
+
+            Select specific scenario and period:
+
+            >>> results.plot_heatmap('Boiler(Qth)|flow_rate', indexer={'scenario': 'base', 'period': 2024})
+
+            Time filtering (summer months only):
+
+            >>> results.plot_heatmap(
+            ...     'Boiler(Qth)|flow_rate',
+            ...     indexer={
+            ...         'scenario': 'base',
+            ...         'time': results.solution.time[results.solution.time.dt.month.isin([6, 7, 8])],
+            ...     },
+            ... )
+
+            Save to specific location:
+
+            >>> results.plot_heatmap(
+            ...     'Boiler(Qth)|flow_rate', indexer={'scenario': 'base'}, save='path/to/my_heatmap.html'
+            ... )
         """
         dataarray = self.solution[variable_name]
 
-        scenario_suffix = ''
-        if 'scenario' in dataarray.indexes:
-            chosen_scenario = scenario or self.scenarios[0]
-            dataarray = dataarray.sel(scenario=chosen_scenario).drop_vars('scenario')
-            scenario_suffix = f'--{chosen_scenario}'
-
         return plot_heatmap(
             dataarray=dataarray,
-            name=f'{variable_name}{scenario_suffix}',
+            name=variable_name,
             folder=self.folder,
             heatmap_timeframes=heatmap_timeframes,
             heatmap_timesteps_per_frame=heatmap_timesteps_per_frame,
@@ -652,41 +748,47 @@ class CalculationResults:
             save=save,
             show=show,
             engine=engine,
+            indexer=indexer,
         )
 
     def plot_network(
         self,
-        controls: Union[
-            bool,
-            List[
+        controls: (
+            bool
+            | list[
                 Literal['nodes', 'edges', 'layout', 'interaction', 'manipulation', 'physics', 'selection', 'renderer']
-            ],
-        ] = True,
-        path: Optional[pathlib.Path] = None,
+            ]
+        ) = True,
+        path: pathlib.Path | None = None,
         show: bool = False,
-    ) -> 'pyvis.network.Network':
-        """See flixopt.flow_system.FlowSystem.plot_network"""
+    ) -> pyvis.network.Network | None:
+        """Plot interactive network visualization of the system.
+
+        Args:
+            controls: Enable/disable interactive controls.
+            path: Save path for network HTML.
+            show: Whether to display the plot.
+        """
         if path is None:
             path = self.folder / f'{self.name}--network.html'
         return self.flow_system.plot_network(controls=controls, path=path, show=show)
 
     def to_file(
         self,
-        folder: Optional[Union[str, pathlib.Path]] = None,
-        name: Optional[str] = None,
+        folder: str | pathlib.Path | None = None,
+        name: str | None = None,
         compression: int = 5,
         document_model: bool = True,
         save_linopy_model: bool = False,
     ):
-        """
-        Save the results to a file
+        """Save results to files.
+
         Args:
-            folder: The folder where the results should be saved. Defaults to the folder of the calculation.
-            name: The name of the results file. If not provided, Defaults to the name of the calculation.
-            compression: The compression level to use when saving the solution file (0-9). 0 means no compression.
-            document_model: Wether to document the mathematical formulations in the model.
-            save_linopy_model: Wether to save the model to file. If True, the (linopy) model is saved as a .nc4 file.
-                The model file size is rougly 100 times larger than the solution file.
+            folder: Save folder (defaults to calculation folder).
+            name: File name (defaults to calculation name).
+            compression: Compression level 0-9.
+            document_model: Whether to document model formulations as yaml.
+            save_linopy_model: Whether to save linopy model file.
         """
         folder = self.folder if folder is None else pathlib.Path(folder)
         name = self.name if name is None else name
@@ -710,7 +812,7 @@ class CalculationResults:
             if self.model is None:
                 logger.critical('No model in the CalculationResults. Saving the model is not possible.')
             else:
-                self.model.to_netcdf(paths.linopy_model)
+                self.model.to_netcdf(paths.linopy_model, engine='h5netcdf')
 
         if document_model:
             if self.model is None:
@@ -723,7 +825,7 @@ class CalculationResults:
 
 class _ElementResults:
     def __init__(
-        self, calculation_results: CalculationResults, label: str, variables: List[str], constraints: List[str]
+        self, calculation_results: CalculationResults, label: str, variables: list[str], constraints: list[str]
     ):
         self._calculation_results = calculation_results
         self.label = label
@@ -734,11 +836,10 @@ class _ElementResults:
 
     @property
     def variables(self) -> linopy.Variables:
-        """
-        Returns the variables of the element.
+        """Get element variables (requires linopy model).
 
         Raises:
-            ValueError: If the linopy model is not availlable.
+            ValueError: If linopy model is unavailable.
         """
         if self._calculation_results.model is None:
             raise ValueError('The linopy model is not available.')
@@ -746,11 +847,10 @@ class _ElementResults:
 
     @property
     def constraints(self) -> linopy.Constraints:
-        """
-        Returns the variables of the element.
+        """Get element constraints (requires linopy model).
 
         Raises:
-            ValueError: If the linopy model is not availlable.
+            ValueError: If linopy model is unavailable.
         """
         if self._calculation_results.model is None:
             raise ValueError('The linopy model is not available.')
@@ -758,11 +858,11 @@ class _ElementResults:
 
     def filter_solution(
         self,
-        variable_dims: Optional[Literal['scalar', 'time', 'scenario', 'timeonly', 'scenarioonly']] = None,
-        timesteps: Optional[pd.DatetimeIndex] = None,
-        scenarios: Optional[pd.Index] = None,
-        contains: Optional[Union[str, List[str]]] = None,
-        startswith: Optional[Union[str, List[str]]] = None,
+        variable_dims: Literal['scalar', 'time', 'scenario', 'timeonly', 'scenarioonly'] | None = None,
+        timesteps: pd.DatetimeIndex | None = None,
+        scenarios: pd.Index | None = None,
+        contains: str | list[str] | None = None,
+        startswith: str | list[str] | None = None,
     ) -> xr.Dataset:
         """
         Filter the solution to a specific variable dimension and element.
@@ -803,11 +903,11 @@ class _NodeResults(_ElementResults):
         self,
         calculation_results: CalculationResults,
         label: str,
-        variables: List[str],
-        constraints: List[str],
-        inputs: List[str],
-        outputs: List[str],
-        flows: List[str],
+        variables: list[str],
+        constraints: list[str],
+        inputs: list[str],
+        outputs: list[str],
+        flows: list[str],
     ):
         super().__init__(calculation_results, label, variables, constraints)
         self.inputs = inputs
@@ -816,15 +916,15 @@ class _NodeResults(_ElementResults):
 
     def plot_node_balance(
         self,
-        save: Union[bool, pathlib.Path] = False,
+        save: bool | pathlib.Path = False,
         show: bool = True,
         colors: plotting.ColorType = 'viridis',
         engine: plotting.PlottingEngine = 'plotly',
-        scenario: Optional[Union[str, int]] = None,
+        indexer: dict[FlowSystemDimensions, Any] | None = None,
         mode: Literal['flow_rate', 'flow_hours'] = 'flow_rate',
         style: Literal['area', 'stacked_bar', 'line'] = 'stacked_bar',
         drop_suffix: bool = True,
-    ) -> Union[plotly.graph_objs.Figure, Tuple[plt.Figure, plt.Axes]]:
+    ) -> plotly.graph_objs.Figure | tuple[plt.Figure, plt.Axes]:
         """
         Plots the node balance of the Component or Bus.
         Args:
@@ -832,20 +932,20 @@ class _NodeResults(_ElementResults):
             show: Whether to show the plot or not.
             colors: The colors to use for the plot. See `flixopt.plotting.ColorType` for options.
             engine: The engine to use for plotting. Can be either 'plotly' or 'matplotlib'.
-            scenario: The scenario to plot. Defaults to the first scenario. Has no effect without scenarios present
-            mode: The mode to use for the dataset. Can be 'flow_rate' or 'flow_hours'.
+            indexer: Optional selection dict, e.g., {'scenario': 'base', 'period': 2024}.
+                 If None, uses first value for each dimension (except time).
+                 If empty dict {}, uses all values.
+            style: The style to use for the dataset. Can be 'flow_rate' or 'flow_hours'.
                 - 'flow_rate': Returns the flow_rates of the Node.
                 - 'flow_hours': Returns the flow_hours of the Node. [flow_hours(t) = flow_rate(t) * dt(t)]. Renames suffixes to |flow_hours.
             drop_suffix: Whether to drop the suffix from the variable names.
         """
-        ds = self.node_balance(with_last_timestep=True, mode=mode, drop_suffix=drop_suffix)
+        ds = self.node_balance(with_last_timestep=True, mode=mode, drop_suffix=drop_suffix, indexer=indexer)
 
-        title = f'{self.label} (flow rates)' if mode == 'flow_rate' else f'{self.label} (flow hours)'
+        ds, suffix_parts = _apply_indexer_to_data(ds, indexer, drop=True)
+        suffix = '--' + '-'.join(suffix_parts) if suffix_parts else ''
 
-        if 'scenario' in ds.indexes:
-            chosen_scenario = scenario or self._calculation_results.scenarios[0]
-            ds = ds.sel(scenario=chosen_scenario).drop_vars('scenario')
-            title = f'{title} - {chosen_scenario}'
+        title = f'{self.label} (flow rates){suffix}' if mode == 'flow_rate' else f'{self.label} (flow hours){suffix}'
 
         if engine == 'plotly':
             figure_like = plotting.with_plotly(
@@ -880,23 +980,22 @@ class _NodeResults(_ElementResults):
         lower_percentage_group: float = 5,
         colors: plotting.ColorType = 'viridis',
         text_info: str = 'percent+label+value',
-        save: Union[bool, pathlib.Path] = False,
+        save: bool | pathlib.Path = False,
         show: bool = True,
         engine: plotting.PlottingEngine = 'plotly',
-        scenario: Optional[Union[str, int]] = None,
-    ) -> plotly.graph_objects.Figure:
-        """
-        Plots a pie chart of the flow hours of the inputs and outputs of buses or components.
-
+        indexer: dict[FlowSystemDimensions, Any] | None = None,
+    ) -> plotly.graph_objs.Figure | tuple[plt.Figure, list[plt.Axes]]:
+        """Plot pie chart of flow hours distribution.
         Args:
-            colors: a colorscale or a list of colors to use for the plot
-            lower_percentage_group: The percentage of flow_hours that is grouped in "Others" (0...100)
-            text_info: What information to display on the pie plot
-            save: Whether to save the figure.
-            show: Whether to show the figure.
-            engine: Plotting engine to use. Only 'plotly' is implemented atm.
-            scenario: If scenarios are present: The scenario to plot. If None, the first scenario is used.
-            drop_suffix: Whether to drop the suffix from the variable names.
+            lower_percentage_group: Percentage threshold for "Others" grouping.
+            colors: Color scheme. Also see plotly.
+            text_info: Information to display on pie slices.
+            save: Whether to save plot.
+            show: Whether to display plot.
+            engine: Plotting engine ('plotly' or 'matplotlib').
+            indexer: Optional selection dict, e.g., {'scenario': 'base', 'period': 2024}.
+                 If None, uses first value for each dimension.
+                 If empty dict {}, uses all values.
         """
         inputs = sanitize_dataset(
             ds=self.solution[self.inputs] * self._calculation_results.hours_per_timestep,
@@ -912,16 +1011,15 @@ class _NodeResults(_ElementResults):
             zero_small_values=True,
             drop_suffix='|',
         )
-        inputs = inputs.sum('time')
-        outputs = outputs.sum('time')
 
-        title = f'{self.label} (total flow hours)'
+        inputs, suffix_parts = _apply_indexer_to_data(inputs, indexer, drop=True)
+        outputs, suffix_parts = _apply_indexer_to_data(outputs, indexer, drop=True)
+        suffix = '--' + '-'.join(suffix_parts) if suffix_parts else ''
 
-        if 'scenario' in inputs.indexes:
-            chosen_scenario = scenario or self._calculation_results.scenarios[0]
-            inputs = inputs.sel(scenario=chosen_scenario).drop_vars('scenario')
-            outputs = outputs.sel(scenario=chosen_scenario).drop_vars('scenario')
-            title = f'{title} - {chosen_scenario}'
+        title = f'{self.label} (total flow hours){suffix}'
+
+        inputs = inputs.sum('time')
+        outputs = outputs.sum('time')
 
         if engine == 'plotly':
             figure_like = plotting.dual_pie_with_plotly(
@@ -963,10 +1061,11 @@ class _NodeResults(_ElementResults):
         self,
         negate_inputs: bool = True,
         negate_outputs: bool = False,
-        threshold: Optional[float] = 1e-5,
+        threshold: float | None = 1e-5,
         with_last_timestep: bool = False,
         mode: Literal['flow_rate', 'flow_hours'] = 'flow_rate',
         drop_suffix: bool = False,
+        indexer: dict[FlowSystemDimensions, Any] | None = None,
     ) -> xr.Dataset:
         """
         Returns a dataset with the node balance of the Component or Bus.
@@ -979,6 +1078,9 @@ class _NodeResults(_ElementResults):
                 - 'flow_rate': Returns the flow_rates of the Node.
                 - 'flow_hours': Returns the flow_hours of the Node. [flow_hours(t) = flow_rate(t) * dt(t)]. Renames suffixes to |flow_hours.
             drop_suffix: Whether to drop the suffix from the variable names.
+            indexer: Optional selection dict, e.g., {'scenario': 'base', 'period': 2024}.
+                 If None, uses first value for each dimension.
+                 If empty dict {}, uses all values.
         """
         ds = self.solution[self.inputs + self.outputs]
 
@@ -998,6 +1100,8 @@ class _NodeResults(_ElementResults):
             drop_suffix='|' if drop_suffix else None,
         )
 
+        ds, _ = _apply_indexer_to_data(ds, indexer, drop=True)
+
         if mode == 'flow_hours':
             ds = ds * self._calculation_results.hours_per_timestep
             ds = ds.rename_vars({var: var.replace('flow_rate', 'flow_hours') for var in ds.data_vars})
@@ -1006,11 +1110,11 @@ class _NodeResults(_ElementResults):
 
 
 class BusResults(_NodeResults):
-    """Results for a Bus"""
+    """Results container for energy/material balance nodes in the system."""
 
 
 class ComponentResults(_NodeResults):
-    """Results for a Component"""
+    """Results container for individual system components with specialized analysis tools."""
 
     @property
     def is_storage(self) -> bool:
@@ -1022,51 +1126,53 @@ class ComponentResults(_NodeResults):
 
     @property
     def charge_state(self) -> xr.DataArray:
-        """Get the solution of the charge state of the Storage."""
+        """Get storage charge state solution."""
         if not self.is_storage:
             raise ValueError(f'Cant get charge_state. "{self.label}" is not a storage')
         return self.solution[self._charge_state]
 
     def plot_charge_state(
         self,
-        save: Union[bool, pathlib.Path] = False,
+        save: bool | pathlib.Path = False,
         show: bool = True,
         colors: plotting.ColorType = 'viridis',
         engine: plotting.PlottingEngine = 'plotly',
         style: Literal['area', 'stacked_bar', 'line'] = 'stacked_bar',
-        scenario: Optional[Union[str, int]] = None,
+        indexer: dict[FlowSystemDimensions, Any] | None = None,
     ) -> plotly.graph_objs.Figure:
-        """
-        Plots the charge state of a Storage.
+        """Plot storage charge state over time, combined with the node balance.
+
         Args:
             save: Whether to save the plot or not. If a path is provided, the plot will be saved at that location.
             show: Whether to show the plot or not.
-            colors: The c
+            colors: Color scheme. Also see plotly.
             engine: Plotting engine to use. Only 'plotly' is implemented atm.
-            style: The plotting mode for the flow_rate
-            scenario: The scenario to plot. Defaults to the first scenario. Has no effect without scenarios present
+            style: The colors to use for the plot. See `flixopt.plotting.ColorType` for options.
+            indexer: Optional selection dict, e.g., {'scenario': 'base', 'period': 2024}.
+                 If None, uses first value for each dimension.
+                 If empty dict {}, uses all values.
 
         Raises:
-            ValueError: If the Component is not a Storage.
+            ValueError: If component is not a storage.
         """
         if not self.is_storage:
             raise ValueError(f'Cant plot charge_state. "{self.label}" is not a storage')
 
-        ds = self.node_balance(with_last_timestep=True)
+        ds = self.node_balance(with_last_timestep=True, indexer=indexer)
         charge_state = self.charge_state
 
-        scenario_suffix = ''
-        if 'scenario' in ds.indexes:
-            chosen_scenario = scenario or self._calculation_results.scenarios[0]
-            ds = ds.sel(scenario=chosen_scenario).drop_vars('scenario')
-            charge_state = charge_state.sel(scenario=chosen_scenario).drop_vars('scenario')
-            scenario_suffix = f'--{chosen_scenario}'
+        ds, suffix_parts = _apply_indexer_to_data(ds, indexer, drop=True)
+        charge_state, suffix_parts = _apply_indexer_to_data(charge_state, indexer, drop=True)
+        suffix = '--' + '-'.join(suffix_parts) if suffix_parts else ''
+
+        title = f'Operation Balance of {self.label}{suffix}'
+
         if engine == 'plotly':
             fig = plotting.with_plotly(
                 ds.to_dataframe(),
                 colors=colors,
                 style=style,
-                title=f'Operation Balance of {self.label}{scenario_suffix}',
+                title=title,
             )
 
             # TODO: Use colors for charge state?
@@ -1077,12 +1183,12 @@ class ComponentResults(_NodeResults):
                     x=charge_state.index, y=charge_state.values.flatten(), mode='lines', name=self._charge_state
                 )
             )
-        elif engine=='matplotlib':
+        elif engine == 'matplotlib':
             fig, ax = plotting.with_matplotlib(
                 ds.to_dataframe(),
                 colors=colors,
                 style=style,
-                title=f'Operation Balance of {self.label}{scenario_suffix}',
+                title=title,
             )
 
             charge_state = charge_state.to_dataframe()
@@ -1092,7 +1198,7 @@ class ComponentResults(_NodeResults):
 
         return plotting.export_figure(
             fig,
-            default_path=self._calculation_results.folder / f'{self.label} (charge state){scenario_suffix}',
+            default_path=self._calculation_results.folder / title,
             default_filetype='.html',
             user_path=None if isinstance(save, bool) else pathlib.Path(save),
             show=show,
@@ -1100,17 +1206,20 @@ class ComponentResults(_NodeResults):
         )
 
     def node_balance_with_charge_state(
-        self, negate_inputs: bool = True, negate_outputs: bool = False, threshold: Optional[float] = 1e-5
+        self, negate_inputs: bool = True, negate_outputs: bool = False, threshold: float | None = 1e-5
     ) -> xr.Dataset:
-        """
-        Returns a dataset with the node balance of the Storage including its charge state.
+        """Get storage node balance including charge state.
+
         Args:
-            negate_inputs: Whether to negate the inputs of the Storage.
-            negate_outputs: Whether to negate the outputs of the Storage.
-            threshold: The threshold for small values.
+            negate_inputs: Whether to negate input flows.
+            negate_outputs: Whether to negate output flows.
+            threshold: Threshold for small values.
+
+        Returns:
+            xr.Dataset: Node balance with charge state.
 
         Raises:
-            ValueError: If the Component is not a Storage.
+            ValueError: If component is not a storage.
         """
         if not self.is_storage:
             raise ValueError(f'Cant get charge_state. "{self.label}" is not a storage')
@@ -1135,7 +1244,14 @@ class EffectResults(_ElementResults):
     """Results for an Effect"""
 
     def get_shares_from(self, element: str):
-        """Get the shares from an Element (without subelements) to the Effect"""
+        """Get effect shares from specific element.
+
+        Args:
+            element: Element label to get shares from.
+
+        Returns:
+            xr.Dataset: Element shares to this effect.
+        """
         return self.solution[[name for name in self._variable_names if name.startswith(f'{element}->')]]
 
 
@@ -1144,8 +1260,8 @@ class FlowResults(_ElementResults):
         self,
         calculation_results: CalculationResults,
         label: str,
-        variables: List[str],
-        constraints: List[str],
+        variables: list[str],
+        constraints: list[str],
         start: str,
         end: str,
         component: str,
@@ -1169,22 +1285,110 @@ class FlowResults(_ElementResults):
         if name in self.solution:
             return self.solution[name]
         try:
-            return DataConverter.as_dataarray(
-                self._calculation_results.flow_system.flows[self.label].size,
-                scenarios=self._calculation_results.scenarios
-            ).rename(name)
+            return self._calculation_results.flow_system.flows[self.label].size.rename(name)
         except _FlowSystemRestorationError:
             logger.critical(f'Size of flow {self.label}.size not availlable. Returning NaN')
             return xr.DataArray(np.nan).rename(name)
 
 
 class SegmentedCalculationResults:
-    """
-    Class to store the results of a SegmentedCalculation.
+    """Results container for segmented optimization calculations with temporal decomposition.
+
+    This class manages results from SegmentedCalculation runs where large optimization
+    problems are solved by dividing the time horizon into smaller, overlapping segments.
+    It provides unified access to results across all segments while maintaining the
+    ability to analyze individual segment behavior.
+
+    Key Features:
+        **Unified Time Series**: Automatically assembles results from all segments into
+        continuous time series, removing overlaps and boundary effects
+        **Segment Analysis**: Access individual segment results for debugging and validation
+        **Consistency Checks**: Verify solution continuity at segment boundaries
+        **Memory Efficiency**: Handles large datasets that exceed single-segment memory limits
+
+    Temporal Handling:
+        The class manages the complex task of combining overlapping segment solutions
+        into coherent time series, ensuring proper treatment of:
+        - Storage state continuity between segments
+        - Flow rate transitions at segment boundaries
+        - Aggregated results over the full time horizon
+
+    Examples:
+        Load and analyze segmented results:
+
+        ```python
+        # Load segmented calculation results
+        results = SegmentedCalculationResults.from_file('results', 'annual_segmented')
+
+        # Access unified results across all segments
+        full_timeline = results.all_timesteps
+        total_segments = len(results.segment_results)
+
+        # Analyze individual segments
+        for i, segment in enumerate(results.segment_results):
+            print(f'Segment {i + 1}: {len(segment.solution.time)} timesteps')
+            segment_costs = segment.effects['cost'].total_value
+
+        # Check solution continuity at boundaries
+        segment_boundaries = results.get_boundary_analysis()
+        max_discontinuity = segment_boundaries['max_storage_jump']
+        ```
+
+        Create from segmented calculation:
+
+        ```python
+        # After running segmented calculation
+        segmented_calc = SegmentedCalculation(
+            name='annual_system',
+            flow_system=system,
+            timesteps_per_segment=730,  # Monthly segments
+            overlap_timesteps=48,  # 2-day overlap
+        )
+        segmented_calc.do_modeling_and_solve(solver='gurobi')
+
+        # Extract unified results
+        results = SegmentedCalculationResults.from_calculation(segmented_calc)
+
+        # Save combined results
+        results.to_file(compression=5)
+        ```
+
+        Performance analysis across segments:
+
+        ```python
+        # Compare segment solve times
+        solve_times = [seg.summary['durations']['solving'] for seg in results.segment_results]
+        avg_solve_time = sum(solve_times) / len(solve_times)
+
+        # Verify solution quality consistency
+        segment_objectives = [seg.summary['objective_value'] for seg in results.segment_results]
+
+        # Storage continuity analysis
+        if 'Battery' in results.segment_results[0].components:
+            storage_continuity = results.check_storage_continuity('Battery')
+        ```
+
+    Design Considerations:
+        **Boundary Effects**: Monitor solution quality at segment interfaces where
+        foresight is limited compared to full-horizon optimization.
+
+        **Memory Management**: Individual segment results are maintained for detailed
+        analysis while providing unified access for system-wide metrics.
+
+        **Validation Tools**: Built-in methods to verify temporal consistency and
+        identify potential issues from segmentation approach.
+
+    Common Use Cases:
+        - **Large-Scale Analysis**: Annual or multi-period optimization results
+        - **Memory-Constrained Systems**: Results from systems exceeding hardware limits
+        - **Segment Validation**: Verifying segmentation approach effectiveness
+        - **Performance Monitoring**: Comparing segmented vs. full-horizon solutions
+        - **Debugging**: Identifying issues specific to temporal decomposition
+
     """
 
     @classmethod
-    def from_calculation(cls, calculation: 'SegmentedCalculation'):
+    def from_calculation(cls, calculation: SegmentedCalculation):
         return cls(
             [calc.results for calc in calculation.sub_calculations],
             all_timesteps=calculation.all_timesteps,
@@ -1195,16 +1399,23 @@ class SegmentedCalculationResults:
         )
 
     @classmethod
-    def from_file(cls, folder: Union[str, pathlib.Path], name: str):
-        """Create SegmentedCalculationResults directly from file"""
+    def from_file(cls, folder: str | pathlib.Path, name: str):
+        """Load SegmentedCalculationResults from saved files.
+
+        Args:
+            folder: Directory containing saved files.
+            name: Base name of saved files.
+
+        Returns:
+            SegmentedCalculationResults: Loaded instance.
+        """
         folder = pathlib.Path(folder)
         path = folder / name
-        nc_file = path.with_suffix('.nc4')
-        logger.info(f'loading calculation "{name}" from file ("{nc_file}")')
-        with open(path.with_suffix('.json'), 'r', encoding='utf-8') as f:
+        logger.info(f'loading calculation "{name}" from file ("{path.with_suffix(".nc4")}")')
+        with open(path.with_suffix('.json'), encoding='utf-8') as f:
             meta_data = json.load(f)
         return cls(
-            [CalculationResults.from_file(folder, name) for name in meta_data['sub_calculations']],
+            [CalculationResults.from_file(folder, sub_name) for sub_name in meta_data['sub_calculations']],
             all_timesteps=pd.DatetimeIndex(
                 [datetime.datetime.fromisoformat(date) for date in meta_data['all_timesteps']], name='time'
             ),
@@ -1216,12 +1427,12 @@ class SegmentedCalculationResults:
 
     def __init__(
         self,
-        segment_results: List[CalculationResults],
+        segment_results: list[CalculationResults],
         all_timesteps: pd.DatetimeIndex,
         timesteps_per_segment: int,
         overlap_timesteps: int,
         name: str,
-        folder: Optional[pathlib.Path] = None,
+        folder: pathlib.Path | None = None,
     ):
         self.segment_results = segment_results
         self.all_timesteps = all_timesteps
@@ -1229,10 +1440,10 @@ class SegmentedCalculationResults:
         self.overlap_timesteps = overlap_timesteps
         self.name = name
         self.folder = pathlib.Path(folder) if folder is not None else pathlib.Path.cwd() / 'results'
-        self.hours_per_timestep = TimeSeriesCollection.calculate_hours_per_timestep(self.all_timesteps)
+        self.hours_per_timestep = FlowSystem.calculate_hours_per_timestep(self.all_timesteps)
 
     @property
-    def meta_data(self) -> Dict[str, Union[int, List[str]]]:
+    def meta_data(self) -> dict[str, int | list[str]]:
         return {
             'all_timesteps': [datetime.datetime.isoformat(date) for date in self.all_timesteps],
             'timesteps_per_segment': self.timesteps_per_segment,
@@ -1241,11 +1452,18 @@ class SegmentedCalculationResults:
         }
 
     @property
-    def segment_names(self) -> List[str]:
+    def segment_names(self) -> list[str]:
         return [segment.name for segment in self.segment_results]
 
     def solution_without_overlap(self, variable_name: str) -> xr.DataArray:
-        """Returns the solution of a variable without overlapping timesteps"""
+        """Get variable solution removing segment overlaps.
+
+        Args:
+            variable_name: Name of variable to extract.
+
+        Returns:
+            xr.DataArray: Continuous solution without overlaps.
+        """
         dataarrays = [
             result.solution[variable_name].isel(time=slice(None, self.timesteps_per_segment))
             for result in self.segment_results[:-1]
@@ -1258,21 +1476,23 @@ class SegmentedCalculationResults:
         heatmap_timeframes: Literal['YS', 'MS', 'W', 'D', 'h', '15min', 'min'] = 'D',
         heatmap_timesteps_per_frame: Literal['W', 'D', 'h', '15min', 'min'] = 'h',
         color_map: str = 'portland',
-        save: Union[bool, pathlib.Path] = False,
+        save: bool | pathlib.Path = False,
         show: bool = True,
         engine: plotting.PlottingEngine = 'plotly',
-    ) -> Union[plotly.graph_objs.Figure, Tuple[plt.Figure, plt.Axes]]:
-        """
-        Plots a heatmap of the solution of a variable.
+    ) -> plotly.graph_objs.Figure | tuple[plt.Figure, plt.Axes]:
+        """Plot heatmap of variable solution across segments.
 
         Args:
-            variable_name: The name of the variable to plot.
-            heatmap_timeframes: The timeframes to use for the heatmap.
-            heatmap_timesteps_per_frame: The timesteps per frame to use for the heatmap.
-            color_map: The color map to use for the heatmap.
-            save: Whether to save the plot or not. If a path is provided, the plot will be saved at that location.
-            show: Whether to show the plot or not.
-            engine: The engine to use for plotting. Can be either 'plotly' or 'matplotlib'.
+            variable_name: Variable to plot.
+            heatmap_timeframes: Time aggregation level.
+            heatmap_timesteps_per_frame: Timesteps per frame.
+            color_map: Color scheme. Also see plotly.
+            save: Whether to save plot.
+            show: Whether to display plot.
+            engine: Plotting engine.
+
+        Returns:
+            Figure object.
         """
         return plot_heatmap(
             dataarray=self.solution_without_overlap(variable_name),
@@ -1286,10 +1506,14 @@ class SegmentedCalculationResults:
             engine=engine,
         )
 
-    def to_file(
-        self, folder: Optional[Union[str, pathlib.Path]] = None, name: Optional[str] = None, compression: int = 5
-    ):
-        """Save the results to a file"""
+    def to_file(self, folder: str | pathlib.Path | None = None, name: str | None = None, compression: int = 5):
+        """Save segmented results to files.
+
+        Args:
+            folder: Save folder (defaults to instance folder).
+            name: File name (defaults to instance name).
+            compression: Compression level 0-9.
+        """
         folder = self.folder if folder is None else pathlib.Path(folder)
         name = self.name if name is None else name
         path = folder / name
@@ -1301,7 +1525,7 @@ class SegmentedCalculationResults:
                     f'Folder {folder} and its parent do not exist. Please create them first.'
                 ) from e
         for segment in self.segment_results:
-            segment.to_file(folder=folder, name=f'{name}-{segment.name}', compression=compression)
+            segment.to_file(folder=folder, name=segment.name, compression=compression)
 
         with open(path.with_suffix('.json'), 'w', encoding='utf-8') as f:
             json.dump(self.meta_data, f, indent=4, ensure_ascii=False)
@@ -1315,24 +1539,31 @@ def plot_heatmap(
     heatmap_timeframes: Literal['YS', 'MS', 'W', 'D', 'h', '15min', 'min'] = 'D',
     heatmap_timesteps_per_frame: Literal['W', 'D', 'h', '15min', 'min'] = 'h',
     color_map: str = 'portland',
-    save: Union[bool, pathlib.Path] = False,
+    save: bool | pathlib.Path = False,
     show: bool = True,
     engine: plotting.PlottingEngine = 'plotly',
+    indexer: dict[str, Any] | None = None,
 ):
-    """
-    Plots a heatmap of the solution of a variable.
+    """Plot heatmap of time series data.
 
     Args:
-        dataarray: The dataarray to plot.
-        name: The name of the variable to plot.
-        folder: The folder to save the plot to.
-        heatmap_timeframes: The timeframes to use for the heatmap.
-        heatmap_timesteps_per_frame: The timesteps per frame to use for the heatmap.
-        color_map: The color map to use for the heatmap.
-        save: Whether to save the plot or not. If a path is provided, the plot will be saved at that location.
-        show: Whether to show the plot or not.
-        engine: The engine to use for plotting. Can be either 'plotly' or 'matplotlib'.
+        dataarray: Data to plot.
+        name: Variable name for title.
+        folder: Save folder.
+        heatmap_timeframes: Time aggregation level.
+        heatmap_timesteps_per_frame: Timesteps per frame.
+        color_map: Color scheme. Also see plotly.
+        save: Whether to save plot.
+        show: Whether to display plot.
+        engine: Plotting engine.
+        indexer: Optional selection dict, e.g., {'scenario': 'base', 'period': 2024}.
+             If None, uses first value for each dimension.
+             If empty dict {}, uses all values.
     """
+    dataarray, suffix_parts = _apply_indexer_to_data(dataarray, indexer, drop=True)
+    suffix = '--' + '-'.join(suffix_parts) if suffix_parts else ''
+    name = name if not suffix_parts else name + suffix
+
     heatmap_data = plotting.heat_map_data_from_df(
         dataarray.to_dataframe(name), heatmap_timeframes, heatmap_timesteps_per_frame, 'ffill'
     )
@@ -1364,27 +1595,23 @@ def plot_heatmap(
 
 def sanitize_dataset(
     ds: xr.Dataset,
-    timesteps: Optional[pd.DatetimeIndex] = None,
-    threshold: Optional[float] = 1e-5,
-    negate: Optional[List[str]] = None,
+    timesteps: pd.DatetimeIndex | None = None,
+    threshold: float | None = 1e-5,
+    negate: list[str] | None = None,
     drop_small_vars: bool = True,
     zero_small_values: bool = False,
-    drop_suffix: Optional[str] = None,
+    drop_suffix: str | None = None,
 ) -> xr.Dataset:
-    """
-    Sanitizes a dataset by handling small values (dropping or zeroing) and optionally reindexing the time axis.
+    """Clean dataset by handling small values and reindexing time.
 
     Args:
-        ds: The dataset to sanitize.
-        timesteps: The timesteps to reindex the dataset to. If None, the original timesteps are kept.
-        threshold: The threshold for small values processing. If None, no processing is done.
-        negate: The variables to negate. If None, no variables are negated.
-        drop_small_vars: If True, drops variables where all values are below threshold.
-        zero_small_values: If True, sets values below threshold to zero.
+        ds: Dataset to sanitize.
+        timesteps: Time index for reindexing (optional).
+        threshold: Threshold for small values processing.
+        negate: Variables to negate.
+        drop_small_vars: Whether to drop variables below threshold.
+        zero_small_values: Whether to zero values below threshold.
         drop_suffix: Drop suffix of data var names. Split by the provided str.
-
-    Returns:
-        xr.Dataset: The sanitized dataset.
     """
     # Create a copy to avoid modifying the original
     ds = ds.copy()
@@ -1401,7 +1628,7 @@ def sanitize_dataset(
 
         # Option 1: Drop variables where all values are below threshold
         if drop_small_vars:
-            vars_to_drop = [var for var in ds.data_vars if (ds_no_nan_abs[var] <= threshold).all()]
+            vars_to_drop = [var for var in ds.data_vars if (ds_no_nan_abs[var] <= threshold).all().item()]
             ds = ds.drop_vars(vars_to_drop)
 
         # Option 2: Set small values to zero
@@ -1410,7 +1637,7 @@ def sanitize_dataset(
                 # Create a boolean mask of values below threshold
                 mask = ds_no_nan_abs[var] <= threshold
                 # Only proceed if there are values to zero out
-                if mask.any():
+                if bool(mask.any().item()):
                     # Create a copy to ensure we don't modify data with views
                     ds[var] = ds[var].copy()
                     # Set values below threshold to zero
@@ -1439,14 +1666,13 @@ def sanitize_dataset(
 
 def filter_dataset(
     ds: xr.Dataset,
-    variable_dims: Optional[Literal['scalar', 'time', 'scenario', 'timeonly', 'scenarioonly']] = None,
-    timesteps: Optional[Union[pd.DatetimeIndex, str, pd.Timestamp]] = None,
-    scenarios: Optional[Union[pd.Index, str, int]] = None,
-    contains: Optional[Union[str, List[str]]] = None,
-    startswith: Optional[Union[str, List[str]]] = None,
+    variable_dims: Literal['scalar', 'time', 'scenario', 'timeonly', 'scenarioonly'] | None = None,
+    timesteps: pd.DatetimeIndex | str | pd.Timestamp | None = None,
+    scenarios: pd.Index | str | int | None = None,
+    contains: str | list[str] | None = None,
+    startswith: str | list[str] | None = None,
 ) -> xr.Dataset:
-    """
-    Filters a dataset by its dimensions, indexes, and with string filters for variable names.
+    """Filter dataset by variable dimensions, indexes, and with string filters for variable names.
 
     Args:
         ds: The dataset to filter.
@@ -1468,9 +1694,6 @@ def filter_dataset(
             If a list is provided, variables must contain ALL strings in the list.
         startswith: Filter variables that start with this string or strings.
             If a list is provided, variables must start with ANY of the strings in the list.
-
-    Returns:
-        Filtered dataset with specified variables and indexes.
     """
     # First filter by dimensions
     filtered_ds = ds.copy()
@@ -1537,10 +1760,7 @@ def filter_dataset(
     return filtered_ds
 
 
-def filter_dataarray_by_coord(
-    da: xr.DataArray,
-    **kwargs: Optional[Union[str, List[str]]]
-) -> xr.DataArray:
+def filter_dataarray_by_coord(da: xr.DataArray, **kwargs: str | list[str] | None) -> xr.DataArray:
     """Filter flows by node and component attributes.
 
     Filters are applied in the order they are specified. All filters must match for an edge to be included.
@@ -1560,8 +1780,9 @@ def filter_dataarray_by_coord(
         AttributeError: If required coordinates are missing.
         ValueError: If specified nodes don't exist or no matches found.
     """
+
     # Helper function to process filters
-    def apply_filter(array, coord_name: str, coord_values: Union[Any, List[Any]]):
+    def apply_filter(array, coord_name: str, coord_values: Any | list[Any]):
         # Verify coord exists
         if coord_name not in array.coords:
             raise AttributeError(f"Missing required coordinate '{coord_name}'")
@@ -1573,12 +1794,12 @@ def filter_dataarray_by_coord(
         available = set(array[coord_name].values)
         missing = [v for v in val_list if v not in available]
         if missing:
-            raise ValueError(f"{coord_name.title()} value(s) not found: {missing}")
+            raise ValueError(f'{coord_name.title()} value(s) not found: {missing}')
 
         # Apply filter
         return array.where(
             array[coord_name].isin(val_list) if isinstance(coord_values, list) else array[coord_name] == coord_values,
-            drop=True
+            drop=True,
         )
 
     # Apply filters from kwargs
@@ -1587,10 +1808,45 @@ def filter_dataarray_by_coord(
         for coord, values in filters.items():
             da = apply_filter(da, coord, values)
     except ValueError as e:
-        raise ValueError(f"No edges match criteria: {filters}") from e
+        raise ValueError(f'No edges match criteria: {filters}') from e
 
     # Verify results exist
     if da.size == 0:
-        raise ValueError(f"No edges match criteria: {filters}")
+        raise ValueError(f'No edges match criteria: {filters}')
 
     return da
+
+
+def _apply_indexer_to_data(
+    data: xr.DataArray | xr.Dataset, indexer: dict[str, Any] | None = None, drop=False
+) -> tuple[xr.DataArray | xr.Dataset, list[str]]:
+    """
+    Apply indexer selection or auto-select first values for non-time dimensions.
+
+    Args:
+        data: xarray Dataset or DataArray
+        indexer: Optional selection dict
+            If None, uses first value for each dimension (except time).
+            If empty dict {}, uses all values.
+
+    Returns:
+        Tuple of (selected_data, selection_string)
+    """
+    selection_string = []
+
+    if indexer is not None:
+        # User provided indexer
+        data = data.sel(indexer, drop=drop)
+        selection_string.extend(f'{v}[{k}]' for k, v in indexer.items())
+    else:
+        # Auto-select first value for each dimension except 'time'
+        selection = {}
+        for dim in data.dims:
+            if dim != 'time' and dim in data.coords:
+                first_value = data.coords[dim].values[0]
+                selection[dim] = first_value
+                selection_string.append(f'{first_value}[{dim}]')
+        if selection:
+            data = data.sel(selection, drop=drop)
+
+    return data, selection_string