1. Critical Bug Fix - structure.py:219-229

  - Fixed weights property normalization to handle scalars/lists properly
  - Added zero-sum guard to prevent division by zero
  - Now always aligns weights to model coords before normalizing

  2. Documentation - flow_system.py

  - Added documentation for the weight_of_last_period parameter in the FlowSystem class docstring

  3. Code Quality - interface.py

  - Refactored deprecated kwargs handling to use instance method instead of awkward static call pattern
  - Removed unnecessary import and cleaner implementation

  4. Parameter Name Updates - Test Files

  Updated deprecated parameter names in all test files:
  - tests/test_scenarios.py
  - tests/test_functional.py
  - tests/conftest.py
  - tests/test_flow.py
  - tests/test_linear_converter.py

  5. Parameter Name Updates - Documentation

  Updated parameter names in:
  - docs/user-guide/mathematical-notation/features/OnOffParameters.md

  6. Parameter Name Updates - Examples

  Updated parameter names in:
  - examples/02_Complex/complex_example.py

  7. Enhanced CHANGELOG.md

  Added comprehensive migration guidance including:
  - Clear explanation of weighting behavior for _over_periods constraints
  - Concrete example showing per-period vs over-periods differences
  - Removal timeline (version 4.0.0) for deprecated parameters
  - Simple migration instructions

  All deprecated parameters:
  - on_hours_total_min → on_hours_min
  - on_hours_total_max → on_hours_max
  - switch_on_total_max → switch_on_max
  - flow_hours_total_min → flow_hours_min
  - flow_hours_total_max → flow_hours_max

  The codebase is now fully updated with consistent naming, proper documentation, and backward compatibility maintained through deprecation warnings!

Author: FBumann

CHANGELOG.md

@@ -61,6 +61,19 @@ If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOp
   - `Effect`: Added `minimum_over_periods` and `maximum_over_periods` for weighted sum constraints across all periods (complements existing per-period `minimum_total`/`maximum_total`)
   - `Flow`: Added `flow_hours_max_over_periods` and `flow_hours_min_over_periods` for weighted sum constraints across all periods
 
+  **Important**: Constraints with the `_over_periods` suffix compute weighted sums across all periods using the weights specified in `FlowSystem.weights` or `Effect.weights`. Per-period constraints (without the suffix) apply separately to each individual period.
+
+  **Example**:
+  ```python
+  # Per-period constraint: limits apply to EACH period individually
+  # With periods=[2020, 2030, 2040], this creates 3 separate constraints
+  effect = fx.Effect('costs', maximum_total=1000)  # ≤1000 in 2020 AND ≤1000 in 2030 AND ≤1000 in 2040
+
+  # Over-periods constraint: limits apply to WEIGHTED SUM across ALL periods
+  # With periods=[2020, 2030, 2040] and weights=[0.5, 0.3, 0.2], this creates 1 constraint
+  effect = fx.Effect('costs', maximum_over_periods=1000)  # 0.5×costs₂₀₂₀ + 0.3×costs₂₀₃₀ + 0.2×costs₂₀₄₀ ≤ 1000
+  ```
+
 ### ♻️ Changed
 
 - **Parameter naming consistency**: Established consistent naming pattern for constraint parameters across `Effect`, `Flow`, and `OnOffParameters`:
@@ -81,7 +94,12 @@ If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOp
 - **Flow parameters**: `flow_hours_total_max`, `flow_hours_total_min` (use `flow_hours_max`, `flow_hours_min`)
 - **OnOffParameters**: `on_hours_total_max`, `on_hours_total_min`, `switch_on_total_max` (use `on_hours_max`, `on_hours_min`, `switch_on_max`)
 
-All deprecated parameter names continue to work with deprecation warnings for backward compatibility. Additional property aliases have been added internally to handle various naming variations that may have been used.
+All deprecated parameter names continue to work with deprecation warnings for backward compatibility. **Deprecated names will be removed in version 4.0.0.** Please update your code to use the new parameter names. Additional property aliases have been added internally to handle various naming variations that may have been used.
+
+**Migration**: Simply rename parameters by removing `_total` from the middle:
+- `flow_hours_total_max` → `flow_hours_max`
+- `on_hours_total_min` → `on_hours_min`
+- `switch_on_total_max` → `switch_on_max`
 
 ### 🐛 Fixed
 

docs/user-guide/mathematical-notation/features/OnOffParameters.md

@@ -237,10 +237,10 @@ For equipment with OnOffParameters, the complete constraint system includes:
 **Key Parameters:**
 - `effects_per_switch_on`: Costs per startup event
 - `effects_per_running_hour`: Costs per hour of operation
-- `on_hours_total_min`, `on_hours_total_max`: Total runtime bounds
+- `on_hours_min`, `on_hours_max`: Total runtime bounds
 - `consecutive_on_hours_min`, `consecutive_on_hours_max`: Consecutive runtime bounds
 - `consecutive_off_hours_min`, `consecutive_off_hours_max`: Consecutive shutdown bounds
-- `switch_on_total_max`: Maximum number of startups
+- `switch_on_max`: Maximum number of startups
 - `force_switch_on`: Create switch variables even without limits (for tracking)
 
 See the [`OnOffParameters`][flixopt.interface.OnOffParameters] API documentation for complete parameter list and usage examples.
@@ -265,7 +265,7 @@ power_plant = OnOffParameters(
     effects_per_running_hour={'fixed_om': 125},  # €125/hour while running
     consecutive_on_hours_min=8,  # Minimum 8-hour run
     consecutive_off_hours_min=4,  # 4-hour cooling period
-    on_hours_total_max=6000,  # Annual limit
+    on_hours_max=6000,  # Annual limit
 )
 ```
 
@@ -276,7 +276,7 @@ batch_reactor = OnOffParameters(
     consecutive_on_hours_min=12,  # 12-hour minimum batch
     consecutive_on_hours_max=24,  # 24-hour maximum batch
     consecutive_off_hours_min=6,  # Cleaning time
-    switch_on_total_max=200,  # Max 200 batches
+    switch_on_max=200,  # Max 200 batches
 )
 ```
 
@@ -286,7 +286,7 @@ hvac = OnOffParameters(
     effects_per_switch_on={'compressor_wear': 0.5},
     consecutive_on_hours_min=1,  # Prevent short cycling
     consecutive_off_hours_min=0.5,  # 30-min minimum off
-    switch_on_total_max=2000,  # Limit compressor starts
+    switch_on_max=2000,  # Limit compressor starts
 )
 ```
 
@@ -296,7 +296,7 @@ backup_gen = OnOffParameters(
     effects_per_switch_on={'fuel_priming': 50},  # L diesel
     consecutive_on_hours_min=0.5,  # 30-min test duration
     consecutive_off_hours_max=720,  # Test every 30 days
-    on_hours_total_min=26,  # Weekly testing requirement
+    on_hours_min=26,  # Weekly testing requirement
 )
 ```
 

examples/02_Complex/complex_example.py

@@ -68,15 +68,15 @@
             relative_minimum=5 / 50,  # Minimum part load
             relative_maximum=1,  # Maximum part load
             previous_flow_rate=50,  # Previous flow rate
-            flow_hours_total_max=1e6,  # Total energy flow limit
+            flow_hours_max=1e6,  # Total energy flow limit
             on_off_parameters=fx.OnOffParameters(
-                on_hours_total_min=0,  # Minimum operating hours
-                on_hours_total_max=1000,  # Maximum operating hours
+                on_hours_min=0,  # Minimum operating hours
+                on_hours_max=1000,  # Maximum operating hours
                 consecutive_on_hours_max=10,  # Max consecutive operating hours
                 consecutive_on_hours_min=np.array([1, 1, 1, 1, 1, 2, 2, 2, 2]),  # min consecutive operation hours
                 consecutive_off_hours_max=10,  # Max consecutive off hours
                 effects_per_switch_on=0.01,  # Cost per switch-on
-                switch_on_total_max=1000,  # Max number of starts
+                switch_on_max=1000,  # Max number of starts
             ),
         ),
         Q_fu=fx.Flow(label='Q_fu', bus='Gas', size=200),

flixopt/effects.py

@@ -78,10 +78,6 @@ class Effect(Element):
         maximum_invest: Use `maximum_periodic` instead.
         minimum_operation_per_hour: Use `minimum_per_hour` instead.
         maximum_operation_per_hour: Use `maximum_per_hour` instead.
-        minimum_total_per_period: Use `minimum_total` instead.
-        maximum_total_per_period: Use `maximum_total` instead.
-        minimum: Use `minimum_over_periods` instead.
-        maximum: Use `maximum_over_periods` instead.
 
     Examples:
         Basic cost objective:
@@ -232,20 +228,6 @@ def __init__(
         maximum_per_hour = self._handle_deprecated_kwarg(
             kwargs, 'maximum_operation_per_hour', 'maximum_per_hour', maximum_per_hour
         )
-        minimum_total = self._handle_deprecated_kwarg(
-            kwargs, 'minimum_total_per_period', 'minimum_total', minimum_total
-        )
-        maximum_total = self._handle_deprecated_kwarg(
-            kwargs, 'maximum_total_per_period', 'maximum_total', maximum_total
-        )
-        minimum_over_periods = self._handle_deprecated_kwarg(
-            kwargs, 'minimum', 'minimum_over_periods', minimum_over_periods
-        )
-        maximum_over_periods = self._handle_deprecated_kwarg(
-            kwargs, 'maximum', 'maximum_over_periods', maximum_over_periods
-        )
-
-        # Validate any remaining unexpected kwargs
         self._validate_kwargs(kwargs)
 
         # Set attributes directly

flixopt/elements.py

@@ -593,46 +593,6 @@ def size_is_fixed(self) -> bool:
         return False if (isinstance(self.size, InvestParameters) and self.size.fixed_size is None) else True
 
     # Backwards compatible properties (deprecated)
-    @property
-    def flow_hours_per_period_max(self):
-        """DEPRECATED: Use 'flow_hours_max' property instead."""
-        warnings.warn(
-            "Property 'flow_hours_per_period_max' is deprecated. Use 'flow_hours_max' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.flow_hours_max
-
-    @flow_hours_per_period_max.setter
-    def flow_hours_per_period_max(self, value):
-        """DEPRECATED: Use 'flow_hours_max' property instead."""
-        warnings.warn(
-            "Property 'flow_hours_per_period_max' is deprecated. Use 'flow_hours_max' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        self.flow_hours_max = value
-
-    @property
-    def flow_hours_per_period_min(self):
-        """DEPRECATED: Use 'flow_hours_min' property instead."""
-        warnings.warn(
-            "Property 'flow_hours_per_period_min' is deprecated. Use 'flow_hours_min' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.flow_hours_min
-
-    @flow_hours_per_period_min.setter
-    def flow_hours_per_period_min(self, value):
-        """DEPRECATED: Use 'flow_hours_min' property instead."""
-        warnings.warn(
-            "Property 'flow_hours_per_period_min' is deprecated. Use 'flow_hours_min' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        self.flow_hours_min = value
-
     @property
     def flow_hours_total_max(self):
         """DEPRECATED: Use 'flow_hours_max' property instead."""
@@ -673,46 +633,6 @@ def flow_hours_total_min(self, value):
         )
         self.flow_hours_min = value
 
-    @property
-    def total_flow_hours_max(self):
-        """DEPRECATED: Use 'flow_hours_max_over_periods' property instead."""
-        warnings.warn(
-            "Property 'total_flow_hours_max' is deprecated. Use 'flow_hours_max_over_periods' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.flow_hours_max_over_periods
-
-    @total_flow_hours_max.setter
-    def total_flow_hours_max(self, value):
-        """DEPRECATED: Use 'flow_hours_max_over_periods' property instead."""
-        warnings.warn(
-            "Property 'total_flow_hours_max' is deprecated. Use 'flow_hours_max_over_periods' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        self.flow_hours_max_over_periods = value
-
-    @property
-    def total_flow_hours_min(self):
-        """DEPRECATED: Use 'flow_hours_min_over_periods' property instead."""
-        warnings.warn(
-            "Property 'total_flow_hours_min' is deprecated. Use 'flow_hours_min_over_periods' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.flow_hours_min_over_periods
-
-    @total_flow_hours_min.setter
-    def total_flow_hours_min(self, value):
-        """DEPRECATED: Use 'flow_hours_min_over_periods' property instead."""
-        warnings.warn(
-            "Property 'total_flow_hours_min' is deprecated. Use 'flow_hours_min_over_periods' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        self.flow_hours_min_over_periods = value
-
     def _format_invest_params(self, params: InvestParameters) -> str:
         """Format InvestParameters for display."""
         return f'size: {params.format_for_repr()}'
@@ -755,16 +675,16 @@ def _do_modeling(self):
             weight_per_period = self._model.flow_system.weight_per_period
             if weight_per_period is not None:
                 # Calculate weighted sum over all periods
-                weighted_total_flow_hours = (self.total_flow_hours * weight_per_period).sum('period')
+                weighted_flow_hours_over_periods = (self.total_flow_hours * weight_per_period).sum('period')
             else:
                 # No period weights defined, use unweighted sum
-                weighted_total_flow_hours = self.total_flow_hours.sum('period')
+                weighted_flow_hours_over_periods = self.total_flow_hours.sum('period')
 
             # Create tracking variable for the weighted sum
             ModelingPrimitives.expression_tracking_variable(
                 model=self,
-                name=f'{self.label_full}|total_flow_hours_over_periods',
-                tracked_expression=weighted_total_flow_hours,
+                name=f'{self.label_full}|flow_hours_over_periods',
+                tracked_expression=weighted_flow_hours_over_periods,
                 bounds=(
                     self.element.flow_hours_min_over_periods
                     if self.element.flow_hours_min_over_periods is not None
@@ -774,7 +694,7 @@ def _do_modeling(self):
                     else None,
                 ),
                 coords=['scenario'],
-                short_name='total_flow_hours_over_periods',
+                short_name='flow_hours_over_periods',
             )
 
         # Load factor constraints

flixopt/flow_system.py

@@ -51,6 +51,8 @@ class FlowSystem(Interface, CompositeContainerMixin[Element]):
         hours_of_previous_timesteps: Duration of previous timesteps. If None, computed from the first time interval.
             Can be a scalar (all previous timesteps have same duration) or array (different durations).
             Used to calculate previous values (e.g., consecutive_on_hours).
+        weight_of_last_period: Weight/duration of the last period. If None, computed from the last period interval.
+            Used for calculating sums over periods in multi-period models.
         weights: The weights of each period and scenario. If None, all scenarios have the same weight (normalized to 1).
             Its recommended to normalize the weights to sum up to 1.
         scenario_independent_sizes: Controls whether investment sizes are equalized across scenarios.

flixopt/interface.py

@@ -1273,20 +1273,10 @@ def __init__(
         **kwargs,
     ):
         # Handle deprecated parameters
-        from .structure import Element  # Import here to avoid circular import
-
-        on_hours_min = Element._handle_deprecated_kwarg(
-            None, kwargs, 'on_hours_total_min', 'on_hours_min', on_hours_min
-        )
-        on_hours_max = Element._handle_deprecated_kwarg(
-            None, kwargs, 'on_hours_total_max', 'on_hours_max', on_hours_max
-        )
-        switch_on_max = Element._handle_deprecated_kwarg(
-            None, kwargs, 'switch_on_total_max', 'switch_on_max', switch_on_max
-        )
-        # Validate any remaining unexpected kwargs
-        if kwargs:
-            raise TypeError(f'OnOffParameters got unexpected keyword arguments: {", ".join(kwargs.keys())}')
+        on_hours_min = self._handle_deprecated_kwarg(kwargs, 'on_hours_total_min', 'on_hours_min', on_hours_min)
+        on_hours_max = self._handle_deprecated_kwarg(kwargs, 'on_hours_total_max', 'on_hours_max', on_hours_max)
+        switch_on_max = self._handle_deprecated_kwarg(kwargs, 'switch_on_total_max', 'switch_on_max', switch_on_max)
+        self._validate_kwargs(kwargs)
 
         self.effects_per_switch_on = effects_per_switch_on if effects_per_switch_on is not None else {}
         self.effects_per_running_hour = effects_per_running_hour if effects_per_running_hour is not None else {}

flixopt/structure.py

@@ -216,16 +216,20 @@ def get_coords(
         return xr.Coordinates(coords) if coords else None
 
     @property
-    def weights(self) -> int | xr.DataArray:
+    def weights(self) -> xr.DataArray:
         """Returns the weights of the FlowSystem. Normalizes to 1 if normalize_weights is True"""
-        if self.flow_system.weights is not None:
-            weights = self.flow_system.weights
-            if self.normalize_weights:
-                # Normalize weights to sum to 1
-                weights = weights / weights.sum()
+        weights = self.flow_system.fit_to_model_coords(
+            name='weights',
+            data=self.flow_system.weights if self.flow_system.weights is not None else 1,
+            dims=['period', 'scenario'],
+        )
+        if not self.normalize_weights:
             return weights
 
-        return self.flow_system.fit_to_model_coords('weights', 1, dims=['period', 'scenario'])
+        total = weights.sum()
+        if np.isclose(total, 0):
+            raise ValueError('FlowSystemModel.weights: weights sum to 0; cannot normalize.')
+        return weights / total
 
     def __repr__(self) -> str:
         """

tests/conftest.py

@@ -165,15 +165,15 @@ def complex():
                         effects_of_investment_per_size={'costs': 10, 'PE': 2},
                     ),
                     on_off_parameters=fx.OnOffParameters(
-                        on_hours_total_min=0,
-                        on_hours_total_max=1000,
+                        on_hours_min=0,
+                        on_hours_max=1000,
                         consecutive_on_hours_max=10,
                         consecutive_on_hours_min=1,
                         consecutive_off_hours_max=10,
                         effects_per_switch_on=0.01,
-                        switch_on_total_max=1000,
+                        switch_on_max=1000,
                     ),
-                    flow_hours_total_max=1e6,
+                    flow_hours_max=1e6,
                 ),
                 Q_fu=fx.Flow('Q_fu', bus='Gas', size=200, relative_minimum=0, relative_maximum=1),
             )

tests/test_flow.py

@@ -48,8 +48,8 @@ def test_flow(self, basic_flow_system_linopy_coords, coords_config):
             size=100,
             relative_minimum=np.linspace(0, 0.5, timesteps.size),
             relative_maximum=np.linspace(0.5, 1, timesteps.size),
-            flow_hours_total_max=1000,
-            flow_hours_total_min=10,
+            flow_hours_max=1000,
+            flow_hours_min=10,
             load_factor_min=0.1,
             load_factor_max=0.9,
         )
@@ -976,7 +976,7 @@ def test_switch_on_constraints(self, basic_flow_system_linopy_coords, coords_con
             bus='Fernwärme',
             size=100,
             on_off_parameters=fx.OnOffParameters(
-                switch_on_total_max=5,  # Maximum 5 startups
+                switch_on_max=5,  # Maximum 5 startups
                 effects_per_switch_on={'costs': 100},  # 100 EUR startup cost
             ),
         )
@@ -1038,8 +1038,8 @@ def test_on_hours_limits(self, basic_flow_system_linopy_coords, coords_config):
             bus='Fernwärme',
             size=100,
             on_off_parameters=fx.OnOffParameters(
-                on_hours_total_min=20,  # Minimum 20 hours of operation
-                on_hours_total_max=100,  # Maximum 100 hours of operation
+                on_hours_min=20,  # Minimum 20 hours of operation
+                on_hours_max=100,  # Maximum 100 hours of operation
             ),
         )