engine.clustering
=================

.. py:module:: engine.clustering

.. autoapi-nested-parse::

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



Attributes
----------

.. autoapisummary::

   engine.clustering.CLUSTER_METHODS


Functions
---------

.. autoapisummary::

   engine.clustering.cluster_by_distance_kmeans
   engine.clustering.cluster_by_time_window
   engine.clustering.cluster_by_spatiotemporal
   engine.clustering.cluster_by_time_overlap
   engine.clustering.cluster_by_time_density
   engine.clustering.cluster_hybrid_optimized
   engine.clustering.call_cluster
   engine.clustering.pure_name
   engine.clustering.find_method_func


Module Contents
---------------

.. py:function:: 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]]: 每个分组包含的景点索引列表。


.. py:function:: cluster_by_time_window(spots: dict, depot: int, n_clusters: int)

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

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

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

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


.. py:function:: 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]]: 每个分组包含的景点索引列表。


.. py:function:: cluster_by_time_overlap(spots: dict, depot: int, n_clusters: int)

   时间窗重叠启发式分组。

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

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

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


.. py:function:: cluster_by_time_density(spots: dict, depot: int, n_clusters: int)

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

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

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

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


.. py:function:: 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]]: 每个分组包含的景点索引列表。


.. py:data:: CLUSTER_METHODS

.. py:function:: 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]]: 每组包含的景点索引列表。


.. py:function:: pure_name(full_name: str) -> str

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

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


.. py:function:: find_method_func(name: str)

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

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

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