flixOpt · FBumann · Dec 8, 2025 · Nov 28, 2025 · Nov 28, 2025 · Nov 28, 2025
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -763,6 +763,26 @@ button:focus-visible {
   scrollbar-color: var(--md-default-fg-color--lighter) var(--md-default-bg-color);
 }
 
+/* ============================================================================
+   Color Swatches for Carrier Documentation
+   ========================================================================= */
+
+/* Inline color swatch - a small colored square */
+.color-swatch {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  border-radius: 3px;
+  vertical-align: middle;
+  margin-right: 0.3em;
+  border: 1px solid rgba(0, 0, 0, 0.15);
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
+}
+
+[data-md-color-scheme="slate"] .color-swatch {
+  border-color: rgba(255, 255, 255, 0.2);
+}
+
 /* ============================================================================
    Footer Alignment Fix
    ========================================================================= */

diff --git a/docs/user-guide/core-concepts.md b/docs/user-guide/core-concepts.md
@@ -31,6 +31,17 @@ $$\sum inputs = \sum outputs$$
 
 This balance constraint is what makes your model physically meaningful — energy can't appear or disappear.
 
+### Carriers
+
+Buses can be assigned a **carrier** — a type of energy or material (electricity, heat, gas, etc.). Carriers enable automatic coloring in plots and help organize your system semantically:
+
+```python
+heat_bus = fx.Bus('HeatNetwork', carrier='heat')  # Uses default heat color
+elec_bus = fx.Bus('Grid', carrier='electricity')
+```
+
+See [Color Management](results-plotting.md#color-management) for details.
+
 ## Flows: What Moves Between Elements
 
 A [`Flow`][flixopt.elements.Flow] represents the movement of energy or material. Every flow connects a component to a bus, with a defined direction.

diff --git a/docs/user-guide/mathematical-notation/elements/Bus.md b/docs/user-guide/mathematical-notation/elements/Bus.md
@@ -2,6 +2,29 @@
 
 A Bus is where flows meet and must balance — inputs equal outputs at every timestep.
 
+## Carriers
+
+Buses can optionally be assigned a **carrier** — a type of energy or material (e.g., electricity, heat, gas). Carriers enable:
+
+- **Automatic coloring** in plots based on energy type
+- **Unit tracking** for better result visualization
+- **Semantic grouping** of buses by type
+
+```python
+# Assign a carrier by name (uses CONFIG.Carriers defaults)
+heat_bus = fx.Bus('HeatNetwork', carrier='heat')
+elec_bus = fx.Bus('Grid', carrier='electricity')
+
+# Or register custom carriers on the FlowSystem
+biogas = fx.Carrier('biogas', color='#228B22', unit='kW', description='Biogas fuel')
+flow_system.add_carrier(biogas)
+gas_bus = fx.Bus('BiogasNetwork', carrier='biogas')
+```
+
+See [Color Management](../../../user-guide/results-plotting.md#color-management) for more on how carriers affect visualization.
+
+---
+
 ## Basic: Balance Equation
 
 $$

diff --git a/docs/user-guide/results-plotting.md b/docs/user-guide/results-plotting.md
@@ -318,6 +318,113 @@ flow_system.statistics.plot.balance('Bus', colors={
 })
 ```
 
+## Color Management
+
+flixOpt provides centralized color management through the `flow_system.colors` accessor and carriers. This ensures consistent colors across all visualizations.
+
+### Carriers
+
+[`Carriers`][flixopt.carrier.Carrier] define energy or material types with associated colors. Built-in carriers are available in `CONFIG.Carriers`:
+
+| Carrier | Color | Description |
+|---------|-------|-------------|
+| `electricity` | <span class="color-swatch" style="background:#FECB52"></span>`#FECB52` | Yellow - lightning/energy |
+| `heat` | <span class="color-swatch" style="background:#D62728"></span>`#D62728` | Red - warmth/fire |
+| `gas` | <span class="color-swatch" style="background:#1F77B4"></span>`#1F77B4` | Blue - natural gas |
+| `hydrogen` | <span class="color-swatch" style="background:#9467BD"></span>`#9467BD` | Purple - clean/future |
+| `fuel` | <span class="color-swatch" style="background:#8C564B"></span>`#8C564B` | Brown - fossil/oil |
+| `biomass` | <span class="color-swatch" style="background:#2CA02C"></span>`#2CA02C` | Green - organic/renewable |
+
+Colors are from the D3/Plotly palettes for professional consistency.
+
+Assign carriers to buses for automatic coloring:
+
+```python
+# Buses use carrier colors automatically
+heat_bus = fx.Bus('HeatNetwork', carrier='heat')
+elec_bus = fx.Bus('Grid', carrier='electricity')
+
+# Plots automatically use carrier colors for bus-related elements
+flow_system.statistics.plot.sankey()  # Buses colored by carrier
+```
+
+### Custom Carriers
+
+Register custom carriers on your FlowSystem:
+
+```python
+# Create a custom carrier
+biogas = fx.Carrier('biogas', color='#228B22', unit='kW', description='Biogas fuel')
+hydrogen = fx.Carrier('hydrogen', color='#00CED1', unit='kg/h')
+
+# Register with FlowSystem (overrides CONFIG.Carriers defaults)
+flow_system.add_carrier(biogas)
+flow_system.add_carrier(hydrogen)
+
+# Access registered carriers
+flow_system.carriers  # CarrierContainer with locally registered carriers
+flow_system.get_carrier('biogas')  # Returns Carrier object
+```
+
+### Color Accessor
+
+The `flow_system.colors` accessor provides centralized color configuration:
+
+```python
+# Configure colors for components
+flow_system.colors.setup({
+    'Boiler': '#D35400',
+    'CHP': '#8E44AD',
+    'HeatPump': '#27AE60',
+})
+
+# Or set individual colors
+flow_system.colors.set_component_color('Boiler', '#D35400')
+flow_system.colors.set_carrier_color('biogas', '#228B22')
+
+# Load from file
+flow_system.colors.setup('colors.json')  # or .yaml
+```
+
+### Context-Aware Coloring
+
+Plot colors are automatically resolved based on context:
+
+- **Bus balance plots**: Colors based on the connected component
+- **Component balance plots**: Colors based on the connected bus/carrier
+- **Sankey diagrams**: Buses use carrier colors, components use configured colors
+
+```python
+# Plotting a bus balance → flows colored by their parent component
+flow_system.statistics.plot.balance('ElectricityBus')
+
+# Plotting a component balance → flows colored by their connected bus/carrier
+flow_system.statistics.plot.balance('CHP')
+```
+
+### Color Resolution Priority
+
+Colors are resolved in this order:
+
+1. **Explicit colors** passed to plot methods (always override)
+2. **Component/bus colors** set via `flow_system.colors.setup()`
+3. **Element `meta_data['color']`** if present
+4. **Carrier colors** from FlowSystem or CONFIG.Carriers
+5. **Default colorscale** (controlled by `CONFIG.Plotting.default_qualitative_colorscale`)
+
+### Persistence
+
+Color configurations are automatically saved with the FlowSystem:
+
+```python
+# Colors are persisted
+flow_system.to_netcdf('my_system.nc')
+
+# And restored
+loaded = fx.FlowSystem.from_netcdf('my_system.nc')
+loaded.colors  # Configuration restored
+```
+
 ### Display Control
 
 Control whether plots are shown automatically:

diff --git a/examples/01_Simple/simple_example.py b/examples/01_Simple/simple_example.py
@@ -21,7 +21,12 @@
 
     # --- Define Energy Buses ---
     # These represent nodes, where the used medias are balanced (electricity, heat, and gas)
-    flow_system.add_elements(fx.Bus(label='Strom'), fx.Bus(label='Fernwärme'), fx.Bus(label='Gas'))
+    # Carriers provide automatic color assignment in plots (yellow for electricity, red for heat, etc.)
+    flow_system.add_elements(
+        fx.Bus(label='Strom', carrier='electricity'),
+        fx.Bus(label='Fernwärme', carrier='heat'),
+        fx.Bus(label='Gas', carrier='gas'),
+    )
 
     # --- Define Effects (Objective and CO2 Emissions) ---
     # Cost effect: used as the optimization objective --> minimizing costs
@@ -109,13 +114,14 @@
     # Plotting through statistics accessor - returns PlotResult with .data and .figure
     flow_system.statistics.plot.balance('Fernwärme')
     flow_system.statistics.plot.balance('Storage')
-    flow_system.statistics.plot.heatmap('CHP(Q_th)|flow_rate')
-    flow_system.statistics.plot.heatmap('Storage|charge_state')
+    flow_system.statistics.plot.heatmap('CHP(Q_th)')
+    flow_system.statistics.plot.heatmap('Storage')
+    flow_system.statistics.plot.heatmap('Storage')
 
     # Access data as xarray Datasets
     print(flow_system.statistics.flow_rates)
     print(flow_system.statistics.charge_states)
 
     # Duration curve and effects analysis
-    flow_system.statistics.plot.duration_curve('Boiler(Q_th)|flow_rate')
+    flow_system.statistics.plot.duration_curve('Boiler(Q_th)')
     print(flow_system.statistics.temporal_effects)
diff --git a/examples/02_Complex/complex_example.py b/examples/02_Complex/complex_example.py
@@ -32,10 +32,11 @@
 
     # --- Define Energy Buses ---
     # Represent node balances (inputs=outputs) for the different energy carriers (electricity, heat, gas) in the system
+    # Carriers provide automatic color assignment in plots (yellow for electricity, red for heat, blue for gas)
     flow_system.add_elements(
-        fx.Bus('Strom', imbalance_penalty_per_flow_hour=imbalance_penalty),
-        fx.Bus('Fernwärme', imbalance_penalty_per_flow_hour=imbalance_penalty),
-        fx.Bus('Gas', imbalance_penalty_per_flow_hour=imbalance_penalty),
+        fx.Bus('Strom', carrier='electricity', imbalance_penalty_per_flow_hour=imbalance_penalty),
+        fx.Bus('Fernwärme', carrier='heat', imbalance_penalty_per_flow_hour=imbalance_penalty),
+        fx.Bus('Gas', carrier='gas', imbalance_penalty_per_flow_hour=imbalance_penalty),
     )
 
     # --- Define Effects ---
@@ -200,7 +201,7 @@
     flow_system.to_netcdf('results/complex_example.nc')
 
     # Plot results using the statistics accessor
-    flow_system.statistics.plot.heatmap('BHKW2(Q_th)|flow_rate')
+    flow_system.statistics.plot.heatmap('BHKW2(Q_th)')  # Flow label - auto-resolves to flow_rate
     flow_system.statistics.plot.balance('BHKW2')
-    flow_system.statistics.plot.heatmap('Speicher|charge_state')
+    flow_system.statistics.plot.heatmap('Speicher')  # Storage label - auto-resolves to charge_state
     flow_system.statistics.plot.balance('Fernwärme')
diff --git a/examples/03_Optimization_modes/example_optimization_modes.py b/examples/03_Optimization_modes/example_optimization_modes.py
@@ -69,10 +69,10 @@ def get_solutions(optimizations: list, variable: str) -> xr.Dataset:
 
     flow_system = fx.FlowSystem(timesteps)
     flow_system.add_elements(
-        fx.Bus('Strom', imbalance_penalty_per_flow_hour=imbalance_penalty),
-        fx.Bus('Fernwärme', imbalance_penalty_per_flow_hour=imbalance_penalty),
-        fx.Bus('Gas', imbalance_penalty_per_flow_hour=imbalance_penalty),
-        fx.Bus('Kohle', imbalance_penalty_per_flow_hour=imbalance_penalty),
+        fx.Bus('Strom', carrier='electricity', imbalance_penalty_per_flow_hour=imbalance_penalty),
+        fx.Bus('Fernwärme', carrier='heat', imbalance_penalty_per_flow_hour=imbalance_penalty),
+        fx.Bus('Gas', carrier='gas', imbalance_penalty_per_flow_hour=imbalance_penalty),
+        fx.Bus('Kohle', carrier='fuel', imbalance_penalty_per_flow_hour=imbalance_penalty),
     )
 
     # Effects

diff --git a/examples/04_Scenarios/scenario_example.py b/examples/04_Scenarios/scenario_example.py
@@ -89,7 +89,12 @@
 
     # --- Define Energy Buses ---
     # These represent nodes, where the used medias are balanced (electricity, heat, and gas)
-    flow_system.add_elements(fx.Bus(label='Strom'), fx.Bus(label='Fernwärme'), fx.Bus(label='Gas'))
+    # Carriers provide automatic color assignment in plots (yellow for electricity, red for heat, blue for gas)
+    flow_system.add_elements(
+        fx.Bus(label='Strom', carrier='electricity'),
+        fx.Bus(label='Fernwärme', carrier='heat'),
+        fx.Bus(label='Gas', carrier='gas'),
+    )
 
     # --- Define Effects (Objective and CO2 Emissions) ---
     # Cost effect: used as the optimization objective --> minimizing costs
@@ -199,10 +204,10 @@
 
     # --- Analyze Results ---
     # Plotting through statistics accessor - returns PlotResult with .data and .figure
-    flow_system.statistics.plot.heatmap('CHP(Q_th)|flow_rate')
+    flow_system.statistics.plot.heatmap('CHP(Q_th)')  # Flow label - auto-resolves to flow_rate
     flow_system.statistics.plot.balance('Fernwärme')
     flow_system.statistics.plot.balance('Storage')
-    flow_system.statistics.plot.heatmap('Storage|charge_state')
+    flow_system.statistics.plot.heatmap('Storage')  # Storage label - auto-resolves to charge_state
 
     # Access data as xarray Datasets
     print(flow_system.statistics.flow_rates)

diff --git a/examples/05_Two-stage-optimization/two_stage_optimization.py b/examples/05_Two-stage-optimization/two_stage_optimization.py
@@ -37,11 +37,12 @@
     gas_price = filtered_data['Gaspr.€/MWh'].to_numpy()
 
     flow_system = fx.FlowSystem(timesteps)
+    # Carriers provide automatic color assignment in plots
     flow_system.add_elements(
-        fx.Bus('Strom'),
-        fx.Bus('Fernwärme'),
-        fx.Bus('Gas'),
-        fx.Bus('Kohle'),
+        fx.Bus('Strom', carrier='electricity'),
+        fx.Bus('Fernwärme', carrier='heat'),
+        fx.Bus('Gas', carrier='gas'),
+        fx.Bus('Kohle', carrier='fuel'),
         fx.Effect('costs', '€', 'Kosten', is_standard=True, is_objective=True),
         fx.Effect('CO2', 'kg', 'CO2_e-Emissionen'),
         fx.Effect('PE', 'kWh_PE', 'Primärenergie'),

diff --git a/flixopt/__init__.py b/flixopt/__init__.py
@@ -14,6 +14,7 @@
 
 # Import commonly used classes and functions
 from . import linear_converters, plotting, results, solvers
+from .carrier import Carrier, CarrierContainer
 from .clustering import ClusteringParameters
 from .components import (
     LinearConverter,
@@ -34,6 +35,8 @@
 __all__ = [
     'TimeSeriesData',
     'CONFIG',
+    'Carrier',
+    'CarrierContainer',
     'Flow',
     'Bus',
     'Effect',