Motivation
The current variable/constraint naming convention uses | as delimiter (e.g., flow|rate, storage|charge). This is problematic:
- Typing ergonomics: On German QWERTZ keyboards,
| requires AltGr+< — one of the most awkward key combos. Even on US keyboards it requires Shift.
-- is better: No shift key on any layout, visually distinct, unambiguous in Python/xarray string contexts.
Delimiter comparison
| Delimiter |
Example |
Shift? (US) |
Shift? (DE) |
Verdict |
| (current) |
flow|rate |
Yes |
AltGr (painful) |
Hard to type |
-- |
flow--rate |
No |
No |
Easy, clear separator |
. |
flow.rate |
No |
No |
Conflicts with xarray attribute access |
- |
flow-rate |
No |
No |
Ambiguous with multi-word names |
:: |
flow::rate |
Yes |
Yes |
Still needs shift |
/ |
flow/rate |
No |
Shift+7 |
Path separator confusion |
Additional change: () for mode suffixes
Share and effect variables that carry a mode suffix (e.g., share|temporal, share|periodic) should use parentheses instead: share(temporal), share(periodic). This is consistent with the existing penalty naming convention (Bus->Penalty(temporal)).
Scope
This is a breaking change for anyone accessing variables by name in the solution dataset.
Three distinct uses of | as delimiter in the codebase:
- VarName enum constants (
structure.py): 'flow|rate' → 'flow--rate'
- f-string name construction (throughout):
f'{prefix}|share' → f'{prefix}--share'
- Name parsing (
split('|'), endswith('|flow_rate')): update to --
Not changing: clustering/base.py tuple serialization (unrelated use of |), -> penalty separator.
Files to modify (~20 source + test + doc files)
Source files:
flixopt/structure.py — VarName enums (centralized names) + _valid_label() (add -- to forbidden chars, remove |)flixopt/modeling.py — ~25 constraint name f-stringsflixopt/features.py — ~10 builder name paramsflixopt/elements.py — ~30 constraint/variable names + _fit_coords callsflixopt/components.py — ~35 storage constraint namesflixopt/effects.py — ~15 effect variable/share namesflixopt/interface.py — ~10 _fit_coords name argsflixopt/results.py — per-element name patterns, .split('|') callsflixopt/statistics_accessor.py — name patterns, split calls, endswith checksflixopt/optimize_accessor.py — rolling horizon name patternsflixopt/transform_accessor.py — rsplit call + name constructionflixopt/flow_system.py — batched_var_map values
Test files: test_flow.py, test_bus.py, test_component.py, test_storage.py, test_clustering/, test_solution_persistence.py
Documentation: docs/variable_names.md, docs/architecture/batched_modeling.md, docs/user-guide/building-models/index.md, docs/user-guide/optimization/index.md
Label validation
Element._valid_label() in structure.py currently forbids | in user labels. Update to:
- Remove
'|' from not_allowed
- Add
'--' to not_allowed
Verification plan
grep -rn "'[a-z_]*|[a-z_]" flixopt/ --include="*.py" — no remaining pipe delimiters (excluding clustering)python -m pytest tests/ — all tests passpython -m mkdocs build — docs build
Motivation
The current variable/constraint naming convention uses
|as delimiter (e.g.,flow|rate,storage|charge). This is problematic:|requires AltGr+< — one of the most awkward key combos. Even on US keyboards it requires Shift.--is better: No shift key on any layout, visually distinct, unambiguous in Python/xarray string contexts.Delimiter comparison
|(current)flow|rate--flow--rate.flow.rate-flow-rate::flow::rate/flow/rateAdditional change:
()for mode suffixesShare and effect variables that carry a mode suffix (e.g.,
share|temporal,share|periodic) should use parentheses instead:share(temporal),share(periodic). This is consistent with the existing penalty naming convention (Bus->Penalty(temporal)).Scope
This is a breaking change for anyone accessing variables by name in the solution dataset.
Three distinct uses of
|as delimiter in the codebase:structure.py):'flow|rate'→'flow--rate'f'{prefix}|share'→f'{prefix}--share'split('|'),endswith('|flow_rate')): update to--Not changing:
clustering/base.pytuple serialization (unrelated use of|),->penalty separator.Files to modify (~20 source + test + doc files)
Source files:
flixopt/structure.py— VarName enums (centralized names) +_valid_label()(add--to forbidden chars, remove|)flixopt/modeling.py— ~25 constraint name f-stringsflixopt/features.py— ~10 builder name paramsflixopt/elements.py— ~30 constraint/variable names +_fit_coordscallsflixopt/components.py— ~35 storage constraint namesflixopt/effects.py— ~15 effect variable/share namesflixopt/interface.py— ~10_fit_coordsname argsflixopt/results.py— per-element name patterns,.split('|')callsflixopt/statistics_accessor.py— name patterns, split calls, endswith checksflixopt/optimize_accessor.py— rolling horizon name patternsflixopt/transform_accessor.py— rsplit call + name constructionflixopt/flow_system.py—batched_var_mapvaluesTest files:
test_flow.py,test_bus.py,test_component.py,test_storage.py,test_clustering/,test_solution_persistence.pyDocumentation:
docs/variable_names.md,docs/architecture/batched_modeling.md,docs/user-guide/building-models/index.md,docs/user-guide/optimization/index.mdLabel validation
Element._valid_label()instructure.pycurrently forbids|in user labels. Update to:'|'fromnot_allowed'--'tonot_allowedVerification plan
grep -rn "'[a-z_]*|[a-z_]" flixopt/ --include="*.py"— no remaining pipe delimiters (excluding clustering)python -m pytest tests/— all tests passpython -m mkdocs build— docs build