flixopt 3.0.1__py3-none-any.whl → 6.0.0rc7__py3-none-any.whl

flixopt/components.py

@@ -4,6 +4,7 @@ This module contains the basic components of the flixopt framework.
 
 from __future__ import annotations
 
+import functools
 import logging
 import warnings
 from typing import TYPE_CHECKING, Literal
@@ -11,17 +12,18 @@ from typing import TYPE_CHECKING, Literal
 import numpy as np
 import xarray as xr
 
-from .core import PeriodicDataUser, PlausibilityError, TemporalData, TemporalDataUser
+from . import io as fx_io
+from .core import PlausibilityError
 from .elements import Component, ComponentModel, Flow
 from .features import InvestmentModel, PiecewiseModel
-from .interface import InvestParameters, OnOffParameters, PiecewiseConversion
-from .modeling import BoundingPatterns
-from .structure import FlowSystemModel, register_class_for_io
+from .interface import InvestParameters, PiecewiseConversion, StatusParameters
+from .modeling import BoundingPatterns, _scalar_safe_isel, _scalar_safe_isel_drop, _scalar_safe_reduce
+from .structure import FlowSystemModel, VariableCategory, register_class_for_io
 
 if TYPE_CHECKING:
     import linopy
 
-    from .flow_system import FlowSystem
+    from .types import Numeric_PS, Numeric_TPS
 
 logger = logging.getLogger('flixopt')
 
@@ -41,16 +43,15 @@ class LinearConverter(Component):
     behavior approximated through piecewise linear segments.
 
     Mathematical Formulation:
-        See the complete mathematical model in the documentation:
-        [LinearConverter](../user-guide/mathematical-notation/elements/LinearConverter.md)
+        See <https://flixopt.github.io/flixopt/latest/user-guide/mathematical-notation/elements/LinearConverter/>
 
     Args:
         label: The label of the Element. Used to identify it in the FlowSystem.
         inputs: list of input Flows that feed into the converter.
         outputs: list of output Flows that are produced by the converter.
-        on_off_parameters: Information about on and off state of LinearConverter.
-            Component is On/Off if all connected Flows are On/Off. This induces an
-            On-Variable (binary) in all Flows! If possible, use OnOffParameters in a
+        status_parameters: Information about active and inactive state of LinearConverter.
+            Component is active/inactive if all connected Flows are active/inactive. This induces a
+            status variable (binary) in all Flows! If possible, use StatusParameters in a
             single Flow instead to keep the number of binary variables low.
         conversion_factors: Linear relationships between flows expressed as a list of
             dictionaries. Each dictionary maps flow labels to their coefficients in one
@@ -160,17 +161,20 @@ class LinearConverter(Component):
 
     """
 
+    submodel: LinearConverterModel | None
+
     def __init__(
         self,
         label: str,
         inputs: list[Flow],
         outputs: list[Flow],
-        on_off_parameters: OnOffParameters | None = None,
-        conversion_factors: list[dict[str, TemporalDataUser]] | None = None,
+        status_parameters: StatusParameters | None = None,
+        conversion_factors: list[dict[str, Numeric_TPS]] | None = None,
         piecewise_conversion: PiecewiseConversion | None = None,
         meta_data: dict | None = None,
+        color: str | None = None,
     ):
-        super().__init__(label, inputs, outputs, on_off_parameters, meta_data=meta_data)
+        super().__init__(label, inputs, outputs, status_parameters, meta_data=meta_data, color=color)
         self.conversion_factors = conversion_factors or []
         self.piecewise_conversion = piecewise_conversion
 
@@ -179,6 +183,12 @@ class LinearConverter(Component):
         self.submodel = LinearConverterModel(model, self)
         return self.submodel
 
+    def link_to_flow_system(self, flow_system, prefix: str = '') -> None:
+        """Propagate flow_system reference to parent Component and piecewise_conversion."""
+        super().link_to_flow_system(flow_system, prefix)
+        if self.piecewise_conversion is not None:
+            self.piecewise_conversion.link_to_flow_system(flow_system, self._sub_prefix('PiecewiseConversion'))
+
     def _plausibility_checks(self) -> None:
         super()._plausibility_checks()
         if not self.conversion_factors and not self.piecewise_conversion:
@@ -209,23 +219,22 @@ class LinearConverter(Component):
                         f'({flow.label_full}).'
                     )
 
-    def transform_data(self, flow_system: FlowSystem, name_prefix: str = '') -> None:
-        prefix = '|'.join(filter(None, [name_prefix, self.label_full]))
-        super().transform_data(flow_system, prefix)
+    def transform_data(self) -> None:
+        super().transform_data()
         if self.conversion_factors:
-            self.conversion_factors = self._transform_conversion_factors(flow_system)
+            self.conversion_factors = self._transform_conversion_factors()
         if self.piecewise_conversion:
             self.piecewise_conversion.has_time_dim = True
-            self.piecewise_conversion.transform_data(flow_system, f'{prefix}|PiecewiseConversion')
+            self.piecewise_conversion.transform_data()
 
-    def _transform_conversion_factors(self, flow_system: FlowSystem) -> list[dict[str, xr.DataArray]]:
+    def _transform_conversion_factors(self) -> list[dict[str, xr.DataArray]]:
         """Converts all conversion factors to internal datatypes"""
         list_of_conversion_factors = []
         for idx, conversion_factor in enumerate(self.conversion_factors):
             transformed_dict = {}
             for flow, values in conversion_factor.items():
                 # TODO: Might be better to use the label of the component instead of the flow
-                ts = flow_system.fit_to_model_coords(f'{self.flows[flow].label_full}|conversion_factor{idx}', values)
+                ts = self._fit_coords(f'{self.flows[flow].label_full}|conversion_factor{idx}', values)
                 if ts is None:
                     raise PlausibilityError(f'{self.label_full}: conversion factor for flow "{flow}" must not be None')
                 transformed_dict[flow] = ts
@@ -252,28 +261,19 @@ class Storage(Component):
     and investment-optimized storage systems with comprehensive techno-economic modeling.
 
     Mathematical Formulation:
-        See the complete mathematical model in the documentation:
-        [Storage](../user-guide/mathematical-notation/elements/Storage.md)
-
-        - Equation (1): Charge state bounds
-        - Equation (3): Storage balance (charge state evolution)
-
-        Variable Mapping:
-            - ``capacity_in_flow_hours`` → C (storage capacity)
-            - ``charge_state`` → c(t_i) (state of charge at time t_i)
-            - ``relative_loss_per_hour`` → ċ_rel,loss (self-discharge rate)
-            - ``eta_charge`` → η_in (charging efficiency)
-            - ``eta_discharge`` → η_out (discharging efficiency)
+        See <https://flixopt.github.io/flixopt/latest/user-guide/mathematical-notation/elements/Storage/>
 
     Args:
         label: Element identifier used in the FlowSystem.
         charging: Incoming flow for loading the storage.
         discharging: Outgoing flow for unloading the storage.
         capacity_in_flow_hours: Storage capacity in flow-hours (kWh, m³, kg).
-            Scalar for fixed size or InvestParameters for optimization.
+            Scalar for fixed size, InvestParameters for optimization, or None (unbounded).
+            Default: None (unbounded capacity). When using InvestParameters,
+            maximum_size (or fixed_size) must be explicitly set for proper model scaling.
         relative_minimum_charge_state: Minimum charge state (0-1). Default: 0.
         relative_maximum_charge_state: Maximum charge state (0-1). Default: 1.
-        initial_charge_state: Charge at start. Numeric or 'lastValueOfSim'. Default: 0.
+        initial_charge_state: Charge at start. Numeric, 'equals_final', or None (free). Default: 0.
         minimal_final_charge_state: Minimum absolute charge required at end (optional).
         maximal_final_charge_state: Maximum absolute charge allowed at end (optional).
         relative_minimum_final_charge_state: Minimum relative charge at end.
@@ -285,6 +285,21 @@ class Storage(Component):
         relative_loss_per_hour: Self-discharge per hour (0-0.1). Default: 0.
         prevent_simultaneous_charge_and_discharge: Prevent charging and discharging
             simultaneously. Adds binary variables. Default: True.
+        cluster_mode: How this storage is treated during clustering optimization.
+            Only relevant when using ``transform.cluster()``. Options:
+
+            - ``'independent'``: Clusters are fully decoupled. No constraints between
+              clusters, each cluster has free start/end SOC. Fast but ignores
+              seasonal storage value.
+            - ``'cyclic'``: Each cluster is self-contained. The SOC at the start of
+              each cluster equals its end (cluster returns to initial state).
+              Good for "average day" modeling.
+            - ``'intercluster'``: Link storage state across the original timeline using
+              SOC boundary variables (Kotzur et al. approach). Properly values
+              seasonal storage patterns. Overall SOC can drift.
+            - ``'intercluster_cyclic'`` (default): Like 'intercluster' but also enforces
+              that overall SOC returns to initial state (yearly cyclic).
+
         meta_data: Additional information stored in results. Python native types only.
 
     Examples:
@@ -337,7 +352,7 @@ class Storage(Component):
             ),
             eta_charge=0.85,  # Pumping efficiency
             eta_discharge=0.90,  # Turbine efficiency
-            initial_charge_state='lastValueOfSim',  # Ensuring no deficit compared to start
+            initial_charge_state='equals_final',  # Ensuring no deficit compared to start
             relative_loss_per_hour=0.0001,  # Minimal evaporation
         )
         ```
@@ -371,30 +386,39 @@ class Storage(Component):
         variables enforce mutual exclusivity, increasing solution time but preventing unrealistic
         simultaneous charging and discharging.
 
+        **Unbounded capacity**: When capacity_in_flow_hours is None (default), the storage has
+        unlimited capacity. Note that prevent_simultaneous_charge_and_discharge requires the
+        charging and discharging flows to have explicit sizes. Use prevent_simultaneous_charge_and_discharge=False
+        with unbounded storages, or set flow sizes explicitly.
+
         **Units**: Flow rates and charge states are related by the concept of 'flow hours' (=flow_rate * time).
         With flow rates in kW, the charge state is therefore (usually) kWh.
         With flow rates in m3/h, the charge state is therefore in m3.
     """
 
+    submodel: StorageModel | None
+
     def __init__(
         self,
         label: str,
         charging: Flow,
         discharging: Flow,
-        capacity_in_flow_hours: PeriodicDataUser | InvestParameters,
-        relative_minimum_charge_state: TemporalDataUser = 0,
-        relative_maximum_charge_state: TemporalDataUser = 1,
-        initial_charge_state: PeriodicDataUser | Literal['lastValueOfSim'] = 0,
-        minimal_final_charge_state: PeriodicDataUser | None = None,
-        maximal_final_charge_state: PeriodicDataUser | None = None,
-        relative_minimum_final_charge_state: PeriodicDataUser | None = None,
-        relative_maximum_final_charge_state: PeriodicDataUser | None = None,
-        eta_charge: TemporalDataUser = 1,
-        eta_discharge: TemporalDataUser = 1,
-        relative_loss_per_hour: TemporalDataUser = 0,
+        capacity_in_flow_hours: Numeric_PS | InvestParameters | None = None,
+        relative_minimum_charge_state: Numeric_TPS = 0,
+        relative_maximum_charge_state: Numeric_TPS = 1,
+        initial_charge_state: Numeric_PS | Literal['equals_final'] | None = 0,
+        minimal_final_charge_state: Numeric_PS | None = None,
+        maximal_final_charge_state: Numeric_PS | None = None,
+        relative_minimum_final_charge_state: Numeric_PS | None = None,
+        relative_maximum_final_charge_state: Numeric_PS | None = None,
+        eta_charge: Numeric_TPS = 1,
+        eta_discharge: Numeric_TPS = 1,
+        relative_loss_per_hour: Numeric_TPS = 0,
         prevent_simultaneous_charge_and_discharge: bool = True,
         balanced: bool = False,
+        cluster_mode: Literal['independent', 'cyclic', 'intercluster', 'intercluster_cyclic'] = 'intercluster_cyclic',
         meta_data: dict | None = None,
+        color: str | None = None,
     ):
         # TODO: fixed_relative_chargeState implementieren
         super().__init__(
@@ -403,13 +427,14 @@ class Storage(Component):
             outputs=[discharging],
             prevent_simultaneous_flows=[charging, discharging] if prevent_simultaneous_charge_and_discharge else None,
             meta_data=meta_data,
+            color=color,
         )
 
         self.charging = charging
         self.discharging = discharging
         self.capacity_in_flow_hours = capacity_in_flow_hours
-        self.relative_minimum_charge_state: TemporalDataUser = relative_minimum_charge_state
-        self.relative_maximum_charge_state: TemporalDataUser = relative_maximum_charge_state
+        self.relative_minimum_charge_state: Numeric_TPS = relative_minimum_charge_state
+        self.relative_maximum_charge_state: Numeric_TPS = relative_maximum_charge_state
 
         self.relative_minimum_final_charge_state = relative_minimum_final_charge_state
         self.relative_maximum_final_charge_state = relative_maximum_final_charge_state
@@ -418,58 +443,86 @@ class Storage(Component):
         self.minimal_final_charge_state = minimal_final_charge_state
         self.maximal_final_charge_state = maximal_final_charge_state
 
-        self.eta_charge: TemporalDataUser = eta_charge
-        self.eta_discharge: TemporalDataUser = eta_discharge
-        self.relative_loss_per_hour: TemporalDataUser = relative_loss_per_hour
+        self.eta_charge: Numeric_TPS = eta_charge
+        self.eta_discharge: Numeric_TPS = eta_discharge
+        self.relative_loss_per_hour: Numeric_TPS = relative_loss_per_hour
         self.prevent_simultaneous_charge_and_discharge = prevent_simultaneous_charge_and_discharge
         self.balanced = balanced
+        self.cluster_mode = cluster_mode
 
     def create_model(self, model: FlowSystemModel) -> StorageModel:
+        """Create the appropriate storage model based on cluster_mode and flow system state.
+
+        For intercluster modes ('intercluster', 'intercluster_cyclic'), uses
+        :class:`InterclusterStorageModel` which implements S-N linking.
+        For other modes, uses the base :class:`StorageModel`.
+
+        Args:
+            model: The FlowSystemModel to add constraints to.
+
+        Returns:
+            StorageModel or InterclusterStorageModel instance.
+        """
         self._plausibility_checks()
-        self.submodel = StorageModel(model, self)
+
+        # Use InterclusterStorageModel for intercluster modes when clustering is active
+        clustering = model.flow_system.clustering
+        is_intercluster = clustering is not None and self.cluster_mode in (
+            'intercluster',
+            'intercluster_cyclic',
+        )
+
+        if is_intercluster:
+            self.submodel = InterclusterStorageModel(model, self)
+        else:
+            self.submodel = StorageModel(model, self)
+
         return self.submodel
 
-    def transform_data(self, flow_system: FlowSystem, name_prefix: str = '') -> None:
-        prefix = '|'.join(filter(None, [name_prefix, self.label_full]))
-        super().transform_data(flow_system, prefix)
-        self.relative_minimum_charge_state = flow_system.fit_to_model_coords(
-            f'{prefix}|relative_minimum_charge_state',
-            self.relative_minimum_charge_state,
+    def link_to_flow_system(self, flow_system, prefix: str = '') -> None:
+        """Propagate flow_system reference to parent Component and capacity_in_flow_hours if it's InvestParameters."""
+        super().link_to_flow_system(flow_system, prefix)
+        if isinstance(self.capacity_in_flow_hours, InvestParameters):
+            self.capacity_in_flow_hours.link_to_flow_system(flow_system, self._sub_prefix('InvestParameters'))
+
+    def transform_data(self) -> None:
+        super().transform_data()
+        self.relative_minimum_charge_state = self._fit_coords(
+            f'{self.prefix}|relative_minimum_charge_state', self.relative_minimum_charge_state
         )
-        self.relative_maximum_charge_state = flow_system.fit_to_model_coords(
-            f'{prefix}|relative_maximum_charge_state',
-            self.relative_maximum_charge_state,
+        self.relative_maximum_charge_state = self._fit_coords(
+            f'{self.prefix}|relative_maximum_charge_state', self.relative_maximum_charge_state
         )
-        self.eta_charge = flow_system.fit_to_model_coords(f'{prefix}|eta_charge', self.eta_charge)
-        self.eta_discharge = flow_system.fit_to_model_coords(f'{prefix}|eta_discharge', self.eta_discharge)
-        self.relative_loss_per_hour = flow_system.fit_to_model_coords(
-            f'{prefix}|relative_loss_per_hour', self.relative_loss_per_hour
+        self.eta_charge = self._fit_coords(f'{self.prefix}|eta_charge', self.eta_charge)
+        self.eta_discharge = self._fit_coords(f'{self.prefix}|eta_discharge', self.eta_discharge)
+        self.relative_loss_per_hour = self._fit_coords(
+            f'{self.prefix}|relative_loss_per_hour', self.relative_loss_per_hour
         )
-        if not isinstance(self.initial_charge_state, str):
-            self.initial_charge_state = flow_system.fit_to_model_coords(
-                f'{prefix}|initial_charge_state', self.initial_charge_state, dims=['period', 'scenario']
+        if self.initial_charge_state is not None and not isinstance(self.initial_charge_state, str):
+            self.initial_charge_state = self._fit_coords(
+                f'{self.prefix}|initial_charge_state', self.initial_charge_state, dims=['period', 'scenario']
             )
-        self.minimal_final_charge_state = flow_system.fit_to_model_coords(
-            f'{prefix}|minimal_final_charge_state', self.minimal_final_charge_state, dims=['period', 'scenario']
+        self.minimal_final_charge_state = self._fit_coords(
+            f'{self.prefix}|minimal_final_charge_state', self.minimal_final_charge_state, dims=['period', 'scenario']
         )
-        self.maximal_final_charge_state = flow_system.fit_to_model_coords(
-            f'{prefix}|maximal_final_charge_state', self.maximal_final_charge_state, dims=['period', 'scenario']
+        self.maximal_final_charge_state = self._fit_coords(
+            f'{self.prefix}|maximal_final_charge_state', self.maximal_final_charge_state, dims=['period', 'scenario']
         )
-        self.relative_minimum_final_charge_state = flow_system.fit_to_model_coords(
-            f'{prefix}|relative_minimum_final_charge_state',
+        self.relative_minimum_final_charge_state = self._fit_coords(
+            f'{self.prefix}|relative_minimum_final_charge_state',
             self.relative_minimum_final_charge_state,
             dims=['period', 'scenario'],
         )
-        self.relative_maximum_final_charge_state = flow_system.fit_to_model_coords(
-            f'{prefix}|relative_maximum_final_charge_state',
+        self.relative_maximum_final_charge_state = self._fit_coords(
+            f'{self.prefix}|relative_maximum_final_charge_state',
             self.relative_maximum_final_charge_state,
             dims=['period', 'scenario'],
         )
         if isinstance(self.capacity_in_flow_hours, InvestParameters):
-            self.capacity_in_flow_hours.transform_data(flow_system, f'{prefix}|InvestParameters')
+            self.capacity_in_flow_hours.transform_data()
         else:
-            self.capacity_in_flow_hours = flow_system.fit_to_model_coords(
-                f'{prefix}|capacity_in_flow_hours', self.capacity_in_flow_hours, dims=['period', 'scenario']
+            self.capacity_in_flow_hours = self._fit_coords(
+                f'{self.prefix}|capacity_in_flow_hours', self.capacity_in_flow_hours, dims=['period', 'scenario']
             )
 
     def _plausibility_checks(self) -> None:
@@ -479,38 +532,68 @@ class Storage(Component):
         super()._plausibility_checks()
 
         # Validate string values and set flag
-        initial_is_last = False
+        initial_equals_final = False
         if isinstance(self.initial_charge_state, str):
-            if self.initial_charge_state == 'lastValueOfSim':
-                initial_is_last = True
-            else:
+            if not self.initial_charge_state == 'equals_final':
                 raise PlausibilityError(f'initial_charge_state has undefined value: {self.initial_charge_state}')
+            initial_equals_final = True
 
-        # Use new InvestParameters methods to get capacity bounds
-        if isinstance(self.capacity_in_flow_hours, InvestParameters):
-            minimum_capacity = self.capacity_in_flow_hours.minimum_or_fixed_size
-            maximum_capacity = self.capacity_in_flow_hours.maximum_or_fixed_size
-        else:
-            maximum_capacity = self.capacity_in_flow_hours
-            minimum_capacity = self.capacity_in_flow_hours
-
-        # Initial capacity should not constraint investment decision
-        minimum_initial_capacity = maximum_capacity * self.relative_minimum_charge_state.isel(time=0)
-        maximum_initial_capacity = minimum_capacity * self.relative_maximum_charge_state.isel(time=0)
-
-        # Only perform numeric comparisons if not using 'lastValueOfSim'
-        if not initial_is_last:
-            if (self.initial_charge_state > maximum_initial_capacity).any():
+        # Capacity is required when using non-default relative bounds
+        if self.capacity_in_flow_hours is None:
+            if np.any(self.relative_minimum_charge_state > 0):
+                raise PlausibilityError(
+                    f'Storage "{self.label_full}" has relative_minimum_charge_state > 0 but no capacity_in_flow_hours. '
+                    f'A capacity is required because the lower bound is capacity * relative_minimum_charge_state.'
+                )
+            if np.any(self.relative_maximum_charge_state < 1):
+                raise PlausibilityError(
+                    f'Storage "{self.label_full}" has relative_maximum_charge_state < 1 but no capacity_in_flow_hours. '
+                    f'A capacity is required because the upper bound is capacity * relative_maximum_charge_state.'
+                )
+            if self.relative_minimum_final_charge_state is not None:
                 raise PlausibilityError(
-                    f'{self.label_full}: {self.initial_charge_state=} '
-                    f'is constraining the investment decision. Chosse a value above {maximum_initial_capacity}'
+                    f'Storage "{self.label_full}" has relative_minimum_final_charge_state but no capacity_in_flow_hours. '
+                    f'A capacity is required for relative final charge state constraints.'
                 )
-            if (self.initial_charge_state < minimum_initial_capacity).any():
+            if self.relative_maximum_final_charge_state is not None:
                 raise PlausibilityError(
-                    f'{self.label_full}: {self.initial_charge_state=} '
-                    f'is constraining the investment decision. Chosse a value below {minimum_initial_capacity}'
+                    f'Storage "{self.label_full}" has relative_maximum_final_charge_state but no capacity_in_flow_hours. '
+                    f'A capacity is required for relative final charge state constraints.'
                 )
 
+        # Skip capacity-related checks if capacity is None (unbounded)
+        if self.capacity_in_flow_hours is not None:
+            # Use new InvestParameters methods to get capacity bounds
+            if isinstance(self.capacity_in_flow_hours, InvestParameters):
+                minimum_capacity = self.capacity_in_flow_hours.minimum_or_fixed_size
+                maximum_capacity = self.capacity_in_flow_hours.maximum_or_fixed_size
+            else:
+                maximum_capacity = self.capacity_in_flow_hours
+                minimum_capacity = self.capacity_in_flow_hours
+
+            # Initial charge state should not constrain investment decision
+            # If initial > (min_cap * rel_max), investment is forced to increase capacity
+            # If initial < (max_cap * rel_min), investment is forced to decrease capacity
+            min_initial_at_max_capacity = maximum_capacity * _scalar_safe_isel(
+                self.relative_minimum_charge_state, {'time': 0}
+            )
+            max_initial_at_min_capacity = minimum_capacity * _scalar_safe_isel(
+                self.relative_maximum_charge_state, {'time': 0}
+            )
+
+            # Only perform numeric comparisons if using a numeric initial_charge_state
+            if not initial_equals_final and self.initial_charge_state is not None:
+                if (self.initial_charge_state > max_initial_at_min_capacity).any():
+                    raise PlausibilityError(
+                        f'{self.label_full}: {self.initial_charge_state=} '
+                        f'is constraining the investment decision. Choose a value <= {max_initial_at_min_capacity}.'
+                    )
+                if (self.initial_charge_state < min_initial_at_max_capacity).any():
+                    raise PlausibilityError(
+                        f'{self.label_full}: {self.initial_charge_state=} '
+                        f'is constraining the investment decision. Choose a value >= {min_initial_at_max_capacity}.'
+                    )
+
         if self.balanced:
             if not isinstance(self.charging.size, InvestParameters) or not isinstance(
                 self.discharging.size, InvestParameters
@@ -519,15 +602,24 @@ class Storage(Component):
                     f'Balancing charging and discharging Flows in {self.label_full} is only possible with Investments.'
                 )
 
-            if (self.charging.size.minimum_size > self.discharging.size.maximum_size).any() or (
-                self.charging.size.maximum_size < self.discharging.size.minimum_size
+            if (self.charging.size.minimum_or_fixed_size > self.discharging.size.maximum_or_fixed_size).any() or (
+                self.charging.size.maximum_or_fixed_size < self.discharging.size.minimum_or_fixed_size
             ).any():
                 raise PlausibilityError(
                     f'Balancing charging and discharging Flows in {self.label_full} need compatible minimum and maximum sizes.'
-                    f'Got: {self.charging.size.minimum_size=}, {self.charging.size.maximum_size=} and '
-                    f'{self.discharging.size.minimum_size=}, {self.discharging.size.maximum_size=}.'
+                    f'Got: {self.charging.size.minimum_or_fixed_size=}, {self.charging.size.maximum_or_fixed_size=} and '
+                    f'{self.discharging.size.minimum_or_fixed_size=}, {self.discharging.size.maximum_or_fixed_size=}.'
                 )
 
+    def __repr__(self) -> str:
+        """Return string representation."""
+        # Use build_repr_from_init directly to exclude charging and discharging
+        return fx_io.build_repr_from_init(
+            self,
+            excluded_params={'self', 'label', 'charging', 'discharging', 'kwargs'},
+            skip_default_size=True,
+        ) + fx_io.format_flow_details(self)
+
 
 @register_class_for_io
 class Transmission(Component):
@@ -553,8 +645,8 @@ class Transmission(Component):
         relative_losses: Proportional losses as fraction of throughput (e.g., 0.02 for 2% loss).
             Applied as: output = input × (1 - relative_losses)
         absolute_losses: Fixed losses that occur when transmission is active.
-            Automatically creates binary variables for on/off states.
-        on_off_parameters: Parameters defining binary operation constraints and costs.
+            Automatically creates binary variables for active/inactive states.
+        status_parameters: Parameters defining binary operation constraints and costs.
         prevent_simultaneous_flows_in_both_directions: If True, prevents simultaneous
             flow in both directions. Increases binary variables but reflects physical
             reality for most transmission systems. Default is True.
@@ -609,7 +701,7 @@ class Transmission(Component):
         )
         ```
 
-        Material conveyor with on/off operation:
+        Material conveyor with active/inactive status:
 
         ```python
         conveyor_belt = Transmission(
@@ -617,10 +709,10 @@ class Transmission(Component):
             in1=loading_station,
             out1=unloading_station,
             absolute_losses=25,  # 25 kW motor power when running
-            on_off_parameters=OnOffParameters(
-                effects_per_switch_on={'maintenance': 0.1},
-                consecutive_on_hours_min=2,  # Minimum 2-hour operation
-                switch_on_total_max=10,  # Maximum 10 starts per day
+            status_parameters=StatusParameters(
+                effects_per_startup={'maintenance': 0.1},
+                min_uptime=2,  # Minimum 2-hour operation
+                startup_limit=10,  # Maximum 10 starts per period
             ),
         )
         ```
@@ -634,12 +726,14 @@ class Transmission(Component):
         When using InvestParameters on in1, the capacity automatically applies to in2
         to maintain consistent bidirectional capacity without additional investment variables.
 
-        Absolute losses force the creation of binary on/off variables, which increases
+        Absolute losses force the creation of binary on/inactive variables, which increases
         computational complexity but enables realistic modeling of equipment with
         standby power consumption.
 
     """
 
+    submodel: TransmissionModel | None
+
     def __init__(
         self,
         label: str,
@@ -647,22 +741,24 @@ class Transmission(Component):
         out1: Flow,
         in2: Flow | None = None,
         out2: Flow | None = None,
-        relative_losses: TemporalDataUser | None = None,
-        absolute_losses: TemporalDataUser | None = None,
-        on_off_parameters: OnOffParameters = None,
+        relative_losses: Numeric_TPS | None = None,
+        absolute_losses: Numeric_TPS | None = None,
+        status_parameters: StatusParameters | None = None,
         prevent_simultaneous_flows_in_both_directions: bool = True,
         balanced: bool = False,
         meta_data: dict | None = None,
+        color: str | None = None,
     ):
         super().__init__(
             label,
             inputs=[flow for flow in (in1, in2) if flow is not None],
             outputs=[flow for flow in (out1, out2) if flow is not None],
-            on_off_parameters=on_off_parameters,
+            status_parameters=status_parameters,
             prevent_simultaneous_flows=None
             if in2 is None or prevent_simultaneous_flows_in_both_directions is False
             else [in1, in2],
             meta_data=meta_data,
+            color=color,
         )
         self.in1 = in1
         self.out1 = out1
@@ -695,8 +791,8 @@ class Transmission(Component):
             ).any():
                 raise ValueError(
                     f'Balanced Transmission needs compatible minimum and maximum sizes.'
-                    f'Got: {self.in1.size.minimum_size=}, {self.in1.size.maximum_size=}, {self.in1.size.fixed_size=} and '
-                    f'{self.in2.size.minimum_size=}, {self.in2.size.maximum_size=}, {self.in2.size.fixed_size=}.'
+                    f'Got: {self.in1.size.minimum_or_fixed_size=}, {self.in1.size.maximum_or_fixed_size=} and '
+                    f'{self.in2.size.minimum_or_fixed_size=}, {self.in2.size.maximum_or_fixed_size=}.'
                 )
 
     def create_model(self, model) -> TransmissionModel:
@@ -704,11 +800,10 @@ class Transmission(Component):
         self.submodel = TransmissionModel(model, self)
         return self.submodel
 
-    def transform_data(self, flow_system: FlowSystem, name_prefix: str = '') -> None:
-        prefix = '|'.join(filter(None, [name_prefix, self.label_full]))
-        super().transform_data(flow_system, prefix)
-        self.relative_losses = flow_system.fit_to_model_coords(f'{prefix}|relative_losses', self.relative_losses)
-        self.absolute_losses = flow_system.fit_to_model_coords(f'{prefix}|absolute_losses', self.absolute_losses)
+    def transform_data(self) -> None:
+        super().transform_data()
+        self.relative_losses = self._fit_coords(f'{self.prefix}|relative_losses', self.relative_losses)
+        self.absolute_losses = self._fit_coords(f'{self.prefix}|absolute_losses', self.absolute_losses)
 
 
 class TransmissionModel(ComponentModel):
@@ -717,13 +812,16 @@ class TransmissionModel(ComponentModel):
     def __init__(self, model: FlowSystemModel, element: Transmission):
         if (element.absolute_losses is not None) and np.any(element.absolute_losses != 0):
             for flow in element.inputs + element.outputs:
-                if flow.on_off_parameters is None:
-                    flow.on_off_parameters = OnOffParameters()
+                if flow.status_parameters is None:
+                    flow.status_parameters = StatusParameters()
+                    flow.status_parameters.link_to_flow_system(
+                        model.flow_system, f'{flow.label_full}|status_parameters'
+                    )
 
         super().__init__(model, element)
 
     def _do_modeling(self):
-        """Initiates all FlowModels"""
+        """Create transmission efficiency equations and optional absolute loss constraints for both flow directions"""
         super()._do_modeling()
 
         # first direction
@@ -750,13 +848,23 @@ class TransmissionModel(ComponentModel):
             short_name=name,
         )
 
-        if self.element.absolute_losses is not None:
-            con_transmission.lhs += in_flow.submodel.on_off.on * self.element.absolute_losses
+        if (self.element.absolute_losses is not None) and np.any(self.element.absolute_losses != 0):
+            con_transmission.lhs += in_flow.submodel.status.status * self.element.absolute_losses
 
         return con_transmission
 
 
 class LinearConverterModel(ComponentModel):
+    """Mathematical model implementation for LinearConverter components.
+
+    Creates optimization constraints for linear conversion relationships between
+    input and output flows, supporting both simple conversion factors and piecewise
+    non-linear approximations.
+
+    Mathematical Formulation:
+        See <https://flixopt.github.io/flixopt/latest/user-guide/mathematical-notation/elements/LinearConverter/>
+    """
+
     element: LinearConverter
 
     def __init__(self, model: FlowSystemModel, element: LinearConverter):
@@ -764,8 +872,10 @@ class LinearConverterModel(ComponentModel):
         super().__init__(model, element)
 
     def _do_modeling(self):
+        """Create linear conversion equations or piecewise conversion constraints between input and output flows"""
         super()._do_modeling()
-        # conversion_factors:
+
+        # Create conversion factor constraints if specified
         if self.element.conversion_factors:
             all_input_flows = set(self.element.inputs)
             all_output_flows = set(self.element.outputs)
@@ -783,7 +893,7 @@ class LinearConverterModel(ComponentModel):
                 )
 
         else:
-            # TODO: Improve Inclusion of OnOffParameters. Instead of creating a Binary in every flow, the binary could only be part of the Piece itself
+            # TODO: Improve Inclusion of StatusParameters. Instead of creating a Binary in every flow, the binary could only be part of the Piece itself
             piecewise_conversion = {
                 self.element.flows[flow].submodel.flow_rate.name: piecewise
                 for flow, piecewise in self.element.piecewise_conversion.items()
@@ -795,7 +905,7 @@ class LinearConverterModel(ComponentModel):
                     label_of_element=self.label_of_element,
                     label_of_model=f'{self.label_of_element}',
                     piecewise_variables=piecewise_conversion,
-                    zero_point=self.on_off.on if self.on_off is not None else False,
+                    zero_point=self.status.status if self.status is not None else False,
                     dims=('time', 'period', 'scenario'),
                 ),
                 short_name='PiecewiseConversion',
@@ -803,7 +913,18 @@ class LinearConverterModel(ComponentModel):
 
 
 class StorageModel(ComponentModel):
-    """Submodel of Storage"""
+    """Mathematical model implementation for Storage components.
+
+    Creates optimization variables and constraints for charge state tracking,
+    storage balance equations, and optional investment sizing.
+
+    Mathematical Formulation:
+        See <https://flixopt.github.io/flixopt/latest/user-guide/mathematical-notation/elements/Storage/>
+
+    Note:
+        This class uses a template method pattern. Subclasses (e.g., InterclusterStorageModel)
+        can override individual methods to customize behavior without duplicating code.
+    """
 
     element: Storage
 
@@ -811,42 +932,54 @@ class StorageModel(ComponentModel):
         super().__init__(model, element)
 
     def _do_modeling(self):
+        """Create charge state variables, energy balance equations, and optional investment submodels."""
         super()._do_modeling()
-
+        self._create_storage_variables()
+        self._add_netto_discharge_constraint()
+        self._add_energy_balance_constraint()
+        self._add_cluster_cyclic_constraint()
+        self._add_investment_model()
+        self._add_initial_final_constraints()
+        self._add_balanced_sizes_constraint()
+
+    def _create_storage_variables(self):
+        """Create charge_state and netto_discharge variables."""
         lb, ub = self._absolute_charge_state_bounds
         self.add_variables(
             lower=lb,
             upper=ub,
             coords=self._model.get_coords(extra_timestep=True),
             short_name='charge_state',
+            category=VariableCategory.CHARGE_STATE,
+        )
+        self.add_variables(
+            coords=self._model.get_coords(),
+            short_name='netto_discharge',
+            category=VariableCategory.NETTO_DISCHARGE,
         )
 
-        self.add_variables(coords=self._model.get_coords(), short_name='netto_discharge')
-
-        # netto_discharge:
-        # eq: nettoFlow(t) - discharging(t) + charging(t) = 0
+    def _add_netto_discharge_constraint(self):
+        """Add constraint: netto_discharge = discharging - charging."""
         self.add_constraints(
             self.netto_discharge
             == self.element.discharging.submodel.flow_rate - self.element.charging.submodel.flow_rate,
             short_name='netto_discharge',
         )
 
-        charge_state = self.charge_state
-        rel_loss = self.element.relative_loss_per_hour
-        hours_per_step = self._model.hours_per_step
-        charge_rate = self.element.charging.submodel.flow_rate
-        discharge_rate = self.element.discharging.submodel.flow_rate
-        eff_charge = self.element.eta_charge
-        eff_discharge = self.element.eta_discharge
+    def _add_energy_balance_constraint(self):
+        """Add energy balance constraint linking charge states across timesteps."""
+        self.add_constraints(self._build_energy_balance_lhs() == 0, short_name='charge_state')
 
-        self.add_constraints(
-            charge_state.isel(time=slice(1, None))
-            == charge_state.isel(time=slice(None, -1)) * ((1 - rel_loss) ** hours_per_step)
-            + charge_rate * eff_charge * hours_per_step
-            - discharge_rate * hours_per_step / eff_discharge,
-            short_name='charge_state',
-        )
+    def _add_cluster_cyclic_constraint(self):
+        """For 'cyclic' cluster mode: each cluster's start equals its end."""
+        if self._model.flow_system.clusters is not None and self.element.cluster_mode == 'cyclic':
+            self.add_constraints(
+                self.charge_state.isel(time=0) == self.charge_state.isel(time=-2),
+                short_name='cluster_cyclic',
+            )
 
+    def _add_investment_model(self):
+        """Create InvestmentModel and add capacity-scaled bounds if using investment sizing."""
         if isinstance(self.element.capacity_in_flow_hours, InvestParameters):
             self.add_submodels(
                 InvestmentModel(
@@ -854,10 +987,10 @@ class StorageModel(ComponentModel):
                     label_of_element=self.label_of_element,
                     label_of_model=self.label_of_element,
                     parameters=self.element.capacity_in_flow_hours,
+                    size_category=VariableCategory.STORAGE_SIZE,
                 ),
                 short_name='investment',
             )
-
             BoundingPatterns.scaled_bounds(
                 self,
                 variable=self.charge_state,
@@ -865,21 +998,28 @@ class StorageModel(ComponentModel):
                 relative_bounds=self._relative_charge_state_bounds,
             )
 
-        # Initial charge state
-        self._initial_and_final_charge_state()
+    def _add_initial_final_constraints(self):
+        """Add initial and final charge state constraints.
 
-        if self.element.balanced:
-            self.add_constraints(
-                self.element.charging.submodel._investment.size * 1
-                == self.element.discharging.submodel._investment.size * 1,
-                short_name='balanced_sizes',
-            )
+        For clustered systems with 'independent' or 'cyclic' mode, these constraints
+        are skipped because:
+        - 'independent': Each cluster has free start/end SOC
+        - 'cyclic': Start == end is handled by _add_cluster_cyclic_constraint,
+          but no specific initial value is enforced
+        """
+        # Skip initial/final constraints for clustered systems with independent/cyclic mode
+        # These modes should have free or cyclic SOC, not a fixed initial value per cluster
+        if self._model.flow_system.clusters is not None and self.element.cluster_mode in (
+            'independent',
+            'cyclic',
+        ):
+            return
 
-    def _initial_and_final_charge_state(self):
         if self.element.initial_charge_state is not None:
             if isinstance(self.element.initial_charge_state, str):
                 self.add_constraints(
-                    self.charge_state.isel(time=0) == self.charge_state.isel(time=-1), short_name='initial_charge_state'
+                    self.charge_state.isel(time=0) == self.charge_state.isel(time=-1),
+                    short_name='initial_charge_state',
                 )
             else:
                 self.add_constraints(
@@ -899,21 +1039,76 @@ class StorageModel(ComponentModel):
                 short_name='final_charge_min',
             )
 
+    def _add_balanced_sizes_constraint(self):
+        """Add constraint ensuring charging and discharging capacities are equal."""
+        if self.element.balanced:
+            self.add_constraints(
+                self.element.charging.submodel._investment.size - self.element.discharging.submodel._investment.size
+                == 0,
+                short_name='balanced_sizes',
+            )
+
+    def _build_energy_balance_lhs(self):
+        """Build the left-hand side of the energy balance constraint.
+
+        The energy balance equation is:
+            charge_state[t+1] = charge_state[t] * (1 - loss)^dt
+                              + charge_rate * eta_charge * dt
+                              - discharge_rate / eta_discharge * dt
+
+        Rearranged as LHS = 0:
+            charge_state[t+1] - charge_state[t] * (1 - loss)^dt
+            - charge_rate * eta_charge * dt
+            + discharge_rate / eta_discharge * dt = 0
+
+        Returns:
+            The LHS expression (should equal 0).
+        """
+        charge_state = self.charge_state
+        rel_loss = self.element.relative_loss_per_hour
+        timestep_duration = self._model.timestep_duration
+        charge_rate = self.element.charging.submodel.flow_rate
+        discharge_rate = self.element.discharging.submodel.flow_rate
+        eff_charge = self.element.eta_charge
+        eff_discharge = self.element.eta_discharge
+
+        return (
+            charge_state.isel(time=slice(1, None))
+            - charge_state.isel(time=slice(None, -1)) * ((1 - rel_loss) ** timestep_duration)
+            - charge_rate * eff_charge * timestep_duration
+            + discharge_rate * timestep_duration / eff_discharge
+        )
+
     @property
-    def _absolute_charge_state_bounds(self) -> tuple[TemporalData, TemporalData]:
+    def _absolute_charge_state_bounds(self) -> tuple[xr.DataArray, xr.DataArray]:
+        """Get absolute bounds for charge_state variable.
+
+        For base StorageModel, charge_state represents absolute SOC with bounds
+        derived from relative bounds scaled by capacity.
+
+        Note:
+            InterclusterStorageModel overrides this to provide symmetric bounds
+            since charge_state represents ΔE (relative change from cluster start).
+        """
         relative_lower_bound, relative_upper_bound = self._relative_charge_state_bounds
-        if not isinstance(self.element.capacity_in_flow_hours, InvestParameters):
+
+        if self.element.capacity_in_flow_hours is None:
+            return 0, np.inf
+        elif isinstance(self.element.capacity_in_flow_hours, InvestParameters):
+            cap_min = self.element.capacity_in_flow_hours.minimum_or_fixed_size
+            cap_max = self.element.capacity_in_flow_hours.maximum_or_fixed_size
             return (
-                relative_lower_bound * self.element.capacity_in_flow_hours,
-                relative_upper_bound * self.element.capacity_in_flow_hours,
+                relative_lower_bound * cap_min,
+                relative_upper_bound * cap_max,
             )
         else:
+            cap = self.element.capacity_in_flow_hours
             return (
-                relative_lower_bound * self.element.capacity_in_flow_hours.minimum_size,
-                relative_upper_bound * self.element.capacity_in_flow_hours.maximum_size,
+                relative_lower_bound * cap,
+                relative_upper_bound * cap,
             )
 
-    @property
+    @functools.cached_property
     def _relative_charge_state_bounds(self) -> tuple[xr.DataArray, xr.DataArray]:
         """
         Get relative charge state bounds with final timestep values.
@@ -921,26 +1116,51 @@ class StorageModel(ComponentModel):
         Returns:
             Tuple of (minimum_bounds, maximum_bounds) DataArrays extending to final timestep
         """
-        final_coords = {'time': [self._model.flow_system.timesteps_extra[-1]]}
+        timesteps_extra = self._model.flow_system.timesteps_extra
+
+        # Get the original bounds (may be scalar or have time dim)
+        rel_min = self.element.relative_minimum_charge_state
+        rel_max = self.element.relative_maximum_charge_state
 
         # Get final minimum charge state
         if self.element.relative_minimum_final_charge_state is None:
-            min_final = self.element.relative_minimum_charge_state.isel(time=-1, drop=True)
+            min_final_value = _scalar_safe_isel_drop(rel_min, 'time', -1)
         else:
-            min_final = self.element.relative_minimum_final_charge_state
-        min_final = min_final.expand_dims('time').assign_coords(time=final_coords['time'])
+            min_final_value = self.element.relative_minimum_final_charge_state
 
         # Get final maximum charge state
         if self.element.relative_maximum_final_charge_state is None:
-            max_final = self.element.relative_maximum_charge_state.isel(time=-1, drop=True)
+            max_final_value = _scalar_safe_isel_drop(rel_max, 'time', -1)
         else:
-            max_final = self.element.relative_maximum_final_charge_state
-        max_final = max_final.expand_dims('time').assign_coords(time=final_coords['time'])
-        # Concatenate with original bounds
-        min_bounds = xr.concat([self.element.relative_minimum_charge_state, min_final], dim='time')
-        max_bounds = xr.concat([self.element.relative_maximum_charge_state, max_final], dim='time')
+            max_final_value = self.element.relative_maximum_final_charge_state
+
+        # Build bounds arrays for timesteps_extra (includes final timestep)
+        # Handle case where original data may be scalar (no time dim)
+        if 'time' in rel_min.dims:
+            # Original has time dim - concat with final value
+            min_final_da = (
+                min_final_value.expand_dims('time') if 'time' not in min_final_value.dims else min_final_value
+            )
+            min_final_da = min_final_da.assign_coords(time=[timesteps_extra[-1]])
+            min_bounds = xr.concat([rel_min, min_final_da], dim='time')
+        else:
+            # Original is scalar - broadcast to full time range (constant value)
+            min_bounds = rel_min.expand_dims(time=timesteps_extra)
+
+        if 'time' in rel_max.dims:
+            # Original has time dim - concat with final value
+            max_final_da = (
+                max_final_value.expand_dims('time') if 'time' not in max_final_value.dims else max_final_value
+            )
+            max_final_da = max_final_da.assign_coords(time=[timesteps_extra[-1]])
+            max_bounds = xr.concat([rel_max, max_final_da], dim='time')
+        else:
+            # Original is scalar - broadcast to full time range (constant value)
+            max_bounds = rel_max.expand_dims(time=timesteps_extra)
 
-        return min_bounds, max_bounds
+        # Ensure both bounds have matching dimensions (broadcast once here,
+        # so downstream code doesn't need to handle dimension mismatches)
+        return xr.broadcast(min_bounds, max_bounds)
 
     @property
     def _investment(self) -> InvestmentModel | None:
@@ -949,7 +1169,7 @@ class StorageModel(ComponentModel):
 
     @property
     def investment(self) -> InvestmentModel | None:
-        """OnOff feature"""
+        """Investment feature"""
         if 'investment' not in self.submodels:
             return None
         return self.submodels['investment']
@@ -965,6 +1185,435 @@ class StorageModel(ComponentModel):
         return self['netto_discharge']
 
 
+class InterclusterStorageModel(StorageModel):
+    """Storage model with inter-cluster linking for clustered optimization.
+
+    This class extends :class:`StorageModel` to support inter-cluster storage linking
+    when using time series aggregation (clustering). It implements the S-N linking model
+    from Blanke et al. (2022) to properly value seasonal storage in clustered optimizations.
+
+    The Problem with Naive Clustering
+    ---------------------------------
+    When time series are clustered (e.g., 365 days → 8 typical days), storage behavior
+    is fundamentally misrepresented if each cluster operates independently:
+
+    - **Seasonal patterns are lost**: A battery might charge in summer and discharge in
+      winter, but with independent clusters, each "typical summer day" cannot transfer
+      energy to the "typical winter day".
+    - **Storage value is underestimated**: Without inter-cluster linking, storage can only
+      provide intra-day flexibility, not seasonal arbitrage.
+
+    The S-N Linking Model
+    ---------------------
+    This model introduces two key concepts:
+
+    1. **SOC_boundary**: Absolute state-of-charge at the boundary between original periods.
+       With N original periods, there are N+1 boundary points (including start and end).
+
+    2. **charge_state (ΔE)**: Relative change in SOC within each representative cluster,
+       measured from the cluster start (where ΔE = 0).
+
+    The actual SOC at any timestep t within original period d is::
+
+        SOC(t) = SOC_boundary[d] + ΔE(t)
+
+    Key Constraints
+    ---------------
+    1. **Cluster start constraint**: ``ΔE(cluster_start) = 0``
+       Each representative cluster starts with zero relative charge.
+
+    2. **Linking constraint**: ``SOC_boundary[d+1] = SOC_boundary[d] + delta_SOC[cluster_assignments[d]]``
+       The boundary SOC after period d equals the boundary before plus the net
+       charge/discharge of the representative cluster for that period.
+
+    3. **Combined bounds**: ``0 ≤ SOC_boundary[d] + ΔE(t) ≤ capacity``
+       The actual SOC must stay within physical bounds.
+
+    4. **Cyclic constraint** (for ``intercluster_cyclic`` mode):
+       ``SOC_boundary[0] = SOC_boundary[N]``
+       The storage returns to its initial state over the full time horizon.
+
+    Variables Created
+    -----------------
+    - ``SOC_boundary``: Absolute SOC at each original period boundary.
+      Shape: (n_original_clusters + 1,) plus any period/scenario dimensions.
+
+    Constraints Created
+    -------------------
+    - ``cluster_start``: Forces ΔE = 0 at start of each representative cluster.
+    - ``link``: Links consecutive SOC_boundary values via delta_SOC.
+    - ``cyclic`` or ``initial_SOC_boundary``: Initial/final boundary condition.
+    - ``soc_lb_start/mid/end``: Lower bound on combined SOC at sample points.
+    - ``soc_ub_start/mid/end``: Upper bound on combined SOC (if investment).
+    - ``SOC_boundary_ub``: Links SOC_boundary to investment size (if investment).
+    - ``charge_state|lb/ub``: Symmetric bounds on ΔE for intercluster modes.
+
+    References
+    ----------
+    - Blanke, T., et al. (2022). "Inter-Cluster Storage Linking for Time Series
+      Aggregation in Energy System Optimization Models."
+    - Kotzur, L., et al. (2018). "Time series aggregation for energy system design:
+      Modeling seasonal storage."
+
+    See Also
+    --------
+    :class:`StorageModel` : Base storage model without inter-cluster linking.
+    :class:`Storage` : The element class that creates this model.
+
+    Example
+    -------
+    The model is automatically used when a Storage has ``cluster_mode='intercluster'``
+    or ``cluster_mode='intercluster_cyclic'`` and the FlowSystem has been clustered::
+
+        storage = Storage(
+            label='seasonal_storage',
+            charging=charge_flow,
+            discharging=discharge_flow,
+            capacity_in_flow_hours=InvestParameters(maximum_size=10000),
+            cluster_mode='intercluster_cyclic',  # Enable inter-cluster linking
+        )
+
+        # Cluster the flow system
+        fs_clustered = flow_system.transform.cluster(n_clusters=8)
+        fs_clustered.optimize(solver)
+
+        # Access the SOC_boundary in results
+        soc_boundary = fs_clustered.solution['seasonal_storage|SOC_boundary']
+    """
+
+    @property
+    def _absolute_charge_state_bounds(self) -> tuple[xr.DataArray, xr.DataArray]:
+        """Get symmetric bounds for charge_state (ΔE) variable.
+
+        For InterclusterStorageModel, charge_state represents ΔE (relative change
+        from cluster start), which can be negative. Therefore, we need symmetric
+        bounds: -capacity <= ΔE <= capacity.
+
+        Note that for investment-based sizing, additional constraints are added
+        in _add_investment_model to link bounds to the actual investment size.
+        """
+        _, relative_upper_bound = self._relative_charge_state_bounds
+
+        if self.element.capacity_in_flow_hours is None:
+            return -np.inf, np.inf
+        elif isinstance(self.element.capacity_in_flow_hours, InvestParameters):
+            cap_max = self.element.capacity_in_flow_hours.maximum_or_fixed_size * relative_upper_bound
+            # Adding 0.0 converts -0.0 to 0.0 (linopy LP writer bug workaround)
+            return -cap_max + 0.0, cap_max + 0.0
+        else:
+            cap = self.element.capacity_in_flow_hours * relative_upper_bound
+            # Adding 0.0 converts -0.0 to 0.0 (linopy LP writer bug workaround)
+            return -cap + 0.0, cap + 0.0
+
+    def _do_modeling(self):
+        """Create storage model with inter-cluster linking constraints.
+
+        Uses template method pattern: calls parent's _do_modeling, then adds
+        inter-cluster linking. Overrides specific methods to customize behavior.
+        """
+        super()._do_modeling()
+        self._add_intercluster_linking()
+
+    def _add_cluster_cyclic_constraint(self):
+        """Skip cluster cyclic constraint - handled by inter-cluster linking."""
+        pass
+
+    def _add_investment_model(self):
+        """Create InvestmentModel with symmetric bounds for ΔE."""
+        if isinstance(self.element.capacity_in_flow_hours, InvestParameters):
+            self.add_submodels(
+                InvestmentModel(
+                    model=self._model,
+                    label_of_element=self.label_of_element,
+                    label_of_model=self.label_of_element,
+                    parameters=self.element.capacity_in_flow_hours,
+                    size_category=VariableCategory.STORAGE_SIZE,
+                ),
+                short_name='investment',
+            )
+            # Symmetric bounds: -size <= charge_state <= size
+            self.add_constraints(
+                self.charge_state >= -self.investment.size,
+                short_name='charge_state|lb',
+            )
+            self.add_constraints(
+                self.charge_state <= self.investment.size,
+                short_name='charge_state|ub',
+            )
+
+    def _add_initial_final_constraints(self):
+        """Skip initial/final constraints - handled by SOC_boundary in inter-cluster linking."""
+        pass
+
+    def _add_intercluster_linking(self) -> None:
+        """Add inter-cluster storage linking following the S-K model from Blanke et al. (2022).
+
+        This method implements the core inter-cluster linking logic:
+
+        1. Constrains charge_state (ΔE) at each cluster start to 0
+        2. Creates SOC_boundary variables to track absolute SOC at period boundaries
+        3. Links boundaries via Eq. 5: SOC_boundary[d+1] = SOC_boundary[d] * (1-loss)^N + delta_SOC
+        4. Adds combined bounds per Eq. 9: 0 ≤ SOC_boundary * (1-loss)^t + ΔE ≤ capacity
+        5. Enforces initial/cyclic constraint on SOC_boundary
+        """
+        from .clustering.intercluster_helpers import (
+            build_boundary_coords,
+            extract_capacity_bounds,
+        )
+
+        clustering = self._model.flow_system.clustering
+        if clustering is None:
+            return
+
+        n_clusters = clustering.n_clusters
+        timesteps_per_cluster = clustering.timesteps_per_cluster
+        n_original_clusters = clustering.n_original_clusters
+        cluster_assignments = clustering.cluster_assignments
+
+        # 1. Constrain ΔE = 0 at cluster starts
+        self._add_cluster_start_constraints(n_clusters, timesteps_per_cluster)
+
+        # 2. Create SOC_boundary variable
+        flow_system = self._model.flow_system
+        boundary_coords, boundary_dims = build_boundary_coords(n_original_clusters, flow_system)
+        capacity_bounds = extract_capacity_bounds(self.element.capacity_in_flow_hours, boundary_coords, boundary_dims)
+
+        soc_boundary = self.add_variables(
+            lower=capacity_bounds.lower,
+            upper=capacity_bounds.upper,
+            coords=boundary_coords,
+            dims=boundary_dims,
+            short_name='SOC_boundary',
+            category=VariableCategory.SOC_BOUNDARY,
+        )
+
+        # 3. Link SOC_boundary to investment size
+        if capacity_bounds.has_investment and self.investment is not None:
+            self.add_constraints(
+                soc_boundary <= self.investment.size,
+                short_name='SOC_boundary_ub',
+            )
+
+        # 4. Compute delta_SOC for each cluster
+        delta_soc = self._compute_delta_soc(n_clusters, timesteps_per_cluster)
+
+        # 5. Add linking constraints
+        self._add_linking_constraints(
+            soc_boundary, delta_soc, cluster_assignments, n_original_clusters, timesteps_per_cluster
+        )
+
+        # 6. Add cyclic or initial constraint
+        if self.element.cluster_mode == 'intercluster_cyclic':
+            self.add_constraints(
+                soc_boundary.isel(cluster_boundary=0) == soc_boundary.isel(cluster_boundary=n_original_clusters),
+                short_name='cyclic',
+            )
+        else:
+            # Apply initial_charge_state to SOC_boundary[0]
+            initial = self.element.initial_charge_state
+            if initial is not None:
+                if isinstance(initial, str):
+                    # 'equals_final' means cyclic
+                    self.add_constraints(
+                        soc_boundary.isel(cluster_boundary=0)
+                        == soc_boundary.isel(cluster_boundary=n_original_clusters),
+                        short_name='initial_SOC_boundary',
+                    )
+                else:
+                    self.add_constraints(
+                        soc_boundary.isel(cluster_boundary=0) == initial,
+                        short_name='initial_SOC_boundary',
+                    )
+
+        # 7. Add combined bound constraints
+        self._add_combined_bound_constraints(
+            soc_boundary,
+            cluster_assignments,
+            capacity_bounds.has_investment,
+            n_original_clusters,
+            timesteps_per_cluster,
+        )
+
+    def _add_cluster_start_constraints(self, n_clusters: int, timesteps_per_cluster: int) -> None:
+        """Constrain ΔE = 0 at the start of each representative cluster.
+
+        This ensures that the relative charge state is measured from a known
+        reference point (the cluster start).
+
+        With 2D (cluster, time) structure, time=0 is the start of every cluster,
+        so we simply select isel(time=0) which broadcasts across the cluster dimension.
+
+        Args:
+            n_clusters: Number of representative clusters (unused with 2D structure).
+            timesteps_per_cluster: Timesteps in each cluster (unused with 2D structure).
+        """
+        # With 2D structure: time=0 is start of every cluster
+        self.add_constraints(
+            self.charge_state.isel(time=0) == 0,
+            short_name='cluster_start',
+        )
+
+    def _compute_delta_soc(self, n_clusters: int, timesteps_per_cluster: int) -> xr.DataArray:
+        """Compute net SOC change (delta_SOC) for each representative cluster.
+
+        The delta_SOC is the difference between the charge_state at the end
+        and start of each cluster: delta_SOC[c] = ΔE(end_c) - ΔE(start_c).
+
+        Since ΔE(start) = 0 by constraint, this simplifies to delta_SOC[c] = ΔE(end_c).
+
+        With 2D (cluster, time) structure, we can simply select isel(time=-1) and isel(time=0),
+        which already have the 'cluster' dimension.
+
+        Args:
+            n_clusters: Number of representative clusters (unused with 2D structure).
+            timesteps_per_cluster: Timesteps in each cluster (unused with 2D structure).
+
+        Returns:
+            DataArray with 'cluster' dimension containing delta_SOC for each cluster.
+        """
+        # With 2D structure: result already has cluster dimension
+        return self.charge_state.isel(time=-1) - self.charge_state.isel(time=0)
+
+    def _add_linking_constraints(
+        self,
+        soc_boundary: xr.DataArray,
+        delta_soc: xr.DataArray,
+        cluster_assignments: xr.DataArray,
+        n_original_clusters: int,
+        timesteps_per_cluster: int,
+    ) -> None:
+        """Add constraints linking consecutive SOC_boundary values.
+
+        Per Blanke et al. (2022) Eq. 5, implements:
+            SOC_boundary[d+1] = SOC_boundary[d] * (1-loss)^N + delta_SOC[cluster_assignments[d]]
+
+        where N is timesteps_per_cluster and loss is self-discharge rate per timestep.
+
+        This connects the SOC at the end of original period d to the SOC at the
+        start of period d+1, accounting for self-discharge decay over the period.
+
+        Args:
+            soc_boundary: SOC_boundary variable.
+            delta_soc: Net SOC change per cluster.
+            cluster_assignments: Mapping from original periods to representative clusters.
+            n_original_clusters: Number of original (non-clustered) periods.
+            timesteps_per_cluster: Number of timesteps in each cluster period.
+        """
+        soc_after = soc_boundary.isel(cluster_boundary=slice(1, None))
+        soc_before = soc_boundary.isel(cluster_boundary=slice(None, -1))
+
+        # Rename for alignment
+        soc_after = soc_after.rename({'cluster_boundary': 'original_cluster'})
+        soc_after = soc_after.assign_coords(original_cluster=np.arange(n_original_clusters))
+        soc_before = soc_before.rename({'cluster_boundary': 'original_cluster'})
+        soc_before = soc_before.assign_coords(original_cluster=np.arange(n_original_clusters))
+
+        # Get delta_soc for each original period using cluster_assignments
+        delta_soc_ordered = delta_soc.isel(cluster=cluster_assignments)
+
+        # Apply self-discharge decay factor (1-loss)^hours to soc_before per Eq. 5
+        # relative_loss_per_hour is per-hour, so we need total hours per cluster
+        # Use sum over time to get total duration (handles both regular and segmented systems)
+        # Keep as DataArray to respect per-period/scenario values
+        rel_loss = _scalar_safe_reduce(self.element.relative_loss_per_hour, 'time', 'mean')
+        total_hours_per_cluster = _scalar_safe_reduce(self._model.timestep_duration, 'time', 'sum')
+        decay_n = (1 - rel_loss) ** total_hours_per_cluster
+
+        lhs = soc_after - soc_before * decay_n - delta_soc_ordered
+        self.add_constraints(lhs == 0, short_name='link')
+
+    def _add_combined_bound_constraints(
+        self,
+        soc_boundary: xr.DataArray,
+        cluster_assignments: xr.DataArray,
+        has_investment: bool,
+        n_original_clusters: int,
+        timesteps_per_cluster: int,
+    ) -> None:
+        """Add constraints ensuring actual SOC stays within bounds.
+
+        Per Blanke et al. (2022) Eq. 9, the actual SOC at time t in period d is:
+            SOC(t) = SOC_boundary[d] * (1-loss)^t + ΔE(t)
+
+        This must satisfy: 0 ≤ SOC(t) ≤ capacity
+
+        Since checking every timestep is expensive, we sample at the start,
+        middle, and end of each cluster.
+
+        With 2D (cluster, time) structure, we simply select charge_state at a
+        given time offset, then reorder by cluster_assignments to get original_cluster order.
+
+        Args:
+            soc_boundary: SOC_boundary variable.
+            cluster_assignments: Mapping from original periods to clusters.
+            has_investment: Whether the storage has investment sizing.
+            n_original_clusters: Number of original periods.
+            timesteps_per_cluster: Timesteps in each cluster.
+        """
+        charge_state = self.charge_state
+
+        # soc_d: SOC at start of each original period
+        soc_d = soc_boundary.isel(cluster_boundary=slice(None, -1))
+        soc_d = soc_d.rename({'cluster_boundary': 'original_cluster'})
+        soc_d = soc_d.assign_coords(original_cluster=np.arange(n_original_clusters))
+
+        # Get self-discharge rate for decay calculation
+        # relative_loss_per_hour is per-hour, so we need to convert offsets to hours
+        # Keep as DataArray to respect per-period/scenario values
+        rel_loss = _scalar_safe_reduce(self.element.relative_loss_per_hour, 'time', 'mean')
+
+        # Compute cumulative hours for accurate offset calculation with non-uniform timesteps
+        timestep_duration = self._model.timestep_duration
+        if isinstance(timestep_duration, xr.DataArray) and 'time' in timestep_duration.dims:
+            # Use cumsum for accurate hours offset with non-uniform timesteps
+            # Build cumulative_hours with N+1 elements to match charge_state's extra timestep:
+            # index 0 = 0 hours, index i = sum of durations[0:i], index N = total duration
+            cumsum = timestep_duration.cumsum('time')
+            # Prepend 0 at the start, giving [0, cumsum[0], cumsum[1], ..., cumsum[N-1]]
+            cumulative_hours = xr.concat(
+                [xr.zeros_like(timestep_duration.isel(time=0)), cumsum],
+                dim='time',
+            )
+        else:
+            # Scalar or no time dim: fall back to mean-based calculation
+            mean_timestep_duration = _scalar_safe_reduce(timestep_duration, 'time', 'mean')
+            cumulative_hours = None
+
+        # Use actual time dimension size (may be smaller than timesteps_per_cluster for segmented systems)
+        actual_time_size = charge_state.sizes['time']
+        sample_offsets = [0, actual_time_size // 2, actual_time_size - 1]
+
+        for sample_name, offset in zip(['start', 'mid', 'end'], sample_offsets, strict=False):
+            # With 2D structure: select time offset, then reorder by cluster_assignments
+            cs_at_offset = charge_state.isel(time=offset)  # Shape: (cluster, ...)
+            # Reorder to original_cluster order using cluster_assignments indexer
+            cs_t = cs_at_offset.isel(cluster=cluster_assignments)
+            # Suppress xarray warning about index loss - we immediately assign new coords anyway
+            with warnings.catch_warnings():
+                warnings.filterwarnings('ignore', message='.*does not create an index anymore.*')
+                cs_t = cs_t.rename({'cluster': 'original_cluster'})
+            cs_t = cs_t.assign_coords(original_cluster=np.arange(n_original_clusters))
+
+            # Apply decay factor (1-loss)^hours to SOC_boundary per Eq. 9
+            # Convert timestep offset to hours using cumulative duration for non-uniform timesteps
+            if cumulative_hours is not None:
+                hours_offset = cumulative_hours.isel(time=offset)
+            else:
+                hours_offset = offset * mean_timestep_duration
+            decay_t = (1 - rel_loss) ** hours_offset
+            combined = soc_d * decay_t + cs_t
+
+            self.add_constraints(combined >= 0, short_name=f'soc_lb_{sample_name}')
+
+            if has_investment and self.investment is not None:
+                self.add_constraints(combined <= self.investment.size, short_name=f'soc_ub_{sample_name}')
+            elif not has_investment and isinstance(self.element.capacity_in_flow_hours, (int, float)):
+                # Fixed-capacity storage: upper bound is the fixed capacity
+                self.add_constraints(
+                    combined <= self.element.capacity_in_flow_hours, short_name=f'soc_ub_{sample_name}'
+                )
+
+
 @register_class_for_io
 class SourceAndSink(Component):
     """
@@ -1058,58 +1707,18 @@ class SourceAndSink(Component):
         outputs: list[Flow] | None = None,
         prevent_simultaneous_flow_rates: bool = True,
         meta_data: dict | None = None,
-        **kwargs,
+        color: str | None = None,
     ):
-        # Handle deprecated parameters using centralized helper
-        outputs = self._handle_deprecated_kwarg(kwargs, 'source', 'outputs', outputs, transform=lambda x: [x])
-        inputs = self._handle_deprecated_kwarg(kwargs, 'sink', 'inputs', inputs, transform=lambda x: [x])
-        prevent_simultaneous_flow_rates = self._handle_deprecated_kwarg(
-            kwargs,
-            'prevent_simultaneous_sink_and_source',
-            'prevent_simultaneous_flow_rates',
-            prevent_simultaneous_flow_rates,
-            check_conflict=False,
-        )
-
-        # Validate any remaining unexpected kwargs
-        self._validate_kwargs(kwargs)
-
         super().__init__(
             label,
             inputs=inputs,
             outputs=outputs,
             prevent_simultaneous_flows=(inputs or []) + (outputs or []) if prevent_simultaneous_flow_rates else None,
             meta_data=meta_data,
+            color=color,
         )
         self.prevent_simultaneous_flow_rates = prevent_simultaneous_flow_rates
 
-    @property
-    def source(self) -> Flow:
-        warnings.warn(
-            'The source property is deprecated. Use the outputs property instead.',
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.outputs[0]
-
-    @property
-    def sink(self) -> Flow:
-        warnings.warn(
-            'The sink property is deprecated. Use the inputs property instead.',
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.inputs[0]
-
-    @property
-    def prevent_simultaneous_sink_and_source(self) -> bool:
-        warnings.warn(
-            'The prevent_simultaneous_sink_and_source property is deprecated. Use the prevent_simultaneous_flow_rates property instead.',
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.prevent_simultaneous_flow_rates
-
 
 @register_class_for_io
 class Source(Component):
@@ -1193,31 +1802,17 @@ class Source(Component):
         outputs: list[Flow] | None = None,
         meta_data: dict | None = None,
         prevent_simultaneous_flow_rates: bool = False,
-        **kwargs,
+        color: str | None = None,
     ):
-        # Handle deprecated parameter using centralized helper
-        outputs = self._handle_deprecated_kwarg(kwargs, 'source', 'outputs', outputs, transform=lambda x: [x])
-
-        # Validate any remaining unexpected kwargs
-        self._validate_kwargs(kwargs)
-
         self.prevent_simultaneous_flow_rates = prevent_simultaneous_flow_rates
         super().__init__(
             label,
             outputs=outputs,
             meta_data=meta_data,
             prevent_simultaneous_flows=outputs if prevent_simultaneous_flow_rates else None,
+            color=color,
         )
 
-    @property
-    def source(self) -> Flow:
-        warnings.warn(
-            'The source property is deprecated. Use the outputs property instead.',
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.outputs[0]
-
 
 @register_class_for_io
 class Sink(Component):
@@ -1302,27 +1897,18 @@ class Sink(Component):
         inputs: list[Flow] | None = None,
         meta_data: dict | None = None,
         prevent_simultaneous_flow_rates: bool = False,
-        **kwargs,
+        color: str | None = None,
     ):
+        """Initialize a Sink (consumes flow from the system).
+
+        Args:
+            label: Unique element label.
+            inputs: Input flows for the sink.
+            meta_data: Arbitrary metadata attached to the element.
+            prevent_simultaneous_flow_rates: If True, prevents simultaneous nonzero flow rates
+                across the element's inputs by wiring that restriction into the base Component setup.
+            color: Optional color for visualizations.
         """
-        Initialize a Sink (consumes flow from the system).
-
-        Supports legacy `sink=` keyword for backward compatibility (deprecated): if `sink` is provided it is used as the single input flow and a DeprecationWarning is issued; specifying both `inputs` and `sink` raises ValueError.
-
-        Parameters:
-            label (str): Unique element label.
-            inputs (list[Flow], optional): Input flows for the sink.
-            meta_data (dict, optional): Arbitrary metadata attached to the element.
-            prevent_simultaneous_flow_rates (bool, optional): If True, prevents simultaneous nonzero flow rates across the element's inputs by wiring that restriction into the base Component setup.
-
-        Note:
-            The deprecated `sink` kwarg is accepted for compatibility but will be removed in future releases.
-        """
-        # Handle deprecated parameter using centralized helper
-        inputs = self._handle_deprecated_kwarg(kwargs, 'sink', 'inputs', inputs, transform=lambda x: [x])
-
-        # Validate any remaining unexpected kwargs
-        self._validate_kwargs(kwargs)
 
         self.prevent_simultaneous_flow_rates = prevent_simultaneous_flow_rates
         super().__init__(
@@ -1330,13 +1916,5 @@ class Sink(Component):
             inputs=inputs,
             meta_data=meta_data,
             prevent_simultaneous_flows=inputs if prevent_simultaneous_flow_rates else None,
+            color=color,
         )
-
-    @property
-    def sink(self) -> Flow:
-        warnings.warn(
-            'The sink property is deprecated. Use the inputs property instead.',
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.inputs[0]