ClusteringAccessor

ClusteringAccessor(n: Network)

Clustering accessor for clustering a network spatially and temporally.

Clustering

Attributes:

• spatial (SpatialClusteringAccessor) –

  Access spatial clustering methods.

• temporal (TemporalClusteringAccessor) –

  Access temporal clustering methods.

pypsa.Network.cluster.spatial property

spatial: SpatialClusteringAccessor

Access spatial clustering methods.

Returns:

• SpatialClusteringAccessor –

  Accessor for spatial clustering operations.

Examples:

>>> n.cluster.spatial.busmap_by_kmeans(weighting, 50)
>>> n.cluster.spatial.cluster_by_busmap(busmap)
>>> n.cluster.spatial.cluster_by_kmeans(weighting, 50)

pypsa.Network.cluster.temporal property

temporal: TemporalClusteringAccessor

Access temporal clustering methods.

Returns:

• TemporalClusteringAccessor –

  Accessor for temporal clustering operations.

Examples:

>>> n.cluster.temporal.resample("3h")
>>> n.cluster.temporal.downsample(4)
>>> n.cluster.temporal.segment(100)

SpatialClusteringAccessor

SpatialClusteringAccessor(n: Network)

              flowchart TD
              pypsa.clustering.SpatialClusteringAccessor[SpatialClusteringAccessor]
              pypsa.clustering.spatial.SpatialClusteringMixin[SpatialClusteringMixin]

                              pypsa.clustering.spatial.SpatialClusteringMixin --> pypsa.clustering.SpatialClusteringAccessor
                


              click pypsa.clustering.SpatialClusteringAccessor href "" "pypsa.clustering.SpatialClusteringAccessor"
              click pypsa.clustering.spatial.SpatialClusteringMixin href "" "pypsa.clustering.spatial.SpatialClusteringMixin"
            

Spatial clustering accessor for clustering a network spatially.

Clustering

Methods:

• busmap_by_greedy_modularity –

  Create a busmap according to Clauset-Newman-Moore greedy modularity maximization.

• busmap_by_hac –

  Create a busmap according to Hierarchical Agglomerative Clustering.

• busmap_by_kmeans –

  Create a bus map from the clustering of buses in space with a weighting.

• cluster_by_busmap –

  Cluster the network spatially by busmap.

• cluster_by_greedy_modularity –

  Cluster the network using Clauset-Newman-Moore greedy modularity maximization.

• cluster_by_hac –

  Cluster the network using Hierarchical Agglomerative Clustering.

• cluster_by_kmeans –

  Cluster the network according to k-means clustering of the buses.

• get_clustering_from_busmap –

  Get a clustering result from a busmap.

pypsa.clustering.SpatialClusteringAccessor.busmap_by_greedy_modularity

busmap_by_greedy_modularity(n_clusters: int, buses_i: Index | None = None) -> Series

Create a busmap according to Clauset-Newman-Moore greedy modularity maximization.

See [CNM2004_1]_ for more details.

Parameters:

• n_clusters (int) –

  Final number of clusters desired.

• buses_i (Index | None, default: None ) –

  Subset of buses to cluster. If None, all buses are considered.

Returns:

• busmap ( Series ) –

  Mapping of n.buses to clusters (indexed by non-negative integers).

References

[CNM2004_1] Clauset, A., Newman, M. E., & Moore, C. "Finding community structure in very large networks." Physical Review E 70(6), 2004.

pypsa.clustering.SpatialClusteringAccessor.busmap_by_hac

busmap_by_hac(n_clusters: int, buses_i: Index | None = None, branch_components: Collection[str] | None = None, feature: DataFrame | None = None, affinity: str | Callable = 'euclidean', linkage: str = 'ward', **kwargs: Any) -> Series

Create a busmap according to Hierarchical Agglomerative Clustering.

Parameters:

• n_clusters (int) –

  Final number of clusters desired.

• buses_i (Index | None, default: None ) –

  Subset of buses to cluster. If None, all buses are considered.

• branch_components (Collection[str] | None, default: None ) –

  Subset of all branch_components in the network. If None, all branch_components are considered.

• feature (DataFrame | None, default: None ) –

  Feature to be considered for the clustering. The DataFrame must be indexed with buses_i. If None, all buses have the same similarity.

• affinity (str | Callable, default: 'euclidean' ) –

  Metric used to compute the linkage. Can be "euclidean", "l1", "l2", "manhattan", "cosine", or "precomputed". If linkage is "ward", only "euclidean" is accepted. If "precomputed", a distance matrix (instead of a similarity matrix) is needed as input for the fit method.

• linkage (str, default: 'ward' ) –

  Which linkage criterion to use. The linkage criterion determines which distance to use between sets of observation. The algorithm will merge the pairs of cluster that minimize this criterion. - 'ward' minimizes the variance of the clusters being merged. - 'average' uses the average of the distances of each observation of the two sets. - 'complete' or 'maximum' linkage uses the maximum distances between all observations of the two sets. - 'single' uses the minimum of the distances between all observations of the two sets.

• kwargs (Any, default: {} ) –

  Any remaining arguments to be passed to Hierarchical Clustering (e.g. memory, connectivity).

Returns:

• busmap ( Series ) –

  Mapping of n.buses to clusters (indexed by non-negative integers).

pypsa.clustering.SpatialClusteringAccessor.busmap_by_kmeans

busmap_by_kmeans(bus_weightings: Series, n_clusters: int, buses_i: Index | None = None, **kwargs: Any) -> Series

Create a bus map from the clustering of buses in space with a weighting.

Parameters:

• bus_weightings (Series) –

  Series of integer weights for buses, indexed by bus names.

• n_clusters (int) –

  Final number of clusters desired.

• buses_i (None | Index, default: None ) –

  If not None (default), subset of buses to cluster.

• kwargs (Any, default: {} ) –

  Any remaining arguments to be passed to KMeans (e.g. n_init, n_jobs).

Returns:

• busmap ( Series ) –

  Mapping of n.buses to k-means clusters (indexed by non-negative integers).

pypsa.clustering.SpatialClusteringAccessor.cluster_by_busmap

cluster_by_busmap(busmap: dict, with_time: bool = True, line_length_factor: float = 1.0, aggregate_generators_weighted: bool = False, aggregate_one_ports: dict | None = None, aggregate_generators_carriers: Iterable | None = None, scale_link_capital_costs: bool = True, bus_strategies: dict | None = None, one_port_strategies: dict | None = None, generator_strategies: dict | None = None, line_strategies: dict | None = None, aggregate_generators_buses: Iterable | None = None, custom_line_groupers: list | None = None) -> Network

Cluster the network spatially by busmap.

This function calls get_clustering_from_busmap internally. For more information, see the documentation of that function.

Returns:

• n ( Network ) –

pypsa.clustering.SpatialClusteringAccessor.cluster_by_greedy_modularity

cluster_by_greedy_modularity(n_clusters: int, buses_i: Index | None = None, line_length_factor: float = 1.0) -> Network

Cluster the network using Clauset-Newman-Moore greedy modularity maximization.

See [CNM2004_2]_ for more details.

Parameters:

• n_clusters (int) –

  Final number of clusters desired.

• buses_i (Index | None, default: None ) –

  Subset of buses to cluster. If None, all buses are considered.

• line_length_factor (float, default: 1.0 ) –

  Factor to multiply the spherical distance between two new buses to get new line lengths.

Returns:

• Network –

  The clustered network.

References

[CNM2004_2] Clauset, A., Newman, M. E., & Moore, C. "Finding community structure in very large networks." Physical Review E 70(6), 2004.

pypsa.clustering.SpatialClusteringAccessor.cluster_by_hac

cluster_by_hac(n_clusters: int, buses_i: Index | None = None, branch_components: Collection[str] | None = None, feature: DataFrame | None = None, affinity: str | Callable = 'euclidean', linkage: str = 'ward', line_length_factor: float = 1.0, **kwargs: Any) -> Network

Cluster the network using Hierarchical Agglomerative Clustering.

Parameters:

• n_clusters (int) –

  Final number of clusters desired.

• buses_i (Index | None, default: None ) –

  Subset of buses to cluster. If None, all buses are considered.

• branch_components (Collection[str] | None, default: None ) –

  Subset of all branch_components in the network.

• feature (DataFrame | None, default: None ) –

  Feature to be considered for the clustering. The DataFrame must be indexed with buses_i. If None, all buses have the same similarity.

• affinity (str | Callable, default: 'euclidean' ) –

  Metric used to compute the linkage. Can be "euclidean", "l1", "l2", "manhattan", "cosine", or "precomputed". If linkage is "ward", only "euclidean" is accepted. If "precomputed", a distance matrix (instead of a similarity matrix) is needed as input for the fit method.

• linkage (str, default: 'ward' ) –

  Which linkage criterion to use. The linkage criterion determines which distance to use between sets of observation. The algorithm will merge the pairs of cluster that minimize this criterion. - 'ward' minimizes the variance of the clusters being merged. - 'average' uses the average of the distances of each observation of the two sets. - 'complete' or 'maximum' linkage uses the maximum distances between all observations of the two sets. - 'single' uses the minimum of the distances between all observations of the two sets.

• line_length_factor (float, default: 1.0 ) –

  Factor to multiply the spherical distance between two new buses in order to get new line lengths.

• kwargs (Any, default: {} ) –

  Any remaining arguments to be passed to Hierarchical Clustering (e.g. memory, connectivity).

Returns:

• Network –

  The clustered network.

pypsa.clustering.SpatialClusteringAccessor.cluster_by_kmeans

cluster_by_kmeans(bus_weightings: Series, n_clusters: int, line_length_factor: float = 1.0, **kwargs: Any) -> Network

Cluster the network according to k-means clustering of the buses.

Buses can be weighted by an integer in the series bus_weightings.

Note that this clustering method completely ignores the branches of the network.

Parameters:

• bus_weightings (Series) –

  Series of integer weights for buses, indexed by bus names.

• n_clusters (int) –

  Final number of clusters desired.

• line_length_factor (float, default: 1.0 ) –

  Factor to multiply the spherical distance between new buses in order to get new line lengths.

• kwargs (Any, default: {} ) –

  Any remaining arguments to be passed to KMeans (e.g. n_init, n_jobs)

Returns:

• Network –

  The clustered network.

pypsa.clustering.SpatialClusteringAccessor.get_clustering_from_busmap

get_clustering_from_busmap(busmap: dict, with_time: bool = True, line_length_factor: float = 1.0, aggregate_generators_weighted: bool = False, aggregate_one_ports: dict | None = None, aggregate_generators_carriers: Iterable | None = None, scale_link_capital_costs: bool = True, bus_strategies: dict | None = None, one_port_strategies: dict | None = None, generator_strategies: dict | None = None, line_strategies: dict | None = None, aggregate_generators_buses: Iterable | None = None, custom_line_groupers: list | None = None) -> Clustering

Get a clustering result from a busmap.

TemporalClusteringAccessor

TemporalClusteringAccessor(n: Network)

              flowchart TD
              pypsa.clustering.TemporalClusteringAccessor[TemporalClusteringAccessor]
              pypsa.clustering.temporal.TemporalClusteringMixin[TemporalClusteringMixin]

                              pypsa.clustering.temporal.TemporalClusteringMixin --> pypsa.clustering.TemporalClusteringAccessor
                


              click pypsa.clustering.TemporalClusteringAccessor href "" "pypsa.clustering.TemporalClusteringAccessor"
              click pypsa.clustering.temporal.TemporalClusteringMixin href "" "pypsa.clustering.temporal.TemporalClusteringMixin"
            

Temporal clustering accessor for clustering a network temporally.

Provides methods to reduce temporal resolution of networks while preserving total modeled hours through snapshot weighting adjustments.

Examples:

>>> n.cluster.temporal.resample("3h")
>>> n.cluster.temporal.downsample(4)
>>> n.cluster.temporal.segment(100)

Methods:

• downsample –

  Select every Nth snapshot as representative.

• from_snapshot_map –

  Apply pre-computed temporal aggregation mapping.

• get_downsample_result –

  Get full TemporalClustering result from downsample.

• get_from_snapshot_map_result –

  Get full TemporalClustering result from from_snapshot_map.

• get_resample_result –

  Get full TemporalClustering result from resample.

• get_segment_result –

  Get full TemporalClustering result from segment.

• resample –

  Resample network to coarser temporal resolution.

• segment –

  Cluster time series into variable-duration segments using TSAM.

pypsa.clustering.TemporalClusteringAccessor.downsample

downsample(stride: int) -> Network

Select every Nth snapshot as representative.

Weightings are scaled by stride to preserve total modeled hours.

Parameters:

• stride (int) –

  Select every stride-th snapshot.

Returns:

• Network –

  The downsampled network.

Examples:

>>> m = n.cluster.temporal.downsample(4)

pypsa.clustering.TemporalClusteringAccessor.from_snapshot_map

from_snapshot_map(snapshot_map: Series | DataFrame, *, aggregation_rules: dict[str, str] | None = None) -> Network

Apply pre-computed temporal aggregation mapping.

Parameters:

• snapshot_map (Series or DataFrame) –

  Mapping from original snapshots to aggregated snapshots. If DataFrame, must have 'snapshot' index and columns for weightings.

• aggregation_rules (dict, default: None ) –

  Override default aggregation per attribute.

Returns:

• Network –

  The aggregated network.

pypsa.clustering.TemporalClusteringAccessor.get_downsample_result

get_downsample_result(stride: int) -> TemporalClustering

Get full TemporalClustering result from downsample.

Returns the full result including both the clustered network and the snapshot mapping.

Parameters:

• stride (int) –

  Select every stride-th snapshot.

Returns:

• TemporalClustering –

  Result with downsampled network and snapshot mapping.

pypsa.clustering.TemporalClusteringAccessor.get_from_snapshot_map_result

get_from_snapshot_map_result(snapshot_map: Series | DataFrame, *, aggregation_rules: dict[str, str] | None = None) -> TemporalClustering

Get full TemporalClustering result from from_snapshot_map.

Returns the full result including both the clustered network and the snapshot mapping.

Parameters:

• snapshot_map (Series or DataFrame) –

  Mapping from original snapshots to aggregated snapshots. If DataFrame, must have 'snapshot' index and columns for weightings.

• aggregation_rules (dict, default: None ) –

  Override default aggregation per attribute.

Returns:

• TemporalClustering –

  Result with aggregated network and snapshot mapping.

pypsa.clustering.TemporalClusteringAccessor.get_resample_result

get_resample_result(offset: str, *, drop_leap_day: bool = False, aggregation_rules: dict[str, str] | None = None) -> TemporalClustering

Get full TemporalClustering result from resample.

Returns the full result including both the clustered network and the snapshot mapping. Use this when you need the snapshot_map for disaggregation or debugging.

Parameters:

• offset (str) –

  Pandas offset string (e.g., "3h", "6h", "24h").

• drop_leap_day (bool, default: False ) –

  Transfer Feb 29 weights to March 1.

• aggregation_rules (dict, default: None ) –

  Override default aggregation per attribute.

Returns:

• TemporalClustering –

  Result with clustered network and snapshot mapping.

pypsa.clustering.TemporalClusteringAccessor.get_segment_result

get_segment_result(num_segments: int, *, solver: str = 'highs', exclude_attrs: list[str] | None = None, aggregation_rules: dict[str, str] | None = None) -> TemporalClustering

Get full TemporalClustering result from segment.

Returns the full result including both the clustered network and the snapshot mapping.

Parameters:

• num_segments (int) –

  Target number of segments.

• solver (str, default: "highs" ) –

  MIP solver for time clustering.

• exclude_attrs (list, default: None ) –

  Attributes to exclude from clustering (default: ["e_min_pu"]).

• aggregation_rules (dict, default: None ) –

  Override default aggregation per attribute.

Returns:

• TemporalClustering –

  Result with segmented network and snapshot mapping.

pypsa.clustering.TemporalClusteringAccessor.resample

resample(offset: str, *, drop_leap_day: bool = False, aggregation_rules: dict[str, str] | None = None) -> Network

Resample network to coarser temporal resolution.

Parameters:

• offset (str) –

  Pandas offset string (e.g., "3h", "6h", "24h").

• drop_leap_day (bool, default: False ) –

  Transfer Feb 29 weights to March 1.

• aggregation_rules (dict, default: None ) –

  Override default aggregation per attribute.

Returns:

• Network –

  The resampled network.

Note

This is not an inplace operation. Returns a new network.

Examples:

>>> m = n.cluster.temporal.resample("3h")

pypsa.clustering.TemporalClusteringAccessor.segment

segment(num_segments: int, *, solver: str = 'highs', exclude_attrs: list[str] | None = None, aggregation_rules: dict[str, str] | None = None) -> Network

Cluster time series into variable-duration segments using TSAM.

Parameters:

• num_segments (int) –

  Target number of segments.

• solver (str, default: "highs" ) –

  MIP solver for time clustering.

• exclude_attrs (list, default: None ) –

  Attributes to exclude from clustering (default: ["e_min_pu"]).

• aggregation_rules (dict, default: None ) –

  Override default aggregation per attribute.

Returns:

• Network –

  The segmented network.

Note

Requires tsam package: pip install tsam