flixopt 3.0.2__tar.gz → 3.1.0__tar.gz

{flixopt-3.0.2 → flixopt-3.1.0}/CHANGELOG.md

@@ -4,6 +4,10 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 Formatting is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) & [Gitmoji](https://gitmoji.dev).
 For more details regarding the individual PRs and contributors, please refer to our [GitHub releases](https://github.com/flixOpt/flixopt/releases).
 
+!!! tip
+
+    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/).
+
 ---
 
 <!-- This text won't be rendered
@@ -17,6 +21,9 @@ Please keep the format of the changelog consistent with the other releases, so t
 
 ## [Template] - ????-??-??
 
+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
 
 ### 💥 Breaking Changes
@@ -41,38 +48,64 @@ Please keep the format of the changelog consistent with the other releases, so t
 
 ---
 
-
 ## [Unreleased] - ????-??-??
 
-### ✨ Added
+Until here -->
 
-### 💥 Breaking Changes
+## [3.1.0] - 2025-10-19
+
+**Summary**: This release adds faceting and animation support for multidimensional plots and redesigns the documentation website. Plotting results across scenarios or periods is now significantly simpler (Plotly only).
+
+If upgrading from v2.x, see the [Migration Guide](https://flixopt.github.io/flixopt/latest/user-guide/migration-guide-v3/) and [v3.0.0 release notes](https://github.com/flixOpt/flixOpt/releases/tag/v3.0.0).
+
+### ✨ Added
+- **Faceting and animation for multidimensional plots**: All plotting methods now support `facet_by` and `animate_by` parameters to create subplot grids and animations from multidimensional data (scenarios, periods, etc.). *Plotly only.*
+- **Flexible data selection with `select` parameter**: Select data using single values, lists, slices, or index arrays for precise control over what gets plotted
+- **Heatmap fill control**: New `fill` parameter in heatmap methods controls how missing values are filled after reshaping (`'ffill'` or `'bfill'`)
+- **Smart line styling for mixed variables**: Area plots now automatically style variables containing both positive and negative values with dashed lines, while stacking purely positive or negative variables
 
 ### ♻️ Changed
+- **Breaking: Selection behavior**: Plotting methods no longer automatically select the first value for non-time dimensions. Use the `select` parameter for explicit selection of scenarios, periods, or other dimensions
+- **Better error messages**: Enhanced error messages when using Matplotlib with multidimensional data, with clearer guidance on dimension requirements and suggestions to use Plotly
+- **Improved examples**: Enhanced `scenario_example.py` with better demonstration of new features
+- **Robust validation**: Improved dimension validation in `plot_heatmap()` with clearer error messages
 
 ### 🗑️ Deprecated
-
-### 🔥 Removed
+- **`indexer` parameter**: Use the new `select` parameter instead. The `indexer` parameter will be removed in v4.0.0
+- **`heatmap_timeframes` and `heatmap_timesteps_per_frame` parameters**: Use the new `reshape_time=(timeframes, timesteps_per_frame)` parameter instead in heatmap plotting methods
+- **`color_map` parameter**: Use the new `colors` parameter instead in heatmap plotting methods
 
 ### 🐛 Fixed
+- Fixed cryptic errors when working with empty buses by adding proper validation
+- Added early validation for non-existent periods when using linked periods with tuples
 
-### 🔒 Security
+### 📝 Documentation
+- **Redesigned documentation website** with custom css
 
-### 📦 Dependencies
+### 👷 Development
+- Renamed internal `_apply_indexer_to_data()` to `_apply_selection_to_data()` for consistency with new API naming
 
-### 📝 Docs
+---
 
-### 👷 Development
+## [3.0.3] - 2025-10-16
+**Summary**: Hotfixing new plotting parameter `style`. Continue to use `mode`.
 
-### 🚧 Known Issues
+**Note**: If upgrading from v2.x, see the [Migration Guide](https://flixopt.github.io/flixopt/latest/user-guide/migration-guide-v3/) and [v3.0.0 release notes](https://github.com/flixOpt/flixOpt/releases/tag/v3.0.0).
+
+### 🐛 Fixed
+- Reverted breaking change from v3.0.0: continue to use `mode parameter in plotting instead of new `style`
+- Renamed new `mode` parameter in plotting methods to `unit_type`
+
+### 📝 Docs
+- Updated Migration Guide and added missing entries.
+- Improved Changelog of v3.0.0
 
 ---
-Until here -->
 
 ## [3.0.2] - 2025-10-15
 **Summary**: This is a follow-up release to **[v3.0.0](https://github.com/flixOpt/flixOpt/releases/tag/v3.0.0)**, improving the documentation.
 
-**Note**: 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/).
+**Note**: If upgrading from v2.x, see the [Migration Guide](https://flixopt.github.io/flixopt/latest/user-guide/migration-guide-v3/) and [v3.0.0 release notes](https://github.com/flixOpt/flixOpt/releases/tag/v3.0.0).
 
 ### 📝 Docs
 - Update the Readme
@@ -85,7 +118,7 @@ Until here -->
 ## [3.0.1] - 2025-10-14
 **Summary**: This is a follow-up release to **[v3.0.0](https://github.com/flixOpt/flixOpt/releases/tag/v3.0.0)**, adding a Migration Guide and bugfixing the docs.
 
-**Note**: 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/).
+**Note**: If upgrading from v2.x, see the [Migration Guide](https://flixopt.github.io/flixopt/latest/user-guide/migration-guide-v3/) and [v3.0.0 release notes](https://github.com/flixOpt/flixOpt/releases/tag/v3.0.0).
 
 ### 📝 Docs
 - Fixed deployed docs
@@ -99,7 +132,7 @@ 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.
 
-**Note**: 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/).
+**Note**: If upgrading from v2.x, see the [Migration Guide](https://flixopt.github.io/flixopt/latest/user-guide/migration-guide-v3/) and [v3.0.0 release notes](https://github.com/flixOpt/flixOpt/releases/tag/v3.0.0).
 
 ### ✨ Added
 
@@ -139,17 +172,43 @@ This replaces `specific_share_to_other_effects_*` parameters and inverts the dir
 
 ### 💥 Breaking Changes
 
-- `relative_minimum_charge_state` and `relative_maximum_charge_state` don't have an extra timestep anymore.
+**API and Behavior Changes:**
+
+- **Effect system redesigned** (no deprecation):
+  - **Terminology changes**: Effect domains renamed for clarity: `operation` → `temporal`, `invest`/`investment` → `periodic`
+  - **Sharing system**: The old `specific_share_to_other_effects_*` parameters were completely replaced with the new `share_from_temporal` and `share_from_periodic` syntax (see 🔥 Removed section)
+- **FlowSystem independence**: 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
+- **Bus and Effect object assignment**: Direct assignment of Bus/Effect objects is no longer supported. Use labels (strings) instead:
+  - `Flow.bus` must receive a string label, not a Bus object
+  - Effect shares must use effect labels (strings) in dictionaries, not Effect objects
+- **Logging defaults** (from v2.2.0): Console and file logging are now disabled by default. Enable explicitly with `CONFIG.Logging.console = True` and `CONFIG.apply()`
+
+**Class and Method Renaming:**
+
 - 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()`.
+- `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()`
+
+**Variable Renaming in Results:**
+
+- Investment binary variable: `is_invested` → `invested` in `InvestmentModel`
+- Switch tracking variables in `OnOffModel`:
+  - `switch_on` → `switch|on`
+  - `switch_off` → `switch|off`
+  - `switch_on_nr` → `switch|count`
+- Effect submodel variables (following terminology changes):
+  - `Effect(invest)|total` → `Effect(periodic)`
+  - `Effect(operation)|total` → `Effect(temporal)`
+  - `Effect(operation)|total_per_timestep` → `Effect(temporal)|per_timestep`
+  - `Effect|total` → `Effect`
+
+**Data Structure Changes:**
+
+- `relative_minimum_charge_state` and `relative_maximum_charge_state` don't have an extra timestep anymore. Use the new `relative_minimum_final_charge_state` and `relative_maximum_final_charge_state` parameters for final state control
 
 ### ♻️ 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:
@@ -164,8 +223,6 @@ This replaces `specific_share_to_other_effects_*` parameters and inverts the dir
 
 - 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`

{flixopt-3.0.2/flixopt.egg-info → flixopt-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flixopt
-Version: 3.0.2
+Version: 3.1.0
 Summary: Vector based energy and material flow optimization framework in Python.
 Author-email: "Chair of Building Energy Systems and Heat Supply, TU Dresden" <peter.stange@tu-dresden.de>, Felix Bumann <felixbumann387@gmail.com>, Felix Panitz <baumbude@googlemail.com>, Peter Stange <peter.stange@tu-dresden.de>
 Maintainer-email: Felix Bumann <felixbumann387@gmail.com>, Peter Stange <peter.stange@tu-dresden.de>
@@ -9,7 +9,7 @@ Project-URL: homepage, https://tu-dresden.de/ing/maschinenwesen/iet/gewv/forschu
 Project-URL: repository, https://github.com/flixOpt/flixopt
 Project-URL: documentation, https://flixopt.github.io/flixopt/
 Keywords: optimization,energy systems,numerical analysis
-Classifier: Development Status :: 5 - Production/Stable
+Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -66,6 +66,7 @@ Requires-Dist: dash-daq==0.6.0; extra == "dev"
 Requires-Dist: networkx==3.0.0; extra == "dev"
 Requires-Dist: werkzeug==3.0.0; extra == "dev"
 Provides-Extra: docs
+Requires-Dist: mkdocs==1.6.1; extra == "docs"
 Requires-Dist: mkdocs-material==9.6.21; extra == "docs"
 Requires-Dist: mkdocstrings-python==1.18.2; extra == "docs"
 Requires-Dist: mkdocs-table-reader-plugin==3.1.0; extra == "docs"
@@ -76,6 +77,8 @@ Requires-Dist: markdown-include==0.8.1; extra == "docs"
 Requires-Dist: pymdown-extensions==10.16.1; extra == "docs"
 Requires-Dist: pygments==2.19.2; extra == "docs"
 Requires-Dist: mike==2.1.3; extra == "docs"
+Requires-Dist: mkdocs-git-revision-date-localized-plugin==1.4.7; extra == "docs"
+Requires-Dist: mkdocs-minify-plugin==0.8.0; extra == "docs"
 Dynamic: license-file
 
 # FlixOpt: Energy and Material Flow Optimization Framework

{flixopt-3.0.2 → flixopt-3.1.0}/flixopt/__init__.py

@@ -7,7 +7,7 @@ from importlib.metadata import PackageNotFoundError, version
 
 try:
     __version__ = version('flixopt')
-except PackageNotFoundError:
+except (PackageNotFoundError, TypeError):
     # Package is not installed (development mode without editable install)
     __version__ = '0.0.0.dev0'
 

{flixopt-3.0.2 → flixopt-3.1.0}/flixopt/elements.py

@@ -207,6 +207,10 @@ class Bus(Element):
                 logger.warning(
                     f'In Bus {self.label_full}, the excess_penalty_per_flow_hour is 0. Use "None" or a value > 0.'
                 )
+        if len(self.inputs) == 0 and len(self.outputs) == 0:
+            raise ValueError(
+                f'Bus "{self.label_full}" has no Flows connected to it. Please remove it from the FlowSystem'
+            )
 
     @property
     def with_excess(self) -> bool:

{flixopt-3.0.2 → flixopt-3.1.0}/flixopt/interface.py

@@ -963,6 +963,11 @@ class InvestParameters(Interface):
                 raise TypeError(
                     f'If you provide a tuple to "linked_periods", it needs to be len=2. Got {len(self.linked_periods)=}'
                 )
+            if flow_system.periods is None:
+                raise ValueError(
+                    f'Cannot use linked_periods={self.linked_periods} when FlowSystem has no periods defined. '
+                    f'Please define periods in FlowSystem or use linked_periods=None.'
+                )
             logger.debug(f'Computing linked_periods from {self.linked_periods}')
             start, end = self.linked_periods
             if start not in flow_system.periods.values: