flixOpt
diff --git a/‎docs/home/quick-start.md‎
Lines changed: 19 additions & 7 deletions b/‎docs/home/quick-start.md‎
Lines changed: 19 additions & 7 deletions
diff --git a/‎docs/user-guide/core-concepts.md‎
Lines changed: 21 additions & 10 deletions b/‎docs/user-guide/core-concepts.md‎
Lines changed: 21 additions & 10 deletions
diff --git a/‎docs/user-guide/migration-guide-v6.md‎
Lines changed: 25 additions & 0 deletions b/‎docs/user-guide/migration-guide-v6.md‎
Lines changed: 25 additions & 0 deletions
diff --git a/‎docs/user-guide/optimization/index.md‎
Lines changed: 116 additions & 0 deletions b/‎docs/user-guide/optimization/index.md‎
Lines changed: 116 additions & 0 deletions
@@ -88,21 +88,31 @@ battery = fx.Storage(
 flow_system.add_elements(solar, demand, battery, electricity_bus)
 ```
 
-### 5. Run Optimization
+### 5. Visualize and Run Optimization
 
 ```python
-# Run optimization directly on the flow system
+# Optional: visualize your system structure
+flow_system.topology.plot(path='system.html')
+
+# Run optimization
 flow_system.optimize(fx.solvers.HighsSolver())
 ```
 
-### 6. Access Results
+### 6. Access and Visualize Results
 
 ```python
-# Access results directly from the flow system
+# Access raw solution data
 print(flow_system.solution)
 
-# Or access component-specific results
+# Use statistics for aggregated data
+print(flow_system.statistics.flow_hours)
+
+# Access component-specific results
 print(flow_system.components['battery'].solution)
+
+# Visualize results
+flow_system.statistics.plot.balance('electricity')
+flow_system.statistics.plot.storage('battery')
 ```
 
 ### 7. Save Results (Optional)
@@ -132,8 +142,10 @@ Most flixOpt projects follow this pattern:
 2. **Create flow system** - Initialize with time series and effects
 3. **Add buses** - Define connection points
 4. **Add components** - Create generators, storage, converters, loads
-5. **Run optimization** - Call `flow_system.optimize(solver)`
-6. **Access Results** - Via `flow_system.solution` or component `.solution` attributes
+5. **Verify structure** - Use `flow_system.topology.plot()` to visualize
+6. **Run optimization** - Call `flow_system.optimize(solver)`
+7. **Analyze results** - Via `flow_system.statistics` and `.solution`
+8. **Visualize** - Use `flow_system.statistics.plot.*` methods
 
 ## Tips
 
 
@@ -127,23 +127,29 @@ Define your system structure, parameters, and time series data.
 
 ### 2. Run the Optimization
 
-Create an [`Optimization`][flixopt.optimization.Optimization] and solve it:
+Optimize your FlowSystem with a solver:
 
 ```python
-optimization = fx.Optimization('my_model', flow_system)
-results = optimization.solve(fx.solvers.HighsSolver())
+flow_system.optimize(fx.solvers.HighsSolver())
 ```
 
 ### 3. Analyze Results
 
-The [`Results`][flixopt.results.Results] object contains all solution data:
+Access solution data directly from the FlowSystem:
 
 ```python
-# Access component results
-boiler_output = results['Boiler'].node_balance()
+# Access component solutions
+boiler = flow_system.components['Boiler']
+print(boiler.solution)
 
 # Get total costs
-total_costs = results.solution['Costs']
+total_costs = flow_system.solution['costs|total']
+
+# Use statistics for aggregated data
+print(flow_system.statistics.flow_hours)
+
+# Plot results
+flow_system.statistics.plot.balance('HeatBus')
 ```
 
 <figure markdown>
@@ -185,12 +191,17 @@ While our example used a heating system, flixOpt works for any flow-based optimi
 flixOpt is built on [linopy](https://github.com/PyPSA/linopy). You can access and extend the underlying optimization model for custom constraints:
 
 ```python
-# Access the linopy model after building
-optimization.do_modeling()
-model = optimization.model
+# Build the model (without solving)
+flow_system.build_model()
+
+# Access the linopy model
+model = flow_system.model
 
 # Add custom constraints using linopy API
 model.add_constraints(...)
+
+# Then solve
+flow_system.solve(fx.solvers.HighsSolver())
 ```
 
 This allows advanced users to add domain-specific constraints while keeping flixOpt's convenience for standard modeling.
@@ -296,6 +296,31 @@ The new API also applies to advanced optimization modes:
 
 ---
 
+## Statistics Accessor
+
+The new `statistics` accessor provides convenient aggregated data:
+
+```python
+stats = flow_system.statistics
+
+# Flow data (clean labels, no |flow_rate suffix)
+stats.flow_rates['Boiler(Q_th)']  # Not 'Boiler(Q_th)|flow_rate'
+stats.flow_hours['Boiler(Q_th)']
+stats.sizes['Boiler(Q_th)']
+stats.charge_states['Battery']
+
+# Effect breakdown by contributor (replaces effects_per_component)
+stats.temporal_effects['costs']  # Per timestep, per contributor
+stats.periodic_effects['costs']  # Investment costs per contributor
+stats.total_effects['costs']     # Total per contributor
+
+# Group by component or component type
+stats.total_effects['costs'].groupby('component').sum()
+stats.total_effects['costs'].groupby('component_type').sum()
+```
+
+---
+
 ## 🔧 Quick Reference
 
 ### Common Conversions
 
@@ -2,6 +2,21 @@
 
 This section covers how to run optimizations in flixOpt, including different optimization modes and solver configuration.
 
+## Verifying Your Model
+
+Before running an optimization, it's helpful to visualize your system structure:
+
+```python
+# Generate an interactive network diagram
+flow_system.topology.plot(path='my_system.html')
+
+# Or get structure info programmatically
+nodes, edges = flow_system.topology.infos()
+print(f"Components: {[n for n, d in nodes.items() if d['class'] == 'Component']}")
+print(f"Buses: {[n for n, d in nodes.items() if d['class'] == 'Bus']}")
+print(f"Flows: {list(edges.keys())}")
+```
+
 ## Standard Optimization
 
 The recommended way to run an optimization is directly on the `FlowSystem`:
@@ -78,6 +93,107 @@ print(clustered_fs.solution)
 | Standard | Small-Medium | Slow | Optimal |
 | Clustered | Very Large | Fast | Approximate |
 
+## Custom Constraints
+
+flixOpt is built on [linopy](https://github.com/PyPSA/linopy), allowing you to add custom constraints beyond what's available through the standard API.
+
+### Adding Custom Constraints
+
+To add custom constraints, build the model first, then access the underlying linopy model:
+
+```python
+# Build the model (without solving)
+flow_system.build_model()
+
+# Access the linopy model
+model = flow_system.model
+
+# Access variables from the solution namespace
+# Variables are named: "ElementLabel|variable_name"
+boiler_flow = model.variables['Boiler(Q_th)|flow_rate']
+chp_flow = model.variables['CHP(Q_th)|flow_rate']
+
+# Add a custom constraint: Boiler must produce at least as much as CHP
+model.add_constraints(
+    boiler_flow >= chp_flow,
+    name='boiler_min_chp'
+)
+
+# Solve with the custom constraint
+flow_system.solve(fx.solvers.HighsSolver())
+```
+
+### Common Use Cases
+
+**Minimum runtime constraint:**
+```python
+# Require component to run at least 100 hours total
+on_var = model.variables['CHP|on']  # Binary on/off variable
+hours = flow_system.hours_per_timestep
+model.add_constraints(
+    (on_var * hours).sum() >= 100,
+    name='chp_min_runtime'
+)
+```
+
+**Linking flows across components:**
+```python
+# Heat pump and boiler combined must meet minimum base load
+hp_flow = model.variables['HeatPump(Q_th)|flow_rate']
+boiler_flow = model.variables['Boiler(Q_th)|flow_rate']
+model.add_constraints(
+    hp_flow + boiler_flow >= 50,  # At least 50 kW combined
+    name='min_heat_supply'
+)
+```
+
+**Seasonal constraints:**
+```python
+import pandas as pd
+
+# Different constraints for summer vs winter
+summer_mask = flow_system.timesteps.month.isin([6, 7, 8])
+winter_mask = flow_system.timesteps.month.isin([12, 1, 2])
+
+flow_var = model.variables['Boiler(Q_th)|flow_rate']
+
+# Lower capacity in summer
+model.add_constraints(
+    flow_var.sel(time=flow_system.timesteps[summer_mask]) <= 100,
+    name='summer_limit'
+)
+```
+
+### Inspecting the Model
+
+Before adding constraints, inspect available variables and existing constraints:
+
+```python
+flow_system.build_model()
+model = flow_system.model
+
+# List all variables
+print(model.variables)
+
+# List all constraints
+print(model.constraints)
+
+# Get details about a specific variable
+print(model.variables['Boiler(Q_th)|flow_rate'])
+```
+
+### Variable Naming Convention
+
+Variables follow this naming pattern:
+
+| Element Type | Pattern | Example |
+|--------------|---------|---------|
+| Flow rate | `Component(FlowLabel)\|flow_rate` | `Boiler(Q_th)\|flow_rate` |
+| Flow size | `Component(FlowLabel)\|size` | `Boiler(Q_th)\|size` |
+| On/off status | `Component\|on` | `CHP\|on` |
+| Charge state | `Storage\|charge_state` | `Battery\|charge_state` |
+| Effect totals | `effect_name\|total` | `costs\|total` |
+
 ## Solver Configuration
 
 ### Available Solvers