engine.clustering

聚类方法注册表：6 种分组策略（K-means / 启发式 / 混合优化）。

Attributes

CLUSTER_METHODS

Functions

cluster_by_distance_kmeans(spots, depot, n_clusters)	基于地理坐标的 K-means 聚类。
cluster_by_time_window(spots, depot, n_clusters)	基于时间窗特征的 K-means 聚类。
cluster_by_spatiotemporal(spots, depot, n_clusters[, ...])	时空联合聚类（距离 + 时间窗）。
cluster_by_time_overlap(spots, depot, n_clusters)	时间窗重叠启发式分组。
cluster_by_time_density(spots, depot, n_clusters)	基于时间窗密度的 K-means 聚类。
cluster_hybrid_optimized(spots, cost_mat, depot, ...)	混合优化分组（时间窗排序 + 距离优化重分配）。
call_cluster(→ list[list[int]])	统一调用聚类方法。
pure_name(→ str)	从带编号的全称中提取纯方法名，如 '1. xxx' → 'xxx'
find_method_func(name)	通过方法名查找对应的函数对象

Module Contents

engine.clustering.cluster_by_distance_kmeans(spots: dict, depot: int, n_clusters: int)

基于地理坐标的 K-means 聚类。

Args:

spots: 景点字典，每项含 {"x": float, "y": float}。 depot: depot 索引。 n_clusters: 聚类组数。

Returns:

List[List[int]]: 每个分组包含的景点索引列表。

engine.clustering.cluster_by_time_window(spots: dict, depot: int, n_clusters: int)

基于时间窗特征的 K-means 聚类。

特征向量：[开放时间, 关闭时间, 时间窗跨度]。 适用于将营业时间相似的景点分到同一天。

Args:

spots: 景点字典。 depot: depot 索引。 n_clusters: 聚类组数。

Returns:

List[List[int]]: 每个分组包含的景点索引列表。

engine.clustering.cluster_by_spatiotemporal(spots: dict, depot: int, n_clusters: int, sp_w: float = 0.5, tp_w: float = 0.5)

时空联合聚类（距离 + 时间窗）。

将坐标和时间窗拼接为四维特征，通过权重参数调节空间与时间的相对重要性。

Args:

spots: 景点字典。 depot: depot 索引。 n_clusters: 聚类组数。 sp_w: 空间权重（默认 0.5）。 tp_w: 时间权重（默认 0.5）。

Returns:

List[List[int]]: 每个分组包含的景点索引列表。

engine.clustering.cluster_by_time_overlap(spots: dict, depot: int, n_clusters: int)

时间窗重叠启发式分组。

将景点按时间窗起始时间排序后平摊到各组，保证每组时间窗连续。 无随机性，结果确定。

Args:

spots: 景点字典。 depot: depot 索引。 n_clusters: 聚类组数。

Returns:

List[List[int]]: 每个分组包含的景点索引列表。

engine.clustering.cluster_by_time_density(spots: dict, depot: int, n_clusters: int)

基于时间窗密度的 K-means 聚类。

仅使用时间窗起始时间作为一维特征，适用于时间段高度聚集的场景。

Args:

spots: 景点字典。 depot: depot 索引。 n_clusters: 聚类组数。

Returns:

List[List[int]]: 每个分组包含的景点索引列表。

engine.clustering.cluster_hybrid_optimized(spots: dict, cost_mat: numpy.ndarray, depot: int, n_clusters: int)

混合优化分组（时间窗排序 + 距离优化重分配）。

先按时间窗排序平摊，再通过交换分组间边界节点来优化组内距离。 迭代至多 10 轮，无改善则提前停止。

Args:

spots: 景点字典。 cost_mat: 距离矩阵，用于评估交换收益。 depot: depot 索引。 n_clusters: 聚类组数。

Returns:

List[List[int]]: 每个分组包含的景点索引列表。

engine.clustering.CLUSTER_METHODS

engine.clustering.call_cluster(func: collections.abc.Callable, spots: dict, depot: int, k: int, cost_mat: numpy.ndarray | None = None) → list[list[int]]

统一调用聚类方法。

cluster_hybrid_optimized 需要 cost_mat 参数，其余仅需 spots/depot/k。

Args:

func: 聚类函数。 spots: 景点字典，每项含 x/y/tw 等。 depot: depot 索引。 k: 分组数。 cost_mat: 距离矩阵，仅 cluster_hybrid_optimized 需要。

Returns:

list[list[int]]: 每组包含的景点索引列表。

engine.clustering.pure_name(full_name: str) → str

从带编号的全称中提取纯方法名，如 '1. xxx' → 'xxx'

Returns:

str: 纯方法名（去掉前缀编号）。

engine.clustering.find_method_func(name: str)

通过方法名查找对应的函数对象

Args:

name: 方法名（带编号或不带均可）。

Returns:

callable | None: 找到的函数对象，未找到返回 None。