Feature/docs improvement #481
Conversation
- Tab-based organization (Core / Advanced / Patterns / Examples)
- Collapsible definition blocks
- Links to both Flow and FlowModel classes
- Updated docstrings with absolute URLs
2. Bus.md - Restructured with tab organization and dual class linking
3. Storage.md - Restructured with comprehensive examples and dual class linking
4. LinearConverter.md - Restructured with detailed examples including specialized converters
5. InvestParameters.md - Restructured with clear separation of core vs. advanced features
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the WalkthroughThis pull request substantially rewrites and expands documentation across mathematical notation guides (Bus, Flow, Storage, LinearConverter, Effects, InvestParameters, OnOffParameters, Piecewise), updating them from concise descriptions to structured, example-rich guides. It also redesigns the homepage navigation and styling, updates docstrings in core Python modules to reference external formulations, and adjusts documentation configuration. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25–30 minutes
Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (2 warnings, 1 inconclusive)
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 review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
flixopt/effects.py (1)
51-55: Rename documentedweightsarg toperiod_weightsto match signatureThe docstring describes an argument called
weights, but the constructor actually takesperiod_weights. This will mislead users and cause aTypeErrorif they follow the docstring literally.- weights: Optional custom weights for periods and scenarios (Numeric_PS). - If provided, overrides the FlowSystem's default period weights for this effect. - Useful for effect-specific weighting (e.g., discounting for costs vs equal weights for CO2). - If None, uses FlowSystem's default weights. + period_weights: Optional custom weights for periods and scenarios (Numeric_PS). + If provided, overrides the FlowSystem's default period weights for this effect. + Useful for effect-specific weighting (e.g., discounting for costs vs equal weights for CO₂). + If None, uses FlowSystem's default weights.docs/stylesheets/extra.css (1)
98-99: Critical: Fix the body text font-size—0.75rem is unreadable.Line 98 sets
.md-typesettofont-size: 0.75rem;, which renders as ~12px and makes documentation text nearly impossible to read. This appears to be a typo.Apply this fix:
.md-typeset { line-height: 1.6; - font-size: 0.75rem; /* Smaller font for more screen real estate */ + font-size: 0.95rem; /* Appropriate base font size for readability */ max-width: 1300px !important; /* Wider max width */ }
🧹 Nitpick comments (2)
flixopt/components.py (1)
261-263: Avoid duplicate Storage “Mathematical Formulation” references
Storagenow has both an absolute “Mathematical Formulation” link (line 262) and a separate note with a relative Storage link (lines 359–361). Consider keeping a single canonical link style to avoid drift between targets.- Mathematical Formulation: - See <https://flixopt.github.io/flixopt/latest/user-guide/mathematical-notation/elements/Storage/> + Mathematical Formulation: + See <https://flixopt.github.io/flixopt/latest/user-guide/mathematical-notation/elements/Storage/> @@ - **Mathematical formulation**: See [Storage](../user-guide/mathematical-notation/elements/Storage.md) - for charge state evolution equations and balance constraints. + **Mathematical formulation**: See the Storage element documentation linked above + for charge state evolution equations and balance constraints.Also applies to: 359-361
flixopt/interface.py (1)
85-93: Piecewise / investment / on–off parameter docs are consistent with modelsThe enriched docstrings for
Piecewise,PiecewiseConversion,InvestParameters, andOnOffParametersaccurately describe the existing modeling patterns and correctly reference the corresponding mathematical-notation pages. Implementation stays unchanged, so this is a pure documentation win.If you want full consistency later, you could also switch the remaining relative
Piecewiselink inPiecewiseConversionto the same absolute.../latest/...style as the others, but that’s purely cosmetic.Also applies to: 240-435, 715-716, 1145-1146
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (17)
docs/index.md(2 hunks)docs/stylesheets/extra.css(2 hunks)docs/user-guide/mathematical-notation/effects-penalty-objective.md(2 hunks)docs/user-guide/mathematical-notation/elements/Bus.md(1 hunks)docs/user-guide/mathematical-notation/elements/Flow.md(1 hunks)docs/user-guide/mathematical-notation/elements/LinearConverter.md(1 hunks)docs/user-guide/mathematical-notation/elements/Storage.md(1 hunks)docs/user-guide/mathematical-notation/features/InvestParameters.md(3 hunks)docs/user-guide/mathematical-notation/features/OnOffParameters.md(1 hunks)docs/user-guide/mathematical-notation/features/Piecewise.md(1 hunks)flixopt/components.py(4 hunks)flixopt/effects.py(2 hunks)flixopt/elements.py(4 hunks)flixopt/features.py(3 hunks)flixopt/interface.py(3 hunks)mkdocs.yml(1 hunks)scripts/gen_ref_pages.py(1 hunks)
🔇 Additional comments (17)
mkdocs.yml (1)
131-131: Increasing TOC depth to support expanded documentation structure.This change increases the table of contents depth from 2 to 3 levels, enabling the TOC to include h3 headings alongside h1 and h2. Given the restructured navigation (lines 11–40) with deeper nesting and the expanded mathematical notation guides mentioned in the PR summary, this adjustment provides more granular navigation without introducing complexity.
flixopt/components.py (1)
43-45: Docstring links and model descriptions look consistentThe new mathematical formulation links and the added
LinearConverterModel/StorageModeldocstrings align with the implementation and external docs, without changing behavior. Nothing to fix here.Also applies to: 777-786, 835-843
flixopt/elements.py (1)
199-200: Flow/Bus model docstrings and external links are coherentThe added Flow/Bus “Mathematical Formulation” links and model class docstrings accurately describe the existing modeling (flow bounds, flow-hours, nodal balance with optional excess) and introduce no behavioral changes. Looks good as-is.
Also applies to: 334-335, 669-676, 941-948
flixopt/features.py (1)
25-32: Feature model docstrings align with implementationThe expanded docstrings for
InvestmentModel,OnOffModel, andPiecewiseModelcorrectly reflect their existing behavior and reference the right external math docs. No functional impact; nothing to change.Also applies to: 151-158, 381-388
flixopt/effects.py (1)
32-41: Effect / EffectModel math docs and descriptions look correctThe updated Effect/EffectModel docstrings and the new external “effects-penalty-objective” link match how effects are modeled (temporal/periodic shares, bounds, weighted totals). No behavior changes; these additions look good.
Also applies to: 472-480
docs/user-guide/mathematical-notation/features/InvestParameters.md (1)
1-271: Well-structured documentation with comprehensive examples and consistent cross-references.The InvestParameters documentation has been substantially improved with:
- Clear Variables and Constraints sections with formal mathematical notation
- Comprehensive Parameters table
- Five detailed Use Cases with practical Python code examples
- Proper cross-references to Piecewise, Flow, Storage, and LinearConverter
- Consistent import statements across code examples
docs/user-guide/mathematical-notation/elements/Storage.md (1)
1-187: Well-structured documentation with clear mathematical formulations and practical examples.The Storage documentation has been significantly improved with:
- Formal definitions of state-of-charge bounds and storage balance equations
- Clear Variables and Parameters tables mapping mathematical symbols to Python names
- Four comprehensive Use Cases covering basic batteries, thermal storage, investment decisions, and cyclic conditions
- Consistent cross-references to InvestParameters and related features
docs/user-guide/mathematical-notation/features/OnOffParameters.md (1)
1-191: Comprehensive documentation with well-organized constraints and practical use cases.The OnOffParameters documentation follows the new structure effectively with:
- Clear Variables table documenting all binary and continuous state variables
- Eight distinct constraint types with formal mathematical notation
- Three practical Use Cases demonstrating startup costs, cycling limits, and operating hour bounds
- Proper references to related features (InvestParameters) and patterns
docs/user-guide/mathematical-notation/effects-penalty-objective.md (1)
1-391: Comprehensive system-level documentation with excellent multi-dimensional modeling guidance.The Effects, Penalty & Objective documentation is well-structured with:
- Clear formal definitions of periodic, temporal, and combined effects
- Comprehensive constraint formulations including cross-effect aggregation
- Six practical Use Cases covering costs, emissions, carbon pricing, investments, and peak constraints
- Detailed Multi-Dimensional Objective section clarifying how periods and scenarios interact
- Helpful Summary Table for quick reference
The documentation effectively ties together the element-level effects (from Flow, Storage, etc.) into a system-wide optimization framework.
Verify the investment constraints example code to ensure both effects are properly applied as documented.
docs/index.md (2)
135-138: README.md markers verified and correct.Both markers exist and are properly positioned:
## 🛠️ Installationat line 147## 📄 Licenseat line 190The include-markdown directive will correctly extract the installation documentation between these markers. No issues found.
85-111: External links verified as accessible; internal link requires manual confirmation.The main GitHub repository (https://github.com/flixOpt/flixopt) is confirmed public and active. However, the Discussions page fetch timed out, leaving that status inconclusive—though the Discussions feature is enabled on the repository. The internal
contribute/link (line 103) cannot be verified through web search and should be manually confirmed in the documentation structure.docs/user-guide/mathematical-notation/elements/LinearConverter.md (1)
159-163: No issues found. All specialized LinearConverter classes and references are correct.All verification checks passed:
- All 5 classes exist in
flixopt/linear_converters.pyand inherit fromLinearConverter- Module path
flixopt.linear_convertersis correct- Markdown reference syntax
[ClassName][flixopt.linear_converters.ClassName]is properly configured and consistent with other documentation filesdocs/user-guide/mathematical-notation/elements/Flow.md (2)
53-53: All cross-referenced documentation files exist at expected paths.Verification confirms that all markdown file references in Flow.md (lines 53, 141, and 192-194) point to existing files:
../features/OnOffParameters.md✓../features/InvestParameters.md✓../effects-penalty-objective.md✓../modeling-patterns/bounds-and-states.md✓../modeling-patterns/index.md✓No broken or missing references detected.
187-188: Verify documentation build system configuration for reference-link resolution.MkDocs does not natively resolve Python dotted names in reference-style links; this requires a plugin like mkdocstrings or an "autorefs"/inventory plugin. The links
[flixopt.elements.Flow]and[flixopt.elements.FlowModel]will only resolve correctly if:
- Your
mkdocs.ymlhas mkdocstrings (or similar plugin) enabled with Python handler configured- The plugin generates anchors for these Python objects and registers them in an inventory
- The reference links are rewritten to correct page/anchor paths during the build
Without access to your build configuration, I cannot confirm these are set up. Verify that your documentation build includes the necessary plugin configuration to resolve these Python object references.
docs/stylesheets/extra.css (3)
508-509: Clarify the intent of the comment on line 509.The comment states "Remove this rule as it conflicts with TOC layout," but no rule removal is evident immediately after. Either the comment should be deleted, or the conflicting rule needs to be identified and removed.
520-528: Verify gradient text fallback behavior.The
.hero-section h1uses a gradient text effect with both-webkit-and standardbackground-clipsyntax. While modern browsers support this, confirm that fallback rendering is acceptable in target browsers (e.g., older Safari versions, Firefox). Consider adding a solid color fallback for accessibility.
511-582: Hero and architecture section layout looks well-structured.The centered layout with
margin: 0 autoand consistentmax-width: 1200pximproves readability and maintains alignment with the main content area. The responsive breakpoint at 768px (line 586) is appropriate.
| <div class="grid cards" markdown> | ||
|
|
||
| - :rocket: **[Getting Started](getting-started/)** | ||
|
|
||
| --- | ||
|
|
||
| New to FlixOpt? Start here with installation and your first model | ||
|
|
||
| - :bulb: **[Examples Gallery](examples/)** | ||
|
|
||
| --- | ||
|
|
||
| Explore real-world examples from simple to complex systems | ||
|
|
||
| - :books: **[API Reference](api-reference/)** | ||
|
|
||
| --- | ||
|
|
||
| Detailed documentation of all classes, methods and parameters | ||
|
|
||
| - :book: **[Recipes](user-guide/recipes/)** | ||
|
|
||
| --- | ||
|
|
||
| Common patterns and best practices for modeling energy systems | ||
|
|
||
| - :material-math-integral: **[Mathematical Notation](user-guide/mathematical-notation/)** | ||
|
|
||
| --- | ||
|
|
||
| Understand the mathematical formulations behind the framework | ||
|
|
||
| - :material-road: **[Roadmap](roadmap/)** | ||
|
|
||
| --- | ||
|
|
||
| See what's coming next and contribute to the future of FlixOpt | ||
|
|
||
| </div> |
There was a problem hiding this comment.
🧩 Analysis chain
Verify all Quick Navigation links target valid documentation pages.
The Quick Navigation section links to several documentation sections. Confirm these directories/pages exist and are correct:
getting-started/examples/api-reference/user-guide/recipes/user-guide/mathematical-notation/roadmap/
🏁 Script executed:
#!/bin/bash
# Verify Quick Navigation link targets exist
docs_dir="docs"
links=(
"getting-started"
"examples"
"api-reference"
"user-guide/recipes"
"user-guide/mathematical-notation"
"roadmap"
)
for link in "${links[@]}"; do
if [ -d "$docs_dir/$link" ]; then
echo "✓ Directory exists: $link"
else
echo "✗ Missing directory: $link"
fi
doneLength of output: 221
I found several missing directories. Let me investigate further to determine if these pages exist under different names or structures.
---
🏁 Script executed:
```shell
#!/bin/bash
# Search for alternative locations and file formats of missing pages
docs_dir="docs"
echo "=== Searching for 'getting-started' references ==="
find "$docs_dir" -type f -name "*getting*started*" -o -type d -name "*getting*started*" 2>/dev/null
echo -e "\n=== Searching for 'api-reference' references ==="
find "$docs_dir" -type f -name "*api*reference*" -o -type d -name "*api*reference*" 2>/dev/null
echo -e "\n=== Searching for 'roadmap' references ==="
find "$docs_dir" -type f -name "*roadmap*" -o -type d -name "*roadmap*" 2>/dev/null
echo -e "\n=== Full docs directory structure ==="
ls -la "$docs_dir" | head -30
echo -e "\n=== Check for index.md or _index.md files ==="
find "$docs_dir" -maxdepth 2 -type f \( -name "index.md" -o -name "_index.md" \)
Length of output: 975
Let me search for any references to api-reference and check the project structure more thoroughly.
---
🏁 Script executed:
```shell
#!/bin/bash
# Search for api-reference and check mkdocs config
echo "=== Search for 'api-reference' anywhere in repo ==="
grep -r "api-reference" --include="*.md" --include="*.yml" --include="*.yaml" 2>/dev/null | head -20
echo -e "\n=== Check for mkdocs config ==="
find . -maxdepth 2 -name "mkdocs.yml" -o -name "mkdocs.yaml" -o -name ".mkdocs.yml" 2>/dev/null
echo -e "\n=== List structure of user-guide ==="
find docs/user-guide -type f -o -type d | sort
echo -e "\n=== Check what getting-started.md and roadmap.md contain ==="
echo "--- getting-started.md first 5 lines ---"
head -5 docs/getting-started.md
echo -e "\n--- roadmap.md first 5 lines ---"
head -5 docs/roadmap.md
Length of output: 2675
Fix three broken Quick Navigation links in the Quick Navigation section.
The verification found that three of six links are broken:
getting-started/→ Should link togetting-started.md(file exists as markdown, not directory)roadmap/→ Should link toroadmap.md(file exists as markdown, not directory)api-reference/→ Directory does not exist (referenced inmkdocs.ymland other documentation files, but content/directory structure is missing)
The three working links are:
examples/✓user-guide/recipes/✓user-guide/mathematical-notation/✓
Either convert the markdown files to directories with index.md files, or update the links to point directly to .md files. Additionally, the api-reference/ directory needs to be created with appropriate content as indicated in the project configuration.
🤖 Prompt for AI Agents
In docs/index.md around lines 25-63, three Quick Navigation links are broken:
getting-started/ and roadmap/ should point to existing markdown files
(getting-started.md and roadmap.md) or you should convert those markdown files
into directories with index.md; api-reference/ is missing entirely and must be
created (add docs/api-reference/index.md with appropriate content/frontmatter
consistent with mkdocs.yml) or update the link to an existing api-reference.md
if that file exists; verify links against the repo file tree, update the three
hrefs accordingly or add the missing directory+index, and run a local mkdocs
serve/build to confirm all navigation links resolve before committing.
| # Battery with investment | ||
| battery_flow = Flow( | ||
| label='storage_capacity', | ||
| bus='electricity', | ||
| size=InvestParameters( | ||
| minimum_size=0, | ||
| maximum_size=1000, | ||
| effects_of_investment_per_size={'capital_costs': 600}, # €600/kWh | ||
| effects_of_investment_per_size={'total_costs': 80}, # Annualized: €80/kWh/year | ||
| ), | ||
| ) | ||
| ``` |
There was a problem hiding this comment.
Lines 288-289 show two separate effects_of_investment_per_size parameter assignments to the same Flow:
effects_of_investment_per_size={'capital_costs': 600}, # Line 288
effects_of_investment_per_size={'total_costs': 80}, # Line 289In Python, when you pass duplicate keyword arguments, the second assignment overwrites the first. This example would only use {'total_costs': 80}, not both effects.
Suggested fix: Combine both effects into a single dictionary:
size=InvestParameters(
minimum_size=0,
maximum_size=1000,
- effects_of_investment_per_size={'capital_costs': 600}, # €600/kWh
- effects_of_investment_per_size={'total_costs': 80}, # Annualized: €80/kWh/year
+ effects_of_investment_per_size={
+ 'capital_costs': 600, # €600/kWh
+ 'total_costs': 80, # Annualized: €80/kWh/year
+ },
),This allows both effects to be properly applied to the Flow.
🤖 Prompt for AI Agents
In docs/user-guide/mathematical-notation/effects-penalty-objective.md around
lines 281 to 292, the Flow instantiation mistakenly passes the same keyword
twice so the second effects_of_investment_per_size overwrites the first; merge
both effect entries into a single effects_of_investment_per_size dictionary
containing both 'capital_costs': 600 and 'total_costs': 80 so the Flow receives
both effects together.
| $$\label{eq:bus_penalty} | ||
| \Phi(\text{t}_i) = \text a_{b \rightarrow \Phi}(\text{t}_i) \cdot \Delta \text{t}_i \cdot [ \phi_\text{in}(\text{t}_i) + \phi_\text{out}(\text{t}_i) ] | ||
| $$ |
There was a problem hiding this comment.
Fix LaTeX syntax in penalty cost equation
The penalty equation uses \text a_{b \rightarrow \Phi}, which is invalid LaTeX and may not render.
- $$\label{eq:bus_penalty}
- \Phi(\text{t}_i) = \text a_{b \rightarrow \Phi}(\text{t}_i) \cdot \Delta \text{t}_i \cdot [ \phi_\text{in}(\text{t}_i) + \phi_\text{out}(\text{t}_i) ]
- $$
+ $$\label{eq:bus_penalty}
+ \Phi(\text{t}_i) = a_{b \rightarrow \Phi}(\text{t}_i) \cdot \Delta \text{t}_i \cdot [ \phi_\text{in}(\text{t}_i) + \phi_\text{out}(\text{t}_i) ]
+ $$
+ % or, if you really want text mode:
+ % \Phi(\text{t}_i) = \text{a}_{b \rightarrow \Phi}(\text{t}_i) \cdot \Delta \text{t}_i \cdot [ \phi_\text{in}(\text{t}_i) + \phi_\text{out}(\text{t}_i) ]🤖 Prompt for AI Agents
In docs/user-guide/mathematical-notation/elements/Bus.md around lines 36 to 38,
the LaTeX token `\text a_{b \rightarrow \Phi}` is invalid; replace it with a
valid expression such as `\text{a}_{b \rightarrow \Phi}` or simply `a_{b
\rightarrow \Phi}` (or `a_{b\to\Phi}`) so the macro is correctly formed and the
equation renders, keeping the rest of the formula unchanged.
| ## Economies of Scale (Investment Costs) | ||
|
|
||
| ```python | ||
| from flixopt import InvestParameters, Piecewise, Piece, PiecewiseEffects | ||
|
|
||
| # Cost per kWh decreases with scale | ||
| battery_cost = InvestParameters( | ||
| minimum_size=10, | ||
| maximum_size=1000, | ||
| piecewise_effects_of_investment=PiecewiseEffects( | ||
| piecewise_origin=Piecewise([ | ||
| Piece((0, 0), (100, 100)), # Small | ||
| Piece((100, 100), (500, 500)), # Medium | ||
| Piece((500, 500), (1000, 1000)), # Large | ||
| ]), | ||
| piecewise_shares={ | ||
| 'cost': Piecewise([ | ||
| Piece((0, 0), (100, 80000)), # €800/kWh | ||
| Piece((100, 80000), (500, 350000)), # €750-600/kWh | ||
| Piece((500, 350000), (1000, 850000)), # €600-500/kWh (bulk discount) | ||
| ]) | ||
| }, | ||
| ), | ||
| ) | ||
| ``` | ||
|
|
||
| **Variables:** Shared $\beta_k$, $\lambda_{0,k}$, $\lambda_{1,k}$ for size and cost | ||
|
|
||
| **Constraints:** $\eqref{eq:piecewise_combined}$ coupling size to cost with decreasing unit cost | ||
|
|
||
| **Behavior:** Investment size and total cost are coupled through piecewise relationship modeling economies of scale. |
There was a problem hiding this comment.
The Economies of Scale use case demonstrates piecewise costs with bulk discounts. However, the cost progression shows an anomaly:
- Small (0-100 kWh): €80,000 total → €800/kWh
- Medium (100-500 kWh): €350,000 total → €600-€750/kWh marginal cost ✓
- Large (500-1000 kWh): €850,000 total → €1,000/kWh marginal cost, NOT €500-€600/kWh
The comment claims "bulk discount from €800/kWh to €500/kWh," but the large segment shows an increase in marginal cost from €675/kWh (medium) to €1,000/kWh (large). This contradicts the intended bulk discount behavior.
Suggested fix: Adjust the large piece endpoint to reflect declining costs. For example:
- Large (500-1000 kWh): adjust to approximately €700,000 total → ~€500/kWh marginal cost
Piece((500, 500), (1000, 1000)), # Large
# Current: (1000, 1000)
+ # Should be approximately: (1000, 700000)This would create the intended economies-of-scale pattern.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ## Economies of Scale (Investment Costs) | |
| ```python | |
| from flixopt import InvestParameters, Piecewise, Piece, PiecewiseEffects | |
| # Cost per kWh decreases with scale | |
| battery_cost = InvestParameters( | |
| minimum_size=10, | |
| maximum_size=1000, | |
| piecewise_effects_of_investment=PiecewiseEffects( | |
| piecewise_origin=Piecewise([ | |
| Piece((0, 0), (100, 100)), # Small | |
| Piece((100, 100), (500, 500)), # Medium | |
| Piece((500, 500), (1000, 1000)), # Large | |
| ]), | |
| piecewise_shares={ | |
| 'cost': Piecewise([ | |
| Piece((0, 0), (100, 80000)), # €800/kWh | |
| Piece((100, 80000), (500, 350000)), # €750-600/kWh | |
| Piece((500, 350000), (1000, 850000)), # €600-500/kWh (bulk discount) | |
| ]) | |
| }, | |
| ), | |
| ) | |
| ``` | |
| **Variables:** Shared $\beta_k$, $\lambda_{0,k}$, $\lambda_{1,k}$ for size and cost | |
| **Constraints:** $\eqref{eq:piecewise_combined}$ coupling size to cost with decreasing unit cost | |
| **Behavior:** Investment size and total cost are coupled through piecewise relationship modeling economies of scale. | |
| ## Economies of Scale (Investment Costs) |
🤖 Prompt for AI Agents
In docs/user-guide/mathematical-notation/features/Piecewise.md around lines
172-202, the large-piece total cost (500->1000 kWh) is 850,000 which produces a
higher marginal cost than the medium segment and breaks the intended
bulk-discount decreasing unit cost; change the large piece endpoint total cost
to ~700,000 (e.g. replace the Piece((500, 350000), (1000, 850000)) entry with
Piece((500, 350000), (1000, 700000))) so the marginal cost falls to about
€500/kWh and update the explanatory text to match the new numbers.
| index_file.write( | ||
| 'This section contains the documentation for all modules and classes in flixopt.\n' | ||
| 'For more information on how to use the classes and functions, see the [User Guide](../user-guide/index.md) section.\n' | ||
| 'For more information on how to use the classes and functions, see the [User Guide](../user-guide/core-concepts/) section.\n' |
There was a problem hiding this comment.
🧩 Analysis chain
Verify the new documentation path exists.
The link update aligns with the PR's documentation reorganization objective. However, ensure that the target path user-guide/core-concepts/ exists and contains an index file to prevent broken links in the generated API reference.
Run the following script to verify the documentation structure:
🏁 Script executed:
#!/bin/bash
# Description: Verify that the user-guide/core-concepts/ directory exists and has proper documentation files
# Check if the directory exists
fd --type d --max-depth 3 "core-concepts" | grep "user-guide/core-concepts"
# Check for index files in the core-concepts directory
fd --type f --max-depth 1 "index.md" user-guide/core-concepts/ 2>/dev/null || echo "No index.md found in user-guide/core-concepts/"
# List all files in the core-concepts directory to understand its structure
echo "Files in user-guide/core-concepts/:"
fd --type f --max-depth 2 . user-guide/core-concepts/ 2>/dev/null || echo "Directory not found"Length of output: 102
I need to investigate the actual documentation structure to understand whether this link is broken or if the new path exists elsewhere.
Now I need to explore the actual documentation structure to understand what exists.
---
🏁 Script executed:
```shell
#!/bin/bash
# Explore documentation directory structure
echo "=== Docs directory structure ==="
fd --type d --max-depth 3 . docs/ 2>/dev/null | head -20 || echo "docs/ directory not found"
echo -e "\n=== User-guide directory contents ==="
fd --type f . docs/user-guide/ 2>/dev/null || echo "docs/user-guide/ not found"
echo -e "\n=== Looking for core-concepts anywhere ==="
fd --type d "core-concepts" 2>/dev/null || echo "No core-concepts directory found"
echo -e "\n=== All markdown files in user-guide or similar ==="
fd --type f "\.md$" docs/ 2>/dev/null | grep -i "user\|guide" | head -10 || echo "No matches"
Length of output: 2084
Fix broken documentation link—directory does not exist.
The link on line 49 is incorrect. The code changes ../user-guide/core-concepts/ (treating it as a directory), but the actual content exists at docs/user-guide/core-concepts.md (a file, not a directory). This creates a broken link in the generated API reference.
Change ../user-guide/core-concepts/ to ../user-guide/core-concepts (without the trailing slash) to correctly reference the file. MkDocs will resolve this to the core-concepts.md file.
🤖 Prompt for AI Agents
In scripts/gen_ref_pages.py around line 49, the documentation link incorrectly
points to '../user-guide/core-concepts/' (treated as a directory) which breaks
the generated API reference; change the link to '../user-guide/core-concepts'
(remove the trailing slash) so MkDocs resolves it to
docs/user-guide/core-concepts.md; update the string on line 49 accordingly and
run the doc build to verify the link resolves.
…provement # Conflicts: # CHANGELOG.md
# Conflicts: # CHANGELOG.md # docs/user-guide/core-concepts.md # docs/user-guide/mathematical-notation/effects-penalty-objective.md # docs/user-guide/mathematical-notation/elements/Flow.md # docs/user-guide/mathematical-notation/elements/Storage.md # docs/user-guide/mathematical-notation/features/InvestParameters.md # docs/user-guide/mathematical-notation/features/OnOffParameters.md # docs/user-guide/mathematical-notation/index.md # flixopt/features.py # flixopt/interface.py # mkdocs.yml
2. Updated all terminology:
- on_off_parameters → status_parameters
- OnOffParameters → StatusParameters
- effects_per_switch_on → effects_per_startup
- effects_per_running_hour → effects_per_active_hour
- consecutive_on_hours_min → min_uptime
- consecutive_on_hours_max → max_uptime
- consecutive_off_hours_min → min_downtime
- on_hours_min/max → active_hours_min/max
- switch_on_max → startup_limit
- switch_on/switch_off → startup/shutdown
- "on/off" language → "active/inactive" language
3. Updated references in Flow.md, LinearConverter.md, and effects-penalty-objective.md
…ystem using pd.Index:
# Conflicts: # CHANGELOG.md # docs/user-guide/mathematical-notation/effects-penalty-objective.md # docs/user-guide/mathematical-notation/elements/Bus.md
* Flow.md - Fully restructured with:
- Tab-based organization (Core / Advanced / Patterns / Examples)
- Collapsible definition blocks
- Links to both Flow and FlowModel classes
- Updated docstrings with absolute URLs
2. Bus.md - Restructured with tab organization and dual class linking
3. Storage.md - Restructured with comprehensive examples and dual class linking
4. LinearConverter.md - Restructured with detailed examples including specialized converters
5. InvestParameters.md - Restructured with clear separation of core vs. advanced features
* Improve organization
* Improve organization
* Improve organization by using tables
* Improve organization by using tables and use eqref
* Add symbol to parameter mapping
* Changed to inline math
* Use propre constraints with numbering
* Move parameters into separate tab
* Reorder parameters
* : Use the columns "symbol" and "python name" in the variables tab
* Update Bus, Storage, and LinearConverter.md
* Update InvestParameters and OnOffParameters.md
* Update Piecewise.md
* Compact effects-penalty-objective.md
* Allow toc level 3
* Add toc to homepage
* Replace ustom css with mkdocs material stuff
* Revert some
* Revert some
* Remove layout css rule
* Show toc on homepage
* FIx broken link
* Add edit uri
* Hide bottom part
* Hide bottom part
* Restructure docs
* Show navigation in home
* Add Changelog fromating
* THighten CHANGELOG.md
* Simplify users.md
* Simplify models.md
* Shorten citing.md
* Shorten support.md
* Update CHANGELOG.md
* Simplify installation.md
* Simplify quick-start.md
* Updated FullCalculation → Optimization in documentation
Fixed mkdocs.yml navigation
Fixed broken link in support.md
* Fixed solver calls in docs
* Move files and restructure
* Delete old docs script
* Improve docs structure
* Imrpove Optimization Modes
* Imrpove Optimization Modes
* Rewrite the core concepts to be user facing
* Reorganize Mathematical Notation
* 1. Minimal variable names — Changed from words to symbols:
- penalty_rate → $c_\phi$
- relative_min → $p_{rel}^{min}$
- flow_hours → $h_f$
- loss → $\dot{c}_{loss}$
- etc.
2. Tabs for conditional constraints — Used === "Tab Name" syntax for:
- Bus.md: "Without Excess (Strict)" vs "With Excess (Soft)"
- Flow.md: "Standard (No On/Off)" vs "With On/Off" vs "Fixed Profile"
- Storage.md: "Fixed Initial" vs "Cyclic" vs "Final Bounds"
- LinearConverter.md: "Single Input/Output" vs "Multiple Outputs" vs "COP > 1" vs "Time-Varying"
- Effects.md: "Temporal (Operational)" vs "Periodic (Investment)" vs "Total"
3. Corrected Flow constraints — Clarified that:
- Without on/off parameters: flow cannot be zero if relative_minimum > 0
- With on/off parameters: flow can be zero (when off) OR within bounds (when on)
4. Cleaner structure — Removed redundant content, focused on essential formulas and examples
* The Flow.md now has four tabs for capacity bounds:
1. Fixed Size — Standard bounds without on/off
2. Fixed Size + On/Off — Can be zero when off
3. Variable Size — Investment decision on capacity
4. Variable Size + On/Off — Both investment and on/off, with big-M linearization for the bilinear term $s(t) \cdot P$
* InvestParameters.md:
- Story-driven intro with real-world examples
- Core concept: "Size as a Variable"
- Tabs for: Binary (Fixed Size) | Continuous (Size Range) | Mandatory
- Tabs for effects: Fixed | Specific | Retirement | Piecewise
- Minimal variable names: $P$, $s_{inv}$, $c_{fix}$, $c_{spec}$, etc.
- Cost annualization formula
OnOffParameters.md:
- Story-driven intro with real-world examples
- Core concept: "Binary State" with flow bound modification
- Tabs for state transitions: Switch Detection | Startup Costs | Running Costs
- Tabs for duration constraints: Min Run Time | Min Off Time | Max Run Time | Total Hours | Max Startups
- Minimal variable names: $s(t)$, $s^{on}(t)$, $s^{off}(t)$, $T_{on}^{min}$, etc.
Piecewise.md:
- Story-driven intro with ASCII diagram
- Core concept: Linear segments with weighted combinations
- Tabs for constraints: Single Piece Active | With Zero Point
- Tabs for piece patterns: Continuous (Touching) | Gap (Forbidden Region) | Zero Point
- Minimal variable names: $\beta_k$, $\lambda_0$, $\lambda_1$, etc.
- Practical examples for heat pumps, boilers, and investment
* Make OnOffParameters better
* Piecewise.md:
- Replaced the useless ASCII diagram with a more informative one showing:
- Actual axis labels (input/output)
- Numeric values on axes
- Two pieces with their connection point labeled
- Clear visual of how pieces connect at (50, 45)
- Shows the start/end points notation
* Add plotly chart
* Add custom javascript
* Remove charts plugin
* Add missing docs file
* Fix quick start
* Delete model.md
* Update citation
* Update license.md
* Simplify faq, support and troubleshooting.md
* Remove old workflow
* 1. Renamed OnOffParameters.md → StatusParameters.md
2. Updated all terminology:
- on_off_parameters → status_parameters
- OnOffParameters → StatusParameters
- effects_per_switch_on → effects_per_startup
- effects_per_running_hour → effects_per_active_hour
- consecutive_on_hours_min → min_uptime
- consecutive_on_hours_max → max_uptime
- consecutive_off_hours_min → min_downtime
- on_hours_min/max → active_hours_min/max
- switch_on_max → startup_limit
- switch_on/switch_off → startup/shutdown
- "on/off" language → "active/inactive" language
3. Updated references in Flow.md, LinearConverter.md, and effects-penalty-objective.md
* Remove Modeling patterns from docs
* Simplify docs
* Improve LinearConverter.md
* Improve Flow.md
* Improve effects-penalty-objective.md
* Improve InvestParameters.md
* Add durtaion constraints
* Update Piecewise stuff
* Update Piecewise stuff
* Update Piecewise stuff
* Combine effects and dimensions into one tab
* The dimension examples now correctly show how to assign them to FlowSystem using pd.Index:
* Update effects-and-dimensions.md
* Update effects-and-dimensions.md
* updated all reference tables across all Mathematical Notation pages to be consistent
* updated all reference tables across all Mathematical Notation pages to be consistent
* updated all reference tables across all Mathematical Notation pages to be consistent
Description
Reorganize docs
Type of Change
Related Issues
Closes #(issue number)
Testing
Checklist
Summary by CodeRabbit
Documentation
Style
✏️ Tip: You can customize this high-level summary in your review settings.