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

flixopt/effects.py

@@ -5,19 +5,22 @@ Different Datatypes are used to represent the effects with assigned values by th
 which are then transformed into the internal data structure.
 """
 
+from __future__ import annotations
+
 import logging
 import warnings
-from typing import TYPE_CHECKING, Dict, Iterator, List, Literal, Optional, Union
+from typing import TYPE_CHECKING, Literal
 
 import linopy
 import numpy as np
-import pandas as pd
 
-from .core import NumericData, NumericDataTS, Scalar, TimeSeries, TimeSeriesCollection
+from .core import NumericDataTS, Scalar, TimeSeries
 from .features import ShareAllocationModel
-from .structure import Element, ElementModel, Interface, Model, SystemModel, register_class_for_io
+from .structure import Element, ElementModel, Model, SystemModel, register_class_for_io
 
 if TYPE_CHECKING:
+    from collections.abc import Iterator
+
     from .flow_system import FlowSystem
 
 logger = logging.getLogger('flixopt')
@@ -26,8 +29,107 @@ logger = logging.getLogger('flixopt')
 @register_class_for_io
 class Effect(Element):
     """
-    Effect, i.g. costs, CO2 emissions, area, ...
-    Components, FLows, and so on can contribute to an Effect. One Effect is chosen as the Objective of the Optimization
+    Represents system-wide impacts like costs, emissions, resource consumption, or other effects.
+
+    Effects capture the broader impacts of system operation and investment decisions beyond
+    the primary energy/material flows. Each Effect accumulates contributions from Components,
+    Flows, and other system elements. One Effect is typically chosen as the optimization
+    objective, while others can serve as constraints or tracking metrics.
+
+    Effects support comprehensive modeling including operational and investment contributions,
+    cross-effect relationships (e.g., carbon pricing), and flexible constraint formulation.
+
+    Args:
+        label: The label of the Element. Used to identify it in the FlowSystem.
+        unit: The unit of the effect (e.g., '€', 'kg_CO2', 'kWh_primary', 'm²').
+            This is informative only and does not affect optimization calculations.
+        description: Descriptive name explaining what this effect represents.
+        is_standard: If True, this is a standard effect allowing direct value input
+            without effect dictionaries. Used for simplified effect specification (and less boilerplate code).
+        is_objective: If True, this effect serves as the optimization objective function.
+            Only one effect can be marked as objective per optimization.
+        specific_share_to_other_effects_operation: Operational cross-effect contributions.
+            Maps this effect's operational values to contributions to other effects
+        specific_share_to_other_effects_invest: Investment cross-effect contributions.
+            Maps this effect's investment values to contributions to other effects.
+        minimum_operation: Minimum allowed total operational contribution across all timesteps.
+        maximum_operation: Maximum allowed total operational contribution across all timesteps.
+        minimum_operation_per_hour: Minimum allowed operational contribution per timestep.
+        maximum_operation_per_hour: Maximum allowed operational contribution per timestep.
+        minimum_invest: Minimum allowed total investment contribution.
+        maximum_invest: Maximum allowed total investment contribution.
+        minimum_total: Minimum allowed total effect (operation + investment combined).
+        maximum_total: Maximum allowed total effect (operation + investment combined).
+        meta_data: Used to store additional information. Not used internally but saved
+            in results. Only use Python native types.
+
+    Examples:
+        Basic cost objective:
+
+        ```python
+        cost_effect = Effect(label='system_costs', unit='€', description='Total system costs', is_objective=True)
+        ```
+
+        CO2 emissions with carbon pricing:
+
+        ```python
+        co2_effect = Effect(
+            label='co2_emissions',
+            unit='kg_CO2',
+            description='Carbon dioxide emissions',
+            specific_share_to_other_effects_operation={'costs': 50},  # €50/t_CO2
+            maximum_total=1_000_000,  # 1000 t CO2 annual limit
+        )
+        ```
+
+        Land use constraint:
+
+        ```python
+        land_use = Effect(
+            label='land_usage',
+            unit='m²',
+            description='Land area requirement',
+            maximum_total=50_000,  # Maximum 5 hectares available
+        )
+        ```
+
+        Primary energy tracking:
+
+        ```python
+        primary_energy = Effect(
+            label='primary_energy',
+            unit='kWh_primary',
+            description='Primary energy consumption',
+            specific_share_to_other_effects_operation={'costs': 0.08},  # €0.08/kWh
+        )
+        ```
+
+        Water consumption with tiered constraints:
+
+        ```python
+        water_usage = Effect(
+            label='water_consumption',
+            unit='m³',
+            description='Industrial water usage',
+            minimum_operation_per_hour=10,  # Minimum 10 m³/h for process stability
+            maximum_operation_per_hour=500,  # Maximum 500 m³/h capacity limit
+            maximum_total=100_000,  # Annual permit limit: 100,000 m³
+        )
+        ```
+
+    Note:
+        Effect bounds can be None to indicate no constraint in that direction.
+
+        Cross-effect relationships enable sophisticated modeling like carbon pricing,
+        resource valuation, or multi-criteria optimization with weighted objectives.
+
+        The unit field is purely informational - ensure dimensional consistency
+        across all contributions to each effect manually.
+
+        Effects are accumulated as:
+        - Total = Σ(operational contributions) + Σ(investment contributions)
+        - Cross-effects add to target effects based on specific_share ratios
+
     """
 
     def __init__(
@@ -35,41 +137,20 @@ class Effect(Element):
         label: str,
         unit: str,
         description: str,
-        meta_data: Optional[Dict] = None,
+        meta_data: dict | None = None,
         is_standard: bool = False,
         is_objective: bool = False,
-        specific_share_to_other_effects_operation: Optional['EffectValuesUser'] = None,
-        specific_share_to_other_effects_invest: Optional['EffectValuesUser'] = None,
-        minimum_operation: Optional[Scalar] = None,
-        maximum_operation: Optional[Scalar] = None,
-        minimum_invest: Optional[Scalar] = None,
-        maximum_invest: Optional[Scalar] = None,
-        minimum_operation_per_hour: Optional[NumericDataTS] = None,
-        maximum_operation_per_hour: Optional[NumericDataTS] = None,
-        minimum_total: Optional[Scalar] = None,
-        maximum_total: Optional[Scalar] = None,
+        specific_share_to_other_effects_operation: EffectValuesUser | None = None,
+        specific_share_to_other_effects_invest: EffectValuesUser | None = None,
+        minimum_operation: Scalar | None = None,
+        maximum_operation: Scalar | None = None,
+        minimum_invest: Scalar | None = None,
+        maximum_invest: Scalar | None = None,
+        minimum_operation_per_hour: NumericDataTS | None = None,
+        maximum_operation_per_hour: NumericDataTS | None = None,
+        minimum_total: Scalar | None = None,
+        maximum_total: Scalar | None = None,
     ):
-        """
-        Args:
-            label: The label of the Element. Used to identify it in the FlowSystem
-            unit: The unit of effect, i.g. €, kg_CO2, kWh_primaryEnergy
-            description: The long name
-            is_standard: true, if Standard-Effect (for direct input of value without effect (alternatively to dict)) , else false
-            is_objective: true, if optimization target
-            specific_share_to_other_effects_operation: {effectType: TS, ...}, i.g. 180 €/t_CO2, input as {costs: 180}, optional
-                share to other effects (only operation)
-            specific_share_to_other_effects_invest: {effectType: TS, ...}, i.g. 180 €/t_CO2, input as {costs: 180}, optional
-                share to other effects (only invest).
-            minimum_operation: minimal sum (only operation) of the effect.
-            maximum_operation: maximal sum (nur operation) of the effect.
-            minimum_operation_per_hour: max. value per hour (only operation) of effect (=sum of all effect-shares) for each timestep!
-            maximum_operation_per_hour:  min. value per hour (only operation) of effect (=sum of all effect-shares) for each timestep!
-            minimum_invest: minimal sum (only invest) of the effect
-            maximum_invest: maximal sum (only invest) of the effect
-            minimum_total: min sum of effect (invest+operation).
-            maximum_total: max sum of effect (invest+operation).
-            meta_data: used to store more information about the Element. Is not used internally, but saved in the results. Only use python native types.
-        """
         super().__init__(label, meta_data=meta_data)
         self.label = label
         self.unit = unit
@@ -82,14 +163,14 @@ class Effect(Element):
         self.specific_share_to_other_effects_invest: EffectValuesUser = specific_share_to_other_effects_invest or {}
         self.minimum_operation = minimum_operation
         self.maximum_operation = maximum_operation
-        self.minimum_operation_per_hour: NumericDataTS = minimum_operation_per_hour
-        self.maximum_operation_per_hour: NumericDataTS = maximum_operation_per_hour
+        self.minimum_operation_per_hour = minimum_operation_per_hour
+        self.maximum_operation_per_hour = maximum_operation_per_hour
         self.minimum_invest = minimum_invest
         self.maximum_invest = maximum_invest
         self.minimum_total = minimum_total
         self.maximum_total = maximum_total
 
-    def transform_data(self, flow_system: 'FlowSystem'):
+    def transform_data(self, flow_system: FlowSystem):
         self.minimum_operation_per_hour = flow_system.create_time_series(
             f'{self.label_full}|minimum_operation_per_hour', self.minimum_operation_per_hour
         )
@@ -102,7 +183,7 @@ class Effect(Element):
             f'{self.label_full}|operation->', self.specific_share_to_other_effects_operation, 'operation'
         )
 
-    def create_model(self, model: SystemModel) -> 'EffectModel':
+    def create_model(self, model: SystemModel) -> EffectModel:
         self._plausibility_checks()
         self.model = EffectModel(model, self)
         return self.model
@@ -116,7 +197,7 @@ class EffectModel(ElementModel):
     def __init__(self, model: SystemModel, element: Effect):
         super().__init__(model, element)
         self.element: Effect = element
-        self.total: Optional[linopy.Variable] = None
+        self.total: linopy.Variable | None = None
         self.invest: ShareAllocationModel = self.add(
             ShareAllocationModel(
                 self._model,
@@ -169,13 +250,13 @@ class EffectModel(ElementModel):
         )
 
 
-EffectValuesExpr = Dict[str, linopy.LinearExpression]  # Used to create Shares
-EffectTimeSeries = Dict[str, TimeSeries]  # Used internally to index values
-EffectValuesDict = Dict[str, NumericDataTS]  # How effect values are stored
-EffectValuesUser = Union[NumericDataTS, Dict[str, NumericDataTS]]  # User-specified Shares to Effects
+EffectValuesExpr = dict[str, linopy.LinearExpression]  # Used to create Shares
+EffectTimeSeries = dict[str, TimeSeries]  # Used internally to index values
+EffectValuesDict = dict[str, NumericDataTS]  # How effect values are stored
+EffectValuesUser = NumericDataTS | dict[str, NumericDataTS]  # User-specified Shares to Effects
 """ This datatype is used to define the share to an effect by a certain attribute. """
 
-EffectValuesUserScalar = Union[Scalar, Dict[str, Scalar]]  # User-specified Shares to Effects
+EffectValuesUserScalar = Scalar | dict[str, Scalar]  # User-specified Shares to Effects
 """ This datatype is used to define the share to an effect by a certain attribute. Only scalars are allowed. """
 
 
@@ -184,15 +265,15 @@ class EffectCollection:
     Handling all Effects
     """
 
-    def __init__(self, *effects: List[Effect]):
+    def __init__(self, *effects: Effect):
         self._effects = {}
-        self._standard_effect: Optional[Effect] = None
-        self._objective_effect: Optional[Effect] = None
+        self._standard_effect: Effect | None = None
+        self._objective_effect: Effect | None = None
 
-        self.model: Optional[EffectCollectionModel] = None
+        self.model: EffectCollectionModel | None = None
         self.add_effects(*effects)
 
-    def create_model(self, model: SystemModel) -> 'EffectCollectionModel':
+    def create_model(self, model: SystemModel) -> EffectCollectionModel:
         self._plausibility_checks()
         self.model = EffectCollectionModel(model, self)
         return self.model
@@ -208,7 +289,7 @@ class EffectCollection:
             self._effects[effect.label] = effect
             logger.info(f'Registered new Effect: {effect.label}')
 
-    def create_effect_values_dict(self, effect_values_user: EffectValuesUser) -> Optional[EffectValuesDict]:
+    def create_effect_values_dict(self, effect_values_user: EffectValuesUser) -> EffectValuesDict | None:
         """
         Converts effect values into a dictionary. If a scalar is provided, it is associated with a default effect type.
 
@@ -224,7 +305,7 @@ class EffectCollection:
             A dictionary with None or Effect as the key, or None if input is None.
         """
 
-        def get_effect_label(eff: Union[Effect, str]) -> str:
+        def get_effect_label(eff: Effect | str) -> str:
             """Temporary function to get the label of an effect and warn for deprecation"""
             if isinstance(eff, Effect):
                 warnings.warn(
@@ -233,7 +314,7 @@ class EffectCollection:
                     UserWarning,
                     stacklevel=2,
                 )
-                return eff.label_full
+                return eff.label
             else:
                 return eff
 
@@ -241,7 +322,7 @@ class EffectCollection:
             return None
         if isinstance(effect_values_user, dict):
             return {get_effect_label(effect): value for effect, value in effect_values_user.items()}
-        return {self.standard_effect.label_full: effect_values_user}
+        return {self.standard_effect.label: effect_values_user}
 
     def _plausibility_checks(self) -> None:
         # Check circular loops in effects:
@@ -258,15 +339,15 @@ class EffectCollection:
             # operation:
             for target_effect in effect.specific_share_to_other_effects_operation.keys():
                 assert effect not in self[target_effect].specific_share_to_other_effects_operation.keys(), (
-                    f'Error: circular operation-shares \n{error_str(target_effect.label, target_effect.label)}'
+                    f'Error: circular operation-shares \n{error_str(effect.label, self[target_effect].label)}'
                 )
             # invest:
             for target_effect in effect.specific_share_to_other_effects_invest.keys():
                 assert effect not in self[target_effect].specific_share_to_other_effects_invest.keys(), (
-                    f'Error: circular invest-shares \n{error_str(target_effect.label, target_effect.label)}'
+                    f'Error: circular invest-shares \n{error_str(effect.label, self[target_effect].label)}'
                 )
 
-    def __getitem__(self, effect: Union[str, Effect]) -> 'Effect':
+    def __getitem__(self, effect: str | Effect | None) -> Effect:
         """
         Get an effect by label, or return the standard effect if None is passed
 
@@ -292,7 +373,7 @@ class EffectCollection:
     def __len__(self) -> int:
         return len(self._effects)
 
-    def __contains__(self, item: Union[str, 'Effect']) -> bool:
+    def __contains__(self, item: str | Effect) -> bool:
         """Check if the effect exists. Checks for label or object"""
         if isinstance(item, str):
             return item in self.effects  # Check if the label exists
@@ -301,7 +382,7 @@ class EffectCollection:
         return False
 
     @property
-    def effects(self) -> Dict[str, Effect]:
+    def effects(self) -> dict[str, Effect]:
         return self._effects
 
     @property
@@ -337,7 +418,7 @@ class EffectCollectionModel(Model):
     def __init__(self, model: SystemModel, effects: EffectCollection):
         super().__init__(model, label_of_element='Effects')
         self.effects = effects
-        self.penalty: Optional[ShareAllocationModel] = None
+        self.penalty: ShareAllocationModel | None = None
 
     def add_share_to_effects(
         self,