Scenarios no ts/main

CHANGELOG.md

@@ -5,7 +5,83 @@ All notable changes to this project will be documented in this file.
 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).
 
-## [Unreleased]
+## [Unreleased - New Model dimensions]
+
+## What's New
+
+### Scenarios
+Scenarios are a new feature of flixopt. They can be used to model uncertainties in the flow system, such as:
+* Different demand profiles
+* Different price forecasts
+* Different weather conditions
+They might also be used to model an evolving system with multiple investment periods. Each **scenario** might be a new year, a new month, or a new day, with a different set of investment decisions to take.
+
+The weighted sum of the total objective effect of each scenario is used as the objective of the optimization.
+
+#### Investments and scenarios
+Scenarios allow for more flexibility in investment decisions.
+You can decide to allow different investment decisions for each scenario, or to allow a single investment decision for a subset of all scenarios, while not allowing for an invest in others.
+This enables the following use cases:
+* Find the best investment decision for each scenario individually
+* Find the best overall investment decision for possible scenarios (robust decision-making)
+* Find the best overall investment decision for a subset of all scenarios
+
+The last one might be useful if you want to model a system with multiple investment periods, where one investment decision is made for more than one scenario.
+This might occur when scenarios represent years or months, while an investment decision influences the system for multiple years or months.
+
+
+### Other new features
+* Balanced storage - Storage charging and discharging sizes can now be forced to be equal in when optimizing their size.
+* Feature 2 - Description
+
+
+## [Unreleased - Data Management and IO]
+
+### Changed
+* **BREAKING**: `relative_minimum_charge_state` and `relative_maximum_charge_state` don't have an extra timestep anymore. The final charge state can now be constrained by parameters `relative_minimum_final_charge_state` and `relative_maximum_final_charge_state` instead
+* **BREAKING**: Calculation.do_modeling() now returns the Calculation object instead of its linopy.Model
+* FlowSystems can not be shared across multiple Calculations anymore. A copy of the FlowSystem is created instead, making every Calculation independent
+* Type system overhaul - added clear separation between temporal and non-temporal data throughout codebase for better clarity
+* FlowSystem data management simplified - removed `time_series_collection` pattern in favor of direct timestep properties
+* Enhanced FlowSystem interface with improved `__repr__()` and `__str__()` methods
+
+### Added
+* Complete serialization infrastructure through `Interface` base class
+   * IO for all Interfaces and the FlowSystem with round-trip serialization support
+   * Automatic DataArray extraction and restoration
+   * NetCDF export/import capabilities for all Interface objects and FlowSystem
+   * JSON export for documentation purposes
+   * Recursive handling of nested Interface objects
+* FlowSystem data manipulation methods
+   * `sel()` and `isel()` methods for temporal data selection
+   * `resample()` method for temporal resampling
+   * `copy()` method to create a copy of a FlowSystem, including all underlying Elements and their data
+   * `__eq__()` method for FlowSystem comparison
+* Storage component enhancements
+   * `relative_minimum_final_charge_state` parameter for final state control
+   * `relative_maximum_final_charge_state` parameter for final state control
+* Core data handling improvements
+   * `get_dataarray_stats()` function for statistical summaries
+   * Enhanced `DataConverter` class with better TimeSeriesData support
+* Internal: Enhanced data handling methods
+   * `fit_to_model_coords()` method for data alignment
+   * `fit_effects_to_model_coords()` method for effect data processing
+   * `connect_and_transform()` method replacing several operations
+
+### Fixed
+* Enhanced NetCDF I/O with proper attribute preservation for DataArrays
+* Improved error handling and validation in serialization processes
+* Better type consistency across all framework components
+
+### Know Issues
+* Plotly >= 6 may raise errors if "nbformat" is not installed. We pinned plotly to <6, but this may be fixed in the future.
+* IO for single Interfaces/Elemenets to Datasets might not work properly if the Interface/Element is not part of a fully transformed and connected FlowSystem. This arrises from Numeric Data not being stored as xr.DataArray by the user. To avoid this, always use the `to_dataset()` on Elements inside a FlowSystem thats connected and transformed.
+
+### Deprecated
+* The `agg_group` and `agg_weight` parameters of `TimeSeriesData` are deprecated and will be removed in a future version. Use `aggregation_group` and `aggregation_weight` instead.
+* The `active_timesteps` parameter of `Calculation` is deprecated and will be removed in a future version. Use the new `sel(time=...)` method on the FlowSystem instead.
+* The assignment of Bus Objects to Flow.bus is deprecated and will be removed in a future version. Use the label of the Bus instead.
+* The usage of Effects objects in Dicts to assign shares to Effects is deprecated and will be removed in a future version. Use the label of the Effect instead.
 
 ## [2.1.2] - 2025-06-14
 

docs/user-guide/Mathematical Notation/Investment.md

@@ -0,0 +1,115 @@
+# Investments
+
+## Current state
+$$
+\beta_{\text{invest}} \cdot \text{max}(\epsilon, \text V^{\text L}) \leq V \leq  \beta_{\text{invest}} \cdot \text V^{\text U}
+$$
+With:
+- $V$ = size
+- $V^{\text L}$ = minimum size
+- $V^{\text U}$ = maximum size
+- $\epsilon$ = epsilon, a small number (such as $1e^{-5}$)
+- $\beta_{invest} \in {0,1}$ = wether the size is invested or not
+
+_Please edit the use cases as needed_
+## Quickfix 1: Optimize the single best size overall
+### Single variable
+This is already possible and should be, as this is a needed use case
+An additional factor to when the size is actually available might me practical (Which indicates the (fixed) time of investment)
+## Math
+$$
+V(p) = V * a(p)
+$$
+with:
+- $V$ = size
+- $a(p)$ = factor for availlability per period
+
+Factor $a(p)$ is simply multiplied with relative minimum or maximum(t). This is already possible by doing this yourself.
+Effectively, the relative minimum or maximum are altered before using the same constraiints as before.
+THis might lead to some issues regariding minimum_load factor, or others, as the size is not 0 in a scenario where the component cant produce.
+**Therefore this might not be the best choice. See (#Variable per Scenario)
+
+## Variable per Scenario
+- **size** and **invest** as a variable per period $V(s)$ and $\beta_{invest}(s)$
+- with scenario $s \in S$
+
+### Usecase 1: Optimize the size for each Scenario independently
+Restrictions are seperatly for each scenario
+No changes needed. This could be the default behaviour.
+
+### Usecase 2: Optimize ONE size for ALL scenarios
+The size is the same globally, but not a scalar, but a variable per scenario $V(s)$
+#### 2a: The same size in all scenarios
+$$
+V(s) = V(s') \quad \forall s,s' \in S
+$$
+
+With:
+- $V(s)$ and $V(s')$ = size
+- $S$ = set of scenarios
+
+#### 2b: The same size, but can be 0 prior to the first increment
+- Find the Optimal time of investment.
+- Force an investment in a certain scenario (parameter optional as a list/array ob booleans)
+- Combine optional and minimum/maximum size to force an investment inside a range if scenarios
+
+$$
+\beta_{\text{invest}}(s) \leq \beta_{\text{invest}}(s+1) \quad \forall s \in \{1,2,\ldots,S-1\}
+$$
+
+$$
+V(s') - V(s) \leq M \cdot (2 - \beta_{\text{invest}}(s) - \beta_{\text{invest}}(s')) \quad \forall s, s' \in S
+$$
+$$
+V(s') - V(s) \geq M \cdot (2 - \beta_{\text{invest}}(s) - \beta_{\text{invest}}(s')) \quad \forall s, s' \in S
+$$
+
+This could be the default behaviour. (which would be consistent with other variables)
+
+
+### Switch
+
+$$
+\begin{aligned}
+& \text{SWITCH}_s \in \{0,1\} \quad \forall s \in \{1,2,\ldots,S\} \\
+& \sum_{s=1}^{S} \text{SWITCH}_s = 1 \\
+& \beta_{\text{invest}}(s) = \sum_{s'=1}^{s} \text{SWITCH}_{s'} \quad \forall s \in \{1,2,\ldots,S\} \\
+\end{aligned}
+$$
+
+$$
+\begin{aligned}
+& V(s) \leq V_{\text{actual}} \quad \forall s \in \{1,2,\ldots,S\} \\
+& V(s) \geq V_{\text{actual}} - M \cdot (1 - \beta_{\text{invest}}(s)) \quad \forall s \in \{1,2,\ldots,S\}
+\end{aligned}
+$$
+
+
+
+
+### Usecase 3: Find the best scenario to increment the size (Timing of the investment)
+The size can only increment once (based on a starting point). This allows to optimize the timing of an investment.
+#### Math
+Treat $\beta_{invest}$ like an ON/OFF variable, and introduce a SwitchOn, that can only be active once.
+
+*Thoughts:*
+- Treating $\beta_{invest}$ like an ON/OFF variable suggest using the already presentconstraints linked to On/OffModel
+- The timing could be constraint to be first in scenario x, or last in scenario y
+- Restrict the number of consecutive scenarios
+THis might needs the OnOffModel to be more generic (HOURS). Further, the span between scenarios needs to be weighted (like dt_in_hours), or the scenarios need to be measureable (integers)
+
+
+### Others
+
+#### Usecase 4: Only increase/decrease the size
+Start from a certain size. For each scenario, the size can increase, but never decrease. (Or the other way around).
+This would mean that a size expansion is possible,
+
+#### Usecase 5: Restrict the increment in size per scenario
+Restrict how much the size can increase/decrease for in scenario, based on the prior scenario.
+
+
+
+
+
+Many more are possible

examples/01_Simple/simple_example.py

@@ -67,7 +67,8 @@
         discharging=fx.Flow('Q_th_unload', bus='Fernwärme', size=1000),
         capacity_in_flow_hours=fx.InvestParameters(fix_effects=20, fixed_size=30, optional=False),
         initial_charge_state=0,  # Initial storage state: empty
-        relative_maximum_charge_state=1 / 100 * np.array([80, 70, 80, 80, 80, 80, 80, 80, 80, 80]),
+        relative_maximum_charge_state=1 / 100 * np.array([80, 70, 80, 80, 80, 80, 80, 80, 80]),
+        relative_maximum_final_charge_state=0.8,
         eta_charge=0.9,
         eta_discharge=1,  # Efficiency factors for charging/discharging
         relative_loss_per_hour=0.08,  # 8% loss per hour. Absolute loss depends on current charge state

examples/03_Calculation_types/example_calculation_types.py

@@ -48,9 +48,9 @@
 
     # TimeSeriesData objects
     TS_heat_demand = fx.TimeSeriesData(heat_demand)
-    TS_electricity_demand = fx.TimeSeriesData(electricity_demand, agg_weight=0.7)
-    TS_electricity_price_sell = fx.TimeSeriesData(-(electricity_demand - 0.5), agg_group='p_el')
-    TS_electricity_price_buy = fx.TimeSeriesData(electricity_price + 0.5, agg_group='p_el')
+    TS_electricity_demand = fx.TimeSeriesData(electricity_demand, aggregation_weight=0.7)
+    TS_electricity_price_sell = fx.TimeSeriesData(-(electricity_demand - 0.5), aggregation_group='p_el')
+    TS_electricity_price_buy = fx.TimeSeriesData(electricity_price + 0.5, aggregation_group='p_el')
 
     flow_system = fx.FlowSystem(timesteps)
     flow_system.add_elements(
@@ -164,12 +164,12 @@
     if full:
         calculation = fx.FullCalculation('Full', flow_system)
         calculation.do_modeling()
-        calculation.solve(fx.solvers.HighsSolver(0, 60))
+        calculation.solve(fx.solvers.HighsSolver(0.01/100, 60))
         calculations.append(calculation)
 
     if segmented:
         calculation = fx.SegmentedCalculation('Segmented', flow_system, segment_length, overlap_length)
-        calculation.do_modeling_and_solve(fx.solvers.HighsSolver(0, 60))
+        calculation.do_modeling_and_solve(fx.solvers.HighsSolver(0.01/100, 60))
         calculations.append(calculation)
 
     if aggregated:
@@ -178,7 +178,7 @@
             aggregation_parameters.time_series_for_low_peaks = [TS_electricity_demand, TS_heat_demand]
         calculation = fx.AggregatedCalculation('Aggregated', flow_system, aggregation_parameters)
         calculation.do_modeling()
-        calculation.solve(fx.solvers.HighsSolver(0, 60))
+        calculation.solve(fx.solvers.HighsSolver(0.01/100, 60))
         calculations.append(calculation)
 
     # Get solutions for plotting for different calculations
@@ -194,34 +194,34 @@ def get_solutions(calcs: List, variable: str) -> xr.Dataset:
     # --- Plotting for comparison ---
     fx.plotting.with_plotly(
         get_solutions(calculations, 'Speicher|charge_state').to_dataframe(),
-        mode='line',
+        style='line',
         title='Charge State Comparison',
         ylabel='Charge state',
     ).write_html('results/Charge State.html')
 
     fx.plotting.with_plotly(
         get_solutions(calculations, 'BHKW2(Q_th)|flow_rate').to_dataframe(),
-        mode='line',
+        style='line',
         title='BHKW2(Q_th) Flow Rate Comparison',
         ylabel='Flow rate',
     ).write_html('results/BHKW2 Thermal Power.html')
 
     fx.plotting.with_plotly(
         get_solutions(calculations, 'costs(operation)|total_per_timestep').to_dataframe(),
-        mode='line',
+        style='line',
         title='Operation Cost Comparison',
         ylabel='Costs [€]',
     ).write_html('results/Operation Costs.html')
 
     fx.plotting.with_plotly(
         pd.DataFrame(get_solutions(calculations, 'costs(operation)|total_per_timestep').to_dataframe().sum()).T,
-        mode='bar',
+        style='stacked_bar',
         title='Total Cost Comparison',
         ylabel='Costs [€]',
     ).update_layout(barmode='group').write_html('results/Total Costs.html')
 
     fx.plotting.with_plotly(
-        pd.DataFrame([calc.durations for calc in calculations], index=[calc.name for calc in calculations]), 'bar'
+        pd.DataFrame([calc.durations for calc in calculations], index=[calc.name for calc in calculations]), 'stacked_bar'
     ).update_layout(title='Duration Comparison', xaxis_title='Calculation type', yaxis_title='Time (s)').write_html(
         'results/Speed Comparison.html'
     )