Feature/sums over all periods

CHANGELOG.md

@@ -51,18 +51,67 @@ If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOp
 
 ## [Unreleased] - ????-??-??
 
-**Summary**: Renaming parameters in Linear Transformers for readability & Internal architecture improvements to simplify FlowSystem-Element coupling and eliminate circular dependencies. Old parameters till work but emmit warnings.
+**Summary**: Renaming parameters in Linear Transformers for readability (old parameters still work but emit warnings), new bounds for weighted sums over all periods for effects and flow hours, and refactored weights handling to fix `.sel()` issues with periods.
 
 If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOpt/flixOpt/releases/tag/v3.0.0) and [Migration Guide](https://flixopt.github.io/flixopt/latest/user-guide/migration-guide-v3/).
 
 ### ✨ Added
+- **Internal period weight computation**: `FlowSystem` now automatically computes `period_weights` from the period index (similar to `hours_per_timestep` for time dimension), ensuring weights are always consistent with the actual periods
+
+- **New constraint parameters for sum across all periods**:
+  - `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 **raw** weights from period durations (or user-specified weights). These constraints always use unnormalized weights.
+  - The `normalize_weights` parameter (in `Calculation` or `FlowSystem.create_model()`) only affects the objective function, not the `_over_periods` constraints.
+  - 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] (auto-derived weights: [10, 10, 10] from 10-year intervals)
+  effect = fx.Effect('costs', maximum_over_periods=1000)  # 10×costs₂₀₂₀ + 10×costs₂₀₃₀ + 10×costs₂₀₄₀ ≤ 1000
+
+  # Note: If normalize_weights=True, the objective uses normalized weights [0.33, 0.33, 0.33],
+  # but the constraint above still uses raw weights [10, 10, 10]
+  ```
+
 - **Auto-modeling**: `Calculation.solve()` now automatically calls `do_modeling()` if not already done, making the explicit `do_modeling()` call optional for simpler workflows
-- **System validation**: Added `_validate_system_integrity()` to validate cross-element references (e.g., Flow.bus) immediately after transformation, providing clearer error messages
-- **Element registration validation**: Added checks to prevent elements from being assigned to multiple FlowSystems simultaneously
-- **Helper methods in Interface base class**: Added `_fit_coords()` and `_fit_effect_coords()` convenience wrappers for cleaner data transformation code
-- **FlowSystem property in Interface**: Added `flow_system` property to access the linked FlowSystem with clear error messages if not yet linked
+
+### 💥 Breaking Changes
+- **FlowSystem weights parameter renamed**: The `weights` parameter in `FlowSystem.__init__()` has been renamed to `scenario_weights` to clarify that it only accepts scenario dimension weights (not period × scenario)
+  - Period weights are now **always computed internally** from the period index (similar to `hours_per_timestep` for time)
+  - The combined `weights` (period × scenario) are computed automatically by multiplying `period_weights × scenario_weights`
+  - only scenario_weights are normalized in the objective function
+
+  **Migration**: Update your code from:
+  ```python
+  # Old (v3.6 and earlier)
+  fs = FlowSystem(..., weights=np.array([0.3, 0.5, 0.2]))  # scenario weights
+  ```
+
+  To:
+  ```python
+  # New (v3.7+)
+  fs = FlowSystem(..., scenario_weights=np.array([0.3, 0.5, 0.2]))
+  ```
+
+  **Note**: If you were previously passing period × scenario weights to `weights`, you now need to:
+  1. Pass only scenario weights to `scenario_weights`
+  2. Period weights will be computed automatically from your `periods` index
 
 ### ♻️ Changed
+- **Period weights now computed from period index**: FlowSystem now computes `period_weights` automatically from the period index (using period intervals/differences), making weight handling consistent with `hours_per_timestep` for time dimension
+  - Added `_update_period_metadata()` method (analogous to `_update_time_metadata()`) to recalculate weights when periods are selected
+  - Period weights are stored separately in `FlowSystem.period_weights` (1D array with 'period' dimension)
+  - Scenario weights are stored in `FlowSystem.scenario_weights` (1D array with 'scenario' dimension)
+  - Combined weights `FlowSystem.weights` (2D array with 'period' and 'scenario' dimensions) are computed via `_compute_weights()` method
+
 - **Refactored FlowSystem-Element coupling**:
     - Introduced `_set_flow_system()` method in Interface base class to propagate FlowSystem reference to nested Interface objects
     - Each Interface subclass now explicitly propagates the reference to its nested interfaces (e.g., Component → OnOffParameters, Flow → InvestParameters)
@@ -83,19 +132,48 @@ If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOp
         - `Boiler`: `eta` → `thermal_efficiency`
         - `Power2Heat`: `eta` → `thermal_efficiency`
         - `CHP`: `eta_th` → `thermal_efficiency`, `eta_el` → `electrical_efficiency`
-        - `HetaPump`: `COP` → `cop`
-        - `HetaPumpWithSource`: `COP` → `cop`
+        - `HeatPump`: `COP` → `cop`
+        - `HeatPumpWithSource`: `COP` → `cop`
     - **Storage Parameters**:
         - `Storage`: `initial_charge_state="lastValueOfSim"` → `initial_charge_state="equals_last"`
 
+- **Parameter naming consistency**: Established consistent naming pattern for constraint parameters across `Effect`, `Flow`, and `OnOffParameters`:
+  - Per-period constraints use no suffix or clarified names (e.g., `minimum_total`, `flow_hours_max`, `on_hours_min`)
+  - Sum-over-all-periods constraints use `_over_periods` suffix (e.g., `minimum_over_periods`, `flow_hours_max_over_periods`)
+
+- **Flow parameters** (renamed for consistency):
+  - Renamed `flow_hours_total_max` → `flow_hours_max` (per-period constraint)
+  - Renamed `flow_hours_total_min` → `flow_hours_min` (per-period constraint)
+
+- **OnOffParameters** (renamed for consistency):
+  - Renamed `on_hours_total_max` → `on_hours_max` (per-period constraint)
+  - Renamed `on_hours_total_min` → `on_hours_min` (per-period constraint)
+  - Renamed `switch_on_total_max` → `switch_on_max` (per-period constraint)
+
 ### 🗑️ Deprecated
 - **Old parameter names in `linear_converters.py`**: The following parameter names are now deprecated and accessible as properties/kwargs that emit `DeprecationWarning`. They will be removed in v4.0.0:
     - **Flow parameters**: `Q_fu`, `Q_th`, `P_el`, `Q_ab`  (use `fuel_flow`, `thermal_flow`, `electrical_flow`, `heat_source_flow` instead)
     - **Efficiency parameters**: `eta`, `eta_th`, `eta_el` (use `thermal_efficiency`, `electrical_efficiency` instead)
     - **COP parameter**: `COP` (use lowercase `cop` instead)
     - **Storage Parameter**: `Storage`: `initial_charge_state="lastValueOfSim"` (use `initial_charge_state="equals_last"`)
 
+
+- **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`)
+
+**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`
+
+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.
+
+
 ### 🐛 Fixed
+- **Fixed weights not recalculating when using `.sel()` on periods**: `FlowSystem.sel()` and `FlowSystem.isel()` now correctly recalculate `period_weights` and `weights` when selecting a subset of periods (previously weights would be incorrectly sliced instead of recomputed from the new period index)
+  - Added `_update_period_metadata()` call in `_dataset_sel()` and `_dataset_isel()` to ensure weights stay consistent with selected periods
+  - This matches the existing behavior for time dimension where `hours_per_timestep` is recalculated on selection
+
 - Fixed inconsistent argument passing in `_fit_effect_coords()` - standardized all calls to use named arguments (`prefix=`, `effect_values=`, `suffix=`) instead of mix of positional and named arguments
 - Fixed `check_bounds` function in `linear_converters.py` to normalize array inputs before comparisons, ensuring correct boundary checks with DataFrames, Series, and other array-like types
 
@@ -104,6 +182,10 @@ If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOp
 - Added comprehensive docstrings to `_do_modeling()` methods explaining the pattern: "Create variables, constraints, and nested submodels"
 - Added missing type hints throughout the codebase
 - Improved code organization by making FlowSystem reference propagation explicit and traceable
+- **System validation**: Added `_validate_system_integrity()` to validate cross-element references (e.g., Flow.bus) immediately after transformation, providing clearer error messages
+- **Element registration validation**: Added checks to prevent elements from being assigned to multiple FlowSystems simultaneously
+- **Helper methods in Interface base class**: Added `_fit_coords()` and `_fit_effect_coords()` convenience wrappers for cleaner data transformation code
+- **FlowSystem property in Interface**: Added `flow_system` property to access the linked FlowSystem with clear error messages if not yet linked
 
 ---
 

docs/user-guide/mathematical-notation/dimensions.md

@@ -52,7 +52,7 @@ flow_system = fx.FlowSystem(
     timesteps=timesteps,
     periods=periods,
     scenarios=scenarios,
-    weights=np.array([0.5, 0.5])  # Scenario weights
+    scenario_weights=np.array([0.5, 0.5])  # Scenario weights
 )
 ```
 
@@ -220,28 +220,75 @@ Where:
 
 Weights determine the relative importance of scenarios and periods in the objective function.
 
-**Specification:**
+### Scenario Weights
+
+You provide scenario weights explicitly via the `scenario_weights` parameter:
 
 ```python
 flow_system = fx.FlowSystem(
     timesteps=timesteps,
-    periods=periods,
     scenarios=scenarios,
-    weights=weights  # Shape depends on dimensions
+    scenario_weights=np.array([0.3, 0.7])  # Scenario probabilities
 )
 ```
 
-**Weight Dimensions:**
+**Default:** If not specified, all scenarios have equal weight (normalized to sum to 1).
+
+### Period Weights
+
+Period weights are **automatically computed** from the period index (similar to how `hours_per_timestep` is computed from the time index):
 
-| Dimensions Present | Weight Shape | Example | Meaning |
-|-------------------|--------------|---------|---------|
-| Time + Scenario | 1D array of length `n_scenarios` | `[0.3, 0.7]` | Scenario probabilities |
-| Time + Period | 1D array of length `n_periods` | `[0.5, 0.3, 0.2]` | Period importance |
-| Time + Period + Scenario | 2D array `(n_periods, n_scenarios)` | `[[0.25, 0.25], [0.25, 0.25]]` | Combined weights |
+```python
+# Period weights are computed from the differences between period values
+periods = pd.Index([2020, 2025, 2030, 2035])
+# → period_weights = [5, 5, 5, 5] (representing 5-year intervals)
 
-**Default:** If not specified, all scenarios/periods have equal weight (normalized to sum to 1).
+flow_system = fx.FlowSystem(
+    timesteps=timesteps,
+    periods=periods,
+    # No need to specify period weights - they're computed automatically
+)
+```
+
+**How period weights are computed:**
+- For periods `[2020, 2025, 2030, 2035]`, the weights are `[5, 5, 5, 5]` (the interval sizes)
+- This ensures that when you use `.sel()` to select a subset of periods, the weights are correctly recalculated
+- You can specify `weight_of_last_period` if the last period weight cannot be inferred from the index
+
+### Combined Weights
+
+When both periods and scenarios are present, the combined `weights` array (accessible via `flow_system.model.objective_weights`) is computed as:
+
+$$
+w_{y,s} = w_y \times \frac{w_s}{\sum_{s \in \mathcal{S}} w_s}
+$$
+
+Where:
+- $w_y$ are the period weights (computed from period index)
+- $w_s$ are the scenario weights (user-specified)
+- $\mathcal{S}$ is the set of all scenarios
+- The scenario weights are normalized to sum to 1 before multiplication
+
+**Example:**
+```python
+periods = pd.Index([2020, 2030, 2040])  # → period_weights = [10, 10, 10]
+scenarios = pd.Index(['Base', 'High'])
+scenario_weights = np.array([0.6, 0.4])
+
+flow_system = fx.FlowSystem(
+    timesteps=timesteps,
+    periods=periods,
+    scenarios=scenarios,
+    scenario_weights=scenario_weights
+)
+
+# Combined weights shape: (3 periods, 2 scenarios)
+# [[6.0, 4.0],   # 2020: 10 × [0.6, 0.4]
+#  [6.0, 4.0],   # 2030: 10 × [0.6, 0.4]
+#  [6.0, 4.0]]   # 2040: 10 × [0.6, 0.4]
+```
 
-**Normalization:** Set `normalize_weights=True` in `Calculation` to automatically normalize weights to sum to 1.
+**Normalization:** Set `normalize_weights=False` in `Calculation` to turn of the normalization.
 
 ---
 

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
             ),
         ),
         fuel_flow=fx.Flow(label='Q_fu', bus='Gas', size=200),

examples/04_Scenarios/scenario_example.py

@@ -83,7 +83,9 @@
     # Base Case: 60% probability, High Demand: 40% probability
     scenario_weights = np.array([0.6, 0.4])
 
-    flow_system = fx.FlowSystem(timesteps=timesteps, periods=periods, scenarios=scenarios, weights=scenario_weights)
+    flow_system = fx.FlowSystem(
+        timesteps=timesteps, periods=periods, scenarios=scenarios, scenario_weights=scenario_weights
+    )
 
     # --- Define Energy Buses ---
     # These represent nodes, where the used medias are balanced (electricity, heat, and gas)

flixopt/calculation.py

@@ -48,7 +48,7 @@ class for defined way of solving a flow_system optimization
         name: name of calculation
         flow_system: flow_system which should be calculated
         folder: folder where results should be saved. If None, then the current working directory is used.
-        normalize_weights: Whether to automatically normalize the weights (periods and scenarios) to sum up to 1 when solving.
+        normalize_weights: Whether to automatically normalize the weights of scenarios to sum up to 1 when solving.
         active_timesteps: Deprecated. Use FlowSystem.sel(time=...) or FlowSystem.isel(time=...) instead.
     """
 
@@ -182,7 +182,7 @@ class FullCalculation(Calculation):
         name: name of calculation
         flow_system: flow_system which should be calculated
         folder: folder where results should be saved. If None, then the current working directory is used.
-        normalize_weights: Whether to automatically normalize the weights (periods and scenarios) to sum up to 1 when solving.
+        normalize_weights: Whether to automatically normalize the weights of scenarios to sum up to 1 when solving.
         active_timesteps: Deprecated. Use FlowSystem.sel(time=...) or FlowSystem.isel(time=...) instead.
     """
 

flixopt/components.py

@@ -647,7 +647,7 @@ class Transmission(Component):
             on_off_parameters=OnOffParameters(
                 effects_per_switch_on={'maintenance': 0.1},
                 consecutive_on_hours_min=2,  # Minimum 2-hour operation
-                switch_on_total_max=10,  # Maximum 10 starts per day
+                switch_on_max=10,  # Maximum 10 starts per day
             ),
         )
         ```