Fix kmeans::predict argument order (rapidsai#915)

This PR updates the order of arguments in `kmeans::predict` to match the order in the documentation. The order in the documentation is considered appropriate because it lists the output arguments last, unlike the order of the actual function arguments.

Authors:
  - tsuki (https://github.com/enp1s0)

Approvers:
  - Corey J. Nolet (https://github.com/cjnolet)

URL: rapidsai#915

Author: enp1s0

cpp/include/cuvs/cluster/kmeans.hpp

@@ -519,10 +519,26 @@ void predict(raft::resources const& handle,
              raft::device_matrix_view<const float, int> X,
              std::optional<raft::device_vector_view<const float, int>> sample_weight,
              raft::device_matrix_view<const float, int> centroids,
-             raft::device_vector_view<int, int> labels,
              bool normalize_weight,
+             raft::device_vector_view<int, int> labels,
              raft::host_scalar_view<float> inertia);
 
+// This overload is retained for backward compatibility.
+[[deprecated(
+  "The argument order of kmeans::predict has been corrected. Please use the new function "
+  "instead.")]]
+inline void predict(raft::resources const& handle,
+                    const kmeans::params& params,
+                    raft::device_matrix_view<const float, int> X,
+                    std::optional<raft::device_vector_view<const float, int>> sample_weight,
+                    raft::device_matrix_view<const float, int> centroids,
+                    raft::device_vector_view<int, int> labels,
+                    bool normalize_weight,
+                    raft::host_scalar_view<float> inertia)
+{
+  predict(handle, params, X, sample_weight, centroids, normalize_weight, labels, inertia);
+}
+
 /**
  * @brief Predict the closest cluster each sample in X belongs to.
  *
@@ -577,10 +593,26 @@ void predict(raft::resources const& handle,
              raft::device_matrix_view<const float, int> X,
              std::optional<raft::device_vector_view<const float, int>> sample_weight,
              raft::device_matrix_view<const float, int> centroids,
-             raft::device_vector_view<int64_t, int> labels,
              bool normalize_weight,
+             raft::device_vector_view<int64_t, int> labels,
              raft::host_scalar_view<float> inertia);
 
+// This overload is retained for backward compatibility.
+[[deprecated(
+  "The argument order of kmeans::predict has been corrected. Please use the new function "
+  "instead.")]]
+inline void predict(raft::resources const& handle,
+                    const kmeans::params& params,
+                    raft::device_matrix_view<const float, int> X,
+                    std::optional<raft::device_vector_view<const float, int>> sample_weight,
+                    raft::device_matrix_view<const float, int> centroids,
+                    raft::device_vector_view<int64_t, int> labels,
+                    bool normalize_weight,
+                    raft::host_scalar_view<float> inertia)
+{
+  predict(handle, params, X, sample_weight, centroids, normalize_weight, labels, inertia);
+}
+
 /**
  * @brief Predict the closest cluster each sample in X belongs to.
  *
@@ -635,10 +667,26 @@ void predict(raft::resources const& handle,
              raft::device_matrix_view<const double, int> X,
              std::optional<raft::device_vector_view<const double, int>> sample_weight,
              raft::device_matrix_view<const double, int> centroids,
-             raft::device_vector_view<int, int> labels,
              bool normalize_weight,
+             raft::device_vector_view<int, int> labels,
              raft::host_scalar_view<double> inertia);
 
+// This overload is retained for backward compatibility.
+[[deprecated(
+  "The argument order of kmeans::predict has been corrected. Please use the new function "
+  "instead.")]]
+inline void predict(raft::resources const& handle,
+                    const kmeans::params& params,
+                    raft::device_matrix_view<const double, int> X,
+                    std::optional<raft::device_vector_view<const double, int>> sample_weight,
+                    raft::device_matrix_view<const double, int> centroids,
+                    raft::device_vector_view<int, int> labels,
+                    bool normalize_weight,
+                    raft::host_scalar_view<double> inertia)
+{
+  predict(handle, params, X, sample_weight, centroids, normalize_weight, labels, inertia);
+}
+
 /**
  * @brief Predict the closest cluster each sample in X belongs to.
  *
@@ -693,10 +741,26 @@ void predict(raft::resources const& handle,
              raft::device_matrix_view<const double, int> X,
              std::optional<raft::device_vector_view<const double, int>> sample_weight,
              raft::device_matrix_view<const double, int> centroids,
-             raft::device_vector_view<int64_t, int> labels,
              bool normalize_weight,
+             raft::device_vector_view<int64_t, int> labels,
              raft::host_scalar_view<double> inertia);
 
+// This overload is retained for backward compatibility.
+[[deprecated(
+  "The argument order of kmeans::predict has been corrected. Please use the new function "
+  "instead.")]]
+inline void predict(raft::resources const& handle,
+                    const kmeans::params& params,
+                    raft::device_matrix_view<const double, int> X,
+                    std::optional<raft::device_vector_view<const double, int>> sample_weight,
+                    raft::device_matrix_view<const double, int> centroids,
+                    raft::device_vector_view<int64_t, int> labels,
+                    bool normalize_weight,
+                    raft::host_scalar_view<double> inertia)
+{
+  predict(handle, params, X, sample_weight, centroids, normalize_weight, labels, inertia);
+}
+
 /**
  * @brief Predict the closest cluster each sample in X belongs to.
  *

cpp/src/cluster/kmeans.cuh

@@ -163,8 +163,8 @@ void predict(raft::resources const& handle,
              raft::device_matrix_view<const DataT, IndexT> X,
              std::optional<raft::device_vector_view<const DataT, IndexT>> sample_weight,
              raft::device_matrix_view<const DataT, IndexT> centroids,
-             raft::device_vector_view<IndexT, IndexT> labels,
              bool normalize_weight,
+             raft::device_vector_view<IndexT, IndexT> labels,
              raft::host_scalar_view<DataT> inertia)
 {
   cuvs::cluster::kmeans::detail::kmeans_predict<DataT, IndexT>(

cpp/src/cluster/kmeans_predict_double.cu

@@ -24,26 +24,26 @@ void predict(raft::resources const& handle,
              raft::device_matrix_view<const double, int> X,
              std::optional<raft::device_vector_view<const double, int>> sample_weight,
              raft::device_matrix_view<const double, int> centroids,
-             raft::device_vector_view<int, int> labels,
              bool normalize_weight,
+             raft::device_vector_view<int, int> labels,
              raft::host_scalar_view<double> inertia)
 
 {
   cuvs::cluster::kmeans::predict<double, int>(
-    handle, params, X, sample_weight, centroids, labels, normalize_weight, inertia);
+    handle, params, X, sample_weight, centroids, normalize_weight, labels, inertia);
 }
 
 void predict(raft::resources const& handle,
              const kmeans::params& params,
              raft::device_matrix_view<const double, int> X,
              std::optional<raft::device_vector_view<const double, int>> sample_weight,
              raft::device_matrix_view<const double, int> centroids,
-             raft::device_vector_view<int64_t, int> labels,
              bool normalize_weight,
+             raft::device_vector_view<int64_t, int> labels,
              raft::host_scalar_view<double> inertia)
 
 {
   cuvs::cluster::kmeans::predict<double, int64_t>(
-    handle, params, X, sample_weight, centroids, labels, normalize_weight, inertia);
+    handle, params, X, sample_weight, centroids, normalize_weight, labels, inertia);
 }
 }  // namespace cuvs::cluster::kmeans

cpp/src/cluster/kmeans_predict_float.cu

@@ -24,25 +24,25 @@ void predict(raft::resources const& handle,
              raft::device_matrix_view<const float, int> X,
              std::optional<raft::device_vector_view<const float, int>> sample_weight,
              raft::device_matrix_view<const float, int> centroids,
-             raft::device_vector_view<int, int> labels,
              bool normalize_weight,
+             raft::device_vector_view<int, int> labels,
              raft::host_scalar_view<float> inertia)
 
 {
   cuvs::cluster::kmeans::predict<float, int>(
-    handle, params, X, sample_weight, centroids, labels, normalize_weight, inertia);
+    handle, params, X, sample_weight, centroids, normalize_weight, labels, inertia);
 }
 void predict(raft::resources const& handle,
              const kmeans::params& params,
              raft::device_matrix_view<const float, int> X,
              std::optional<raft::device_vector_view<const float, int>> sample_weight,
              raft::device_matrix_view<const float, int> centroids,
-             raft::device_vector_view<int64_t, int> labels,
              bool normalize_weight,
+             raft::device_vector_view<int64_t, int> labels,
              raft::host_scalar_view<float> inertia)
 
 {
   cuvs::cluster::kmeans::predict<float, int64_t>(
-    handle, params, X, sample_weight, centroids, labels, normalize_weight, inertia);
+    handle, params, X, sample_weight, centroids, normalize_weight, labels, inertia);
 }
 }  // namespace cuvs::cluster::kmeans