Skip to content

Support unexpanded L2 metrics in KMeans transform - #3051

Merged
rapids-bot[bot] merged 2 commits into
NVIDIA:release/26.12from
viclafargue:kmeans-transform-unexpanded-l2
Nov 18, 2026
Merged

rapids-bot[bot] merged 2 commits into
NVIDIA:release/26.12from
viclafargue:kmeans-transform-unexpanded-l2

Conversation

@viclafargue

Copy link
Copy Markdown
Contributor

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.

@viclafargue
viclafargue requested a review from a team as a code owner November 12, 2026 10:50
@viclafargue viclafargue added improvement Improves an existing functionality non-breaking Introduces a non-breaking change labels Nov 12, 2026
@coderabbitai

coderabbitai Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Explain Change →

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

Run configuration

Commits

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.

Changes: K-means transform

Layer / File(s) Summary
Transform distance calculation
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
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.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Feature

Suggested reviewers: tarang-jain, divyegala

Merge Risk: Minimal · previous review c014a

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: Passed 4

Check name Status Explanation
Title check Passed 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 Passed 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 Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed 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
Recent review info

Run configuration

  • Source mode: Auto
  • Repository: NVIDIA/cuvs
  • Branch: main
  • File: .coderabbit.yaml
  • Commit: 024a40f
  • Layers: Repository YAML
  • Review profile: CHILL
  • Plan: Enterprise
  • Run ID: fbbe73fa-77a4-42eb-92ac-e0a4207dd4d3
Commits

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.

@csadorf

csadorf commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

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.

#include <cuvs/cluster/kmeans.hpp>
#include <raft/core/device_mdspan.hpp>
#include <raft/core/resources.hpp>
#include <cuda_runtime.h>

#include <algorithm>
#include <cmath>
#include <iostream>
#include <random>
#include <stdexcept>
#include <string>
#include <vector>

#define CUDA_CHECK(call) do { \
  auto err = (call); \
  if (err != cudaSuccess) throw std::runtime_error(cudaGetErrorString(err)); \
} while (0)

int main(int argc, char** argv) try {
  const std::string mode = argc > 1 ? argv[1] : "expanded";
  if (argc > 2 || (mode != "expanded" && mode != "unexpanded")) {
    std::cerr << "Usage: " << argv[0] << " [expanded|unexpanded]\n";
    return 2;
  }

  constexpr int n = 256, d = 64;
  std::mt19937 rng(42);
  std::normal_distribution<float> normal(0, 1);
  std::vector<float> x(n * d), got(n * n);
  for (auto& v : x) v = 100.0f + 0.01f * normal(rng);

  // Identical values in separate allocations.
  float *dx, *dy, *out;
  CUDA_CHECK(cudaMalloc(reinterpret_cast<void**>(&dx), x.size() * sizeof(float)));
  CUDA_CHECK(cudaMalloc(reinterpret_cast<void**>(&dy), x.size() * sizeof(float)));
  CUDA_CHECK(cudaMalloc(reinterpret_cast<void**>(&out), got.size() * sizeof(float)));
  CUDA_CHECK(cudaMemcpy(dx, x.data(), x.size() * sizeof(float), cudaMemcpyHostToDevice));
  CUDA_CHECK(cudaMemcpy(dy, x.data(), x.size() * sizeof(float), cudaMemcpyHostToDevice));

  raft::resources handle;
  cuvs::cluster::kmeans::params params;
  params.n_clusters = n;
  params.metric = mode == "expanded"
    ? cuvs::distance::DistanceType::L2SqrtExpanded
    : cuvs::distance::DistanceType::L2SqrtUnexpanded;

  cuvs::cluster::kmeans::transform(
    handle, params,
    raft::make_device_matrix_view<const float, int>(dx, n, d),
    raft::make_device_matrix_view<const float, int>(dy, n, d),
    raft::make_device_matrix_view<float, int>(out, n, n));
  CUDA_CHECK(cudaDeviceSynchronize());
  CUDA_CHECK(cudaMemcpy(
    got.data(), out, got.size() * sizeof(float), cudaMemcpyDeviceToHost));

  double max_self = 0, max_nearby_error = 0;
  for (int i = 0; i < n; ++i) {
    max_self = std::max(max_self, double(got[i * n + i]));
    for (int j = 0; j < n; ++j) {
      if (i == j) continue;
      double sq = 0;
      for (int k = 0; k < d; ++k) {
        double diff = double(x[i * d + k]) - double(x[j * d + k]);
        sq += diff * diff;
      }
      max_nearby_error = std::max(
        max_nearby_error,
        std::abs(double(got[i * n + j]) - std::sqrt(sq)));
    }
  }
  std::cout << "Metric: " << mode << '\n'
            << "Maximum self-distance: " << max_self << '\n'
            << "Maximum error for distinct vectors: " << max_nearby_error << '\n';

  CUDA_CHECK(cudaFree(dx));
  CUDA_CHECK(cudaFree(dy));
  CUDA_CHECK(cudaFree(out));
  return 0;
} catch (const std::exception& e) {
  std::cerr << e.what() << '\n';
  return 1;
}

Build in an activated conda environment containing the PR’s cuVS build and dependencies. Adjust -arch for your GPU.

nvcc -std=c++20 -DRAFT_SYSTEM_LITTLE_ENDIAN=1 -arch=sm_120 \
  -I"$CONDA_PREFIX/include/rapids" -I"$CONDA_PREFIX/include" \
  issue.cu -L"$CONDA_PREFIX/lib" \
  -Xlinker -rpath -Xlinker "$CONDA_PREFIX/lib" \
  -lcuvs -lrmm -o reproducer

./reproducer expanded
./reproducer unexpanded

@csadorf

csadorf commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

Can we target this for release/26.12, please?

@viclafargue
viclafargue force-pushed the kmeans-transform-unexpanded-l2 branch from c014a33 to eb9cd5c Compare November 16, 2026 18:11
@viclafargue
viclafargue changed the base branch from main to release/26.12 November 16, 2026 18:11
@viclafargue

Copy link
Copy Markdown
Contributor Author

/merge

@csadorf csadorf mentioned this pull request Nov 17, 2026
1 task done
@rapids-bot
rapids-bot Bot merged commit 668006e into NVIDIA:release/26.12 Nov 18, 2026
340 of 345 checks passed
@github-project-automation github-project-automation Bot moved this from Approved to Done in Unstructured Data Processing Nov 18, 2026
rapids-bot Bot pushed a commit to NVIDIA/cuml that referenced this pull request Nov 18, 2026
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

improvement Improves an existing functionality non-breaking Introduces a non-breaking change

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

4 participants