flixopt 2.1.0__py3-none-any.whl → 2.2.0b0__py3-none-any.whl

docs/release-notes/v2.2.0.md

@@ -0,0 +1,55 @@
+# Release v2.2.0
+
+**Release Date:** YYYY-MM-DD
+
+## 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
+* Different climate conditions
+The 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 scnarios, 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
+
+## Improvements
+
+* Improvement 1 - Description
+* Improvement 2 - Description
+
+## Bug Fixes
+
+* Fixed issue with X
+* Resolved problem with Y
+
+## Breaking Changes
+
+* Change 1 - Migration instructions
+* Change 2 - Migration instructions
+
+## Deprecations
+
+* Feature X will be removed in v{next_version}
+
+## Dependencies
+
+* Added dependency X v1.2.3
+* Updated dependency Y to v2.0.0

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

flixopt/calculation.py

@@ -12,6 +12,7 @@ import logging
 import math
 import pathlib
 import timeit
+import warnings
 from typing import Any, Dict, List, Optional, Union
 
 import numpy as np
@@ -43,20 +44,32 @@ class Calculation:
         self,
         name: str,
         flow_system: FlowSystem,
-        active_timesteps: Optional[pd.DatetimeIndex] = None,
+        selected_timesteps: Optional[pd.DatetimeIndex] = None,
+        selected_scenarios: Optional[pd.Index] = None,
         folder: Optional[pathlib.Path] = None,
+        active_timesteps: Optional[pd.DatetimeIndex] = None,
     ):
         """
         Args:
             name: name of calculation
             flow_system: flow_system which should be calculated
-            active_timesteps: list with indices, which should be used for calculation. If None, then all timesteps are used.
+            selected_timesteps: timesteps which should be used for calculation. If None, then all timesteps are used.
+            selected_scenarios: scenarios which should be used for calculation. If None, then all scenarios are used.
             folder: folder where results should be saved. If None, then the current working directory is used.
+            active_timesteps: Deprecated. Use selected_timesteps instead.
         """
+        if active_timesteps is not None:
+            warnings.warn(
+                'active_timesteps is deprecated. Use selected_timesteps instead.',
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            selected_timesteps = active_timesteps
         self.name = name
         self.flow_system = flow_system
         self.model: Optional[SystemModel] = None
-        self.active_timesteps = active_timesteps
+        self.selected_timesteps = selected_timesteps
+        self.selected_scenarios = selected_scenarios
 
         self.durations = {'modeling': 0.0, 'solving': 0.0, 'saving': 0.0}
         self.folder = pathlib.Path.cwd() / 'results' if folder is None else pathlib.Path(folder)
@@ -74,47 +87,49 @@ class Calculation:
     def main_results(self) -> Dict[str, Union[Scalar, Dict]]:
         from flixopt.features import InvestmentModel
 
-        return {
+        main_results = {
             'Objective': self.model.objective.value,
-            'Penalty': float(self.model.effects.penalty.total.solution.values),
+            'Penalty': self.model.effects.penalty.total.solution.values,
             'Effects': {
                 f'{effect.label} [{effect.unit}]': {
-                    'operation': float(effect.model.operation.total.solution.values),
-                    'invest': float(effect.model.invest.total.solution.values),
-                    'total': float(effect.model.total.solution.values),
+                    'operation': effect.model.operation.total.solution.values,
+                    'invest': effect.model.invest.total.solution.values,
+                    'total': effect.model.total.solution.values,
                 }
                 for effect in self.flow_system.effects
             },
             'Invest-Decisions': {
                 'Invested': {
-                    model.label_of_element: float(model.size.solution)
+                    model.label_of_element: model.size.solution
                     for component in self.flow_system.components.values()
                     for model in component.model.all_sub_models
-                    if isinstance(model, InvestmentModel) and float(model.size.solution) >= CONFIG.modeling.EPSILON
+                    if isinstance(model, InvestmentModel) and model.size.solution.max() >= CONFIG.modeling.EPSILON
                 },
                 'Not invested': {
-                    model.label_of_element: float(model.size.solution)
+                    model.label_of_element: model.size.solution
                     for component in self.flow_system.components.values()
                     for model in component.model.all_sub_models
-                    if isinstance(model, InvestmentModel) and float(model.size.solution) < CONFIG.modeling.EPSILON
+                    if isinstance(model, InvestmentModel) and model.size.solution.max() < CONFIG.modeling.EPSILON
                 },
             },
             'Buses with excess': [
                 {
                     bus.label_full: {
-                        'input': float(np.sum(bus.model.excess_input.solution.values)),
-                        'output': float(np.sum(bus.model.excess_output.solution.values)),
+                        'input': bus.model.excess_input.solution.sum('time'),
+                        'output': bus.model.excess_output.solution.sum('time'),
                     }
                 }
                 for bus in self.flow_system.buses.values()
                 if bus.with_excess
                 and (
-                    float(np.sum(bus.model.excess_input.solution.values)) > 1e-3
-                    or float(np.sum(bus.model.excess_output.solution.values)) > 1e-3
+                    bus.model.excess_input.solution.sum() > 1e-3
+                    or bus.model.excess_output.solution.sum() > 1e-3
                 )
             ],
         }
 
+        return utils.round_floats(main_results)
+
     @property
     def summary(self):
         return {
@@ -128,6 +143,15 @@ class Calculation:
             'Config': CONFIG.to_dict(),
         }
 
+    @property
+    def active_timesteps(self) -> pd.DatetimeIndex:
+        warnings.warn(
+            'active_timesteps is deprecated. Use selected_timesteps instead.',
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.selected_timesteps
+
 
 class FullCalculation(Calculation):
     """
@@ -183,8 +207,8 @@ class FullCalculation(Calculation):
 
     def _activate_time_series(self):
         self.flow_system.transform_data()
-        self.flow_system.time_series_collection.activate_timesteps(
-            active_timesteps=self.active_timesteps,
+        self.flow_system.time_series_collection.set_selection(
+            timesteps=self.selected_timesteps, scenarios=self.selected_scenarios
         )
 
 
@@ -199,7 +223,7 @@ class AggregatedCalculation(FullCalculation):
         flow_system: FlowSystem,
         aggregation_parameters: AggregationParameters,
         components_to_clusterize: Optional[List[Component]] = None,
-        active_timesteps: Optional[pd.DatetimeIndex] = None,
+        selected_timesteps: Optional[pd.DatetimeIndex] = None,
         folder: Optional[pathlib.Path] = None,
     ):
         """
@@ -213,11 +237,13 @@ class AggregatedCalculation(FullCalculation):
             components_to_clusterize: List of Components to perform aggregation on. If None, then all components are aggregated.
                 This means, teh variables in the components are equalized to each other, according to the typical periods
                 computed in the DataAggregation
-            active_timesteps: pd.DatetimeIndex or None
+            selected_timesteps: pd.DatetimeIndex or None
                 list with indices, which should be used for calculation. If None, then all timesteps are used.
             folder: folder where results should be saved. If None, then the current working directory is used.
         """
-        super().__init__(name, flow_system, active_timesteps, folder=folder)
+        if flow_system.time_series_collection.scenarios is not None:
+            raise ValueError('Aggregation is not supported for scenarios yet. Please use FullCalculation instead.')
+        super().__init__(name, flow_system, selected_timesteps, folder=folder)
         self.aggregation_parameters = aggregation_parameters
         self.components_to_clusterize = components_to_clusterize
         self.aggregation = None
@@ -272,9 +298,9 @@ class AggregatedCalculation(FullCalculation):
 
         # Aggregation - creation of aggregated timeseries:
         self.aggregation = Aggregation(
-            original_data=self.flow_system.time_series_collection.to_dataframe(
-                include_extra_timestep=False
-            ),  # Exclude last row (NaN)
+            original_data=self.flow_system.time_series_collection.as_dataset(
+                with_extra_timestep=False, with_constants=False
+            ).to_dataframe(),
             hours_per_time_step=float(dt_min),
             hours_per_period=self.aggregation_parameters.hours_per_period,
             nr_of_periods=self.aggregation_parameters.nr_of_periods,
@@ -286,9 +312,11 @@ class AggregatedCalculation(FullCalculation):
         self.aggregation.cluster()
         self.aggregation.plot(show=True, save=self.folder / 'aggregation.html')
         if self.aggregation_parameters.aggregate_data_and_fix_non_binary_vars:
-            self.flow_system.time_series_collection.insert_new_data(
-                self.aggregation.aggregated_data, include_extra_timestep=False
-            )
+            for col in self.aggregation.aggregated_data.columns:
+                data = self.aggregation.aggregated_data[col].values
+                if col in self.flow_system.time_series_collection._has_extra_timestep:
+                    data = np.append(data, data[-1])
+                self.flow_system.time_series_collection.update_time_series(col, data)
         self.durations['aggregation'] = round(timeit.default_timer() - t_start_agg, 2)
 
 
@@ -327,13 +355,13 @@ class SegmentedCalculation(Calculation):
         self.nr_of_previous_values = nr_of_previous_values
         self.sub_calculations: List[FullCalculation] = []
 
-        self.all_timesteps = self.flow_system.time_series_collection.all_timesteps
-        self.all_timesteps_extra = self.flow_system.time_series_collection.all_timesteps_extra
+        self.all_timesteps = self.flow_system.time_series_collection._full_timesteps
+        self.all_timesteps_extra = self.flow_system.time_series_collection._full_timesteps_extra
 
         self.segment_names = [
             f'Segment_{i + 1}' for i in range(math.ceil(len(self.all_timesteps) / self.timesteps_per_segment))
         ]
-        self.active_timesteps_per_segment = self._calculate_timesteps_of_segment()
+        self.selected_timesteps_per_segment = self._calculate_timesteps_of_segment()
 
         assert timesteps_per_segment > 2, 'The Segment length must be greater 2, due to unwanted internal side effects'
         assert self.timesteps_per_segment_with_overlap <= len(self.all_timesteps), (
@@ -359,7 +387,7 @@ class SegmentedCalculation(Calculation):
         logger.info(f'{" Segmented Solving ":#^80}')
 
         for i, (segment_name, timesteps_of_segment) in enumerate(
-            zip(self.segment_names, self.active_timesteps_per_segment, strict=False)
+            zip(self.segment_names, self.selected_timesteps_per_segment, strict=False)
         ):
             if self.sub_calculations:
                 self._transfer_start_values(i)
@@ -370,7 +398,7 @@ class SegmentedCalculation(Calculation):
             )
 
             calculation = FullCalculation(
-                f'{self.name}-{segment_name}', self.flow_system, active_timesteps=timesteps_of_segment
+                f'{self.name}-{segment_name}', self.flow_system, selected_timesteps=timesteps_of_segment
             )
             self.sub_calculations.append(calculation)
             calculation.do_modeling()
@@ -404,9 +432,9 @@ class SegmentedCalculation(Calculation):
         This function gets the last values of the previous solved segment and
         inserts them as start values for the next segment
         """
-        timesteps_of_prior_segment = self.active_timesteps_per_segment[segment_index - 1]
+        timesteps_of_prior_segment = self.selected_timesteps_per_segment[segment_index - 1]
 
-        start = self.active_timesteps_per_segment[segment_index][0]
+        start = self.selected_timesteps_per_segment[segment_index][0]
         start_previous_values = timesteps_of_prior_segment[self.timesteps_per_segment - self.nr_of_previous_values]
         end_previous_values = timesteps_of_prior_segment[self.timesteps_per_segment - 1]
 
@@ -435,12 +463,12 @@ class SegmentedCalculation(Calculation):
                 comp.initial_charge_state = self._original_start_values[comp.label_full]
 
     def _calculate_timesteps_of_segment(self) -> List[pd.DatetimeIndex]:
-        active_timesteps_per_segment = []
+        selected_timesteps_per_segment = []
         for i, _ in enumerate(self.segment_names):
             start = self.timesteps_per_segment * i
             end = min(start + self.timesteps_per_segment_with_overlap, len(self.all_timesteps))
-            active_timesteps_per_segment.append(self.all_timesteps[start:end])
-        return active_timesteps_per_segment
+            selected_timesteps_per_segment.append(self.all_timesteps[start:end])
+        return selected_timesteps_per_segment
 
     @property
     def timesteps_per_segment_with_overlap(self):