Feature/300 piecewiseeffects for flows

.github/workflows/python-app.yaml

@@ -142,11 +142,58 @@ jobs:
         with:
           python-version: ${{ env.PYTHON_VERSION }}
 
-      - name: Extract release notes
+      - name: Check if pre-release
+        id: prerelease
+        run: |
+          if [[ "${{ github.ref }}" =~ (alpha|beta|rc) ]]; then
+            echo "is_prerelease=true" >> $GITHUB_OUTPUT
+            echo "✅ Detected pre-release"
+          else
+            echo "is_prerelease=false" >> $GITHUB_OUTPUT
+            echo "✅ Detected stable release"
+          fi
+
+      - name: Create release notes
         run: |
           VERSION=${GITHUB_REF#refs/tags/v}
-          echo "Extracting release notes for version: $VERSION"
-          python scripts/extract_release_notes.py $VERSION > current_release_notes.md
+          echo "Creating release notes for version: $VERSION"
+
+          if [[ "${{ steps.prerelease.outputs.is_prerelease }}" == "true" ]]; then
+            echo "📝 Generating pre-release notes"
+            cat > current_release_notes.md << EOF
+          # Pre-release $VERSION
+
+          This is a pre-release version for testing and feedback.
+
+          ## Installation
+          \`\`\`bash
+          pip install flixopt==$VERSION --pre
+          \`\`\`
+
+          ## What's Changed
+          See the [unreleased section](https://github.com/flixOpt/flixopt/blob/main/CHANGELOG.md#unreleased) in the changelog for upcoming features and changes.
+
+          ## Feedback
+          Please report any issues or feedback on [GitHub Issues](https://github.com/flixOpt/flixopt/issues).
+          EOF
+          else
+            echo "📝 Extracting release notes from changelog"
+            if python scripts/extract_release_notes.py "$VERSION" > current_release_notes.md 2>/dev/null; then
+              echo "✅ Successfully extracted release notes"
+            else
+              echo "⚠️ No release notes found, using fallback"
+              cat > current_release_notes.md << EOF
+          # Release $VERSION
+
+          See the [full changelog](https://github.com/flixOpt/flixopt/blob/main/CHANGELOG.md) for details.
+          EOF
+            fi
+          fi
+
+          echo "Generated release notes:"
+          echo "========================"
+          cat current_release_notes.md
+          echo "========================"
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2

CHANGELOG.md

@@ -10,6 +10,8 @@ Take Care: The CI will automatically append a "Whats CHanged" section to the cha
 This contains all COmmits, PR's and Contributers.
 Therefore, the Changelog should focus on the user-facing changes.
 
+Template:
+----
 ## [Unreleased] - ????-??-??
 
 ### Changed
@@ -24,8 +26,22 @@ Therefore, the Changelog should focus on the user-facing changes.
 
 ### Development
 
+----
+Upcoming Release:
+
+## [2.2.0] - 2025-09-13
+THis release introduces a new interface `PiecewiseEffectsPerFlowHour` to model non-linear relations between flow rates and effects.
+This greatly enhances Model flexibility.
+
+### Fixed
+- LinearConverter with `PiecewiseConversion` allowed flows to reach 0 values, even though they didnt have `OnOffParameters` nor `PiecewiseConversion` actually containing 0 in its `Piece`s.
+
+### Added
+- Added new Interface `PiecewiseEffectsPerFlowHour` to model non-linear relations between flow rates and effects.
+
 Until here -->
 
+
 ## [2.1.7] - 2025-09-13
 
 This update is a maintenance release to improve Code Quality, CI and update the dependencies.

flixopt/__init__.py

@@ -22,6 +22,7 @@
     Piecewise,
     PiecewiseConversion,
     PiecewiseEffects,
+    PiecewiseEffectsPerFlowHour,
     SegmentedCalculation,
     Sink,
     Source,

flixopt/commons.py

@@ -18,7 +18,15 @@
 from .effects import Effect
 from .elements import Bus, Flow
 from .flow_system import FlowSystem
-from .interface import InvestParameters, OnOffParameters, Piece, Piecewise, PiecewiseConversion, PiecewiseEffects
+from .interface import (
+    InvestParameters,
+    OnOffParameters,
+    Piece,
+    Piecewise,
+    PiecewiseConversion,
+    PiecewiseEffects,
+    PiecewiseEffectsPerFlowHour,
+)
 
 __all__ = [
     'TimeSeriesData',
@@ -48,4 +56,5 @@
     'results',
     'linear_converters',
     'solvers',
+    'PiecewiseEffectsPerFlowHour',
 ]

flixopt/components.py

@@ -24,9 +24,119 @@
 
 @register_class_for_io
 class LinearConverter(Component):
-    """
-    Converts input-Flows into output-Flows via linear conversion factors
+    """Convert input flows into output flows using linear or piecewise linear conversion factors.
+
+    This component models conversion equipment where input flows are transformed
+    into output flows with fixed or variable conversion ratios, such as:
+
+    - Heat pumps and chillers with variable efficiency
+    - Power plants with fuel-to-electricity conversion
+    - Chemical processes with multiple inputs/outputs
+    - Pumps and compressors
+    - Combined heat and power (CHP) plants
+
+    Args:
+        label: Unique identifier for the component in the FlowSystem.
+        inputs: List of input Flow objects that feed into the converter.
+        outputs: List of output Flow objects produced by the converter.
+        on_off_parameters: Controls binary on/off behavior of the converter.
+            When specified, the component can be completely turned on or off, affecting
+            all connected flows. This creates binary variables in the optimization.
+            For better performance, consider using OnOffParameters on individual flows instead.
+        conversion_factors: Linear conversion ratios between flows as time series data.
+            List of dictionaries mapping flow labels to their conversion factors.
+            Mutually exclusive with piecewise_conversion.
+        piecewise_conversion: Piecewise linear conversion relationships between flows.
+            Enables modeling of variable efficiency or discrete operating modes.
+            Mutually exclusive with conversion_factors.
+        meta_data: Additional information stored with the component.
+            Saved in results but not used internally. Use only Python native types.
+
+    Warning:
+        When using `piecewise_conversion` without `on_off_parameters`, flow rates cannot
+        reach zero unless explicitly defined with zero-valued pieces (e.g., `fx.Piece(0, 0)`).
+        This prevents unintended zero flows and maintains mathematical consistency.
+
+        To allow zero flow rates:
+
+        - Add `on_off_parameters` to enable complete shutdown, or
+        - Include explicit zero pieces in your `piecewise_conversion` definition
+
+        This behavior was clarified in v2.1.7 to prevent optimization edge cases.
+
+    Examples:
+        Simple heat pump with fixed COP:
+
+        ```python
+        heat_pump = fx.LinearConverter(
+            label='heat_pump',
+            inputs=[electricity_flow],
+            outputs=[heat_flow],
+            conversion_factors=[
+                {
+                    'electricity_flow': 1.0,  # 1 kW electricity input
+                    'heat_flow': 3.5,  # 3.5 kW heat output (COP=3.5)
+                }
+            ],
+        )
+        ```
+
+        Variable efficiency heat pump:
+
+        ```python
+        heat_pump = fx.LinearConverter(
+            label='variable_heat_pump',
+            inputs=[electricity_flow],
+            outputs=[heat_flow],
+            piecewise_conversion=fx.PiecewiseConversion(
+                {
+                    'electricity_flow': fx.Piecewise(
+                        [
+                            fx.Piece(0, 10),  # Allow zero to 10 kW input
+                            fx.Piece(10, 25),  # Higher load operation
+                        ]
+                    ),
+                    'heat_flow': fx.Piecewise(
+                        [
+                            fx.Piece(0, 35),  # COP=3.5 at low loads
+                            fx.Piece(35, 75),  # COP=3.0 at high loads
+                        ]
+                    ),
+                }
+            ),
+        )
+        ```
+
+        Combined heat and power plant:
+
+        ```python
+        chp_plant = fx.LinearConverter(
+            label='chp_plant',
+            inputs=[natural_gas_flow],
+            outputs=[electricity_flow, heat_flow],
+            conversion_factors=[
+                {
+                    'natural_gas_flow': 1.0,  # 1 MW fuel input
+                    'electricity_flow': 0.4,  # 40% electrical efficiency
+                    'heat_flow': 0.45,  # 45% thermal efficiency
+                }
+            ],
+            on_off_parameters=fx.OnOffParameters(
+                min_on_hours=4,  # Minimum 4-hour operation
+                min_off_hours=2,  # Minimum 2-hour downtime
+            ),
+        )
+        ```
+
+    Note:
+        Either `conversion_factors` or `piecewise_conversion` must be specified, but not both.
+        The component automatically handles the mathematical relationships between all
+        connected flows according to the specified conversion ratios.
 
+    See Also:
+        PiecewiseConversion: For variable efficiency modeling
+        OnOffParameters: For binary on/off control
+        Flow: Input and output flow definitions
     """
 
     def __init__(
@@ -39,21 +149,6 @@ def __init__(
         piecewise_conversion: Optional[PiecewiseConversion] = None,
         meta_data: Optional[Dict] = None,
     ):
-        """
-        Args:
-            label: The label of the Element. Used to identify it in the FlowSystem
-            inputs: The input Flows
-            outputs: The output Flows
-            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 single Flow instead to keep the number of binary variables low.
-                See class OnOffParameters.
-            conversion_factors: linear relation between flows.
-                Either 'conversion_factors' or 'piecewise_conversion' can be used!
-            piecewise_conversion: Define a piecewise linear relation between flow rates of different flows.
-                Either 'conversion_factors' or 'piecewise_conversion' can be used!
-            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, inputs, outputs, on_off_parameters, meta_data=meta_data)
         self.conversion_factors = conversion_factors or []
         self.piecewise_conversion = piecewise_conversion

flixopt/elements.py

@@ -12,8 +12,8 @@
 from .config import CONFIG
 from .core import NumericData, NumericDataTS, PlausibilityError, Scalar, TimeSeriesCollection
 from .effects import EffectValuesUser
-from .features import InvestmentModel, OnOffModel, PreventSimultaneousUsageModel
-from .interface import InvestParameters, OnOffParameters
+from .features import InvestmentModel, OnOffModel, PiecewiseEffectsPerFlowHourModel, PreventSimultaneousUsageModel
+from .interface import InvestParameters, OnOffParameters, PiecewiseEffectsPerFlowHour
 from .structure import Element, ElementModel, SystemModel, register_class_for_io
 
 if TYPE_CHECKING:
@@ -159,6 +159,7 @@ def __init__(
         relative_minimum: NumericDataTS = 0,
         relative_maximum: NumericDataTS = 1,
         effects_per_flow_hour: Optional[EffectValuesUser] = None,
+        piecewise_effects_per_flow_hour: Optional[PiecewiseEffectsPerFlowHour] = None,
         on_off_parameters: Optional[OnOffParameters] = None,
         flow_hours_total_max: Optional[Scalar] = None,
         flow_hours_total_min: Optional[Scalar] = None,
@@ -180,6 +181,7 @@ def __init__(
                  def: :math:`load\_factor:= sumFlowHours/ (nominal\_val \cdot \Delta t_{tot})`
             load_factor_max: maximal load factor (see minimal load factor)
             effects_per_flow_hour: operational costs, costs per flow-"work"
+            piecewise_effects_per_flow_hour: piecewise relation between flow hours and effects
             on_off_parameters: If present, flow can be "off", i.e. be zero (only relevant if relative_minimum > 0)
                 Therefore a binary var "on" is used. Further, several other restrictions and effects can be modeled
                 through this On/Off State (See OnOffParameters)
@@ -207,6 +209,7 @@ def __init__(
         self.load_factor_max = load_factor_max
         # self.positive_gradient = TimeSeries('positive_gradient', positive_gradient, self)
         self.effects_per_flow_hour = effects_per_flow_hour if effects_per_flow_hour is not None else {}
+        self.piecewise_effects_per_flow_hour = piecewise_effects_per_flow_hour
         self.flow_hours_total_max = flow_hours_total_max
         self.flow_hours_total_min = flow_hours_total_min
         self.on_off_parameters = on_off_parameters
@@ -248,6 +251,8 @@ def transform_data(self, flow_system: 'FlowSystem'):
         self.effects_per_flow_hour = flow_system.create_effect_time_series(
             self.label_full, self.effects_per_flow_hour, 'per_flow_hour'
         )
+        if self.piecewise_effects_per_flow_hour is not None:
+            self.piecewise_effects_per_flow_hour.transform_data(flow_system, self.label_full)
         if self.on_off_parameters is not None:
             self.on_off_parameters.transform_data(flow_system, self.label_full)
         if isinstance(self.size, InvestParameters):
@@ -398,6 +403,21 @@ def _create_shares(self):
                 target='operation',
             )
 
+        if self.element.piecewise_effects_per_flow_hour is not None:
+            self.piecewise_effects = self.add(
+                PiecewiseEffectsPerFlowHourModel(
+                    model=self._model,
+                    label_of_element=self.label_of_element,
+                    piecewise_origin=(
+                        self.flow_rate.name,
+                        self.element.piecewise_effects_per_flow_hour.piecewise_flow_rate,
+                    ),
+                    piecewise_shares=self.element.piecewise_effects_per_flow_hour.piecewise_shares,
+                    zero_point=self.on_off.on if self.on_off is not None else False,
+                ),
+            )
+            self.piecewise_effects.do_modeling()
+
     def _create_bounds_for_load_factor(self):
         # TODO: Add Variable load_factor for better evaluation?