flixopt 2.1.7__py3-none-any.whl → 2.1.9__py3-none-any.whl

flixopt/features.py

@@ -3,18 +3,21 @@ This module contains the features of the flixopt framework.
 Features extend the functionality of Elements.
 """
 
+from __future__ import annotations
+
 import logging
-from typing import Dict, List, Optional, Tuple, Union
+from typing import TYPE_CHECKING
 
 import linopy
 import numpy as np
 
-from . import utils
 from .config import CONFIG
 from .core import NumericData, Scalar, TimeSeries
-from .interface import InvestParameters, OnOffParameters, Piecewise
 from .structure import Model, SystemModel
 
+if TYPE_CHECKING:
+    from .interface import InvestParameters, OnOffParameters, Piecewise
+
 logger = logging.getLogger('flixopt')
 
 
@@ -26,16 +29,16 @@ class InvestmentModel(Model):
         model: SystemModel,
         label_of_element: str,
         parameters: InvestParameters,
-        defining_variable: [linopy.Variable],
-        relative_bounds_of_defining_variable: Tuple[NumericData, NumericData],
-        label: Optional[str] = None,
-        on_variable: Optional[linopy.Variable] = None,
+        defining_variable: linopy.Variable,
+        relative_bounds_of_defining_variable: tuple[NumericData, NumericData],
+        label: str | None = None,
+        on_variable: linopy.Variable | None = None,
     ):
         super().__init__(model, label_of_element, label)
-        self.size: Optional[Union[Scalar, linopy.Variable]] = None
-        self.is_invested: Optional[linopy.Variable] = None
+        self.size: Scalar | linopy.Variable | None = None
+        self.is_invested: linopy.Variable | None = None
 
-        self.piecewise_effects: Optional[PiecewiseEffectsModel] = None
+        self.piecewise_effects: PiecewiseEffectsModel | None = None
 
         self._on_variable = on_variable
         self._defining_variable = defining_variable
@@ -205,14 +208,14 @@ class StateModel(Model):
         self,
         model: SystemModel,
         label_of_element: str,
-        defining_variables: List[linopy.Variable],
-        defining_bounds: List[Tuple[NumericData, NumericData]],
-        previous_values: List[Optional[NumericData]] = None,
+        defining_variables: list[linopy.Variable],
+        defining_bounds: list[tuple[NumericData, NumericData]],
+        previous_values: list[NumericData | None] | None = None,
         use_off: bool = True,
-        on_hours_total_min: Optional[NumericData] = 0,
-        on_hours_total_max: Optional[NumericData] = None,
-        effects_per_running_hour: Dict[str, NumericData] = None,
-        label: Optional[str] = None,
+        on_hours_total_min: NumericData | None = 0,
+        on_hours_total_max: NumericData | None = None,
+        effects_per_running_hour: dict[str, NumericData] | None = None,
+        label: str | None = None,
     ):
         """
         Models binary state variables based on a continous variable.
@@ -240,7 +243,7 @@ class StateModel(Model):
         self._effects_per_running_hour = effects_per_running_hour or {}
 
         self.on = None
-        self.total_on_hours: Optional[linopy.Variable] = None
+        self.total_on_hours: linopy.Variable | None = None
         self.off = None
 
     def do_modeling(self):
@@ -345,7 +348,7 @@ class StateModel(Model):
         return 1 - self.previous_states
 
     @staticmethod
-    def compute_previous_states(previous_values: List[NumericData], epsilon: float = 1e-5) -> np.ndarray:
+    def compute_previous_states(previous_values: list[NumericData | None] | None, epsilon: float = 1e-5) -> np.ndarray:
         """Computes the previous states {0, 1} of defining variables as a binary array from their previous values."""
         if not previous_values or all([val is None for val in previous_values]):
             return np.array([0])
@@ -369,8 +372,8 @@ class SwitchStateModel(Model):
         label_of_element: str,
         state_variable: linopy.Variable,
         previous_state=0,
-        switch_on_max: Optional[Scalar] = None,
-        label: Optional[str] = None,
+        switch_on_max: Scalar | None = None,
+        label: str | None = None,
     ):
         super().__init__(model, label_of_element, label)
         self._state_variable = state_variable
@@ -454,10 +457,10 @@ class ConsecutiveStateModel(Model):
         model: SystemModel,
         label_of_element: str,
         state_variable: linopy.Variable,
-        minimum_duration: Optional[NumericData] = None,
-        maximum_duration: Optional[NumericData] = None,
-        previous_states: Optional[NumericData] = None,
-        label: Optional[str] = None,
+        minimum_duration: NumericData | None = None,
+        maximum_duration: NumericData | None = None,
+        previous_states: NumericData | None = None,
+        label: str | None = None,
     ):
         """
         Model and constraint the consecutive duration of a state variable.
@@ -576,7 +579,7 @@ class ConsecutiveStateModel(Model):
 
     @staticmethod
     def compute_consecutive_hours_in_state(
-        binary_values: NumericData, hours_per_timestep: Union[int, float, np.ndarray]
+        binary_values: NumericData, hours_per_timestep: int | float | np.ndarray
     ) -> Scalar:
         """
         Computes the final consecutive duration in state 'on' (=1) in hours, from a binary array.
@@ -616,7 +619,7 @@ class ConsecutiveStateModel(Model):
         if len(hours_per_timestep) < nr_of_indexes_with_consecutive_ones:
             raise ValueError(
                 f'When trying to calculate the consecutive duration, the length of the last duration '
-                f'({len(nr_of_indexes_with_consecutive_ones)}) is longer than the provided hours_per_timestep ({len(hours_per_timestep)}), '
+                f'({nr_of_indexes_with_consecutive_ones}) is longer than the provided hours_per_timestep ({len(hours_per_timestep)}), '
                 f'as {binary_values=}'
             )
 
@@ -637,10 +640,10 @@ class OnOffModel(Model):
         model: SystemModel,
         on_off_parameters: OnOffParameters,
         label_of_element: str,
-        defining_variables: List[linopy.Variable],
-        defining_bounds: List[Tuple[NumericData, NumericData]],
-        previous_values: List[Optional[NumericData]],
-        label: Optional[str] = None,
+        defining_variables: list[linopy.Variable],
+        defining_bounds: list[tuple[NumericData, NumericData]],
+        previous_values: list[NumericData | None],
+        label: str | None = None,
     ):
         """
         Constructor for OnOffModel
@@ -786,9 +789,9 @@ class PieceModel(Model):
         as_time_series: bool = True,
     ):
         super().__init__(model, label_of_element, label)
-        self.inside_piece: Optional[linopy.Variable] = None
-        self.lambda0: Optional[linopy.Variable] = None
-        self.lambda1: Optional[linopy.Variable] = None
+        self.inside_piece: linopy.Variable | None = None
+        self.lambda0: linopy.Variable | None = None
+        self.lambda1: linopy.Variable | None = None
         self._as_time_series = as_time_series
 
     def do_modeling(self):
@@ -835,8 +838,8 @@ class PiecewiseModel(Model):
         self,
         model: SystemModel,
         label_of_element: str,
-        piecewise_variables: Dict[str, Piecewise],
-        zero_point: Optional[Union[bool, linopy.Variable]],
+        piecewise_variables: dict[str, Piecewise],
+        zero_point: bool | linopy.Variable | None,
         as_time_series: bool,
         label: str = '',
     ):
@@ -858,8 +861,8 @@ class PiecewiseModel(Model):
         self._zero_point = zero_point
         self._as_time_series = as_time_series
 
-        self.pieces: List[PieceModel] = []
-        self.zero_point: Optional[linopy.Variable] = None
+        self.pieces: list[PieceModel] = []
+        self.zero_point: linopy.Variable | None = None
 
     def do_modeling(self):
         for i in range(len(list(self._piecewise_variables.values())[0])):
@@ -922,30 +925,30 @@ class ShareAllocationModel(Model):
         self,
         model: SystemModel,
         shares_are_time_series: bool,
-        label_of_element: Optional[str] = None,
-        label: Optional[str] = None,
-        label_full: Optional[str] = None,
-        total_max: Optional[Scalar] = None,
-        total_min: Optional[Scalar] = None,
-        max_per_hour: Optional[NumericData] = None,
-        min_per_hour: Optional[NumericData] = None,
+        label_of_element: str | None = None,
+        label: str | None = None,
+        label_full: str | None = None,
+        total_max: Scalar | None = None,
+        total_min: Scalar | None = None,
+        max_per_hour: NumericData | None = None,
+        min_per_hour: NumericData | None = None,
     ):
         super().__init__(model, label_of_element=label_of_element, label=label, label_full=label_full)
         if not shares_are_time_series:  # If the condition is True
             assert max_per_hour is None and min_per_hour is None, (
                 'Both max_per_hour and min_per_hour cannot be used when shares_are_time_series is False'
             )
-        self.total_per_timestep: Optional[linopy.Variable] = None
-        self.total: Optional[linopy.Variable] = None
-        self.shares: Dict[str, linopy.Variable] = {}
-        self.share_constraints: Dict[str, linopy.Constraint] = {}
+        self.total_per_timestep: linopy.Variable | None = None
+        self.total: linopy.Variable | None = None
+        self.shares: dict[str, linopy.Variable] = {}
+        self.share_constraints: dict[str, linopy.Constraint] = {}
 
-        self._eq_total_per_timestep: Optional[linopy.Constraint] = None
-        self._eq_total: Optional[linopy.Constraint] = None
+        self._eq_total_per_timestep: linopy.Constraint | None = None
+        self._eq_total: linopy.Constraint | None = None
 
         # Parameters
         self._shares_are_time_series = shares_are_time_series
-        self._total_max = total_max if total_min is not None else np.inf
+        self._total_max = total_max if total_max is not None else np.inf
         self._total_min = total_min if total_min is not None else -np.inf
         self._max_per_hour = max_per_hour if max_per_hour is not None else np.inf
         self._min_per_hour = min_per_hour if min_per_hour is not None else -np.inf
@@ -1028,9 +1031,9 @@ class PiecewiseEffectsModel(Model):
         self,
         model: SystemModel,
         label_of_element: str,
-        piecewise_origin: Tuple[str, Piecewise],
-        piecewise_shares: Dict[str, Piecewise],
-        zero_point: Optional[Union[bool, linopy.Variable]],
+        piecewise_origin: tuple[str, Piecewise],
+        piecewise_shares: dict[str, Piecewise],
+        zero_point: bool | linopy.Variable | None,
         label: str = 'PiecewiseEffects',
     ):
         super().__init__(model, label_of_element, label)
@@ -1040,9 +1043,9 @@ class PiecewiseEffectsModel(Model):
         self._zero_point = zero_point
         self._piecewise_origin = piecewise_origin
         self._piecewise_shares = piecewise_shares
-        self.shares: Dict[str, linopy.Variable] = {}
+        self.shares: dict[str, linopy.Variable] = {}
 
-        self.piecewise_model: Optional[PiecewiseModel] = None
+        self.piecewise_model: PiecewiseModel | None = None
 
     def do_modeling(self):
         self.shares = {
@@ -1100,7 +1103,7 @@ class PreventSimultaneousUsageModel(Model):
     def __init__(
         self,
         model: SystemModel,
-        variables: List[linopy.Variable],
+        variables: list[linopy.Variable],
         label_of_element: str,
         label: str = 'PreventSimultaneousUsage',
     ):

flixopt/flow_system.py

@@ -2,50 +2,71 @@
 This module contains the FlowSystem class, which is used to collect instances of many other classes by the end User.
 """
 
+from __future__ import annotations
+
 import json
 import logging
-import pathlib
 import warnings
 from io import StringIO
-from typing import TYPE_CHECKING, Dict, List, Literal, Optional, Tuple, Union
+from typing import TYPE_CHECKING, Literal
 
-import numpy as np
 import pandas as pd
-import xarray as xr
 from rich.console import Console
 from rich.pretty import Pretty
 
 from . import io as fx_io
-from .core import NumericData, NumericDataTS, TimeSeries, TimeSeriesCollection, TimeSeriesData
+from .core import NumericData, TimeSeries, TimeSeriesCollection, TimeSeriesData
 from .effects import Effect, EffectCollection, EffectTimeSeries, EffectValuesDict, EffectValuesUser
 from .elements import Bus, Component, Flow
-from .structure import CLASS_REGISTRY, Element, SystemModel, get_compact_representation, get_str_representation
+from .structure import CLASS_REGISTRY, Element, SystemModel
 
 if TYPE_CHECKING:
+    import pathlib
+
+    import numpy as np
     import pyvis
+    import xarray as xr
 
 logger = logging.getLogger('flixopt')
 
 
 class FlowSystem:
     """
-    A FlowSystem organizes the high level Elements (Components & Effects).
+    A FlowSystem organizes the high level Elements (Components, Buses & Effects).
+
+    This is the main container class that users work with to build and manage their System.
+
+    Args:
+        timesteps: The timesteps of the model.
+        hours_of_last_timestep: The duration of the last time step. Uses the last time interval if not specified
+        hours_of_previous_timesteps: The duration of previous timesteps.
+            If None, the first time increment of time_series is used.
+            This is needed to calculate previous durations (for example consecutive_on_hours).
+            If you use an array, take care that its long enough to cover all previous values!
+
+    Notes:
+        - Creates an empty registry for components and buses, an empty EffectCollection, and a placeholder for a SystemModel.
+        - The instance starts disconnected (self._connected == False) and will be connected automatically when trying to solve a calculation.
     """
 
     def __init__(
         self,
         timesteps: pd.DatetimeIndex,
-        hours_of_last_timestep: Optional[float] = None,
-        hours_of_previous_timesteps: Optional[Union[int, float, np.ndarray]] = None,
+        hours_of_last_timestep: float | None = None,
+        hours_of_previous_timesteps: int | float | np.ndarray | None = None,
     ):
         """
-        Args:
-            timesteps: The timesteps of the model.
-            hours_of_last_timestep: The duration of the last time step. Uses the last time interval if not specified
-            hours_of_previous_timesteps: The duration of previous timesteps.
-                If None, the first time increment of time_series is used.
-                This is needed to calculate previous durations (for example consecutive_on_hours).
-                If you use an array, take care that its long enough to cover all previous values!
+        Initialize a FlowSystem that manages components, buses, effects, and their time-series.
+
+        Parameters:
+            timesteps: DatetimeIndex defining the primary timesteps for the system's TimeSeriesCollection.
+            hours_of_last_timestep: Duration (in hours) of the final timestep; if None, inferred from timesteps or defaults in TimeSeriesCollection.
+            hours_of_previous_timesteps: Scalar or array-like durations (in hours) for the preceding timesteps; used to configure non-uniform timestep lengths.
+
+        Notes:
+            Creates an empty registry for components and buses, an empty EffectCollection, and a placeholder for a SystemModel.
+            The instance starts disconnected (self._connected == False) and with no active network visualization app.
+            This can also be triggered manually with `_connect_network()`.
         """
         self.time_series_collection = TimeSeriesCollection(
             timesteps=timesteps,
@@ -54,10 +75,10 @@ class FlowSystem:
         )
 
         # defaults:
-        self.components: Dict[str, Component] = {}
-        self.buses: Dict[str, Bus] = {}
+        self.components: dict[str, Component] = {}
+        self.buses: dict[str, Bus] = {}
         self.effects: EffectCollection = EffectCollection()
-        self.model: Optional[SystemModel] = None
+        self.model: SystemModel | None = None
 
         self._connected = False
 
@@ -83,7 +104,7 @@ class FlowSystem:
         return flow_system
 
     @classmethod
-    def from_dict(cls, data: Dict) -> 'FlowSystem':
+    def from_dict(cls, data: dict) -> FlowSystem:
         """
         Load a FlowSystem from a dictionary.
 
@@ -112,7 +133,7 @@ class FlowSystem:
         return flow_system
 
     @classmethod
-    def from_netcdf(cls, path: Union[str, pathlib.Path]):
+    def from_netcdf(cls, path: str | pathlib.Path):
         """
         Load a FlowSystem from a netcdf file
         """
@@ -144,7 +165,7 @@ class FlowSystem:
                     f'Tried to add incompatible object to FlowSystem: {type(new_element)=}: {new_element=} '
                 )
 
-    def to_json(self, path: Union[str, pathlib.Path]):
+    def to_json(self, path: str | pathlib.Path):
         """
         Saves the flow system to a json file.
         This not meant to be reloaded and recreate the object,
@@ -156,7 +177,7 @@ class FlowSystem:
         with open(path, 'w', encoding='utf-8') as f:
             json.dump(self.as_dict('stats'), f, indent=4, ensure_ascii=False)
 
-    def as_dict(self, data_mode: Literal['data', 'name', 'stats'] = 'data') -> Dict:
+    def as_dict(self, data_mode: Literal['data', 'name', 'stats'] = 'data') -> dict:
         """Convert the object to a dictionary representation."""
         data = {
             'components': {
@@ -190,7 +211,7 @@ class FlowSystem:
         ds.attrs = self.as_dict(data_mode='name')
         return ds
 
-    def to_netcdf(self, path: Union[str, pathlib.Path], compression: int = 0, constants_in_dataset: bool = True):
+    def to_netcdf(self, path: str | pathlib.Path, compression: int = 0, constants_in_dataset: bool = True):
         """
         Saves the FlowSystem to a netCDF file.
         Args:
@@ -204,15 +225,13 @@ class FlowSystem:
 
     def plot_network(
         self,
-        path: Union[bool, str, pathlib.Path] = 'flow_system.html',
-        controls: Union[
-            bool,
-            List[
-                Literal['nodes', 'edges', 'layout', 'interaction', 'manipulation', 'physics', 'selection', 'renderer']
-            ],
+        path: bool | str | pathlib.Path = 'flow_system.html',
+        controls: bool
+        | list[
+            Literal['nodes', 'edges', 'layout', 'interaction', 'manipulation', 'physics', 'selection', 'renderer']
         ] = True,
         show: bool = False,
-    ) -> Optional['pyvis.network.Network']:
+    ) -> pyvis.network.Network | None:
         """
         Visualizes the network structure of a FlowSystem using PyVis, saving it as an interactive HTML file.
 
@@ -227,7 +246,7 @@ class FlowSystem:
             show: Whether to open the visualization in the web browser.
 
         Returns:
-        - Optional[pyvis.network.Network]: The `Network` instance representing the visualization, or `None` if `pyvis` is not installed.
+        - 'pyvis.network.Network' | None: The `Network` instance representing the visualization, or `None` if `pyvis` is not installed.
 
         Examples:
             >>> flow_system.plot_network()
@@ -245,7 +264,7 @@ class FlowSystem:
 
     def start_network_app(self):
         """Visualizes the network structure of a FlowSystem using Dash, Cytoscape, and networkx.
-        Requires optional dependencies: dash, dash-cytoscape, networkx, werkzeug.
+        Requires optional dependencies: dash, dash-cytoscape, dash-daq, networkx, flask, werkzeug.
         """
         from .network_app import DASH_CYTOSCAPE_AVAILABLE, VISUALIZATION_ERROR, flow_graph, shownetwork
 
@@ -258,7 +277,8 @@ class FlowSystem:
         if not DASH_CYTOSCAPE_AVAILABLE:
             raise ImportError(
                 f'Network visualization requires optional dependencies. '
-                f'Install with: pip install flixopt[viz], flixopt[full] or pip install dash dash_cytoscape networkx werkzeug. '
+                f'Install with: `pip install flixopt[network_viz]`, `pip install flixopt[full]` '
+                f'or: `pip install dash dash-cytoscape dash-daq networkx werkzeug`. '
                 f'Original error: {VISUALIZATION_ERROR}'
             )
 
@@ -278,7 +298,8 @@ class FlowSystem:
         if not DASH_CYTOSCAPE_AVAILABLE:
             raise ImportError(
                 f'Network visualization requires optional dependencies. '
-                f'Install with: pip install flixopt[viz]. '
+                f'Install with: `pip install flixopt[network_viz]`, `pip install flixopt[full]` '
+                f'or: `pip install dash dash-cytoscape dash-daq networkx werkzeug`. '
                 f'Original error: {VISUALIZATION_ERROR}'
             )
 
@@ -295,7 +316,7 @@ class FlowSystem:
         finally:
             self._network_app = None
 
-    def network_infos(self) -> Tuple[Dict[str, Dict[str, str]], Dict[str, Dict[str, str]]]:
+    def network_infos(self) -> tuple[dict[str, dict[str, str]], dict[str, dict[str, str]]]:
         if not self._connected:
             self._connect_network()
         nodes = {
@@ -328,9 +349,9 @@ class FlowSystem:
     def create_time_series(
         self,
         name: str,
-        data: Optional[Union[NumericData, TimeSeriesData, TimeSeries]],
+        data: NumericData | TimeSeriesData | TimeSeries | None,
         needs_extra_timestep: bool = False,
-    ) -> Optional[TimeSeries]:
+    ) -> TimeSeries | None:
         """
         Tries to create a TimeSeries from NumericData Data and adds it to the time_series_collection
         If the data already is a TimeSeries, nothing happens and the TimeSeries gets reset and returned
@@ -353,10 +374,10 @@ class FlowSystem:
 
     def create_effect_time_series(
         self,
-        label_prefix: Optional[str],
+        label_prefix: str | None,
         effect_values: EffectValuesUser,
-        label_suffix: Optional[str] = None,
-    ) -> Optional[EffectTimeSeries]:
+        label_suffix: str | None = None,
+    ) -> EffectTimeSeries | None:
         """
         Transform EffectValues to EffectTimeSeries.
         Creates a TimeSeries for each key in the nested_values dictionary, using the value as the data.
@@ -365,13 +386,13 @@ class FlowSystem:
         followed by the label of the Effect in the nested_values and the label_suffix.
         If the key in the EffectValues is None, the alias 'Standard_Effect' is used
         """
-        effect_values: Optional[EffectValuesDict] = self.effects.create_effect_values_dict(effect_values)
-        if effect_values is None:
+        effect_values_dict: EffectValuesDict | None = self.effects.create_effect_values_dict(effect_values)
+        if effect_values_dict is None:
             return None
 
         return {
             effect: self.create_time_series('|'.join(filter(None, [label_prefix, effect, label_suffix])), value)
-            for effect, value in effect_values.items()
+            for effect, value in effect_values_dict.items()
         }
 
     def create_model(self) -> SystemModel:
@@ -417,14 +438,14 @@ class FlowSystem:
 
                 # Add Bus if not already added (deprecated)
                 if flow._bus_object is not None and flow._bus_object not in self.buses.values():
-                    self._add_buses(flow._bus_object)
                     warnings.warn(
                         f'The Bus {flow._bus_object.label} was added to the FlowSystem from {flow.label_full}.'
                         f'This is deprecated and will be removed in the future. '
                         f'Please pass the Bus.label to the Flow and the Bus to the FlowSystem instead.',
-                        UserWarning,
+                        DeprecationWarning,
                         stacklevel=1,
                     )
+                    self._add_buses(flow._bus_object)
 
                 # Connect Buses
                 bus = self.buses.get(flow.bus)
@@ -454,10 +475,10 @@ class FlowSystem:
         return value
 
     @property
-    def flows(self) -> Dict[str, Flow]:
+    def flows(self) -> dict[str, Flow]:
         set_of_flows = {flow for comp in self.components.values() for flow in comp.inputs + comp.outputs}
         return {flow.label_full: flow for flow in set_of_flows}
 
     @property
-    def all_elements(self) -> Dict[str, Element]:
+    def all_elements(self) -> dict[str, Element]:
         return {**self.components, **self.effects.effects, **self.flows, **self.buses}