flixopt 2.2.0b0__py3-none-any.whl → 2.2.0rc2__py3-none-any.whl

flixopt/interface.py

@@ -4,14 +4,14 @@ These are tightly connected to features.py
 """
 
 import logging
-from typing import TYPE_CHECKING, Dict, Iterator, List, Literal, Optional, Union
+from typing import TYPE_CHECKING, Dict, Iterator, List, Optional, Union
 
 from .config import CONFIG
-from .core import NumericDataTS, Scalar, ScenarioData, TimestepData
+from .core import NumericData, NumericDataTS, Scalar
 from .structure import Interface, register_class_for_io
 
 if TYPE_CHECKING:  # for type checking and preventing circular imports
-    from .effects import EffectValuesUserScenario, EffectValuesUserTimestep
+    from .effects import EffectValuesUser, EffectValuesUserScalar
     from .flow_system import FlowSystem
 
 
@@ -20,7 +20,7 @@ logger = logging.getLogger('flixopt')
 
 @register_class_for_io
 class Piece(Interface):
-    def __init__(self, start: TimestepData, end: TimestepData):
+    def __init__(self, start: NumericData, end: NumericData):
         """
         Define a Piece, which is part of a Piecewise object.
 
@@ -30,15 +30,10 @@ class Piece(Interface):
         """
         self.start = start
         self.end = end
-        self.has_time_dim = False
 
     def transform_data(self, flow_system: 'FlowSystem', name_prefix: str):
-        self.start = flow_system.create_time_series(
-            name=f'{name_prefix}|start', data=self.start, has_time_dim=self.has_time_dim, has_scenario_dim=True
-        )
-        self.end = flow_system.create_time_series(
-            name=f'{name_prefix}|end', data=self.end, has_time_dim=self.has_time_dim, has_scenario_dim=True
-        )
+        self.start = flow_system.create_time_series(f'{name_prefix}|start', self.start)
+        self.end = flow_system.create_time_series(f'{name_prefix}|end', self.end)
 
 
 @register_class_for_io
@@ -51,17 +46,6 @@ class Piecewise(Interface):
             pieces: The pieces of the piecewise.
         """
         self.pieces = pieces
-        self._has_time_dim = False
-
-    @property
-    def has_time_dim(self):
-        return self._has_time_dim
-
-    @has_time_dim.setter
-    def has_time_dim(self, value):
-        self._has_time_dim = value
-        for piece in self.pieces:
-            piece.has_time_dim = value
 
     def __len__(self):
         return len(self.pieces)
@@ -79,28 +63,169 @@ class Piecewise(Interface):
 
 @register_class_for_io
 class PiecewiseConversion(Interface):
-    def __init__(self, piecewises: Dict[str, Piecewise]):
-        """
-        Define a piecewise conversion between multiple Flows.
-        --> "gaps" can be expressed by a piece not starting at the end of the prior piece: [(1,3), (4,5)]
-        --> "points" can expressed as piece with same begin and end: [(3,3), (4,4)]
+    """Define piecewise linear conversion relationships between multiple flows.
+
+    This class models complex conversion processes where the relationship between
+    input and output flows changes at different operating points, such as:
+
+    - Variable efficiency equipment (heat pumps, engines, turbines)
+    - Multi-stage chemical processes with different conversion rates
+    - Equipment with discrete operating modes
+    - Systems with capacity constraints and thresholds
+
+    Args:
+        piecewises: Dictionary mapping flow labels to their Piecewise conversion functions.
+            Keys are flow names (e.g., 'electricity_in', 'heat_out', 'fuel_consumed').
+            Values are Piecewise objects defining conversion factors at different operating points.
+            All Piecewise objects must have the same number of pieces and compatible domains
+            to ensure consistent conversion relationships across operating ranges.
+
+    Note:
+        Special modeling features:
+
+        - **Gaps**: Express forbidden operating ranges by creating non-contiguous pieces.
+          Example: `[(0,50), (100,200)]` - cannot operate between 50-100 units
+        - **Points**: Express discrete operating points using pieces with identical start/end.
+          Example: `[(50,50), (100,100)]` - can only operate at exactly 50 or 100 units
+
+    Examples:
+        Heat pump with variable COP (Coefficient of Performance):
+
+        ```python
+        PiecewiseConversion(
+            {
+                'electricity_in': Piecewise(
+                    [
+                        Piece(0, 10),  # Low load: 0-10 kW electricity
+                        Piece(10, 25),  # High load: 10-25 kW electricity
+                    ]
+                ),
+                'heat_out': Piecewise(
+                    [
+                        Piece(0, 35),  # Low load COP=3.5: 0-35 kW heat output
+                        Piece(35, 75),  # High load COP=3.0: 35-75 kW heat output
+                    ]
+                ),
+            }
+        )
+        # At 15 kW electricity input → 52.5 kW heat output (interpolated)
+        ```
+
+        Engine with fuel consumption and emissions:
+
+        ```python
+        PiecewiseConversion(
+            {
+                'fuel_input': Piecewise(
+                    [
+                        Piece(5, 15),  # Part load: 5-15 L/h fuel
+                        Piece(15, 30),  # Full load: 15-30 L/h fuel
+                    ]
+                ),
+                'power_output': Piecewise(
+                    [
+                        Piece(10, 25),  # Part load: 10-25 kW output
+                        Piece(25, 45),  # Full load: 25-45 kW output
+                    ]
+                ),
+                'co2_emissions': Piecewise(
+                    [
+                        Piece(12, 35),  # Part load: 12-35 kg/h CO2
+                        Piece(35, 78),  # Full load: 35-78 kg/h CO2
+                    ]
+                ),
+            }
+        )
+        ```
+
+        Discrete operating modes (on/off equipment):
+
+        ```python
+        PiecewiseConversion(
+            {
+                'electricity_in': Piecewise(
+                    [
+                        Piece(0, 0),  # Off mode: no consumption
+                        Piece(20, 20),  # On mode: fixed 20 kW consumption
+                    ]
+                ),
+                'cooling_out': Piecewise(
+                    [
+                        Piece(0, 0),  # Off mode: no cooling
+                        Piece(60, 60),  # On mode: fixed 60 kW cooling
+                    ]
+                ),
+            }
+        )
+        ```
+
+        Equipment with forbidden operating range:
+
+        ```python
+        PiecewiseConversion(
+            {
+                'steam_input': Piecewise(
+                    [
+                        Piece(0, 100),  # Low pressure operation
+                        Piece(200, 500),  # High pressure (gap: 100-200)
+                    ]
+                ),
+                'power_output': Piecewise(
+                    [
+                        Piece(0, 80),  # Low efficiency at low pressure
+                        Piece(180, 400),  # High efficiency at high pressure
+                    ]
+                ),
+            }
+        )
+        ```
+
+        Multi-product chemical reactor:
+
+        ```python
+        fx.PiecewiseConversion(
+            {
+                'feedstock': fx.Piecewise(
+                    [
+                        fx.Piece(10, 50),  # Small batch: 10-50 kg/h
+                        fx.Piece(50, 200),  # Large batch: 50-200 kg/h
+                    ]
+                ),
+                'product_A': fx.Piecewise(
+                    [
+                        fx.Piece(7, 32),  # Small batch yield: 70%
+                        fx.Piece(32, 140),  # Large batch yield: 70%
+                    ]
+                ),
+                'product_B': fx.Piecewise(
+                    [
+                        fx.Piece(2, 12),  # Small batch: 20% to product B
+                        fx.Piece(12, 45),  # Large batch: better selectivity
+                    ]
+                ),
+                'waste': fx.Piecewise(
+                    [
+                        fx.Piece(1, 6),  # Small batch waste: 10%
+                        fx.Piece(6, 15),  # Large batch waste: 7.5%
+                    ]
+                ),
+            }
+        )
+        ```
 
-        Args:
-            piecewises: Dict of Piecewises defining the conversion factors. flow labels as keys, piecewise as values
-        """
-        self.piecewises = piecewises
-        self._has_time_dim = True
-        self.has_time_dim = True  # Inital propagation
+    Common Use Cases:
+        - Heat pumps/chillers: COP varies with load and ambient conditions
+        - Power plants: Heat rate curves showing fuel efficiency vs output
+        - Chemical reactors: Conversion rates and selectivity vs throughput
+        - Compressors/pumps: Power consumption vs flow rate
+        - Multi-stage processes: Different conversion rates per stage
+        - Equipment with minimum loads: Cannot operate below threshold
+        - Batch processes: Discrete production campaigns
 
-    @property
-    def has_time_dim(self):
-        return self._has_time_dim
+    """
 
-    @has_time_dim.setter
-    def has_time_dim(self, value):
-        self._has_time_dim = value
-        for piecewise in self.piecewises.values():
-            piecewise.has_time_dim = value
+    def __init__(self, piecewises: Dict[str, Piecewise]):
+        self.piecewises = piecewises
 
     def items(self):
         return self.piecewises.items()
@@ -122,24 +247,118 @@ class PiecewiseEffects(Interface):
         """
         self.piecewise_origin = piecewise_origin
         self.piecewise_shares = piecewise_shares
-        self._has_time_dim = False
-        self.has_time_dim = False  # Inital propagation
 
-    @property
-    def has_time_dim(self):
-        return self._has_time_dim
+    def transform_data(self, flow_system: 'FlowSystem', name_prefix: str):
+        raise NotImplementedError('PiecewiseEffects is not yet implemented for non scalar shares')
+        # self.piecewise_origin.transform_data(flow_system, f'{name_prefix}|PiecewiseEffects|origin')
+        # for name, piecewise in self.piecewise_shares.items():
+        #    piecewise.transform_data(flow_system, f'{name_prefix}|PiecewiseEffects|{name}')
+
+
+@register_class_for_io
+class PiecewiseEffectsPerFlowHour(Interface):
+    """
+    Define piecewise linear relationships between flow rate and various effects (costs, emissions, etc.).
+
+    This class models situations where the relationship between flow rate and effects changes at
+    different flow rate levels, such as:
+    - Pump efficiency curves across operating ranges
+    - Emission factors that vary with operating levels
+    - Capacity-dependent transportation costs
+    - Decision between different operating modes or suppliers
+    - Optional equipment activation with minimum flow requirements
+
+    Args:
+        piecewise_flow_rate: `Piecewise` defining the valid flow rate segments.
+            Each Piece represents a linear segment with (min_flow, max_flow) bounds.
+
+        piecewise_shares: Dictionary mapping effect names to their `Piecewise`.
+            Keys are effect names (e.g., 'Costs', 'CO2', 'Maintenance').
+            Values are `Piecewise` objects defining the absolute effect values (not rates/prices).
+
+            ⚠️  IMPORTANT: Values represent total effect amounts, not unit rates.
+            For a flow rate of X, the effect value is interpolated from the `Piecewise`.
+            This is NOT flow_rate × unit_price (which would be non-linear).
+
+    Behavior:
+        - If the first piece doesn't start at zero, flow rate is automatically bounded
+          by piecewise_flow_rate (when OnOffParameters are not used)
+        - Each segment represents a linear relationship within that flow rate range
+        - Effects are interpolated linearly within each piece
+        - All `Piece`s of the different `Piecewise`s at index i are active at the same time
+        - A decision whether to utilize the effect can be modeled by defining multiple Pieces for the same flow rate range
+
+    Examples:
+        # Tiered cost structure with increasing rates
+        PiecewiseEffectsPerFlowHour(
+            piecewise_flow_rate=Piecewise([
+                Piece(0, 50),    # Low flow segment: 0-50 units
+                Piece(50, 200)   # High flow segment: 50-200 units
+            ]),
+            piecewise_shares={
+                'Costs': Piecewise([
+                    Piece(0, 500),     # At flow=0: cost=0, at flow=50: cost=500
+                    Piece(500, 2000)   # At flow=50: cost=500, at flow=200: cost=2000
+                ]),
+                'CO2': Piecewise([
+                    Piece(0, 100),     # At flow=0: CO2=0, at flow=50: CO2=100
+                    Piece(100, 800)    # At flow=50: CO2=100, at flow=200: CO2=800
+                ])
+            }
+        )
+
+        # Decision between two suppliers with overlapping flow ranges
+        PiecewiseEffectsPerFlowHour(
+            piecewise_flow_rate=Piecewise([
+                Piece(0, 100),     # Supplier A: 0-100 units
+                Piece(50, 150)     # Supplier B: 50-150 units (overlaps with A)
+            ]),
+            piecewise_shares={
+                'Costs': Piecewise([
+                    Piece(0, 800),     # Supplier A: cheaper for low volumes
+                    Piece(400, 1200)   # Supplier B: better rates for high volumes
+                ])
+            }
+        )
+        # Flow range 50-100: Optimizer chooses between suppliers based on cost
+
+        # Optional equipment with minimum activation threshold
+        PiecewiseEffectsPerFlowHour(
+            piecewise_flow_rate=Piecewise([
+                Piece(0, 0),       # Equipment off: no flow
+                Piece(20, 100)     # Equipment on: minimum 20 units required
+            ]),
+            piecewise_shares={
+                'Costs': Piecewise([
+                    Piece(0, 0),       # No cost when off
+                    Piece(200, 800)    # Fixed startup cost + variable cost
+                ]),
+                'CO2': Piecewise([
+                    Piece(0, 0),       # No CO2 when off
+                    Piece(50, 300)     # Decreasing CO2 per fuel burn with higher power
+                ])
+            }
+        )
+        # Decision: Either flow=0 (off) or flow≥20 (on with minimum threshold)
+
+        # Equipment efficiency curve (although this might be better modeled as a Flow rather than an effect)
+        PiecewiseEffectsPerFlowHour(
+            piecewise_flow_rate=Piecewise([Piece(10, 100)]),  # Min 10, max 100 units
+            piecewise_shares={
+                'PowerConsumption': Piecewise([Piece(50, 800)])  # Non-linear efficiency
+            }
+        )
+
+    """
 
-    @has_time_dim.setter
-    def has_time_dim(self, value):
-        self._has_time_dim = value
-        self.piecewise_origin.has_time_dim = value
-        for piecewise in self.piecewise_shares.values():
-            piecewise.has_time_dim = value
+    def __init__(self, piecewise_flow_rate: Piecewise, piecewise_shares: Dict[str, Piecewise]):
+        self.piecewise_flow_rate = piecewise_flow_rate
+        self.piecewise_shares = piecewise_shares
 
     def transform_data(self, flow_system: 'FlowSystem', name_prefix: str):
-        self.piecewise_origin.transform_data(flow_system, f'{name_prefix}|PiecewiseEffects|origin')
-        for effect, piecewise in self.piecewise_shares.items():
-            piecewise.transform_data(flow_system, f'{name_prefix}|PiecewiseEffects|{effect}')
+        self.piecewise_flow_rate.transform_data(flow_system, f'{name_prefix}|PiecewiseEffectsPerFlowHour|origin')
+        for name, piecewise in self.piecewise_shares.items():
+            piecewise.transform_data(flow_system, f'{name_prefix}|PiecewiseEffectsPerFlowHour|{name}')
 
 
 @register_class_for_io
@@ -150,15 +369,14 @@ class InvestParameters(Interface):
 
     def __init__(
         self,
-        fixed_size: Optional[ScenarioData] = None,
-        minimum_size: Optional[ScenarioData] = None,
-        maximum_size: Optional[ScenarioData] = None,
+        fixed_size: Optional[Union[int, float]] = None,
+        minimum_size: Optional[Union[int, float]] = None,
+        maximum_size: Optional[Union[int, float]] = None,
         optional: bool = True,  # Investition ist weglassbar
-        fix_effects: Optional['EffectValuesUserScenario'] = None,
-        specific_effects: Optional['EffectValuesUserScenario'] = None,  # costs per Flow-Unit/Storage-Size/...
+        fix_effects: Optional['EffectValuesUserScalar'] = None,
+        specific_effects: Optional['EffectValuesUserScalar'] = None,  # costs per Flow-Unit/Storage-Size/...
         piecewise_effects: Optional[PiecewiseEffects] = None,
-        divest_effects: Optional['EffectValuesUserScenario'] = None,
-        investment_scenarios: Optional[Union[Literal['individual'], List[Union[int, str]]]] = None,
+        divest_effects: Optional['EffectValuesUserScalar'] = None,
     ):
         """
         Args:
@@ -169,99 +387,58 @@ class InvestParameters(Interface):
             specific_effects: Specific costs, e.g., in €/kW_nominal or €/m²_nominal.
                 Example: {costs: 3, CO2: 0.3} with costs and CO2 representing an Object of class Effect
                 (Attention: Annualize costs to chosen period!)
-            piecewise_effects: Define the effects of the investment as a piecewise function of the size of the investment.
-            minimum_size: Minimum possible size of the investment.
-            maximum_size: Maximum possible size of the investment.
-            investment_scenarios: For which scenarios to optimize the size for.
-                - 'individual': Optimize the size of each scenario individually
-                - List of scenario names: Optimize the size for the passed scenario names (equal size in all). All other scenarios will have the size 0.
-                - None: Equals to a list of all scenarios (default)
+            piecewise_effects: Linear piecewise relation [invest_pieces, cost_pieces].
+                Example 1:
+                    [           [5, 25, 25, 100],       # size in kW
+                     {costs:    [50,250,250,800],       # €
+                      PE:       [5, 25, 25, 100]        # kWh_PrimaryEnergy
+                      }
+                    ]
+                Example 2 (if only standard-effect):
+                    [   [5, 25, 25, 100],  # kW # size in kW
+                        [50,250,250,800]        # value for standart effect, typically €
+                     ]  # €
+                (Attention: Annualize costs to chosen period!)
+                (Args 'specific_effects' and 'fix_effects' can be used in parallel to Investsizepieces)
+            minimum_size: Min nominal value (only if: size_is_fixed = False). Defaults to CONFIG.modeling.EPSILON.
+            maximum_size: Max nominal value (only if: size_is_fixed = False). Defaults to CONFIG.modeling.BIG.
         """
-        self.fix_effects: EffectValuesUserScenario = fix_effects if fix_effects is not None else {}
-        self.divest_effects: EffectValuesUserScenario = divest_effects if divest_effects is not None else {}
+        self.fix_effects: EffectValuesUser = fix_effects or {}
+        self.divest_effects: EffectValuesUser = divest_effects or {}
         self.fixed_size = fixed_size
         self.optional = optional
-        self.specific_effects: EffectValuesUserScenario = specific_effects if specific_effects is not None else {}
+        self.specific_effects: EffectValuesUser = specific_effects or {}
         self.piecewise_effects = piecewise_effects
         self._minimum_size = minimum_size if minimum_size is not None else CONFIG.modeling.EPSILON
         self._maximum_size = maximum_size if maximum_size is not None else CONFIG.modeling.BIG  # default maximum
-        self.investment_scenarios = investment_scenarios
 
-    def transform_data(self, flow_system: 'FlowSystem', name_prefix: str):
-        self._plausibility_checks(flow_system)
-        self.fix_effects = flow_system.create_effect_time_series(
-            label_prefix=name_prefix,
-            effect_values=self.fix_effects,
-            label_suffix='fix_effects',
-            has_time_dim=False,
-            has_scenario_dim=True,
-        )
-        self.divest_effects = flow_system.create_effect_time_series(
-            label_prefix=name_prefix,
-            effect_values=self.divest_effects,
-            label_suffix='divest_effects',
-            has_time_dim=False,
-            has_scenario_dim=True,
-        )
-        self.specific_effects = flow_system.create_effect_time_series(
-            label_prefix=name_prefix,
-            effect_values=self.specific_effects,
-            label_suffix='specific_effects',
-            has_time_dim=False,
-            has_scenario_dim=True,
-        )
-        if self.piecewise_effects is not None:
-            self.piecewise_effects.has_time_dim = False
-            self.piecewise_effects.transform_data(flow_system, f'{name_prefix}|PiecewiseEffects')
-
-        self._minimum_size = flow_system.create_time_series(
-            f'{name_prefix}|minimum_size', self.minimum_size, has_time_dim=False, has_scenario_dim=True
-        )
-        self._maximum_size = flow_system.create_time_series(
-            f'{name_prefix}|maximum_size', self.maximum_size, has_time_dim=False, has_scenario_dim=True
-        )
-        if self.fixed_size is not None:
-            self.fixed_size = flow_system.create_time_series(
-                f'{name_prefix}|fixed_size', self.fixed_size, has_time_dim=False, has_scenario_dim=True
-            )
-
-    def _plausibility_checks(self, flow_system):
-        if isinstance(self.investment_scenarios, list):
-            if not set(self.investment_scenarios).issubset(flow_system.time_series_collection.scenarios):
-                raise ValueError(
-                    f'Some scenarios in investment_scenarios are not present in the time_series_collection: '
-                    f'{set(self.investment_scenarios) - set(flow_system.time_series_collection.scenarios)}'
-                )
-        if self.investment_scenarios is not None:
-            if not self.optional:
-                if self.minimum_size is not None or self.fixed_size is not None:
-                    logger.warning(
-                        'When using investment_scenarios, minimum_size and fixed_size should only ne used if optional is True.'
-                        'Otherwise the investment cannot be 0 incertain scenarios while being non-zero in others.'
-                    )
+    def transform_data(self, flow_system: 'FlowSystem'):
+        self.fix_effects = flow_system.effects.create_effect_values_dict(self.fix_effects)
+        self.divest_effects = flow_system.effects.create_effect_values_dict(self.divest_effects)
+        self.specific_effects = flow_system.effects.create_effect_values_dict(self.specific_effects)
 
     @property
     def minimum_size(self):
-        return self.fixed_size if self.fixed_size is not None else self._minimum_size
+        return self.fixed_size or self._minimum_size
 
     @property
     def maximum_size(self):
-        return self.fixed_size if self.fixed_size is not None else self._maximum_size
+        return self.fixed_size or self._maximum_size
 
 
 @register_class_for_io
 class OnOffParameters(Interface):
     def __init__(
         self,
-        effects_per_switch_on: Optional['EffectValuesUserTimestep'] = None,
-        effects_per_running_hour: Optional['EffectValuesUserTimestep'] = None,
-        on_hours_total_min: Optional[ScenarioData] = None,
-        on_hours_total_max: Optional[ScenarioData] = None,
-        consecutive_on_hours_min: Optional[TimestepData] = None,
-        consecutive_on_hours_max: Optional[TimestepData] = None,
-        consecutive_off_hours_min: Optional[TimestepData] = None,
-        consecutive_off_hours_max: Optional[TimestepData] = None,
-        switch_on_total_max: Optional[ScenarioData] = None,
+        effects_per_switch_on: Optional['EffectValuesUser'] = None,
+        effects_per_running_hour: Optional['EffectValuesUser'] = None,
+        on_hours_total_min: Optional[int] = None,
+        on_hours_total_max: Optional[int] = None,
+        consecutive_on_hours_min: Optional[NumericData] = None,
+        consecutive_on_hours_max: Optional[NumericData] = None,
+        consecutive_off_hours_min: Optional[NumericData] = None,
+        consecutive_off_hours_max: Optional[NumericData] = None,
+        switch_on_total_max: Optional[int] = None,
         force_switch_on: bool = False,
     ):
         """
@@ -284,8 +461,8 @@ class OnOffParameters(Interface):
             switch_on_total_max: max nr of switchOn operations
             force_switch_on: force creation of switch on variable, even if there is no switch_on_total_max
         """
-        self.effects_per_switch_on: EffectValuesUserTimestep = effects_per_switch_on or {}
-        self.effects_per_running_hour: EffectValuesUserTimestep = effects_per_running_hour or {}
+        self.effects_per_switch_on: EffectValuesUser = effects_per_switch_on or {}
+        self.effects_per_running_hour: EffectValuesUser = effects_per_running_hour or {}
         self.on_hours_total_min: Scalar = on_hours_total_min
         self.on_hours_total_max: Scalar = on_hours_total_max
         self.consecutive_on_hours_min: NumericDataTS = consecutive_on_hours_min
@@ -314,15 +491,6 @@ class OnOffParameters(Interface):
         self.consecutive_off_hours_max = flow_system.create_time_series(
             f'{name_prefix}|consecutive_off_hours_max', self.consecutive_off_hours_max
         )
-        self.on_hours_total_max = flow_system.create_time_series(
-            f'{name_prefix}|on_hours_total_max', self.on_hours_total_max, has_time_dim=False
-        )
-        self.on_hours_total_min = flow_system.create_time_series(
-            f'{name_prefix}|on_hours_total_min', self.on_hours_total_min, has_time_dim=False
-        )
-        self.switch_on_total_max = flow_system.create_time_series(
-            f'{name_prefix}|switch_on_total_max', self.switch_on_total_max, has_time_dim=False
-        )
 
     @property
     def use_off(self) -> bool: