You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Support unexpanded L2 metrics in KMeans transform - #3051
Expanded L2 distances can lose accuracy for points close to cluster centers because of cancellation.
Add support for L2Unexpanded and L2SqrtUnexpanded in cuvs::cluster::kmeans::transform for float32 and float64. Each batch calls the existing pairwise_distance implementation, keeping batch processing in cuVS.
This enables cuML to address NVIDIA/cuml#8885 by explicitly selecting L2SqrtUnexpanded.
Reviewing files that changed from the base of the PR and between eb9cd5c and 0695a4f.
You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.
Use the checkbox below for a quick retry:
Trigger review
No actionable comments were generated in the recent review.
Summary
Summary by CodeRabbit
New Features
K-means transform now supports unexpanded L2 and square-root L2 distance metrics, alongside the expanded variants. Inputs can be processed in batches, and results contain one distance per cluster.
Documentation
Updated the API documentation to describe supported metrics, batching, and the output dimensions for both float and double inputs.
The k-means transform now supports four L2 metrics and calculates distances in batches. The API documentation describes the supported metrics, batching parameter, and output dimensions.
The transform accepts expanded and unexpanded L2 metrics, returns for empty input, and checks that input and centroid feature counts match. It calculates each batch with pairwise_distance. Tests cover float and double, all four metrics, and two batch sizes. The API documentation describes batching and specifies n_samples × n_clusters output dimensions.
K-means transform gains support for unexpanded L2 metrics, with tests and corrected documentation of the output shape. No actionable merge-blocking risk was found.
Security architecture risk: Minimal · up to c014a
The added distance options retain the existing caller-owned buffers and GPU execution context. The review found no material security risk introduced or worsened by this change.
Retained concerns
No architecture-level concerns identified.
Security review details
Security Blast Radius
inferred — The direct exposure remains the calling application's device matrices and GPU resource context. Metric selection now reaches two additional existing numerical implementations, but the inspected path passes no additional identity, credential or service authority.
Trust Boundaries and Controls
observed — The general distance interface is not exposed without restriction: transform allowlists exactly four L2 metrics. The new callee checks feature agreement, batch-output dimensions against its inputs and contiguity. The former helper also enforced feature and centroid-count agreement through its matrix-distance callee.
Resilience and Maintainability Implications
observed — The replacement preserves in-place, nontransactional batch writes: interruption or failure after completed batches can leave partial output, as before. No cross-call output ownership or recovery state is introduced. Both new unexpanded implementations explicitly leave workspace unused and execute through the caller's stream.
Pre-merge checks: 4
Check name
Status
Explanation
Title check
The title states the main change: adding L2Unexpanded and L2SqrtUnexpanded metric support to KMeans transform. The raw summary confirms the kmeans.cuh implementation now accepts these metrics, and the…
Description check
The description gives the reason for the change: expanded L2 distances lose accuracy near cluster centers through cancellation. It names the added metrics, the float32 and float64 scope, the use of th…
Linked Issues check
Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check
Check skipped because no linked issues were found for this pull request.
Full details: Title check
Explanation
The title states the main change: adding L2Unexpanded and L2SqrtUnexpanded metric support to KMeans transform. The raw summary confirms the kmeans.cuh implementation now accepts these metrics, and the docs and tests were updated to match.
Full details: Description check
Explanation
The description gives the reason for the change: expanded L2 distances lose accuracy near cluster centers through cancellation. It names the added metrics, the float32 and float64 scope, the use of the existing pairwise_distance call per batch, and the cuML issue this enables. This matches the changeset.
Finishing Touches
Generate unit tests (beta)
Create a new PR
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Reviewing files that changed from the base of the PR and between 024a40f and c014a33.
Files selected for processing: 4
cpp/include/cuvs/cluster/kmeans.hpp
cpp/src/cluster/detail/kmeans.cuh
cpp/tests/cluster/kmeans.cu
fern/pages/cpp_api/cpp-api-cluster-kmeans.md
Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.
Thanks for opening this PR. I verified that this also benefits cuVS callers directly, without cuML. With c014a335, the C++ reproducer below returns self-distances up to 0.866 using L2SqrtExpanded; switching to L2SqrtUnexpanded gives exact zeros and reduces the maximum error between distinct vectors from 0.765 to 3.28e-8.
Tested on an RTX PRO 6000 Blackwell with CUDA 12.9.
C++ reproducer
Compares identical input data using either metric. The reference uses direct float64 subtraction of the same float32 inputs.
Closes#8885.
This PR updates KMeans’s transform method to call `cuvs::cluster::kmeans::transform` with the `L2SqrtUnexpanded` metric, improving numerical accuracy with minimal performance impact across most problem sizes.
Depends on NVIDIA/cuvs#3051.
- [x] **Before merging:** remove `ci/utils/use_cuvs_pr.sh` and its calls from the CI scripts. These overrides temporarily use pinned artifacts from NVIDIA/cuvs#3051 for integration testing. Rerun CI with the normal dependencies once they include the required cuVS change.
Authors:
- Victor Lafargue (https://github.com/viclafargue)
Approvers:
- Philip Hyunsu Cho (https://github.com/chyunsu3)
URL: #8914
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Expanded L2 distances can lose accuracy for points close to cluster centers because of cancellation.
Add support for
L2UnexpandedandL2SqrtUnexpandedincuvs::cluster::kmeans::transformfor float32 and float64. Each batch calls the existing pairwise_distance implementation, keeping batch processing in cuVS.This enables cuML to address NVIDIA/cuml#8885 by explicitly selecting
L2SqrtUnexpanded.