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

!!! note "Requirements" This notebook requires the tsam package with ClusterConfig and ExtremeConfig support. Install with: pip install "flixopt[full]"

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.

Understanding the Clustering¶

The clustering algorithm groups similar days together. Access all metadata via fs.clustering:

Inspect Clustering Input Data¶

Before clustering, you can inspect which time-varying data will be used. The clustering_data() method returns only the arrays that vary over time (constant arrays are excluded since they don't affect clustering):

Selective Clustering with data_vars¶

By default, clustering uses all time-varying data to determine typical periods. However, you may want to cluster based on only a subset of variables while still applying the clustering to all data.

Use the data_vars parameter to specify which variables determine the clustering:

• Cluster based on subset: Only the specified variables affect which days are grouped together
• Apply to all data: The resulting clustering is applied to ALL time-varying data

This is useful when:

• You want to cluster based on demand patterns only (ignoring price variations)
• You have dominant time series that should drive the clustering
• You want to ensure certain patterns are well-represented in typical periods

Advanced Clustering Options¶

The cluster() method exposes many parameters for fine-tuning:

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¶

transform.clustering_data() Method¶

Inspect which time-varying data will be used for clustering:

# Get all time-varying variables
clustering_data = flow_system.transform.clustering_data()
print(list(clustering_data.data_vars))

# Get data for a specific period (multi-period systems)
clustering_data = flow_system.transform.clustering_data(period=2024)

Clustering Object Properties¶

After clustering, access metadata via fs.clustering:

ClusteringResults (xarray-like)¶

Access the underlying tsam results via clustering.results:

# Dimension info (like xarray)
clustering.results.dims      # ('period', 'scenario') or ()
clustering.results.coords    # {'period': [2020, 2030], 'scenario': ['high', 'low']}

# Select specific result (like xarray)
clustering.results.sel(period=2020, scenario='high')   # Label-based
clustering.results.isel(period=0, scenario=1)          # Index-based

# Apply existing clustering to new data
agg_results = clustering.results.apply(dataset)  # Returns AggregationResults

Storage Behavior¶

Each Storage component has a cluster_mode parameter:

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

Peak Forcing with ExtremeConfig¶

from tsam import ExtremeConfig

extremes = ExtremeConfig(
    method='new_cluster',  # Creates new cluster for extremes
    max_value=['ComponentName(FlowName)|fixed_relative_profile'],  # Capture peak demand
    preserve_n_clusters=True,  # Keep total cluster count unchanged
)

Recommended Workflow¶

from tsam import ExtremeConfig

# Stage 1: Fast sizing
fs_sizing = flow_system.transform.cluster(
    n_clusters=8,
    cluster_duration='1D',
    extremes=ExtremeConfig(method='new_cluster', max_value=['Demand(Flow)|fixed_relative_profile'], preserve_n_clusters=True),
)
fs_sizing.optimize(solver)

# Apply safety margin
sizes = {k: v.item() * 1.05 for k, v in fs_sizing.stats.sizes.items()}

# Stage 2: Accurate dispatch
fs_dispatch = flow_system.transform.fix_sizes(sizes)
fs_dispatch.optimize(solver)

Summary¶

You learned how to:

• Use cluster() to reduce time series into typical periods
• Inspect clustering data with clustering_data() before clustering
• Use data_vars to cluster based on specific variables only
• 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 (metrics, cluster_assignments, cluster_occurrences)
• Use advanced options like different algorithms with ClusterConfig
• 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. Inspect data first with clustering_data() to see available variables
3. Use data_vars to cluster on specific variables (e.g., demand only, ignoring prices)
4. Add safety margin (5-10%) when fixing sizes from clustering
5. Two-stage is recommended: clustering for sizing, full resolution for dispatch
6. Storage handling is configurable via cluster_mode
7. Check metrics to evaluate clustering quality
8. Use apply_clustering() to apply the same clustering to different FlowSystem variants

Next Steps¶

• 08c2-clustering-storage-modes: Compare storage modes using a seasonal storage system
• 08d-clustering-multiperiod: Clustering with multiple periods and scenarios