Add Multi-Period-modeling and stochastic modeling to flixopt

.github/workflows/python-app.yaml

@@ -5,7 +5,7 @@ on:
     branches: [main]        # Only main branch
     tags: ['v*.*.*']
   pull_request:
-    branches: [main, dev]
+    branches: [main, 'dev*', 'dev/**', 'feature/**']
     types: [opened, synchronize, reopened]
     paths-ignore:
       - 'docs/**'
@@ -88,7 +88,7 @@ jobs:
           uv pip install --system .[dev]
 
       - name: Run tests
-        run: pytest -v -p no:warnings --numprocesses=auto
+        run: pytest -v --numprocesses=auto
 
   test-examples:
     runs-on: ubuntu-24.04

CHANGELOG.md

@@ -41,6 +41,7 @@ Please keep the format of the changelog consistent with the other releases, so t
 
 ---
 
+
 ## [Unreleased] - ????-??-??
 
 ### ✨ Added
@@ -62,12 +63,149 @@ Please keep the format of the changelog consistent with the other releases, so t
 ### 📝 Docs
 
 ### 👷 Development
-- Enable blank issues
 
 ### 🚧 Known Issues
 
+---
 Until here -->
 
+## [3.0.0] - 2025-10-13
+**Summary**: This release introduces new model dimensions (periods and scenarios) for multi-period investments and stochastic modeling, along with a redesigned effect sharing system and enhanced I/O capabilities.
+
+### ✨ Added
+
+**New model dimensions:**
+
+- **Period dimension**: Enables multi-period investment modeling with distinct decisions in each period for transformation pathway optimization
+- **Scenario dimension**: Supports stochastic modeling with weighted scenarios for robust decision-making under uncertainty (demand, prices, weather)
+    - Control variable independence across scenarios via `scenario_independent_sizes` and `scenario_independent_flow_rates` parameters
+    - By default, investment sizes are shared across scenarios while flow rates vary per scenario
+
+**Redesigned effect sharing system:**
+
+Effects now use intuitive `share_from_*` syntax that clearly shows contribution sources:
+
+```python
+costs = fx.Effect('costs', '€', 'Total costs',
+    share_from_temporal={'CO2': 0.2},      # From temporal effects
+    share_from_periodic={'land': 100})     # From periodic effects
+```
+
+This replaces `specific_share_to_other_effects_*` parameters and inverts the direction for clearer relationships.
+
+**Enhanced I/O and data handling:**
+
+- NetCDF/JSON serialization for all Interface objects and FlowSystem with round-trip support
+- FlowSystem manipulation: `sel()`, `isel()`, `resample()`, `copy()`, `__eq__()` methods
+- Direct access to FlowSystem from results without manual restoring (lazily loaded)
+- New `FlowResults` class and precomputed DataArrays for sizes/flow_rates/flow_hours
+- `effects_per_component` dataset for component impact evaluation, including all indirect effects through effect shares
+
+**Other additions:**
+
+- Balanced storage - charging and discharging sizes can be forced equal via `balanced` parameter
+- New Storage parameters: `relative_minimum_final_charge_state` and `relative_maximum_final_charge_state` for final state control
+- Improved filter methods in results
+- Example for 2-stage investment decisions leveraging FlowSystem resampling
+
+### 💥 Breaking Changes
+
+- `relative_minimum_charge_state` and `relative_maximum_charge_state` don't have an extra timestep anymore.
+- Renamed class `SystemModel` to `FlowSystemModel`
+- Renamed class `Model` to `Submodel`
+- Renamed `mode` parameter in plotting methods to `style`
+- Renamed investment binary variable `is_invested` to `invested` in `InvestmentModel`
+- `Calculation.do_modeling()` now returns the `Calculation` object instead of its `linopy.Model`. Callers that previously accessed the linopy model directly should now use `calculation.do_modeling().model` instead of `calculation.do_modeling()`.
+
+### ♻️ Changed
+
+- FlowSystems cannot be shared across multiple Calculations anymore. A copy of the FlowSystem is created instead, making every Calculation independent
+- Each Subcalculation in `SegmentedCalculation` now has its own distinct `FlowSystem` object
+- Type system overhaul - added clear separation between temporal and non-temporal data throughout codebase for better clarity
+- Enhanced FlowSystem interface with improved `__repr__()` and `__str__()` methods
+- Improved Model Structure - Views and organisation is now divided into:
+    - Model: The main Model (linopy.Model) that is used to create and store the variables and constraints for the FlowSystem.
+    - Submodel: The base class for all submodels. Each is a subset of the Model, for simpler access and clearer code.
+- Made docstrings in `config.py` more compact and easier to read
+- Improved format handling in configuration module
+- Enhanced console output to support both `stdout` and `stderr` stream selection
+- Added `show_logger_name` parameter to `CONFIG.Logging` for displaying logger names in messages
+
+### 🗑️ 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.
+- **InvestParameters** parameters renamed for improved clarity around investment and retirement effects:
+    - `fix_effects` → `effects_of_investment`
+    - `specific_effects` → `effects_of_investment_per_size`
+    - `divest_effects` → `effects_of_retirement`
+    - `piecewise_effects` → `piecewise_effects_of_investment`
+- **Effect** parameters renamed:
+    - `minimum_investment` → `minimum_periodic`
+    - `maximum_investment` → `maximum_periodic`
+    - `minimum_operation` → `minimum_temporal`
+    - `maximum_operation` → `maximum_temporal`
+    - `minimum_operation_per_hour` → `minimum_per_hour`
+    - `maximum_operation_per_hour` → `maximum_per_hour`
+- **Component** parameters renamed:
+    - `Source.source` → `Source.outputs`
+    - `Sink.sink` → `Sink.inputs`
+    - `SourceAndSink.source` → `SourceAndSink.outputs`
+    - `SourceAndSink.sink` → `SourceAndSink.inputs`
+    - `SourceAndSink.prevent_simultaneous_sink_and_source` → `SourceAndSink.prevent_simultaneous_flow_rates`
+
+### 🔥 Removed
+
+- **Effect share parameters**: The old `specific_share_to_other_effects_*` parameters were replaced WITHOUT DEPRECATION
+    - `specific_share_to_other_effects_operation` → `share_from_temporal` (with inverted direction)
+    - `specific_share_to_other_effects_invest` → `share_from_periodic` (with inverted direction)
+
+### 🐛 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
+- Added extra validation in `config.py` to improve error handling
+
+### 📝 Docs
+
+- Reorganized mathematical notation docs: moved to lowercase `mathematical-notation/` with subdirectories (`elements/`, `features/`, `modeling-patterns/`)
+- Added comprehensive documentation pages: `dimensions.md` (time/period/scenario), `effects-penalty-objective.md`, modeling patterns
+- Enhanced all element pages with implementation details, cross-references, and "See Also" sections
+- Rewrote README and landing page with clearer vision, roadmap, and universal applicability emphasis
+- Removed deprecated `docs/SUMMARY.md`, updated `mkdocs.yml` for new structure
+- Tightened docstrings in core modules with better cross-referencing
+- Added recipes section to docs
+
+### 🚧 Known Issues
+
+- IO for single Interfaces/Elements to Datasets might not work properly if the Interface/Element is not part of a fully transformed and connected FlowSystem. This arises 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 that's connected and transformed.
+
+### 👷 Development
+
+- **Centralized deprecation pattern**: Added `_handle_deprecated_kwarg()` helper method to `Interface` base class that provides reusable deprecation handling with consistent warnings, conflict detection, and optional value transformation. Applied across 5 classes (InvestParameters, Source, Sink, SourceAndSink, Effect) reducing deprecation boilerplate by 72%.
+- FlowSystem data management simplified - removed `time_series_collection` pattern in favor of direct timestep properties
+- Change modeling hierarchy to allow for more flexibility in future development. This leads to minimal changes in the access and creation of Submodels and their variables.
+- Added new module `.modeling` that contains modeling primitives and utilities
+- Clearer separation between the main Model and "Submodels"
+- Improved access to the Submodels and their variables, constraints and submodels
+- Added `__repr__()` for Submodels to easily inspect its content
+- 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
+- **Testing improvements**: Eliminated warnings during test execution
+    - Updated deprecated code patterns in tests and examples (e.g., `sink`/`source` → `inputs`/`outputs`, `'H'` → `'h'` frequency)
+    - Refactored plotting logic to handle test environments explicitly with non-interactive backends
+    - Added comprehensive warning filters in `__init__.py` and `pyproject.toml` to suppress third-party library warnings
+    - Improved test fixtures with proper figure cleanup to prevent memory leaks
+    - Enhanced backend detection and handling in `plotting.py` for both Matplotlib and Plotly
+    - Always run dependent tests in order
+
+---
+
 ## [2.2.0] - 2025-10-11
 **Summary:** This release is a Configuration and Logging management release.
 
@@ -77,9 +215,16 @@ Until here -->
 - Added configurable log format settings: `CONFIG.Logging.date_format` and `CONFIG.Logging.format`
 - Added configurable console settings: `CONFIG.Logging.console_width` and `CONFIG.Logging.show_path`
 - Added `CONFIG.Logging.Colors` nested class for customizable log level colors using ANSI escape codes (works with both standard and Rich handlers)
+- All examples now enable console logging to demonstrate proper logging usage
+- Console logging now outputs to `sys.stdout` instead of `sys.stderr` for better compatibility with output redirection
+
+### 💥 Breaking Changes
+- Console logging is now disabled by default (`CONFIG.Logging.console = False`). Enable it explicitly in your scripts with `CONFIG.Logging.console = True` and `CONFIG.apply()`
+- File logging is now disabled by default (`CONFIG.Logging.file = None`). Set a file path to enable file logging
 
 ### ♻️ Changed
 - Logging and Configuration management changed
+- Improved default logging colors: DEBUG is now gray (`\033[90m`) for de-emphasized messages, INFO uses terminal default color (`\033[0m`) for clean output
 
 ### 🗑️ Deprecated
 - `change_logging_level()` function is now deprecated in favor of `CONFIG.Logging.level` and `CONFIG.apply()`. Will be removed in version 3.0.0.

MANIFEST.in

@@ -5,7 +5,7 @@ include CHANGELOG.md
 include pyproject.toml
 
 # Include package source and data
-recursive-include flixopt *.py *.yaml
+recursive-include flixopt *.py
 
 # Exclude everything else
 global-exclude *.pyc *.pyo __pycache__