Feature/readme and vision

README.md

@@ -3,115 +3,178 @@
 [![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.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/)
+[![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)
 
 ---
 
-## 🎯 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 and flexible 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**. Too often, frameworks force you to choose between ease of use and flexibility. FlixOpt refuses this compromise.
-
-### 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)
+## 🚀 Quick Start
 
-**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
+```bash
+pip install flixopt
+```
 
-**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
-- **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
+That's it! FlixOpt comes with the [HiGHS](https://highs.dev/) solver included. You're ready to optimize.
 
-### Why FlixOpt Exists
+**The basic workflow:**
 
-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.
+```python
+import flixopt as fx
 
-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:
+# 1. Define your system structure
+flow_system = fx.FlowSystem(timesteps)
+flow_system.add_elements(buses, components, effects)
 
-- **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
+# 2. Create and solve
+calculation = fx.FullCalculation("MyModel", flow_system)
+calculation.solve()
 
-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.
+# 3. Analyze results
+calculation.results.solution
+```
 
-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).
+**Get started with real examples:**
+- 📚 [Full Documentation](https://flixopt.github.io/flixopt/latest/)
+- 💡 [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/)
 
 ---
 
-## 🌟 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.
+### Progressive Enhancement - Your Model Grows With You
 
+**Start simple:**
 ```python
-import flixopt as fx
-
-# Simple start
+# Basic single-period model
+flow_system = fx.FlowSystem(timesteps)
 boiler = fx.Boiler("Boiler", eta=0.9, ...)
-
-# Advanced control when needed - extend with native linopy
-boiler.model.add_constraints(custom_constraint, name="my_constraint")
 ```
 
-### 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:
+**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
-costs = fx.Effect('costs', '€', 'Total costs',
-                  share_from_temporal={'CO2': 180})  # 180 €/tCO2
-co2 = fx.Effect('CO2', 'kg', 'Emissions', maximum_periodic=50000)
-```
+**No refactoring required.** Your component definitions stay the same - periods, scenarios, and features are added as dimensions and parameters.
+
+→ [Learn more about multi-period and stochastic modeling](https://flixopt.github.io/flixopt/latest/user-guide/mathematical-notation/dimensions/)
+
+### For Everyone
+
+- **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
 
-### 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
+### Key Features
 
-### 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.
+**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/)
+
+**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/)
+
+**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/)
+
+**Flexible data operations:** Transform FlowSystems with xarray-style operations (`sel()`, `resample()`) for multi-stage optimization.
 
 ---
 
-## 🚀 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
+- **Integrated systems:** Water-energy nexus, industrial symbiosis
+
+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 **performance** and **transparency**. Full access to variables, constraints, and model structure. Extend anything with native linopy syntax.
+
+### 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
+
+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
+
+**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.
+
+**Current focus:**
+- Enhanced component library (sector coupling, hydrogen, thermal networks)
+- Examples showcasing multi-period and stochastic modeling
+- Advanced result analysis and visualization
+
+**Future vision:**
+- Modeling to generate alternatives (MGA) for robust decision-making
+- Advanced stochastic optimization (two-stage, CVaR)
+- Community ecosystem of user-contributed components
+
+→ [Full roadmap and vision](https://flixopt.github.io/flixopt/latest/roadmap/)
+
+---
+
+## 🛠️ 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), **Gurobi**, **CPLEX**, **CBC**, **GLPK**, and more.
+
+→ [Installation guide](https://flixopt.github.io/flixopt/latest/getting-started/)
 
 ---
 
 ## 🤝 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.
+→ [Contribution guide](https://flixopt.github.io/flixopt/latest/contribute/)
 
 ---
 

docs/roadmap.md

@@ -0,0 +1,49 @@
+# 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 optimization modeling should be **approachable for beginners** yet **powerful for experts**, minimizing context switching between **short-term dispatch** and **long-term investment** planning.
+
+---
+
+## 🚀 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/)
+
+## 🔮 Medium-term (6-12 months)
+
+- **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 (12+ months)
+
+- **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
+
+---
+
+## 🤝 How to Help
+
+- **Code**: Implement features, fix bugs, add tests
+- **Docs**: Write tutorials, improve examples, create case studies
+- **Components**: Contribute domain-specific components
+- **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.
+
+---
+
+## 📅 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
+
+Target: Patch releases as needed, minor releases every 2-3 months.

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,6 +32,8 @@ 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/
   - Contribute: contribute.md
   - API Reference: api-reference/

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",