Time Series Clustering with cluster()¶

Accelerate investment optimization using typical periods (clustering).

This notebook demonstrates:

• Typical periods: Cluster similar time segments (e.g., days) and solve only representative ones
• Weighted costs: Automatically weight operational costs by cluster occurrence
• Two-stage workflow: Fast sizing with clustering, accurate dispatch at full resolution
• Segmentation: Reduce timesteps within each cluster for further compression

!!! note "Requirements" This notebook requires the tsam and tsam_xarray packages. Install with: pip install "flixopt[full]"

!!! tip "tsam_xarray" flixopt uses tsam_xarray for clustering, which wraps tsam. For advanced clustering options (custom algorithms, weights, tuning), see the tsam_xarray documentation.

Create the FlowSystem¶

We use a district heating system with real-world time series data (one month at 15-min resolution):

Method 1: Full Optimization (Baseline)¶

First, solve the complete problem with all 2976 timesteps:

Method 2: Clustering with cluster()¶

The cluster() method:

1. Clusters similar days using the TSAM (Time Series Aggregation Module) package
2. Reduces timesteps to only typical periods (e.g., 8 typical days = 768 timesteps)
3. Weights costs by how many original days each typical day represents
4. Handles storage with configurable behavior via storage_mode

!!! warning "Peak Forcing" Always use extremes=ExtremeConfig(max_value=[...]) to ensure extreme demand days are captured. Without this, clustering may miss peak periods, causing undersized components.

!!! note "Which variables get clustered?" By default, all time-varying inputs influence cluster assignments with equal weight (1.0). To see which variables cluster() will feed to tsam, call list(flow_system.transform.cluster_inputs()) — it lists every variable with a time dim (constants included).

To restrict clustering to a subset, pass explicit weights via
`ClusterConfig(weights={...})`. Variables listed with weight `0` are still
aggregated but don't influence cluster assignments; variables not listed
keep the default weight of `1.0`. Example:

```python
from tsam import ClusterConfig

cols = list(flow_system.transform.cluster_inputs())
target = 'HeatDemand(Q_th)|fixed_relative_profile'
weights = {target: 1, **{v: 0 for v in cols if v != target}}

fs_clustered = flow_system.transform.cluster(
    n_clusters=8, cluster_duration='1D',
    cluster=ClusterConfig(weights=weights),
    extremes=ExtremeConfig(method='new_cluster', max_value=[target]),
)
```

Understanding the Clustering¶

Access clustering metadata via fs.clustering. For full access to the underlying tsam_xarray ClusteringResult, use fs.clustering.clustering_result.

Apply Existing Clustering¶

When comparing design variants or performing sensitivity analysis, you often want to use the same cluster structure across different FlowSystem configurations. Use apply_clustering() to reuse a clustering from another FlowSystem:

# First, create a reference clustering
fs_reference = flow_system.transform.cluster(n_clusters=8, cluster_duration='1D')

# Modify the FlowSystem (e.g., different storage size)
flow_system_modified = flow_system.copy()
flow_system_modified.components['Storage'].capacity_in_flow_hours.maximum_size = 2000

# Apply the SAME clustering for fair comparison
fs_modified = flow_system_modified.transform.apply_clustering(fs_reference.clustering)

This ensures both systems use identical typical periods for fair comparison.

Method 3: Two-Stage Workflow (Recommended)¶

The recommended approach for investment optimization:

1. Stage 1: Fast sizing with cluster()
2. Stage 2: Fix sizes (with safety margin) and dispatch at full resolution

!!! tip "Safety Margin" Typical periods aggregate similar days, so individual days may have higher demand than the typical day. Adding a 5-10% margin ensures feasibility.

Compare Results¶

Expand Solution to Full Resolution¶

Use expand() to map the clustered solution back to all original timesteps. This repeats the typical period values for all days belonging to that cluster:

Visualize Clustered Heat Balance¶

API Reference¶

transform.cluster() Parameters¶

Clustering Object Properties¶

After clustering, access metadata via fs.clustering:

Storage Behavior¶

Each Storage component has a cluster_mode parameter:

For a detailed comparison of storage modes, see 08c2-clustering-storage-modes.

Summary¶

You learned how to:

• Use cluster() to reduce time series into typical periods
• Apply peak forcing with ExtremeConfig to capture extreme demand days
• Use two-stage optimization for fast yet accurate investment decisions
• Expand solutions back to full resolution with expand()
• Access clustering metadata via fs.clustering
• Apply existing clustering to other FlowSystems using apply_clustering()

Key Takeaways¶

1. Always use peak forcing (extremes=ExtremeConfig(max_value=[...])) for demand time series
2. Add safety margin (5-10%) when fixing sizes from clustering
3. Two-stage is recommended: clustering for sizing, full resolution for dispatch
4. Storage handling is configurable via cluster_mode
5. Use apply_clustering() to apply the same clustering to different FlowSystem variants
6. For advanced clustering options (weights, algorithms, segmentation, tuning), see tsam_xarray and tsam

Next Steps¶

• 08c2-clustering-storage-modes: Compare storage modes using a seasonal storage system