flixopt 2.1.7__tar.gz → 2.2.0rc2__tar.gz

{flixopt-2.1.7 → flixopt-2.2.0rc2}/.github/workflows/python-app.yaml

@@ -2,12 +2,15 @@ name: Python Package CI/CD
 
 on:
   push:
-    branches: [main, dev]  # Added develop branch
-    tags:
-      - 'v*.*.*'  # Trigger on semantic version tags
+    branches: [main]        # Only main branch
+    tags: ['v*.*.*']
   pull_request:
-    branches: [main, dev, 'feature/*', 'hotfix/*', 'fix/*']
+    branches: [main, dev]
     types: [opened, synchronize, reopened]
+    paths-ignore:
+      - 'docs/**'
+      - '*.md'
+      - 'README*'
   workflow_dispatch:  # Allow manual triggering
 
 # Set permissions for security
@@ -139,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

{flixopt-2.1.7 → flixopt-2.2.0rc2}/CHANGELOG.md

@@ -6,8 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 <!-- This text won't be rendered
+Take Care: The CI will automatically append a "Whats CHanged" section to the changelog.
+This contains all COmmits, PR's and Contributers.
+Therefore, the Changelog should focus on the user-facing changes.
 
-## [Unreleased]
+Template:
+----
+## [Unreleased] - ????-??-??
 
 ### Changed
 
@@ -21,8 +26,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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-2.1.7/flixopt.egg-info → flixopt-2.2.0rc2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flixopt
-Version: 2.1.7
+Version: 2.2.0rc2
 Summary: Vector based energy and material flow optimization framework in Python.
 Author-email: "Chair of Building Energy Systems and Heat Supply, TU Dresden" <peter.stange@tu-dresden.de>, Felix Bumann <felixbumann387@gmail.com>, Felix Panitz <baumbude@googlemail.com>, Peter Stange <peter.stange@tu-dresden.de>
 Maintainer-email: Felix Bumann <felixbumann387@gmail.com>, Peter Stange <peter.stange@tu-dresden.de>

{flixopt-2.1.7 → flixopt-2.2.0rc2}/flixopt/__init__.py

@@ -22,6 +22,7 @@ from .commons import (
     Piecewise,
     PiecewiseConversion,
     PiecewiseEffects,
+    PiecewiseEffectsPerFlowHour,
     SegmentedCalculation,
     Sink,
     Source,

{flixopt-2.1.7 → flixopt-2.2.0rc2}/flixopt/commons.py

@@ -18,7 +18,15 @@ from .core import TimeSeriesData
 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 @@ __all__ = [
     'results',
     'linear_converters',
     'solvers',
+    'PiecewiseEffectsPerFlowHour',
 ]

{flixopt-2.1.7 → flixopt-2.2.0rc2}/flixopt/components.py

@@ -24,9 +24,119 @@ logger = logging.getLogger('flixopt')
 
 @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 @@ class LinearConverter(Component):
         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-2.1.7 → flixopt-2.2.0rc2}/flixopt/elements.py

@@ -12,8 +12,8 @@ import numpy as np
 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 @@ class Flow(Element):
         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 @@ class Flow(Element):
                  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 @@ class Flow(Element):
         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 @@ class Flow(Element):
         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 @@ class FlowModel(ElementModel):
                 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?
 

{flixopt-2.1.7 → flixopt-2.2.0rc2}/flixopt/features.py

@@ -12,7 +12,7 @@ import numpy as np
 from . import utils
 from .config import CONFIG
 from .core import NumericData, Scalar, TimeSeries
-from .interface import InvestParameters, OnOffParameters, Piecewise
+from .interface import InvestParameters, OnOffParameters, Piece, Piecewise
 from .structure import Model, SystemModel
 
 logger = logging.getLogger('flixopt')
@@ -841,7 +841,7 @@ class PiecewiseModel(Model):
         label: str = '',
     ):
         """
-        Modeling a Piecewise relation between miultiple variables.
+        Modeling a Piecewise relation between multiple variables.
         The relation is defined by a list of Pieces, which are assigned to the variables.
         Each Piece is a tuple of (start, end).
 
@@ -850,7 +850,9 @@ class PiecewiseModel(Model):
             label_of_element: The label of the parent (Element). Used to construct the full label of the model.
             label: The label of the model. Used to construct the full label of the model.
             piecewise_variables: The variables to which the Pieces are assigned.
-            zero_point: A variable that can be used to define a zero point for the Piecewise relation. If None or False, no zero point is defined.
+            zero_point: A variable that can be used to define a zero point for the Piecewise relation.
+                If None or False, no zero point is defined. THis leads to 0 not being possible,
+                unless its its contained in a Piece.
             as_time_series: Whether the Piecewise relation is defined for a TimeSeries or a single variable.
         """
         super().__init__(model, label_of_element, label)
@@ -896,7 +898,7 @@ class PiecewiseModel(Model):
             # b) eq: -On(t) + Segment1.onSeg(t) + Segment2.onSeg(t) + ... = 0       zusätzlich kann alles auch Null sein
             if isinstance(self._zero_point, linopy.Variable):
                 self.zero_point = self._zero_point
-                rhs = self.zero_point
+                sign, rhs = '<=', self.zero_point
             elif self._zero_point is True:
                 self.zero_point = self.add(
                     self._model.add_variables(
@@ -904,13 +906,15 @@ class PiecewiseModel(Model):
                     ),
                     'zero_point',
                 )
-                rhs = self.zero_point
+                sign, rhs = '<=', self.zero_point
             else:
-                rhs = 1
+                sign, rhs = '=', 1
 
             self.add(
                 self._model.add_constraints(
-                    sum([piece.inside_piece for piece in self.pieces]) <= rhs,
+                    sum([piece.inside_piece for piece in self.pieces]),
+                    sign,
+                    rhs,
                     name=f'{self.label_full}|{variable.name}|single_segment',
                 ),
                 f'{var_name}|single_segment',
@@ -1079,6 +1083,65 @@ class PiecewiseEffectsModel(Model):
         )
 
 
+class PiecewiseEffectsPerFlowHourModel(Model):
+    def __init__(
+        self,
+        model: SystemModel,
+        label_of_element: str,
+        piecewise_origin: Tuple[str, Piecewise],
+        piecewise_shares: Dict[str, Piecewise],
+        zero_point: Optional[Union[bool, linopy.Variable]],
+        label: str = 'PiecewiseEffectsPerFlowHour',
+    ):
+        super().__init__(model, label_of_element, label)
+        assert len(piecewise_origin[1]) == len(list(piecewise_shares.values())[0]), (
+            'Piece length of variable_segments and share_segments must be equal'
+        )
+        self._zero_point = zero_point
+        self._piecewise_origin = piecewise_origin
+        self._piecewise_shares = piecewise_shares
+
+        self.shares: Dict[str, linopy.Variable] = {}
+
+        self.piecewise_model: Optional[PiecewiseModel] = None
+
+    def do_modeling(self):
+        self.shares = {
+            effect: self.add(
+                self._model.add_variables(coords=self._model.coords, name=f'{self.label_full}|{effect}'), f'{effect}'
+            )
+            for effect in self._piecewise_shares
+        }
+
+        piecewise_variables = {
+            self._piecewise_origin[0]: self._piecewise_origin[1],
+            **{
+                self.shares[effect_label].name: self._piecewise_shares[effect_label]
+                for effect_label in self._piecewise_shares
+            },
+        }
+
+        self.piecewise_model = self.add(
+            PiecewiseModel(
+                model=self._model,
+                label_of_element=self.label_of_element,
+                piecewise_variables=piecewise_variables,
+                zero_point=self._zero_point,
+                as_time_series=True,
+                label='PiecewiseEffectsPerFlowHour',
+            )
+        )
+
+        self.piecewise_model.do_modeling()
+
+        # Shares
+        self._model.effects.add_share_to_effects(
+            name=self.label_of_element,
+            expressions={effect: variable * self._model.hours_per_step for effect, variable in self.shares.items()},
+            target='operation',
+        )
+
+
 class PreventSimultaneousUsageModel(Model):
     """
     Prevents multiple Multiple Binary variables from being 1 at the same time