fused_butina#

nvmolkit.clustering.fused_butina(
x: AsyncGpuResult | Tensor | ndarray,
cutoff: float,
return_centroids: bool = False,
metric: str = 'tanimoto',
stream: Stream | None = None,
) → AsyncGpuResult | tuple[AsyncGpuResult, AsyncGpuResult]#

Perform fused Butina clustering on a set of fingerprints.

This function uses a fused implementation of Butina clustering that computes similarities and neighbors on-the-fly, avoiding the need to compute and store the full distance matrix. This makes it suitable for large datasets.

Parameters:

  • x – Tensor-like object of shape (N, D) containing packed int32 or uint32 fingerprints to cluster. Can be an AsyncGpuResult, torch.Tensor, or numpy.ndarray. CPU tensors and NumPy arrays are copied to CUDA.

  • cutoff – Distance threshold for clustering. Items are neighbors if their distance is at most this cutoff (i.e. similarity >= 1 - cutoff).

  • return_centroids – Whether to return centroid indices for each cluster.

  • metric – Metric to use for similarity computation. Currently only “tanimoto” and “cosine” are supported.

  • stream – CUDA stream to use. If None, uses the current stream.

Returns:

AsyncGpuResult of shape (N,) containing one cluster ID per input item when return_centroids is False. When return_centroids is True, returns (cluster_ids, centroids), where centroids contains the input index selected as the centroid for each cluster ID.

On this page