Feature/readme and vision #405
Conversation
WalkthroughREADME and documentation reorganized and rewritten: new badges, reframed product positioning, expanded Quick Start, Roadmap, Modern/Academic context, installation/solvers, and examples. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (1 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(3 hunks)
🧰 Additional context used
🪛 LanguageTool
README.md
[grammar] ~21-~21: There might be a mistake here.
Context: ...ting and even more visualization options - **Examples of stochastic and Multi-Period ...
(QB_NEW_EN)
[grammar] ~22-~22: There might be a mistake here.
Context: ... feature is currently lacking showcases. - Interactive tutorials: Browser-based, ...
(QB_NEW_EN)
[grammar] ~25-~25: There might be a mistake here.
Context: ...ocal installation Medium-term vision: - **Modeling to generate alternatives (MGA)*...
(QB_NEW_EN)
[grammar] ~29-~29: There might be a mistake here.
Context: ...X/OPEX calculations Long-term vision: - Showcase universal applicability: Flix...
(QB_NEW_EN)
[grammar] ~31-~31: Use a hyphen to join words.
Context: ...trate this - Production ready: First class support for modeling in production...
(QB_NEW_EN_HYPHEN)
[grammar] ~93-~93: There might be a mistake here.
Context: ...pliance. ### Flexible Data Manipulation Transform your FlowSystem on the fly for...
(QB_NEW_EN)
README.md
Outdated
| - **Production ready**: First class support for modeling in production | ||
| - **Community ecosystem**: Rich library of user-contributed components, examples, and domain-specific extensions |
There was a problem hiding this comment.
Hyphenate the compound modifiers.
“Production ready” and “First class” should be “Production-ready” and “first-class” when used as compound adjectives.
🧰 Tools
🪛 LanguageTool
[grammar] ~31-~31: Use a hyphen to join words.
Context: ...trate this - Production ready: First class support for modeling in production...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In README.md around lines 31-32, update the compound modifiers for correct
hyphenation: change "**Production ready**: First class support for modeling in
production" to "**Production-ready**: first-class support for modeling in
production" (leave the rest of the line and the following community ecosystem
line unchanged).
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
README.md (2)
27-29: Fix typo and tighten phrasing in short‑term goal.
“THe” → “This”; clearer phrasing recommended.Apply this minimal fix:
- - **Examples of stochastic and Multi-Period Modeling**: THe new feature is currently lacking showcases. + - **Examples of stochastic and Multi-Period Modeling**: This feature currently lacks examples.
37-38: Hyphenate compound modifiers.
Use “Production‑ready” and “first‑class.”- - **Production ready**: First class support for modeling in production + - **Production-ready**: first-class support for modeling in production
🧹 Nitpick comments (2)
README.md (2)
73-86: Minor readability: avoid redefining variables in the example.
Redefining costs/co2 can confuse readers. Either keep a single definition and show augmentation, or add a short note “(redefine to add relationships)”.
97-98: Small wording/formatting tweak for clarity.
Wrap FlowSystem in code formatting; spell out formats.- 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 and JSON serialization 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.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(4 hunks)
🧰 Additional context used
🪛 LanguageTool
README.md
[grammar] ~27-~27: There might be a mistake here.
Context: ...ting and even more visualization options - **Examples of stochastic and Multi-Period ...
(QB_NEW_EN)
[grammar] ~28-~28: There might be a mistake here.
Context: ... feature is currently lacking showcases. - Interactive tutorials: Browser-based, ...
(QB_NEW_EN)
[grammar] ~31-~31: There might be a mistake here.
Context: ...ocal installation Medium-term vision: - **Modeling to generate alternatives (MGA)*...
(QB_NEW_EN)
[grammar] ~35-~35: There might be a mistake here.
Context: ...X/OPEX calculations Long-term vision: - Showcase universal applicability: Flix...
(QB_NEW_EN)
[grammar] ~37-~37: Use a hyphen to join words.
Context: ...trate this - Production ready: First class support for modeling in production...
(QB_NEW_EN_HYPHEN)
[grammar] ~99-~99: There might be a mistake here.
Context: ...pliance. ### Flexible Data Manipulation Transform your FlowSystem on the fly for...
(QB_NEW_EN)
🔇 Additional comments (3)
README.md (3)
6-6: Badges look good.
New badges/links render correctly and add useful metadata.Also applies to: 9-13
94-95: Nice clarity.
Good call-out that mode switching doesn’t require model changes.
108-111: Remove resampling fix suggestion. FlowSystem.resample(time="h") and .resample(time="D") accept unit-only frequencies and default to mean aggregation internally.Likely an incorrect or invalid review comment.
There was a problem hiding this comment.
Actionable comments posted: 5
♻️ Duplicate comments (1)
README.md (1)
33-35: Capitalize and clarify the Multi‑Period item.“THe” typo and awkward “lacking showcases”.
Apply:
-- **Examples of stochastic and Multi-Period Modeling**: THe new feature is currently lacking showcases. +- **Examples of stochastic and multi‑period modeling**: The new capability still lacks dedicated showcases.
🧹 Nitpick comments (1)
README.md (1)
103-104: “Round‑trip fidelity” claim — add reference/tests.Please link to docs or tests demonstrating full NetCDF/JSON round‑trip fidelity (model+results), or soften the claim.
I can propose a small pytest that serializes/deserializes a minimal FlowSystem and asserts structural and numerical equality.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
README.md(3 hunks)pyproject.toml(1 hunks)
🧰 Additional context used
🪛 LanguageTool
README.md
[grammar] ~21-~21: There might be a mistake here.
Context: ...t/flixopt/stargazers) --- ## 🎯 Vision **FlixOpt aims to be the most accessible, ...
(QB_NEW_EN)
[grammar] ~27-~27: Use a hyphen to join words.
Context: ... to be the tool of choice for both short term planning with high grade of detail,...
(QB_NEW_EN_HYPHEN)
[grammar] ~27-~27: There might be a mistake here.
Context: ... of choice for both short term planning with high grade of detail, and for long term...
(QB_NEW_EN)
[grammar] ~27-~27: Use a hyphen to join words.
Context: ... with high grade of detail, and for long term investment planning. We belive that...
(QB_NEW_EN_HYPHEN)
[grammar] ~31-~31: There might be a mistake here.
Context: ...# Where We're Going Short-term goals: - Enhanced component library: More pre-b...
(QB_NEW_EN)
[grammar] ~32-~32: There might be a mistake here.
Context: ...hermal networks, demand-side management) - Advanced result analysis: Automated re...
(QB_NEW_EN)
[grammar] ~33-~33: There might be a mistake here.
Context: ...ting and even more visualization options - **Examples of stochastic and Multi-Period ...
(QB_NEW_EN)
[grammar] ~34-~34: There might be a mistake here.
Context: ... feature is currently lacking showcases. - Interactive tutorials: Browser-based, ...
(QB_NEW_EN)
[grammar] ~41-~41: There might be a mistake here.
Context: ...zation/stochastic/) Long-term vision: - Showcase universal applicability: Flix...
(QB_NEW_EN)
[grammar] ~49-~49: Use a hyphen to join words.
Context: ...m planning and low-level tools for short term operation/dispatch. This approach i...
(QB_NEW_EN_HYPHEN)
[grammar] ~49-~49: There might be a mistake here.
Context: ...tools for short term operation/dispatch. This approach is similar to the mature [...
(QB_NEW_EN)
[grammar] ~105-~105: There might be a mistake here.
Context: ...pliance. ### Flexible Data Manipulation Transform your FlowSystem on the fly for...
(QB_NEW_EN)
[grammar] ~119-~119: Use a hyphen to join words.
Context: ..._system.resample(time="D") ``` ### User Friendly Flixopt is object oriented and ...
(QB_NEW_EN_HYPHEN)
[grammar] ~119-~119: There might be a mistake here.
Context: ...esample(time="D") ``` ### User Friendly Flixopt is object oriented and well docu...
(QB_NEW_EN)
[grammar] ~120-~120: Use a hyphen to join words.
Context: ...``` ### User Friendly Flixopt is object oriented and well documented. We try to ...
(QB_NEW_EN_HYPHEN)
[style] ~121-~121: Consider an alternative verb to strengthen your wording.
Context: ...ng code as readable as possible. If you have any issues with naming or definitions o...
(IF_YOU_HAVE_THIS_PROBLEM)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: test (3.12)
- GitHub Check: test (3.11)
- GitHub Check: test (3.13)
- GitHub Check: test (3.10)
🔇 Additional comments (1)
README.md (1)
105-118: Verify API availability for.sel/.resampleon FlowSystem.These are xarray idioms. Confirm FlowSystem exposes compatible indexers; otherwise, adjust examples or add a brief note that these mirror xarray.
If APIs differ, I can edit the examples to match the public methods.
| keywords = ["optimization", "energy systems", "numerical analysis"] | ||
| classifiers = [ | ||
| "Development Status :: 3 - Alpha", | ||
| "Development Status :: 5 - Production/Stable", |
There was a problem hiding this comment.
🧩 Analysis chain
Classifier bumped to Production/Stable — verify ecosystem readiness.
Looks good. Please confirm:
- CI tests run on 3.10–3.13, and release process is green.
- Critical deps (e.g., highspy) ship wheels for 3.13 and your target OSes.
- Docs/readme have no leftover “alpha/beta” language.
Run this to check CI matrix and stale wording:
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== CI Python matrix =="
fd -H -a ".github/workflows" | xargs -I{} rg -nC2 -i 'setup-python|python-version|matrix' {}
echo "== Classifiers in pyproject =="
rg -n 'Development Status ::' pyproject.toml
echo "== Check for stale alpha/beta wording =="
rg -n -i 'alpha|beta|experimental' -g '!**/site/**' -g '!**/build/**' -g '!**/dist/**'
echo "== Check references to Python 3.13 in docs and workflow =="
rg -n '3\.13' -g '!**/site/**'Length of output: 396
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
echo "== CI Python matrix in workflow files =="
rg -n -C2 'python-version|matrix' .github/workflows
echo "== Classifier in pyproject.toml =="
rg -n 'Development Status ::' pyproject.toml
echo "== Stale alpha/beta/experimental wording =="
rg -n -i 'alpha|beta|experimental' --glob '!**/site/**' --glob '!**/build/**' --glob '!**/dist/**'
echo "== References to Python 3.13 in repo =="
rg -n '3\.13' --glob '!**/site/**'Length of output: 25900
Remove stale “experimental” references & verify highspy wheels
- Remove “network visualization is still experimental” in flixopt/flow_system.py:526 and the corresponding note in CHANGELOG.md:353
- Verify that highspy ships wheels for Python 3.13 on your target OSes
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
README.md
[grammar] ~23-~23: There might be a mistake here.
Context: ...inutes, then progressively add detail - multi-period investments, stochastic scenarios...
(QB_NEW_EN)
[grammar] ~27-~27: There might be a mistake here.
Context: ...iting your code. --- ## 🚀 Quick Start bash pip install flixopt That's it! FlixOpt comes with the [HiGHS...
(QB_NEW_EN)
[grammar] ~57-~57: There might be a mistake here.
Context: ...lation.results.plot() ``` Next steps: - 📚 [Full Documentation](https://flixopt....
(QB_NEW_EN)
[grammar] ~58-~58: There might be a mistake here.
Context: ...Next steps: - 📚 Full Documentation - 💡 [Examples Gallery](https://flixopt.gi...
(QB_NEW_EN)
[grammar] ~59-~59: There might be a mistake here.
Context: .../flixopt/latest/) - 💡 Examples Gallery - 🔧 [API Reference](https://flixopt.githu...
(QB_NEW_EN)
[grammar] ~60-~60: There might be a mistake here.
Context: ...pt/latest/examples/) - 🔧 API Reference --- ## 🌟 Why FlixOpt? ### For Everyone: Start...
(QB_NEW_EN)
[grammar] ~64-~64: There might be a mistake here.
Context: ...api-reference/) --- ## 🌟 Why FlixOpt? ### For Everyone: Start Simple, Scale Comple...
(QB_NEW_EN)
[grammar] ~133-~133: There might be a mistake here.
Context: ...racy for detailed models (hours to days) - Segmented - Rolling horizon for long t...
(QB_NEW_EN)
[grammar] ~134-~134: There might be a mistake here.
Context: ...n for long time series (months to years) - Aggregated - Typical periods using [TS...
(QB_NEW_EN)
[grammar] ~148-~148: There might be a mistake here.
Context: ...N serialization with round-trip fidelity - Load results months later and know exact...
(QB_NEW_EN)
[style] ~182-~182: Using many exclamation marks might seem excessive (in this case: 15 exclamation marks for a text that’s 9234 characters long)
Context: ...lear naming? We welcome your suggestions! --- ## 🎯 What is FlixOpt? ### A Gen...
(EN_EXCESSIVE_EXCLAMATION)
[grammar] ~186-~186: There might be a mistake here.
Context: ...uggestions! --- ## 🎯 What is FlixOpt? ### A General-Purpose Flow Optimization Fram...
(QB_NEW_EN)
[grammar] ~192-~192: There might be a mistake here.
Context: ...s, renewable portfolios, sector coupling - Material flows: Supply chains, product...
(QB_NEW_EN)
[grammar] ~193-~193: There might be a mistake here.
Context: ..., chemical processes, recycling networks - Integrated systems: Water-energy nexus...
(QB_NEW_EN)
[style] ~204-~204: Consider a different adjective to strengthen your wording.
Context: ... need quick prototyping but may require deep customization later - Engineers who...
(DEEP_PROFOUND)
[grammar] ~204-~204: There might be a mistake here.
Context: ...but may require deep customization later - Engineers who want reliable, tested co...
(QB_NEW_EN)
[grammar] ~205-~205: There might be a mistake here.
Context: ...omponents without black-box abstractions - Students learning optimization who ben...
(QB_NEW_EN)
[grammar] ~206-~206: There might be a mistake here.
Context: ... benefit from clear, Pythonic interfaces - Practitioners who need to move from mo...
(QB_NEW_EN)
[grammar] ~207-~207: There might be a mistake here.
Context: ...e from model to production-ready results - Domain experts from any field where th...
(QB_NEW_EN)
[grammar] ~224-~224: There might be a mistake here.
Context: ...oemof/oemof-solph). --- ## 🛣️ Roadmap ### Our Vision **FlixOpt aims to be the mos...
(QB_NEW_EN)
[grammar] ~234-~234: There might be a mistake here.
Context: ...hermal networks, demand-side management) - Advanced result analysis: Automated re...
(QB_NEW_EN)
[grammar] ~235-~235: There might be a mistake here.
Context: ...rting and enhanced visualization options - **Examples of stochastic and multi-period ...
(QB_NEW_EN)
[grammar] ~236-~236: There might be a mistake here.
Context: ...s currently lack comprehensive showcases - Interactive tutorials: Browser-based, ...
(QB_NEW_EN)
[grammar] ~251-~251: There might be a mistake here.
Context: ...fic extensions --- ## 🛠️ Installation ### Basic Installation ```bash pip install ...
(QB_NEW_EN)
[grammar] ~271-~271: There might be a mistake here.
Context: ...lixOpt supports many solvers via linopy: - HiGHS (included, open-source, recommen...
(QB_NEW_EN)
[grammar] ~272-~272: There might be a mistake here.
Context: ...open-source, recommended for most users) - Gurobi (commercial, fast for large pro...
(QB_NEW_EN)
[grammar] ~273-~273: There might be a mistake here.
Context: ...** (commercial, fast for large problems) - CPLEX (commercial) - CBC, GLPK (op...
(QB_NEW_EN)
[grammar] ~274-~274: There might be a mistake here.
Context: ...large problems) - CPLEX (commercial) - CBC, GLPK (open-source alternatives) ...
(QB_NEW_EN)
[grammar] ~279-~279: There might be a mistake here.
Context: ...e alternatives) --- ## 🤝 Contributing FlixOpt thrives on community input. Whet...
(QB_NEW_EN)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: test (3.11)
- GitHub Check: test (3.13)
- GitHub Check: test (3.12)
- GitHub Check: test (3.10)
Description
Improve the Readme and update the Project Roadmap