From 857b421ac4316bcda706c5ff1bcb706b4ea1db34 Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 09:14:20 +0200 Subject: [PATCH 01/20] Update README.md --- README.md | 32 +++++++++++++++++++++++--------- 1 file changed, 23 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 957274f1c..1a61f90b6 100644 --- a/README.md +++ b/README.md @@ -17,21 +17,19 @@ We believe that optimization modeling should be **approachable for beginners** y ### Where We're Going **Short-term goals:** -- **Multi-dimensional modeling**: Full support for multi-period investments and scenario-based stochastic optimization (periods and scenarios are in active development) - **Enhanced component library**: More pre-built, domain-specific components (sector coupling, hydrogen systems, thermal networks, demand-side management) +- **Advanced result analysis**: Automated reporting and even more visualization options +- **Examples of stochastic and Multi-Period Modeling**: THe new feature is currently lacking showcases. +- **Interactive tutorials**: Browser-based, reactive tutorials for learning FlixOpt without local installation **Medium-term vision:** - **Modeling to generate alternatives (MGA)**: Built-in support for exploring near-optimal solution spaces to produce more robust, diverse solutions under uncertainty -- **Interactive tutorials**: Browser-based, reactive tutorials for learning FlixOpt without local installation - **Standardized cost calculations**: Align with industry standards (VDI 2067) for CAPEX/OPEX calculations -- **Advanced result analysis**: Time-series aggregation, automated reporting, and rich visualization options **Long-term vision:** - **Showcase universal applicability**: FlixOpt already handles any flow-based system (supply chains, water networks, production planning, chemical processes) - we need more examples and domain-specific component libraries to demonstrate this -- **Seamless integration**: First-class support for coupling with simulation tools, databases, existing energy system models, and GIS data -- **Robust optimization**: Built-in uncertainty quantification and stochastic programming capabilities +- **Production ready**: First class support for modeling in production - **Community ecosystem**: Rich library of user-contributed components, examples, and domain-specific extensions -- **Model validation tools**: Automated checks for physical plausibility, data consistency, and common modeling errors ### Why FlixOpt Exists @@ -66,12 +64,18 @@ boiler = fx.Boiler("Boiler", eta=0.9, ...) boiler.model.add_constraints(custom_constraint, name="my_constraint") ``` +### Multi-Dimensional Modeling +Model complex real-world decisions with **periods** and **scenarios**: +- **Periods** enable multi-period investment planning - optimize transformation pathways with distinct investment decisions in each period +- **Scenarios** support stochastic optimization with weighted scenarios for robust decision-making under uncertainty (demand variations, price scenarios, weather conditions) + ### Multi-Criteria Optimization Done Right -Model costs, emissions, resource use, and any custom metric simultaneously as **Effects**. Optimize any single Effect, use weighted combinations, or apply ε-constraints: +Model costs, emissions, resource use, and any custom metric simultaneously as **Effects**. Effects now use intuitive `share_from_*` syntax showing clear contribution sources. Optimize any single Effect, use weighted combinations, or apply ε-constraints: ```python costs = fx.Effect('costs', '€', 'Total costs', - share_from_temporal={'CO2': 180}) # 180 €/tCO2 + share_from_temporal={'CO2': 180}, # 180 €/tCO2 from temporal effects + share_from_periodic={'land': 100}) # 100 €/m² from periodic effects co2 = fx.Effect('CO2', 'kg', 'Emissions', maximum_periodic=50000) ``` @@ -82,7 +86,17 @@ Choose the right calculation mode for your problem: - **Aggregated** - Typical periods using [TSAM](https://github.com/FZJ-IEK3-VSA/tsam) for massive models ### Built for Reproducibility -Every result file is self-contained with complete model information. Load it months later and know exactly what you optimized. Export to NetCDF, share with colleagues, archive for compliance. +Every result file is self-contained with complete model information. Full NetCDF/JSON serialization support with round-trip fidelity. Load results months later and know exactly what you optimized - complete with the original FlowSystem. Export to NetCDF, share with colleagues, archive for compliance. + +### Powerful Data Manipulation +FlowSystem objects support intuitive data operations: +```python +# Select specific time ranges or scenarios +system_subset = flow_system.sel(time=slice("2025-06", "2025-12")) + +# Resample for multi-stage optimization +coarse_system = flow_system.resample(time="D") # Daily resolution +``` --- From 7845a503a7f9da627d3a51f34a9a915667b86b7b Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 09:17:22 +0200 Subject: [PATCH 02/20] Update README.md --- README.md | 66 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 52 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 1a61f90b6..6a5a20712 100644 --- a/README.md +++ b/README.md @@ -64,19 +64,51 @@ boiler = fx.Boiler("Boiler", eta=0.9, ...) boiler.model.add_constraints(custom_constraint, name="my_constraint") ``` -### Multi-Dimensional Modeling -Model complex real-world decisions with **periods** and **scenarios**: -- **Periods** enable multi-period investment planning - optimize transformation pathways with distinct investment decisions in each period -- **Scenarios** support stochastic optimization with weighted scenarios for robust decision-making under uncertainty (demand variations, price scenarios, weather conditions) +### Grow Your Model Incrementally +Start with a simple single-period model, then progressively add detail without restructuring: + +```python +import flixopt as fx + +# Step 1: Start simple - single period, deterministic +flow_system = fx.FlowSystem(time_series) +boiler = fx.Boiler("Boiler", eta=0.9, ...) +flow_system.add_component(boiler) + +# Step 2: Add more detail to existing components +boiler.add_effects(fx.Effect('CO2', 'kg', 'Emissions')) +boiler.add_investment(fx.InvestParameters(...)) + +# Step 3: Later, extend to multi-period planning - no refactoring needed! +flow_system_extended = flow_system.resample(time="D") # Coarser resolution +periods = [fx.Period("2025", length=1), fx.Period("2030", length=5)] +calc = fx.Calculation(flow_system_extended, periods=periods) + +# Step 4: Add uncertainty with scenarios - simply extend your existing model +scenarios = [ + fx.Scenario("high_demand", probability=0.3), + fx.Scenario("base_case", probability=0.5), + fx.Scenario("low_demand", probability=0.2) +] +# Create scenario-specific variants of your time series +calc = fx.Calculation(flow_system_extended, periods=periods, scenarios=scenarios) +``` + +**The key**: Your initial model structure stays intact. Periods and scenarios are added as model dimensions, not as rewrites. ### Multi-Criteria Optimization Done Right -Model costs, emissions, resource use, and any custom metric simultaneously as **Effects**. Effects now use intuitive `share_from_*` syntax showing clear contribution sources. Optimize any single Effect, use weighted combinations, or apply ε-constraints: +Model costs, emissions, resource use, and any custom metric simultaneously as **Effects**. Effects use intuitive `share_from_*` syntax showing clear contribution sources. Optimize any single Effect, use weighted combinations, or apply ε-constraints: ```python +# Simple start +costs = fx.Effect('costs', '€', 'Total costs') +co2 = fx.Effect('CO2', 'kg', 'Emissions') + +# Later: Add effect relationships without changing component definitions costs = fx.Effect('costs', '€', 'Total costs', - share_from_temporal={'CO2': 180}, # 180 €/tCO2 from temporal effects - share_from_periodic={'land': 100}) # 100 €/m² from periodic effects -co2 = fx.Effect('CO2', 'kg', 'Emissions', maximum_periodic=50000) + share_from_temporal={'CO2': 180}, # 180 €/tCO2 carbon pricing + share_from_periodic={'land': 100}) # 100 €/m² land cost +co2 = fx.Effect('CO2', 'kg', 'Emissions', maximum_periodic=50000) # Add constraint ``` ### Performance at Any Scale @@ -85,17 +117,23 @@ Choose the right calculation mode for your problem: - **Segmented** - Rolling horizon for large time series - **Aggregated** - Typical periods using [TSAM](https://github.com/FZJ-IEK3-VSA/tsam) for massive models +Switch between modes without changing your model definition. + ### Built for Reproducibility Every result file is self-contained with complete model information. Full NetCDF/JSON serialization support with round-trip fidelity. Load results months later and know exactly what you optimized - complete with the original FlowSystem. Export to NetCDF, share with colleagues, archive for compliance. -### Powerful Data Manipulation -FlowSystem objects support intuitive data operations: +### Flexible Data Manipulation +Transform your FlowSystem on the fly for different analyses: ```python -# Select specific time ranges or scenarios -system_subset = flow_system.sel(time=slice("2025-06", "2025-12")) +# Subset to specific time ranges +system_q2 = flow_system.sel(time=slice("2025-04", "2025-06")) + +# Extract specific scenarios for comparison +system_high = flow_system.sel(scenario="high_demand") -# Resample for multi-stage optimization -coarse_system = flow_system.resample(time="D") # Daily resolution +# Resample to different temporal resolutions for multi-stage optimization +system_hourly = flow_system.resample(time="h") +system_daily = flow_system.resample(time="D") ``` --- From d0c66c289147a3b02aee0bc5d6a24559433b477c Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 09:22:10 +0200 Subject: [PATCH 03/20] Update README.md --- README.md | 36 ++---------------------------------- 1 file changed, 2 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 6a5a20712..83bd3b12a 100644 --- a/README.md +++ b/README.md @@ -64,48 +64,16 @@ boiler = fx.Boiler("Boiler", eta=0.9, ...) boiler.model.add_constraints(custom_constraint, name="my_constraint") ``` -### Grow Your Model Incrementally -Start with a simple single-period model, then progressively add detail without restructuring: - -```python -import flixopt as fx - -# Step 1: Start simple - single period, deterministic -flow_system = fx.FlowSystem(time_series) -boiler = fx.Boiler("Boiler", eta=0.9, ...) -flow_system.add_component(boiler) - -# Step 2: Add more detail to existing components -boiler.add_effects(fx.Effect('CO2', 'kg', 'Emissions')) -boiler.add_investment(fx.InvestParameters(...)) - -# Step 3: Later, extend to multi-period planning - no refactoring needed! -flow_system_extended = flow_system.resample(time="D") # Coarser resolution -periods = [fx.Period("2025", length=1), fx.Period("2030", length=5)] -calc = fx.Calculation(flow_system_extended, periods=periods) - -# Step 4: Add uncertainty with scenarios - simply extend your existing model -scenarios = [ - fx.Scenario("high_demand", probability=0.3), - fx.Scenario("base_case", probability=0.5), - fx.Scenario("low_demand", probability=0.2) -] -# Create scenario-specific variants of your time series -calc = fx.Calculation(flow_system_extended, periods=periods, scenarios=scenarios) -``` - -**The key**: Your initial model structure stays intact. Periods and scenarios are added as model dimensions, not as rewrites. - ### Multi-Criteria Optimization Done Right Model costs, emissions, resource use, and any custom metric simultaneously as **Effects**. Effects use intuitive `share_from_*` syntax showing clear contribution sources. Optimize any single Effect, use weighted combinations, or apply ε-constraints: ```python # Simple start -costs = fx.Effect('costs', '€', 'Total costs') +costs = fx.Effect('costs', '€', 'Total costs', objective=True) co2 = fx.Effect('CO2', 'kg', 'Emissions') # Later: Add effect relationships without changing component definitions -costs = fx.Effect('costs', '€', 'Total costs', +costs = fx.Effect('costs', '€', 'Total costs', objective=True, share_from_temporal={'CO2': 180}, # 180 €/tCO2 carbon pricing share_from_periodic={'land': 100}) # 100 €/m² land cost co2 = fx.Effect('CO2', 'kg', 'Emissions', maximum_periodic=50000) # Add constraint From 7dc10efdee94bd7e87b680f4b5ef22e619308bf8 Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 22:39:59 +0200 Subject: [PATCH 04/20] Add more badges because they are cool --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 83bd3b12a..292193f91 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,14 @@ [![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://flixopt.github.io/flixopt/latest/) [![Build Status](https://github.com/flixOpt/flixopt/actions/workflows/python-app.yaml/badge.svg)](https://github.com/flixOpt/flixopt/actions/workflows/python-app.yaml) [![PyPI version](https://img.shields.io/pypi/v/flixopt)](https://pypi.org/project/flixopt/) +[![PyPI downloads](https://img.shields.io/pypi/dm/flixopt)](https://pypi.org/project/flixopt/) [![Python Versions](https://img.shields.io/pypi/pyversions/flixopt.svg)](https://pypi.org/project/flixopt/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![GitHub stars](https://img.shields.io/github/stars/flixOpt/flixopt?style=social)](https://github.com/flixOpt/flixopt/stargazers) +[![DOI](https://img.shields.io/badge/DOI-10.18086%2Feurosun.2022.04.07-blue)](https://doi.org/10.18086/eurosun.2022.04.07) +[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) +[![GitHub last commit](https://img.shields.io/github/last-commit/flixOpt/flixopt)](https://github.com/flixOpt/flixopt/commits/main) +[![GitHub issues](https://img.shields.io/github/issues/flixOpt/flixopt)](https://github.com/flixOpt/flixopt/issues) --- From 357e2bc418d929242abd0bf47000095bf4a82a75 Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 22:43:02 +0200 Subject: [PATCH 05/20] Add more badges because they are cool --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 292193f91..767fd2cdb 100644 --- a/README.md +++ b/README.md @@ -3,14 +3,14 @@ [![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://flixopt.github.io/flixopt/latest/) [![Build Status](https://github.com/flixOpt/flixopt/actions/workflows/python-app.yaml/badge.svg)](https://github.com/flixOpt/flixopt/actions/workflows/python-app.yaml) [![PyPI version](https://img.shields.io/pypi/v/flixopt)](https://pypi.org/project/flixopt/) -[![PyPI downloads](https://img.shields.io/pypi/dm/flixopt)](https://pypi.org/project/flixopt/) [![Python Versions](https://img.shields.io/pypi/pyversions/flixopt.svg)](https://pypi.org/project/flixopt/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![GitHub stars](https://img.shields.io/github/stars/flixOpt/flixopt?style=social)](https://github.com/flixOpt/flixopt/stargazers) -[![DOI](https://img.shields.io/badge/DOI-10.18086%2Feurosun.2022.04.07-blue)](https://doi.org/10.18086/eurosun.2022.04.07) -[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) +[![PyPI downloads](https://img.shields.io/pypi/dm/flixopt)](https://pypi.org/project/flixopt/) [![GitHub last commit](https://img.shields.io/github/last-commit/flixOpt/flixopt)](https://github.com/flixOpt/flixopt/commits/main) [![GitHub issues](https://img.shields.io/github/issues/flixOpt/flixopt)](https://github.com/flixOpt/flixopt/issues) +[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) +[![DOI](https://img.shields.io/badge/DOI-10.18086%2Feurosun.2022.04.07-blue)](https://doi.org/10.18086/eurosun.2022.04.07) +[![GitHub stars](https://img.shields.io/github/stars/flixOpt/flixopt?style=social)](https://github.com/flixOpt/flixopt/stargazers) --- From dd27114cfeb8fbf2d3006fefebc7b4c9d86cb10a Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 22:46:48 +0200 Subject: [PATCH 06/20] Add more badges because they are cool --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 767fd2cdb..b864209ec 100644 --- a/README.md +++ b/README.md @@ -3,12 +3,16 @@ [![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://flixopt.github.io/flixopt/latest/) [![Build Status](https://github.com/flixOpt/flixopt/actions/workflows/python-app.yaml/badge.svg)](https://github.com/flixOpt/flixopt/actions/workflows/python-app.yaml) [![PyPI version](https://img.shields.io/pypi/v/flixopt)](https://pypi.org/project/flixopt/) +[![PyPI status](https://img.shields.io/pypi/status/flixopt.svg)](https://pypi.org/project/flixopt/) [![Python Versions](https://img.shields.io/pypi/pyversions/flixopt.svg)](https://pypi.org/project/flixopt/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![PyPI downloads](https://img.shields.io/pypi/dm/flixopt)](https://pypi.org/project/flixopt/) [![GitHub last commit](https://img.shields.io/github/last-commit/flixOpt/flixopt)](https://github.com/flixOpt/flixopt/commits/main) [![GitHub issues](https://img.shields.io/github/issues/flixOpt/flixopt)](https://github.com/flixOpt/flixopt/issues) +[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) +[![Powered by linopy](https://img.shields.io/badge/powered%20by-linopy-blue)](https://github.com/PyPSA/linopy/) +[![Powered by xarray](https://img.shields.io/badge/powered%20by-xarray-blue)](https://xarray.dev/) [![DOI](https://img.shields.io/badge/DOI-10.18086%2Feurosun.2022.04.07-blue)](https://doi.org/10.18086/eurosun.2022.04.07) [![GitHub stars](https://img.shields.io/github/stars/flixOpt/flixopt?style=social)](https://github.com/flixOpt/flixopt/stargazers) From 2ef0104281441c49134ec2f961d675e0966ded66 Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 22:52:13 +0200 Subject: [PATCH 07/20] Update Development Status to "Stable" --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 6ea2f232e..391f23c3a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -21,7 +21,7 @@ maintainers = [ ] keywords = ["optimization", "energy systems", "numerical analysis"] classifiers = [ - "Development Status :: 3 - Alpha", + "Development Status :: 5 - Production/Stable", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", From bbdd6e1c4f82ef5b35b68911cb6b57ffeb29f37b Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 23:04:16 +0200 Subject: [PATCH 08/20] Update the vision --- README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b864209ec..1d58ad137 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,11 @@ ## 🎯 Vision -**FlixOpt aims to be the most accessible and flexible Python framework for energy and material flow optimization.** +**FlixOpt aims to be the most accessible, flexible and universal Python framework for energy and material flow optimization.** -We believe that optimization modeling should be **approachable for beginners** yet **powerful for experts**. Too often, frameworks force you to choose between ease of use and flexibility. FlixOpt refuses this compromise. +We believe that optimization modeling should be **approachable for beginners** yet **powerful for experts**. Further we belive in **minimizing context switching**. + +Flixopt aims to be the tool of choice for both short term planning with high grade of detail, and for long term investment planning. We belive that using the same tool and context for both holds a lot of value. ### Where We're Going @@ -33,12 +35,11 @@ We believe that optimization modeling should be **approachable for beginners** y - **Interactive tutorials**: Browser-based, reactive tutorials for learning FlixOpt without local installation **Medium-term vision:** -- **Modeling to generate alternatives (MGA)**: Built-in support for exploring near-optimal solution spaces to produce more robust, diverse solutions under uncertainty -- **Standardized cost calculations**: Align with industry standards (VDI 2067) for CAPEX/OPEX calculations +- **Modeling to generate alternatives (MGA)**: Built-in support for exploring near-optimal solution spaces to produce more robust, diverse solutions under uncertainty. See [PyPSA](https://docs.pypsa.org/latest/user-guide/optimization/modelling-to-generate-alternatives/) and [calliope](https://calliope.readthedocs.io/en/latest/examples/modes/) +- **Stochastic Optimization**: Build sophisticated new `Calculation` classes to perform differnet Stochastic optimization. Like PyPSA's new [**Two-Stage Stochastic-Programming** or **Risk Preferences with Conditional Value-at-Risk (CVaR)**](https://docs.pypsa.org/latest/user-guide/optimization/stochastic/) **Long-term vision:** - **Showcase universal applicability**: FlixOpt already handles any flow-based system (supply chains, water networks, production planning, chemical processes) - we need more examples and domain-specific component libraries to demonstrate this -- **Production ready**: First class support for modeling in production - **Community ecosystem**: Rich library of user-contributed components, examples, and domain-specific extensions ### Why FlixOpt Exists From 820b1326b56ea9648864329ff355d05aa36d402c Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 23:22:21 +0200 Subject: [PATCH 09/20] Update the "Why FlixOpt Exists" --- README.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1d58ad137..7f392eac1 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ [![PyPI downloads](https://img.shields.io/pypi/dm/flixopt)](https://pypi.org/project/flixopt/) [![GitHub last commit](https://img.shields.io/github/last-commit/flixOpt/flixopt)](https://github.com/flixOpt/flixopt/commits/main) [![GitHub issues](https://img.shields.io/github/issues/flixOpt/flixopt)](https://github.com/flixOpt/flixopt/issues) -[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit) +[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/flixOpt/flixopt/main.svg)](https://results.pre-commit.ci/latest/github/flixOpt/flixopt/main) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![Powered by linopy](https://img.shields.io/badge/powered%20by-linopy-blue)](https://github.com/PyPSA/linopy/) [![Powered by xarray](https://img.shields.io/badge/powered%20by-xarray-blue)](https://xarray.dev/) @@ -44,9 +44,10 @@ Flixopt aims to be the tool of choice for both short term planning with high gra ### Why FlixOpt Exists -FlixOpt is a **general-purpose framework for modeling any system involving flows and conversions** - energy, materials, fluids, goods, or data. While energy systems are our primary focus, the same mathematical foundation applies to supply chains, water networks, production lines, and more. +FlixOpt is a **general-purpose framework for modeling any system involving flows and conversions** - energy, materials, fluids, goods, or data. While energy systems are the primary use case, the same mathematical foundation applies to supply chains, water networks, production lines, and more. THis also enables the coupling of such systems with an energy system model. -We bridge the gap between high-level strategic models (like [FINE](https://github.com/FZJ-IEK3-VSA/FINE)) for long-term planning and low-level dispatch tools for operations. FlixOpt is the **sweet spot** for: +We bridge the gap between high-level strategic models (like [FINE](https://github.com/FZJ-IEK3-VSA/FINE)) for long-term planning and low-level tools for short term operation/dispatch. +This approach is similar to the mature [PyPSA](https://docs.pypsa.org/latest/) project. FlixOpt is the **sweet spot** for: - **Researchers** who need to prototype quickly but may require deep customization later - **Engineers** who want reliable, tested components without black-box abstractions @@ -115,6 +116,10 @@ system_hourly = flow_system.resample(time="h") system_daily = flow_system.resample(time="D") ``` +### User Friendly +Flixopt is object oriented and well documented. We try to make the project and the resulting code as readable as possible. +If you have any issues with naming or definitions of parameters feel free to propose a rename. + --- ## 🚀 Quick Start From 0c11ebffd345ad8fdfed9a70424de52cc5f4c3a5 Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 23:25:28 +0200 Subject: [PATCH 10/20] Typos --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 7f392eac1..1af4f4b1c 100644 --- a/README.md +++ b/README.md @@ -22,21 +22,21 @@ **FlixOpt aims to be the most accessible, flexible and universal Python framework for energy and material flow optimization.** -We believe that optimization modeling should be **approachable for beginners** yet **powerful for experts**. Further we belive in **minimizing context switching**. +We believe that optimization modeling should be **approachable for beginners** yet **powerful for experts**. We also believe in **minimizing context switching**. -Flixopt aims to be the tool of choice for both short term planning with high grade of detail, and for long term investment planning. We belive that using the same tool and context for both holds a lot of value. +FlixOpt aims to be the tool of choice for both short-term planning with high detail resolution and long-term investment planning. We believe that using the same tool and context for both holds tremendous value. ### Where We're Going **Short-term goals:** - **Enhanced component library**: More pre-built, domain-specific components (sector coupling, hydrogen systems, thermal networks, demand-side management) -- **Advanced result analysis**: Automated reporting and even more visualization options -- **Examples of stochastic and Multi-Period Modeling**: THe new feature is currently lacking showcases. +- **Advanced result analysis**: Automated reporting and enhanced visualization options +- **Examples of stochastic and multi-period modeling**: The new features currently lack comprehensive showcases - **Interactive tutorials**: Browser-based, reactive tutorials for learning FlixOpt without local installation **Medium-term vision:** -- **Modeling to generate alternatives (MGA)**: Built-in support for exploring near-optimal solution spaces to produce more robust, diverse solutions under uncertainty. See [PyPSA](https://docs.pypsa.org/latest/user-guide/optimization/modelling-to-generate-alternatives/) and [calliope](https://calliope.readthedocs.io/en/latest/examples/modes/) -- **Stochastic Optimization**: Build sophisticated new `Calculation` classes to perform differnet Stochastic optimization. Like PyPSA's new [**Two-Stage Stochastic-Programming** or **Risk Preferences with Conditional Value-at-Risk (CVaR)**](https://docs.pypsa.org/latest/user-guide/optimization/stochastic/) +- **Modeling to generate alternatives (MGA)**: Built-in support for exploring near-optimal solution spaces to produce more robust, diverse solutions under uncertainty. See [PyPSA](https://docs.pypsa.org/latest/user-guide/optimization/modelling-to-generate-alternatives/) and [Calliope](https://calliope.readthedocs.io/en/latest/examples/modes/) for reference implementations +- **Advanced stochastic optimization**: Build sophisticated new `Calculation` classes to perform different stochastic optimization approaches, like PyPSA's [two-stage stochastic programming and risk preferences with Conditional Value-at-Risk (CVaR)](https://docs.pypsa.org/latest/user-guide/optimization/stochastic/) **Long-term vision:** - **Showcase universal applicability**: FlixOpt already handles any flow-based system (supply chains, water networks, production planning, chemical processes) - we need more examples and domain-specific component libraries to demonstrate this @@ -44,9 +44,9 @@ Flixopt aims to be the tool of choice for both short term planning with high gra ### Why FlixOpt Exists -FlixOpt is a **general-purpose framework for modeling any system involving flows and conversions** - energy, materials, fluids, goods, or data. While energy systems are the primary use case, the same mathematical foundation applies to supply chains, water networks, production lines, and more. THis also enables the coupling of such systems with an energy system model. +FlixOpt is a **general-purpose framework for modeling any system involving flows and conversions** - energy, materials, fluids, goods, or data. While energy systems are the primary use case, the same mathematical foundation applies to supply chains, water networks, production lines, and more. This also enables the coupling of such systems within an integrated energy system model. -We bridge the gap between high-level strategic models (like [FINE](https://github.com/FZJ-IEK3-VSA/FINE)) for long-term planning and low-level tools for short term operation/dispatch. +We bridge the gap between high-level strategic models (like [FINE](https://github.com/FZJ-IEK3-VSA/FINE)) for long-term planning and low-level tools for short-term operation and dispatch. This approach is similar to the mature [PyPSA](https://docs.pypsa.org/latest/) project. FlixOpt is the **sweet spot** for: - **Researchers** who need to prototype quickly but may require deep customization later From a5481ff7a615d6108132d7e714d81a08bc8e7b6e Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 23:26:15 +0200 Subject: [PATCH 11/20] Improve "User-Friendly Design" --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1af4f4b1c..03104d368 100644 --- a/README.md +++ b/README.md @@ -116,9 +116,9 @@ system_hourly = flow_system.resample(time="h") system_daily = flow_system.resample(time="D") ``` -### User Friendly -Flixopt is object oriented and well documented. We try to make the project and the resulting code as readable as possible. -If you have any issues with naming or definitions of parameters feel free to propose a rename. +### User-Friendly Design +FlixOpt is object-oriented and comprehensively documented. We prioritize readability in both the framework and user code. +If you find any naming or parameter definitions unclear, we welcome your suggestions for improvements. --- From 86c9f017480900d4c168de9963f7db95f99ffe3f Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 23:35:14 +0200 Subject: [PATCH 12/20] Restructure the README.md --- README.md | 261 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 197 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 03104d368..9ac2276d6 100644 --- a/README.md +++ b/README.md @@ -18,92 +18,151 @@ --- -## 🎯 Vision +**FlixOpt is a Python framework for optimizing energy and material flow systems** - from district heating networks to industrial production lines, from renewable energy portfolios to supply chain logistics. -**FlixOpt aims to be the most accessible, flexible and universal Python framework for energy and material flow optimization.** +**Start simple, scale complex:** Build a working optimization model in minutes, then progressively add detail - multi-period investments, stochastic scenarios, custom constraints - without rewriting your code. -We believe that optimization modeling should be **approachable for beginners** yet **powerful for experts**. We also believe in **minimizing context switching**. +--- -FlixOpt aims to be the tool of choice for both short-term planning with high detail resolution and long-term investment planning. We believe that using the same tool and context for both holds tremendous value. +## 🚀 Quick Start -### Where We're Going +```bash +pip install flixopt +``` -**Short-term goals:** -- **Enhanced component library**: More pre-built, domain-specific components (sector coupling, hydrogen systems, thermal networks, demand-side management) -- **Advanced result analysis**: Automated reporting and enhanced visualization options -- **Examples of stochastic and multi-period modeling**: The new features currently lack comprehensive showcases -- **Interactive tutorials**: Browser-based, reactive tutorials for learning FlixOpt without local installation +That's it! FlixOpt comes with the [HiGHS](https://highs.dev/) solver included. You're ready to optimize. -**Medium-term vision:** -- **Modeling to generate alternatives (MGA)**: Built-in support for exploring near-optimal solution spaces to produce more robust, diverse solutions under uncertainty. See [PyPSA](https://docs.pypsa.org/latest/user-guide/optimization/modelling-to-generate-alternatives/) and [Calliope](https://calliope.readthedocs.io/en/latest/examples/modes/) for reference implementations -- **Advanced stochastic optimization**: Build sophisticated new `Calculation` classes to perform different stochastic optimization approaches, like PyPSA's [two-stage stochastic programming and risk preferences with Conditional Value-at-Risk (CVaR)](https://docs.pypsa.org/latest/user-guide/optimization/stochastic/) +**Create your first model:** -**Long-term vision:** -- **Showcase universal applicability**: FlixOpt already handles any flow-based system (supply chains, water networks, production planning, chemical processes) - we need more examples and domain-specific component libraries to demonstrate this -- **Community ecosystem**: Rich library of user-contributed components, examples, and domain-specific extensions +```python +import flixopt as fx +import pandas as pd -### Why FlixOpt Exists +# Define your time horizon +timesteps = pd.date_range('2025-01-01', periods=8760, freq='h') +flow_system = fx.FlowSystem(timesteps=timesteps) -FlixOpt is a **general-purpose framework for modeling any system involving flows and conversions** - energy, materials, fluids, goods, or data. While energy systems are the primary use case, the same mathematical foundation applies to supply chains, water networks, production lines, and more. This also enables the coupling of such systems within an integrated energy system model. +# Add components +boiler = fx.Boiler("Boiler", eta=0.9, Q_th=fx.Flow(...), Q_fu=fx.Flow(...)) +flow_system.add_component(boiler) -We bridge the gap between high-level strategic models (like [FINE](https://github.com/FZJ-IEK3-VSA/FINE)) for long-term planning and low-level tools for short-term operation and dispatch. -This approach is similar to the mature [PyPSA](https://docs.pypsa.org/latest/) project. FlixOpt is the **sweet spot** for: +# Optimize +calculation = fx.FullCalculation("MyModel", flow_system=flow_system) +calculation.solve() -- **Researchers** who need to prototype quickly but may require deep customization later -- **Engineers** who want reliable, tested components without black-box abstractions -- **Students** learning optimization who benefit from clear, Pythonic interfaces -- **Practitioners** who need to move from model to production-ready results -- **Domain experts** from any field where things flow, transform, and need optimizing - -Built on modern foundations ([linopy](https://github.com/PyPSA/linopy/) and [xarray](https://github.com/pydata/xarray)), FlixOpt delivers both **performance** and **transparency**. You can inspect everything, extend anything, and trust that your model does exactly what you designed. +# Analyze results +calculation.results.plot() +``` -Originally developed at [TU Dresden](https://github.com/gewv-tu-dresden) for the SMARTBIOGRID project (funded by the German Federal Ministry for Economic Affairs and Energy, FKZ: 03KB159B), FlixOpt has evolved from the Matlab-based flixOptMat framework while incorporating the best ideas from [oemof/solph](https://github.com/oemof/oemof-solph). +**Next steps:** +- 📚 [Full Documentation](https://flixopt.github.io/flixopt/latest/) +- 💡 [Examples Gallery](https://flixopt.github.io/flixopt/latest/examples/) +- 🔧 [API Reference](https://flixopt.github.io/flixopt/latest/api-reference/) --- -## 🌟 What Makes FlixOpt Different +## 🌟 Why FlixOpt? -### Start Simple, Scale Complex -Define a working model in minutes with high-level components, then drill down to fine-grained control when needed. No rewriting, no framework switching. +### For Everyone: Start Simple, Scale Complex +**Beginners** get working models in minutes with high-level components: ```python -import flixopt as fx +boiler = fx.Boiler("Boiler", eta=0.9, ...) # Just works +``` -# Simple start -boiler = fx.Boiler("Boiler", eta=0.9, ...) +**Experts** can drill down to fine-grained control when needed: +```python +boiler.submodel.add_constraints(custom_constraint, name="my_constraint") +``` -# Advanced control when needed - extend with native linopy -boiler.model.add_constraints(custom_constraint, name="my_constraint") +**No framework switching.** Your initial model structure stays intact as you add complexity. + +### Grow Your Model Incrementally + +Start simple, then progressively enhance without refactoring: + +```python +# Step 1: Simple single-period model +flow_system = fx.FlowSystem(timesteps=timesteps) +boiler = fx.Boiler("Boiler", eta=0.9, ...) +flow_system.add_component(boiler) + +# Step 2: Add investment decisions +boiler.Q_th.invest_parameters = fx.InvestParameters(...) + +# Step 3: Multi-period planning? Just add periods! +periods = pd.Index([2025, 2030, 2035]) +flow_system_mp = fx.FlowSystem(timesteps=timesteps, periods=periods) +flow_system_mp.add_component(boiler) # Same component! + +# Step 4: Model uncertainty? Add scenarios! +scenarios = pd.Index(['high_demand', 'base_case', 'low_demand']) +flow_system_stoch = fx.FlowSystem( + timesteps=timesteps, + periods=periods, + scenarios=scenarios, + weights=[0.3, 0.5, 0.2] +) ``` -### Multi-Criteria Optimization Done Right -Model costs, emissions, resource use, and any custom metric simultaneously as **Effects**. Effects use intuitive `share_from_*` syntax showing clear contribution sources. Optimize any single Effect, use weighted combinations, or apply ε-constraints: +**The key:** Your component definitions stay the same. Periods and scenarios are dimensions of the FlowSystem, not structural changes to your model. + +### Multi-Criteria Optimization + +Model multiple metrics simultaneously - costs, emissions, resource use, any custom metric: ```python -# Simple start -costs = fx.Effect('costs', '€', 'Total costs', objective=True) +# Start simple +costs = fx.Effect('costs', '€', 'Total costs', is_objective=True) co2 = fx.Effect('CO2', 'kg', 'Emissions') -# Later: Add effect relationships without changing component definitions -costs = fx.Effect('costs', '€', 'Total costs', objective=True, - share_from_temporal={'CO2': 180}, # 180 €/tCO2 carbon pricing - share_from_periodic={'land': 100}) # 100 €/m² land cost -co2 = fx.Effect('CO2', 'kg', 'Emissions', maximum_periodic=50000) # Add constraint +# Add sophisticated relationships later +costs = fx.Effect('costs', '€', 'Total costs', is_objective=True, + share_from_temporal={'CO2': 180}, # Carbon pricing: 180 €/tCO2 + share_from_periodic={'land': 100}) # Land cost: 100 €/m² +co2 = fx.Effect('CO2', 'kg', 'Emissions', + maximum_periodic=50000) # Emission constraint ``` +This enables to model and evaluate cost structures in a system directly from the optimization solution (Costs from Investments, Costs from Operation, Revenues, Funding, Net Costs) + ### Performance at Any Scale -Choose the right calculation mode for your problem: -- **Full** - Maximum accuracy for smaller problems -- **Segmented** - Rolling horizon for large time series -- **Aggregated** - Typical periods using [TSAM](https://github.com/FZJ-IEK3-VSA/tsam) for massive models -Switch between modes without changing your model definition. +Choose the calculation mode that fits your problem - **without changing your model definition:** + +- **Full** - Maximum accuracy for detailed models (hours to days) +- **Segmented** - Rolling horizon for long time series (months to years) +- **Aggregated** - Typical periods using [TSAM](https://github.com/FZJ-IEK3-VSA/tsam) for massive models (decades) + +```python +# Same model, different calculation modes +fx.FullCalculation("MyModel", flow_system) +fx.SegmentedCalculation("MyModel", flow_system, segment_length=168) +fx.AggregatedCalculation("MyModel", flow_system, n_clusters=12) +``` ### Built for Reproducibility -Every result file is self-contained with complete model information. Full NetCDF/JSON serialization support with round-trip fidelity. Load results months later and know exactly what you optimized - complete with the original FlowSystem. Export to NetCDF, share with colleagues, archive for compliance. + +Every result file is **self-contained** with complete model information: + +- Full NetCDF/JSON serialization with round-trip fidelity +- Load results months later and know exactly what you optimized +- Original FlowSystem included - no manual reconstruction needed +- Export to NetCDF, share with colleagues, archive for compliance + +```python +# Save +calculation.results.to_file('my_results.nc') + +# Load later - everything is there +results = fx.results.CalculationResults.from_file('my_results.nc') +original_system = results.flow_system # Automatically restored! +``` ### Flexible Data Manipulation -Transform your FlowSystem on the fly for different analyses: + +Transform your FlowSystem on the fly using familiar xarray-style operations: + ```python # Subset to specific time ranges system_q2 = flow_system.sel(time=slice("2025-04", "2025-06")) @@ -111,41 +170,115 @@ system_q2 = flow_system.sel(time=slice("2025-04", "2025-06")) # Extract specific scenarios for comparison system_high = flow_system.sel(scenario="high_demand") -# Resample to different temporal resolutions for multi-stage optimization -system_hourly = flow_system.resample(time="h") +# Resample for multi-stage optimization system_daily = flow_system.resample(time="D") ``` ### User-Friendly Design -FlixOpt is object-oriented and comprehensively documented. We prioritize readability in both the framework and user code. -If you find any naming or parameter definitions unclear, we welcome your suggestions for improvements. + +- **Object-oriented** and Pythonic - feels natural if you know Python +- **Comprehensively documented** - every parameter explained +- **Readable code** - we prioritize clarity in both framework and user code +- **Open to feedback** - unclear naming? We welcome your suggestions! --- -## 🚀 Quick Start +## 🎯 What is FlixOpt? + +### A General-Purpose Flow Optimization Framework + +FlixOpt models **any system involving flows and conversions:** + +- **Energy systems:** District heating/cooling, microgrids, renewable portfolios, sector coupling +- **Material flows:** Supply chains, production lines, chemical processes, recycling networks +- **Integrated systems:** Water-energy nexus, industrial symbiosis, smart cities + +While energy systems are our primary focus, the same mathematical foundation applies universally. This enables coupling different system types within integrated models. + +### The Sweet Spot + +We bridge the gap between high-level strategic models (like [FINE](https://github.com/FZJ-IEK3-VSA/FINE)) for long-term planning and low-level tools for short-term operation and dispatch. This approach is similar to the mature [PyPSA](https://docs.pypsa.org/latest/) project. + +**FlixOpt is ideal for:** + +- **Researchers** who need quick prototyping but may require deep customization later +- **Engineers** who want reliable, tested components without black-box abstractions +- **Students** learning optimization who benefit from clear, Pythonic interfaces +- **Practitioners** who need to move from model to production-ready results +- **Domain experts** from any field where things flow, transform, and need optimizing + +### Modern Foundations + +Built on [linopy](https://github.com/PyPSA/linopy/) and [xarray](https://github.com/pydata/xarray), FlixOpt delivers both **performance** and **transparency**: + +- **Inspect everything** - full access to variables, constraints, and model structure +- **Extend anything** - add custom constraints using native linopy syntax +- **Trust your model** - you control exactly what gets optimized + +### Academic Roots + +Originally developed at [TU Dresden](https://github.com/gewv-tu-dresden) for the SMARTBIOGRID project (funded by the German Federal Ministry for Economic Affairs and Energy, FKZ: 03KB159B). FlixOpt evolved from the MATLAB-based flixOptMat framework while incorporating best practices from [oemof/solph](https://github.com/oemof/oemof-solph). + +--- + +## 🛣️ Roadmap + +### Our Vision + +**FlixOpt aims to be the most accessible, flexible, and universal Python framework for energy and material flow optimization.** + +We believe optimization modeling should be **approachable for beginners** yet **powerful for experts**. We also believe in **minimizing context switching** - use the same tool for short-term operational planning and long-term investment analysis. + +### Short-term Goals + +- **Enhanced component library:** More pre-built, domain-specific components (sector coupling, hydrogen systems, thermal networks, demand-side management) +- **Advanced result analysis:** Automated reporting and enhanced visualization options +- **Examples of stochastic and multi-period modeling:** The new features currently lack comprehensive showcases +- **Interactive tutorials:** Browser-based, reactive tutorials for learning FlixOpt without local installation + +### Medium-term Vision + +- **Modeling to generate alternatives (MGA):** Built-in support for exploring near-optimal solution spaces to produce more robust, diverse solutions under uncertainty. See [PyPSA](https://docs.pypsa.org/latest/user-guide/optimization/modelling-to-generate-alternatives/) and [Calliope](https://calliope.readthedocs.io/en/latest/examples/modes/) for reference implementations +- **Advanced stochastic optimization:** Build sophisticated new `Calculation` classes to perform different stochastic optimization approaches, like PyPSA's [two-stage stochastic programming and risk preferences with Conditional Value-at-Risk (CVaR)](https://docs.pypsa.org/latest/user-guide/optimization/stochastic/) + +### Long-term Vision + +- **Showcase universal applicability:** FlixOpt already handles any flow-based system (supply chains, water networks, production planning, chemical processes) - we need more examples and domain-specific component libraries to demonstrate this +- **Community ecosystem:** Rich library of user-contributed components, examples, and domain-specific extensions + +--- + +## 🛠️ Installation + +### Basic Installation ```bash pip install flixopt ``` -That's it. FlixOpt comes with the [HiGHS](https://highs.dev/) solver included - you're ready to optimize. -Many more solvers are supported (gurobi, cplex, cbc, glpk, ...) +Includes the [HiGHS](https://highs.dev/) solver - you're ready to optimize immediately. + +### Full Installation For additional features (interactive network visualization, time series aggregation): + ```bash pip install "flixopt[full]" ``` -**Next steps:** -- 📚 [Full Documentation](https://flixopt.github.io/flixopt/latest/) -- 💡 [Examples](https://flixopt.github.io/flixopt/latest/examples/) -- 🔧 [API Reference](https://flixopt.github.io/flixopt/latest/api-reference/) +### Solver Support + +FlixOpt supports many solvers via linopy: +- **HiGHS** (included, open-source, recommended for most users) +- **Gurobi** (commercial, fast for large problems) +- **CPLEX** (commercial) +- **CBC, GLPK** (open-source alternatives) --- ## 🤝 Contributing -FlixOpt thrives on community input. Whether you're fixing bugs, adding components, improving docs, or sharing use cases - we welcome your contributions. +FlixOpt thrives on community input. Whether you're fixing bugs, adding components, improving docs, or sharing use cases - **we welcome your contributions.** See our [contribution guide](https://flixopt.github.io/flixopt/latest/contribute/) to get started. From 937523332284a5fd39d5cc440f528b6af8cd34e1 Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 23:38:07 +0200 Subject: [PATCH 13/20] Update getting started --- README.md | 25 ++++++++++--------------- 1 file changed, 10 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 9ac2276d6..948c47dcf 100644 --- a/README.md +++ b/README.md @@ -32,31 +32,26 @@ pip install flixopt That's it! FlixOpt comes with the [HiGHS](https://highs.dev/) solver included. You're ready to optimize. -**Create your first model:** +**The basic workflow:** ```python import flixopt as fx -import pandas as pd -# Define your time horizon -timesteps = pd.date_range('2025-01-01', periods=8760, freq='h') -flow_system = fx.FlowSystem(timesteps=timesteps) - -# Add components -boiler = fx.Boiler("Boiler", eta=0.9, Q_th=fx.Flow(...), Q_fu=fx.Flow(...)) -flow_system.add_component(boiler) +# 1. Define your system structure +flow_system = fx.FlowSystem(timesteps) +flow_system.add_elements(buses, components, effects) -# Optimize -calculation = fx.FullCalculation("MyModel", flow_system=flow_system) +# 2. Create and solve +calculation = fx.FullCalculation("MyModel", flow_system) calculation.solve() -# Analyze results -calculation.results.plot() +# 3. Analyze results +calculation.results.solution ``` -**Next steps:** +**Get started with real examples:** - 📚 [Full Documentation](https://flixopt.github.io/flixopt/latest/) -- 💡 [Examples Gallery](https://flixopt.github.io/flixopt/latest/examples/) +- 💡 [Examples Gallery](https://flixopt.github.io/flixopt/latest/examples/) - Complete working examples from simple to complex - 🔧 [API Reference](https://flixopt.github.io/flixopt/latest/api-reference/) --- From 95627222de7f9b7d008010da96dcd5b7724fd0e2 Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 23:47:26 +0200 Subject: [PATCH 14/20] Tighten README.md --- README.md | 193 +++++++++++++----------------------------------------- 1 file changed, 46 insertions(+), 147 deletions(-) diff --git a/README.md b/README.md index 948c47dcf..e7e55eaa3 100644 --- a/README.md +++ b/README.md @@ -58,123 +58,45 @@ calculation.results.solution ## 🌟 Why FlixOpt? -### For Everyone: Start Simple, Scale Complex +### Progressive Enhancement - Your Model Grows With You -**Beginners** get working models in minutes with high-level components: +**Start simple:** ```python -boiler = fx.Boiler("Boiler", eta=0.9, ...) # Just works -``` - -**Experts** can drill down to fine-grained control when needed: -```python -boiler.submodel.add_constraints(custom_constraint, name="my_constraint") -``` - -**No framework switching.** Your initial model structure stays intact as you add complexity. - -### Grow Your Model Incrementally - -Start simple, then progressively enhance without refactoring: - -```python -# Step 1: Simple single-period model -flow_system = fx.FlowSystem(timesteps=timesteps) +# Basic single-period model +flow_system = fx.FlowSystem(timesteps) boiler = fx.Boiler("Boiler", eta=0.9, ...) -flow_system.add_component(boiler) - -# Step 2: Add investment decisions -boiler.Q_th.invest_parameters = fx.InvestParameters(...) - -# Step 3: Multi-period planning? Just add periods! -periods = pd.Index([2025, 2030, 2035]) -flow_system_mp = fx.FlowSystem(timesteps=timesteps, periods=periods) -flow_system_mp.add_component(boiler) # Same component! - -# Step 4: Model uncertainty? Add scenarios! -scenarios = pd.Index(['high_demand', 'base_case', 'low_demand']) -flow_system_stoch = fx.FlowSystem( - timesteps=timesteps, - periods=periods, - scenarios=scenarios, - weights=[0.3, 0.5, 0.2] -) -``` - -**The key:** Your component definitions stay the same. Periods and scenarios are dimensions of the FlowSystem, not structural changes to your model. - -### Multi-Criteria Optimization - -Model multiple metrics simultaneously - costs, emissions, resource use, any custom metric: - -```python -# Start simple -costs = fx.Effect('costs', '€', 'Total costs', is_objective=True) -co2 = fx.Effect('CO2', 'kg', 'Emissions') - -# Add sophisticated relationships later -costs = fx.Effect('costs', '€', 'Total costs', is_objective=True, - share_from_temporal={'CO2': 180}, # Carbon pricing: 180 €/tCO2 - share_from_periodic={'land': 100}) # Land cost: 100 €/m² -co2 = fx.Effect('CO2', 'kg', 'Emissions', - maximum_periodic=50000) # Emission constraint -``` - -This enables to model and evaluate cost structures in a system directly from the optimization solution (Costs from Investments, Costs from Operation, Revenues, Funding, Net Costs) - -### Performance at Any Scale - -Choose the calculation mode that fits your problem - **without changing your model definition:** - -- **Full** - Maximum accuracy for detailed models (hours to days) -- **Segmented** - Rolling horizon for long time series (months to years) -- **Aggregated** - Typical periods using [TSAM](https://github.com/FZJ-IEK3-VSA/tsam) for massive models (decades) - -```python -# Same model, different calculation modes -fx.FullCalculation("MyModel", flow_system) -fx.SegmentedCalculation("MyModel", flow_system, segment_length=168) -fx.AggregatedCalculation("MyModel", flow_system, n_clusters=12) ``` -### Built for Reproducibility - -Every result file is **self-contained** with complete model information: - -- Full NetCDF/JSON serialization with round-trip fidelity -- Load results months later and know exactly what you optimized -- Original FlowSystem included - no manual reconstruction needed -- Export to NetCDF, share with colleagues, archive for compliance +**Add complexity incrementally:** +- **Investment decisions** → Add `InvestParameters` to components +- **Multi-period planning** → Add `periods` dimension to FlowSystem +- **Uncertainty modeling** → Add `scenarios` dimension with probabilities +- **Custom constraints** → Extend with native linopy syntax -```python -# Save -calculation.results.to_file('my_results.nc') +**No refactoring required.** Your component definitions stay the same - periods, scenarios, and features are added as dimensions and parameters. -# Load later - everything is there -results = fx.results.CalculationResults.from_file('my_results.nc') -original_system = results.flow_system # Automatically restored! -``` +→ [Learn more about multi-period and stochastic modeling](https://flixopt.github.io/flixopt/latest/user-guide/mathematical-notation/dimensions/) -### Flexible Data Manipulation +### For Everyone -Transform your FlowSystem on the fly using familiar xarray-style operations: +- **Beginners:** High-level components that "just work" +- **Experts:** Full access to modify models with linopy +- **Researchers:** Quick prototyping with customization options +- **Engineers:** Reliable, tested components without black boxes +- **Students:** Clear, Pythonic interfaces for learning optimization -```python -# Subset to specific time ranges -system_q2 = flow_system.sel(time=slice("2025-04", "2025-06")) +### Key Features -# Extract specific scenarios for comparison -system_high = flow_system.sel(scenario="high_demand") +**Multi-criteria optimization:** Model costs, emissions, resource use - any custom metric. Optimize single objectives or use weighted combinations and ε-constraints. +→ [Effects documentation](https://flixopt.github.io/flixopt/latest/user-guide/mathematical-notation/effects-penalty-objective/) -# Resample for multi-stage optimization -system_daily = flow_system.resample(time="D") -``` +**Performance at any scale:** Choose calculation modes without changing your model - Full, Segmented, or Aggregated (using [TSAM](https://github.com/FZJ-IEK3-VSA/tsam)). +→ [Calculation modes](https://flixopt.github.io/flixopt/latest/api-reference/calculation/) -### User-Friendly Design +**Built for reproducibility:** Self-contained NetCDF result files with complete model information. Load results months later - everything is preserved. +→ [Results documentation](https://flixopt.github.io/flixopt/latest/api-reference/results/) -- **Object-oriented** and Pythonic - feels natural if you know Python -- **Comprehensively documented** - every parameter explained -- **Readable code** - we prioritize clarity in both framework and user code -- **Open to feedback** - unclear naming? We welcome your suggestions! +**Flexible data operations:** Transform FlowSystems with xarray-style operations (`sel()`, `resample()`) for multi-stage optimization. --- @@ -185,30 +107,18 @@ system_daily = flow_system.resample(time="D") FlixOpt models **any system involving flows and conversions:** - **Energy systems:** District heating/cooling, microgrids, renewable portfolios, sector coupling -- **Material flows:** Supply chains, production lines, chemical processes, recycling networks -- **Integrated systems:** Water-energy nexus, industrial symbiosis, smart cities - -While energy systems are our primary focus, the same mathematical foundation applies universally. This enables coupling different system types within integrated models. +- **Material flows:** Supply chains, production lines, chemical processes +- **Integrated systems:** Water-energy nexus, industrial symbiosis -### The Sweet Spot - -We bridge the gap between high-level strategic models (like [FINE](https://github.com/FZJ-IEK3-VSA/FINE)) for long-term planning and low-level tools for short-term operation and dispatch. This approach is similar to the mature [PyPSA](https://docs.pypsa.org/latest/) project. - -**FlixOpt is ideal for:** - -- **Researchers** who need quick prototyping but may require deep customization later -- **Engineers** who want reliable, tested components without black-box abstractions -- **Students** learning optimization who benefit from clear, Pythonic interfaces -- **Practitioners** who need to move from model to production-ready results -- **Domain experts** from any field where things flow, transform, and need optimizing +While energy systems are our primary focus, the same foundation applies universally. This enables coupling different system types within integrated models. ### Modern Foundations -Built on [linopy](https://github.com/PyPSA/linopy/) and [xarray](https://github.com/pydata/xarray), FlixOpt delivers both **performance** and **transparency**: +Built on [linopy](https://github.com/PyPSA/linopy/) and [xarray](https://github.com/pydata/xarray), FlixOpt delivers **performance** and **transparency**. Full access to variables, constraints, and model structure. Extend anything with native linopy syntax. -- **Inspect everything** - full access to variables, constraints, and model structure -- **Extend anything** - add custom constraints using native linopy syntax -- **Trust your model** - you control exactly what gets optimized +### Our Position + +We bridge the gap between high-level strategic models (like [FINE](https://github.com/FZJ-IEK3-VSA/FINE)) and low-level dispatch tools - similar to [PyPSA](https://docs.pypsa.org/latest/). FlixOpt is the sweet spot for detailed operational planning and long-term investment analysis in the **same framework**. ### Academic Roots @@ -218,28 +128,19 @@ Originally developed at [TU Dresden](https://github.com/gewv-tu-dresden) for the ## 🛣️ Roadmap -### Our Vision - -**FlixOpt aims to be the most accessible, flexible, and universal Python framework for energy and material flow optimization.** +**FlixOpt aims to be the most accessible, flexible, and universal Python framework for energy and material flow optimization.** We believe optimization modeling should be approachable for beginners yet powerful for experts, minimizing context switching between different planning horizons. -We believe optimization modeling should be **approachable for beginners** yet **powerful for experts**. We also believe in **minimizing context switching** - use the same tool for short-term operational planning and long-term investment analysis. +**Current focus:** +- Enhanced component library (sector coupling, hydrogen, thermal networks) +- Examples showcasing multi-period and stochastic modeling +- Advanced result analysis and visualization -### Short-term Goals +**Future vision:** +- Modeling to generate alternatives (MGA) for robust decision-making +- Advanced stochastic optimization (two-stage, CVaR) +- Community ecosystem of user-contributed components -- **Enhanced component library:** More pre-built, domain-specific components (sector coupling, hydrogen systems, thermal networks, demand-side management) -- **Advanced result analysis:** Automated reporting and enhanced visualization options -- **Examples of stochastic and multi-period modeling:** The new features currently lack comprehensive showcases -- **Interactive tutorials:** Browser-based, reactive tutorials for learning FlixOpt without local installation - -### Medium-term Vision - -- **Modeling to generate alternatives (MGA):** Built-in support for exploring near-optimal solution spaces to produce more robust, diverse solutions under uncertainty. See [PyPSA](https://docs.pypsa.org/latest/user-guide/optimization/modelling-to-generate-alternatives/) and [Calliope](https://calliope.readthedocs.io/en/latest/examples/modes/) for reference implementations -- **Advanced stochastic optimization:** Build sophisticated new `Calculation` classes to perform different stochastic optimization approaches, like PyPSA's [two-stage stochastic programming and risk preferences with Conditional Value-at-Risk (CVaR)](https://docs.pypsa.org/latest/user-guide/optimization/stochastic/) - -### Long-term Vision - -- **Showcase universal applicability:** FlixOpt already handles any flow-based system (supply chains, water networks, production planning, chemical processes) - we need more examples and domain-specific component libraries to demonstrate this -- **Community ecosystem:** Rich library of user-contributed components, examples, and domain-specific extensions +→ [Full roadmap and vision](https://github.com/flixOpt/flixopt#roadmap) --- @@ -263,11 +164,9 @@ pip install "flixopt[full]" ### Solver Support -FlixOpt supports many solvers via linopy: -- **HiGHS** (included, open-source, recommended for most users) -- **Gurobi** (commercial, fast for large problems) -- **CPLEX** (commercial) -- **CBC, GLPK** (open-source alternatives) +FlixOpt supports many solvers via linopy: **HiGHS** (included), **Gurobi**, **CPLEX**, **CBC**, **GLPK**, and more. + +→ [Installation guide](https://flixopt.github.io/flixopt/latest/getting-started/) --- @@ -275,7 +174,7 @@ FlixOpt supports many solvers via linopy: FlixOpt thrives on community input. Whether you're fixing bugs, adding components, improving docs, or sharing use cases - **we welcome your contributions.** -See our [contribution guide](https://flixopt.github.io/flixopt/latest/contribute/) to get started. +→ [Contribution guide](https://flixopt.github.io/flixopt/latest/contribute/) --- From 0ddb1562ede2e8ff20a616412cd9fbecea4a86be Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 23:49:25 +0200 Subject: [PATCH 15/20] Add Roaadmap to docs --- README.md | 2 +- docs/roadmap.md | 216 ++++++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 218 insertions(+), 1 deletion(-) create mode 100644 docs/roadmap.md diff --git a/README.md b/README.md index e7e55eaa3..0a90dcb33 100644 --- a/README.md +++ b/README.md @@ -140,7 +140,7 @@ Originally developed at [TU Dresden](https://github.com/gewv-tu-dresden) for the - Advanced stochastic optimization (two-stage, CVaR) - Community ecosystem of user-contributed components -→ [Full roadmap and vision](https://github.com/flixOpt/flixopt#roadmap) +→ [Full roadmap and vision](https://flixopt.github.io/flixopt/latest/roadmap/) --- diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 000000000..437640330 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,216 @@ +# Roadmap and Vision + +## 🎯 Our Vision + +**FlixOpt aims to be the most accessible, flexible, and universal Python framework for energy and material flow optimization.** + +We believe that optimization modeling should be **approachable for beginners** yet **powerful for experts**. We also believe in **minimizing context switching** - use the same tool for short-term operational planning and long-term investment analysis. + +### Core Principles + +1. **Progressive Enhancement**: Start with simple models and add complexity incrementally without refactoring +2. **Universal Applicability**: One framework for energy, materials, logistics, and integrated systems +3. **Transparency**: Full access to model structure - no black boxes +4. **Reproducibility**: Self-contained results with complete model information +5. **Modern Foundations**: Built on state-of-the-art tools (linopy, xarray) + +--- + +## 🚀 Short-term Goals + +### Enhanced Component Library + +**Goal**: Expand pre-built, domain-specific components to cover more real-world use cases. + +**Planned Components**: +- **Sector coupling**: Power-to-gas, power-to-heat, vehicle-to-grid +- **Hydrogen systems**: Electrolyzers, fuel cells, hydrogen storage +- **Thermal networks**: District heating/cooling with temperature levels +- **Demand-side management**: Flexible loads, demand response + +**Status**: 🟡 In planning - contributions welcome! + +### Examples of Stochastic and Multi-Period Modeling + +**Goal**: Comprehensive showcase examples demonstrating the new multi-dimensional modeling capabilities introduced in v3.0. + +**Planned Examples**: +- Multi-period investment planning with technology evolution +- Stochastic optimization under demand uncertainty +- Combined multi-period + stochastic scenarios +- Two-stage decision making (investment vs. operation) + +**Status**: 🟡 In development - basic examples exist, need comprehensive showcase + +### Advanced Result Analysis + +**Goal**: Make it easier to understand and communicate optimization results. + +**Planned Features**: +- Automated report generation (HTML, PDF) +- Enhanced built-in visualizations +- Cost breakdown analysis tools +- Sensitivity analysis helpers +- Interactive dashboards + +**Status**: 🟡 In planning + +### Interactive Tutorials + +**Goal**: Browser-based, reactive tutorials for learning FlixOpt without local installation. + +**Planned Features**: +- JupyterLite-based tutorials +- Step-by-step interactive examples +- Instant feedback without setup +- Progressive learning path + +**Status**: 🔴 Not started - waiting for infrastructure decisions + +--- + +## 🔮 Medium-term Vision + +### Modeling to Generate Alternatives (MGA) + +**Goal**: Built-in support for exploring near-optimal solution spaces to produce more robust, diverse solutions under uncertainty. + +**Why MGA?** +Traditional optimization finds a single optimal solution. MGA finds multiple near-optimal alternatives that perform similarly but use different technologies or strategies. This is crucial for: +- Robust decision-making under uncertainty +- Exploring diverse technology pathways +- Stakeholder engagement with multiple options +- Avoiding over-optimization to fragile solutions + +**Reference Implementations**: +- [PyPSA MGA](https://docs.pypsa.org/latest/user-guide/optimization/modelling-to-generate-alternatives/) +- [Calliope Modes](https://calliope.readthedocs.io/en/latest/examples/modes/) + +**Status**: 🟡 Research phase - exploring implementation approaches + +### Advanced Stochastic Optimization + +**Goal**: Sophisticated `Calculation` classes for different stochastic optimization paradigms. + +**Planned Approaches**: +- **Two-stage stochastic programming**: Investment decisions (here-and-now) vs. operational decisions (wait-and-see) +- **Risk preferences with CVaR**: Optimize for risk-averse or risk-neutral strategies +- **Rolling horizon with forecast updates**: Progressive uncertainty resolution +- **Chance constraints**: Probabilistic constraints with confidence levels + +**Reference**: [PyPSA Stochastic Optimization](https://docs.pypsa.org/latest/user-guide/optimization/stochastic/) + +**Status**: 🟡 Design phase - basic scenario support exists in v3.0 + +### Standardized Cost Calculations + +**Goal**: Align with industry standards for financial analysis. + +**Planned Features**: +- VDI 2067 compliance for CAPEX/OPEX calculations +- Built-in annuity calculations +- NPV and IRR analysis +- Subsidy and incentive modeling + +**Status**: 🔴 Not started + +--- + +## 🌟 Long-term Vision + +### Showcase Universal Applicability + +**Goal**: Demonstrate that FlixOpt handles any flow-based system, not just energy. + +**Challenges**: +FlixOpt already has the technical capability to model supply chains, water networks, production planning, and chemical processes. The barrier is examples and domain-specific component libraries. + +**Needed**: +- **Example gallery**: Working models from different domains +- **Domain-specific components**: Pre-built abstractions for common patterns in each field +- **Case studies**: Real-world applications with documentation +- **Domain tutorials**: Onboarding guides for non-energy users + +**Status**: 🔴 Limited examples - mostly energy systems + +### Production-Ready Features + +**Goal**: First-class support for deploying FlixOpt models in production environments. + +**Planned Features**: +- **API interfaces**: REST/GraphQL for model-as-a-service +- **Distributed solving**: Large-scale problems across compute clusters +- **Real-time updates**: Streaming data integration for rolling optimization +- **Monitoring and logging**: Production-grade observability +- **Containerization**: Docker images and Kubernetes deployments +- **Versioning**: Model versioning and experiment tracking + +**Status**: 🔴 Research needed - current focus is research/engineering use + +### Community Ecosystem + +**Goal**: Rich library of user-contributed components, examples, and extensions. + +**Vision**: +- **Component registry**: Searchable catalog of community components +- **Plugin system**: Easy-to-share extensions +- **Template library**: Starting points for common use cases +- **Integration packages**: Connectors to data sources, GIS, databases +- **Best practices**: Community-driven patterns and anti-patterns + +**Status**: 🟡 Foundation exists - need community growth + +--- + +## 📊 Feature Status Legend + +- 🟢 **Available**: Feature is implemented and released +- 🟡 **In Progress**: Active development or planning +- 🔴 **Planned**: On roadmap but not yet started +- ⚪ **Under Consideration**: Being evaluated for inclusion + +--- + +## 🤝 How You Can Help + +We welcome contributions in all areas: + +- **Code**: Implement planned features, fix bugs, add tests +- **Documentation**: Write tutorials, improve API docs, create examples +- **Components**: Contribute domain-specific components +- **Use Cases**: Share your FlixOpt applications as case studies +- **Feedback**: Report issues, suggest features, discuss design + +See our [contribution guide](contribute.md) to get started. + +--- + +## 📅 Release Philosophy + +FlixOpt follows [semantic versioning](https://semver.org/): + +- **Major versions** (v3.0, v4.0): Breaking changes, major new features +- **Minor versions** (v3.1, v3.2): New features, backward compatible +- **Patch versions** (v3.0.1, v3.0.2): Bug fixes, no new features + +We aim for: +- Regular patch releases for bug fixes +- Minor releases every 2-3 months with new features +- Major releases when significant architectural changes are needed + +--- + +## 💬 Roadmap Discussions + +The roadmap is not set in stone. We prioritize based on: +- User feedback and requests +- Core team capacity +- Strategic importance for adoption +- Community contributions + +**Join the conversation:** +- [GitHub Discussions](https://github.com/flixOpt/flixopt/discussions) +- [GitHub Issues](https://github.com/flixOpt/flixopt/issues) for specific feature requests +- Pull requests for direct contributions + +Your input shapes FlixOpt's future! diff --git a/mkdocs.yml b/mkdocs.yml index 89bca4793..41db2f659 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -34,6 +34,7 @@ nav: - Duration Tracking: user-guide/mathematical-notation/modeling-patterns/duration-tracking.md - State Transitions: user-guide/mathematical-notation/modeling-patterns/state-transitions.md - Examples: examples/ + - Roadmap: roadmap.md - Contribute: contribute.md - API Reference: api-reference/ - Release Notes: changelog/ From 292646a1ae602b92713e3c9763334a40b369d45d Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 23:54:14 +0200 Subject: [PATCH 16/20] Make roadmap more compact --- docs/roadmap.md | 210 +++++------------------------------------------- 1 file changed, 22 insertions(+), 188 deletions(-) diff --git a/docs/roadmap.md b/docs/roadmap.md index 437640330..2fd018cb5 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -4,182 +4,37 @@ **FlixOpt aims to be the most accessible, flexible, and universal Python framework for energy and material flow optimization.** -We believe that optimization modeling should be **approachable for beginners** yet **powerful for experts**. We also believe in **minimizing context switching** - use the same tool for short-term operational planning and long-term investment analysis. - -### Core Principles - -1. **Progressive Enhancement**: Start with simple models and add complexity incrementally without refactoring -2. **Universal Applicability**: One framework for energy, materials, logistics, and integrated systems -3. **Transparency**: Full access to model structure - no black boxes -4. **Reproducibility**: Self-contained results with complete model information -5. **Modern Foundations**: Built on state-of-the-art tools (linopy, xarray) - ---- - -## 🚀 Short-term Goals - -### Enhanced Component Library - -**Goal**: Expand pre-built, domain-specific components to cover more real-world use cases. - -**Planned Components**: -- **Sector coupling**: Power-to-gas, power-to-heat, vehicle-to-grid -- **Hydrogen systems**: Electrolyzers, fuel cells, hydrogen storage -- **Thermal networks**: District heating/cooling with temperature levels -- **Demand-side management**: Flexible loads, demand response - -**Status**: 🟡 In planning - contributions welcome! - -### Examples of Stochastic and Multi-Period Modeling - -**Goal**: Comprehensive showcase examples demonstrating the new multi-dimensional modeling capabilities introduced in v3.0. - -**Planned Examples**: -- Multi-period investment planning with technology evolution -- Stochastic optimization under demand uncertainty -- Combined multi-period + stochastic scenarios -- Two-stage decision making (investment vs. operation) - -**Status**: 🟡 In development - basic examples exist, need comprehensive showcase - -### Advanced Result Analysis - -**Goal**: Make it easier to understand and communicate optimization results. - -**Planned Features**: -- Automated report generation (HTML, PDF) -- Enhanced built-in visualizations -- Cost breakdown analysis tools -- Sensitivity analysis helpers -- Interactive dashboards - -**Status**: 🟡 In planning - -### Interactive Tutorials - -**Goal**: Browser-based, reactive tutorials for learning FlixOpt without local installation. - -**Planned Features**: -- JupyterLite-based tutorials -- Step-by-step interactive examples -- Instant feedback without setup -- Progressive learning path - -**Status**: 🔴 Not started - waiting for infrastructure decisions - ---- - -## 🔮 Medium-term Vision - -### Modeling to Generate Alternatives (MGA) - -**Goal**: Built-in support for exploring near-optimal solution spaces to produce more robust, diverse solutions under uncertainty. - -**Why MGA?** -Traditional optimization finds a single optimal solution. MGA finds multiple near-optimal alternatives that perform similarly but use different technologies or strategies. This is crucial for: -- Robust decision-making under uncertainty -- Exploring diverse technology pathways -- Stakeholder engagement with multiple options -- Avoiding over-optimization to fragile solutions - -**Reference Implementations**: -- [PyPSA MGA](https://docs.pypsa.org/latest/user-guide/optimization/modelling-to-generate-alternatives/) -- [Calliope Modes](https://calliope.readthedocs.io/en/latest/examples/modes/) - -**Status**: 🟡 Research phase - exploring implementation approaches - -### Advanced Stochastic Optimization - -**Goal**: Sophisticated `Calculation` classes for different stochastic optimization paradigms. - -**Planned Approaches**: -- **Two-stage stochastic programming**: Investment decisions (here-and-now) vs. operational decisions (wait-and-see) -- **Risk preferences with CVaR**: Optimize for risk-averse or risk-neutral strategies -- **Rolling horizon with forecast updates**: Progressive uncertainty resolution -- **Chance constraints**: Probabilistic constraints with confidence levels - -**Reference**: [PyPSA Stochastic Optimization](https://docs.pypsa.org/latest/user-guide/optimization/stochastic/) - -**Status**: 🟡 Design phase - basic scenario support exists in v3.0 - -### Standardized Cost Calculations - -**Goal**: Align with industry standards for financial analysis. - -**Planned Features**: -- VDI 2067 compliance for CAPEX/OPEX calculations -- Built-in annuity calculations -- NPV and IRR analysis -- Subsidy and incentive modeling - -**Status**: 🔴 Not started +We believe optimization modeling should be **approachable for beginners** yet **powerful for experts**, minimizing context switching between **short-term dispatch** and **long-term investment** planning. --- -## 🌟 Long-term Vision - -### Showcase Universal Applicability - -**Goal**: Demonstrate that FlixOpt handles any flow-based system, not just energy. - -**Challenges**: -FlixOpt already has the technical capability to model supply chains, water networks, production planning, and chemical processes. The barrier is examples and domain-specific component libraries. - -**Needed**: -- **Example gallery**: Working models from different domains -- **Domain-specific components**: Pre-built abstractions for common patterns in each field -- **Case studies**: Real-world applications with documentation -- **Domain tutorials**: Onboarding guides for non-energy users - -**Status**: 🔴 Limited examples - mostly energy systems - -### Production-Ready Features +## 🚀 Short-term (Next 6 months) -**Goal**: First-class support for deploying FlixOpt models in production environments. +- **Enhanced component library** - Sector coupling, hydrogen systems, thermal networks, demand-side management +- **Stochastic/multi-period examples** - Showcase v3.0 capabilities with comprehensive examples +- **Advanced result analysis** - Automated reporting, enhanced visualizations, cost breakdowns ([#398](https://github.com/flixOpt/flixopt/issues/398)) -**Planned Features**: -- **API interfaces**: REST/GraphQL for model-as-a-service -- **Distributed solving**: Large-scale problems across compute clusters -- **Real-time updates**: Streaming data integration for rolling optimization -- **Monitoring and logging**: Production-grade observability -- **Containerization**: Docker images and Kubernetes deployments -- **Versioning**: Model versioning and experiment tracking +## 🔮 Medium-term (6-18 months) -**Status**: 🔴 Research needed - current focus is research/engineering use +- **Modeling to Generate Alternatives (MGA)** - Explore near-optimal solutions for robust decision-making ([#338](https://github.com/flixOpt/flixopt/issues/338), [PyPSA](https://docs.pypsa.org/latest/user-guide/optimization/modelling-to-generate-alternatives/), [Calliope](https://calliope.readthedocs.io/en/latest/examples/modes/)) +- **Advanced stochastic optimization** - Two-stage programming, CVaR, rolling horizon ([PyPSA reference](https://docs.pypsa.org/latest/user-guide/optimization/stochastic/)) +- **Standardized cost calculations** - VDI 2067 compliance, NPV/IRR analysis +- **Interactive tutorials** - Browser-based learning without installation ([#304](https://github.com/flixOpt/flixopt/issues/304)) -### Community Ecosystem +## 🌟 Long-term (18+ months) -**Goal**: Rich library of user-contributed components, examples, and extensions. - -**Vision**: -- **Component registry**: Searchable catalog of community components -- **Plugin system**: Easy-to-share extensions -- **Template library**: Starting points for common use cases -- **Integration packages**: Connectors to data sources, GIS, databases -- **Best practices**: Community-driven patterns and anti-patterns - -**Status**: 🟡 Foundation exists - need community growth +- **Universal applicability showcase** - Examples and components for supply chains, water networks, production planning +- **Production-ready features** - API interfaces, distributed solving, real-time optimization ([#402](https://github.com/flixOpt/flixopt/issues/402)) +- **Community ecosystem** - Component registry, plugin system, template library --- -## 📊 Feature Status Legend - -- 🟢 **Available**: Feature is implemented and released -- 🟡 **In Progress**: Active development or planning -- 🔴 **Planned**: On roadmap but not yet started -- ⚪ **Under Consideration**: Being evaluated for inclusion - ---- - -## 🤝 How You Can Help - -We welcome contributions in all areas: +## 🤝 How to Help -- **Code**: Implement planned features, fix bugs, add tests -- **Documentation**: Write tutorials, improve API docs, create examples +- **Code**: Implement features, fix bugs, add tests +- **Docs**: Write tutorials, improve examples, create case studies - **Components**: Contribute domain-specific components -- **Use Cases**: Share your FlixOpt applications as case studies -- **Feedback**: Report issues, suggest features, discuss design +- **Feedback**: [Report issues](https://github.com/flixOpt/flixopt/issues), [join discussions](https://github.com/flixOpt/flixopt/discussions) See our [contribution guide](contribute.md) to get started. @@ -188,29 +43,8 @@ See our [contribution guide](contribute.md) to get started. ## 📅 Release Philosophy FlixOpt follows [semantic versioning](https://semver.org/): +- **Major** (v3→v4): Breaking changes, major features +- **Minor** (v3.0→v3.1): New features, backward compatible +- **Patch** (v3.0.0→v3.0.1): Bug fixes only -- **Major versions** (v3.0, v4.0): Breaking changes, major new features -- **Minor versions** (v3.1, v3.2): New features, backward compatible -- **Patch versions** (v3.0.1, v3.0.2): Bug fixes, no new features - -We aim for: -- Regular patch releases for bug fixes -- Minor releases every 2-3 months with new features -- Major releases when significant architectural changes are needed - ---- - -## 💬 Roadmap Discussions - -The roadmap is not set in stone. We prioritize based on: -- User feedback and requests -- Core team capacity -- Strategic importance for adoption -- Community contributions - -**Join the conversation:** -- [GitHub Discussions](https://github.com/flixOpt/flixopt/discussions) -- [GitHub Issues](https://github.com/flixOpt/flixopt/issues) for specific feature requests -- Pull requests for direct contributions - -Your input shapes FlixOpt's future! +Target: Patch releases as needed, minor releases every 2-3 months. From 265492554004790dafefde1a9cc90d5345d7260e Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 23:55:33 +0200 Subject: [PATCH 17/20] Updaet roadmap.md --- docs/roadmap.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/roadmap.md b/docs/roadmap.md index 2fd018cb5..5fbbad86c 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -10,16 +10,15 @@ We believe optimization modeling should be **approachable for beginners** yet ** ## 🚀 Short-term (Next 6 months) -- **Enhanced component library** - Sector coupling, hydrogen systems, thermal networks, demand-side management - **Stochastic/multi-period examples** - Showcase v3.0 capabilities with comprehensive examples - **Advanced result analysis** - Automated reporting, enhanced visualizations, cost breakdowns ([#398](https://github.com/flixOpt/flixopt/issues/398)) +- **Interactive tutorials** - Browser-based learning without installation ([#304](https://github.com/flixOpt/flixopt/issues/304)) -## 🔮 Medium-term (6-18 months) +## 🔮 Medium-term (6-12 months) - **Modeling to Generate Alternatives (MGA)** - Explore near-optimal solutions for robust decision-making ([#338](https://github.com/flixOpt/flixopt/issues/338), [PyPSA](https://docs.pypsa.org/latest/user-guide/optimization/modelling-to-generate-alternatives/), [Calliope](https://calliope.readthedocs.io/en/latest/examples/modes/)) - **Advanced stochastic optimization** - Two-stage programming, CVaR, rolling horizon ([PyPSA reference](https://docs.pypsa.org/latest/user-guide/optimization/stochastic/)) -- **Standardized cost calculations** - VDI 2067 compliance, NPV/IRR analysis -- **Interactive tutorials** - Browser-based learning without installation ([#304](https://github.com/flixOpt/flixopt/issues/304)) +- **Enhanced component library** - Sector coupling, hydrogen systems, thermal networks, demand-side management ## 🌟 Long-term (18+ months) From 1adeae845915cd2ee76dbe0efd537dcbf8a59496 Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Tue, 14 Oct 2025 23:58:26 +0200 Subject: [PATCH 18/20] Update roadmap.md --- docs/roadmap.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/roadmap.md b/docs/roadmap.md index 5fbbad86c..f18aa44e7 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -10,21 +10,20 @@ We believe optimization modeling should be **approachable for beginners** yet ** ## 🚀 Short-term (Next 6 months) -- **Stochastic/multi-period examples** - Showcase v3.0 capabilities with comprehensive examples -- **Advanced result analysis** - Automated reporting, enhanced visualizations, cost breakdowns ([#398](https://github.com/flixOpt/flixopt/issues/398)) -- **Interactive tutorials** - Browser-based learning without installation ([#304](https://github.com/flixOpt/flixopt/issues/304)) +- **Examples of stochastic and multi-period modeling** - The new v3.0 features currently lack comprehensive showcases +- **Advanced result analysis** - Automated reporting and enhanced visualization options +- **Interactive tutorials** - Browser-based, reactive tutorials for learning FlixOpt without local installation using [Marimo](https://marimo.io/) ## 🔮 Medium-term (6-12 months) -- **Modeling to Generate Alternatives (MGA)** - Explore near-optimal solutions for robust decision-making ([#338](https://github.com/flixOpt/flixopt/issues/338), [PyPSA](https://docs.pypsa.org/latest/user-guide/optimization/modelling-to-generate-alternatives/), [Calliope](https://calliope.readthedocs.io/en/latest/examples/modes/)) -- **Advanced stochastic optimization** - Two-stage programming, CVaR, rolling horizon ([PyPSA reference](https://docs.pypsa.org/latest/user-guide/optimization/stochastic/)) -- **Enhanced component library** - Sector coupling, hydrogen systems, thermal networks, demand-side management +- **Modeling to Generate Alternatives (MGA)** - Built-in support for exploring near-optimal solution spaces to produce more robust, diverse solutions under uncertainty. See [PyPSA](https://docs.pypsa.org/latest/user-guide/optimization/modelling-to-generate-alternatives/) and [Calliope](https://calliope.readthedocs.io/en/latest/examples/modes/) for reference implementations +- **Advanced stochastic optimization** - Build sophisticated new `Calculation` classes to perform different stochastic optimization approaches, like PyPSA's [two-stage stochastic programming and risk preferences with Conditional Value-at-Risk (CVaR)](https://docs.pypsa.org/latest/user-guide/optimization/stochastic/) +- **Enhanced component library** - More pre-built, domain-specific components (sector coupling, hydrogen systems, thermal networks, demand-side management) -## 🌟 Long-term (18+ months) +## 🌟 Long-term (12+ months) -- **Universal applicability showcase** - Examples and components for supply chains, water networks, production planning -- **Production-ready features** - API interfaces, distributed solving, real-time optimization ([#402](https://github.com/flixOpt/flixopt/issues/402)) -- **Community ecosystem** - Component registry, plugin system, template library +- **Showcase universal applicability** - FlixOpt already handles any flow-based system (supply chains, water networks, production planning, chemical processes) - we need more examples and domain-specific component libraries to demonstrate this +- **Community ecosystem** - Rich library of user-contributed components, examples, and domain-specific extensions --- From 7c619b1219fbcc27b42b034104a01c13eaa27929 Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Wed, 15 Oct 2025 00:03:11 +0200 Subject: [PATCH 19/20] Update mkdocs.yml --- mkdocs.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 41db2f659..72ecbe549 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,11 +10,10 @@ repo_name: flixOpt/flixopt nav: - Home: index.md - - Getting Started: getting-started.md - User Guide: - user-guide/index.md - Migration to v3.0.0: user-guide/migration-guide-v3.md - - Recipes: user-guide/recipes/index.md + - Getting Started: getting-started.md - Mathematical Notation: - Overview: user-guide/mathematical-notation/index.md - Dimensions: user-guide/mathematical-notation/dimensions.md @@ -33,8 +32,9 @@ nav: - Bounds and States: user-guide/mathematical-notation/modeling-patterns/bounds-and-states.md - Duration Tracking: user-guide/mathematical-notation/modeling-patterns/duration-tracking.md - State Transitions: user-guide/mathematical-notation/modeling-patterns/state-transitions.md + - Recipes: user-guide/recipes/index.md + - Roadmap: roadmap.md - Examples: examples/ - - Roadmap: roadmap.md - Contribute: contribute.md - API Reference: api-reference/ - Release Notes: changelog/ From efc2f896f94c5d8d7493345c39a2991d5cabf125 Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Wed, 15 Oct 2025 00:06:45 +0200 Subject: [PATCH 20/20] Update roadmap.md --- docs/roadmap.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/roadmap.md b/docs/roadmap.md index f18aa44e7..fbad1043c 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -10,6 +10,7 @@ We believe optimization modeling should be **approachable for beginners** yet ** ## 🚀 Short-term (Next 6 months) +- **Recipe collection** - Community-driven library of common modeling patterns, data manipulation techniques, and optimization strategies - **Examples of stochastic and multi-period modeling** - The new v3.0 features currently lack comprehensive showcases - **Advanced result analysis** - Automated reporting and enhanced visualization options - **Interactive tutorials** - Browser-based, reactive tutorials for learning FlixOpt without local installation using [Marimo](https://marimo.io/)