Merge pull request #178 from sbaldu/feature-default-convolutiona-kernel

Reorder `make_clusters` arguments and provide default value to convolutional kernel

Author: sbaldu

CLUEstering/BindingModules/Run.hpp

@@ -21,5 +21,5 @@ void run(float dc,
   clue::PointsHost<Ndim> h_points(queue, n_points, std::get<0>(pData), std::get<1>(pData));
   clue::PointsDevice<Ndim> d_points(queue, n_points);
 
-  algo.make_clusters(h_points, d_points, kernel, queue, block_size);
+  algo.make_clusters(queue, h_points, d_points, kernel, block_size);
 }

benchmark/dataset_size/main.cpp

@@ -81,7 +81,7 @@ void to_csv(const TimeMeasures& measures, const std::string& filename) {
 void run(clue::PointsHost<2>& h_points, clue::PointsDevice<2>& d_points, clue::Queue& queue) {
   const float dc{1.5f}, rhoc{10.f}, outlier{1.5f};
   clue::Clusterer<2> algo(queue, dc, rhoc, outlier);
-  algo.make_clusters(h_points, d_points, clue::FlatKernel{.5f}, queue);
+  algo.make_clusters(queue, h_points, d_points);
 }
 
 int main(int argc, char* argv[]) {

benchmark/profiling/main.cpp

@@ -17,7 +17,7 @@ void run(const std::string& input_file) {
   const float dc{1.5f}, rhoc{10.f}, outlier{1.5f};
   clue::Clusterer<2> algo(queue, dc, rhoc, outlier);
 
-  algo.make_clusters(h_points, d_points, clue::FlatKernel{.5f}, queue);
+  algo.make_clusters(queue, h_points, d_points);
   auto clusters = algo.getClusters(h_points);
 }
 

docs/getting-started.dox

@@ -22,8 +22,7 @@
  * 
  *   // Launch the clustering
  *   // The results will be stored in the `clue::PointsHost` object
- *   const std::size_t block_size{256};
- *   algo.make_clusters(h_points, d_points, clue::FlatKernel{.5f}, queue, block_size);
+ *   algo.make_clusters(queue, h_points, d_points);
  *   // Read the data from the host points
  *   auto clusters_indexes = h_points.clusterIndexes();  // Get the cluster index for each points
  *   auto seed_map =
@@ -49,9 +48,10 @@
  * Then, the `clue::Clusterer`, which is the object that handles the internal allocations and contains the algorithm logic, is created. The `Clusterer`
  * requires the CLUE algorithm's parameters to be passed. Their meaning is explained in the introduction section, along with a description of the algorithm.
  *
- * Finally, the algorithm is launched with the `make_clusters` method, which takes as arguments the host and device points, the kernel to use for the
- * clustering, the queue to use for the operations and the bloch size. The input data is copied from the host to the device container, the algorithm is then 
- * executed on the device, where the results are computed and finally copied back to the host container.
+ * Finally, the algorithm is launched with the `make_clusters` method, which takes as arguments the queue to use for the device operations, the host and
+ * device points and optionally the kernel to use for computing the points' density and the block-size that the kernels are launched with.
+ * The input data is copied from the host to the device container, the algorithm is then executed on the device, where the results are computed and finally
+ * copied back to the host container.
  *
  * The results of the clustering can then be read from the host points: the `clue::PointsHost::clusterIndexes` method returns a span of integers
  * representing the cluster index for each point, while the `clue::PointsHost::isSeed` method returns a boolean array indicating which points are the seeds

examples/main.cpp

@@ -15,7 +15,7 @@ int main() {
 
   // Launch the clustering
   // The results will be stored in the `clue::PointsHost` object
-  algo.make_clusters(h_points, d_points, clue::FlatKernel{.5f}, queue);
+  algo.make_clusters(queue, h_points, d_points);
   // Read the data from the host points
   auto clusters_indexes = h_points.clusterIndexes();  // Get the cluster index for each points
   auto seed_map =

include/CLUEstering/core/Clusterer.hpp

@@ -128,58 +128,60 @@ namespace clue {
 
     /// @brief Construct the clusters from host points
     ///
-    /// @param h_points Host points to cluster
-    /// @param kernel The convolutional kernel to use for clustering
     /// @param queue The queue to use for the device operations
+    /// @param h_points Host points to cluster
+    /// @param kernel The convolutional kernel to use for computing the local densities, default is FlatKernel with height 0.5
     /// @param block_size The size of the blocks to use for clustering, default is 256
-    template <concepts::convolutional_kernel Kernel>
-    void make_clusters(PointsHost& h_points,
-                       const Kernel& kernel,
-                       Queue& queue,
+    template <concepts::convolutional_kernel Kernel = FlatKernel>
+    void make_clusters(Queue& queue,
+                       PointsHost& h_points,
+                       const Kernel& kernel = FlatKernel{.5f},
                        std::size_t block_size = 256);
     /// @brief Construct the clusters from host points
     ///
     /// @param h_points Host points to cluster
-    /// @param kernel The convolutional kernel to use for clustering
+    /// @param kernel The convolutional kernel to use for computing the local densities, default is FlatKernel with height 0.5
     /// @param block_size The size of the blocks to use for clustering, default is 256
     /// @note This method creates a temporary queue for the operations on the device
-    template <concepts::convolutional_kernel Kernel>
-    void make_clusters(PointsHost& h_points, const Kernel& kernel, std::size_t block_size = 256);
+    template <concepts::convolutional_kernel Kernel = FlatKernel>
+    void make_clusters(PointsHost& h_points,
+                       const Kernel& kernel = FlatKernel{.5f},
+                       std::size_t block_size = 256);
     /// @brief Construct the clusters from host and device points
     ///
+    /// @param queue The queue to use for the device operations
     /// @param h_points Host points to cluster
     /// @param dev_points Device points to cluster
-    /// @param kernel The convolutional kernel to use for clustering
-    /// @param queue The queue to use for the device operations
+    /// @param kernel The convolutional kernel to use for computing the local densities, default is FlatKernel with height 0.5
     /// @param block_size The size of the blocks to use for clustering, default is 256
-    template <concepts::convolutional_kernel Kernel>
-    void make_clusters(PointsHost& h_points,
+    template <concepts::convolutional_kernel Kernel = FlatKernel>
+    void make_clusters(Queue& queue,
+                       PointsHost& h_points,
                        PointsDevice& dev_points,
-                       const Kernel& kernel,
-                       Queue& queue,
+                       const Kernel& kernel = FlatKernel{.5f},
                        std::size_t block_size = 256);
     /// @brief Construct the clusters from host and device points
     ///
     /// @param h_points Host points to cluster
     /// @param dev_points Device points to cluster
-    /// @param kernel The convolutional kernel to use for clustering
+    /// @param kernel The convolutional kernel to use for computing the local densities, default is FlatKernel with height 0.5
     /// @param block_size The size of the blocks to use for clustering, default is 256
     /// @note This method creates a temporary queue for the operations on the device
-    template <concepts::convolutional_kernel Kernel>
+    template <concepts::convolutional_kernel Kernel = FlatKernel>
     void make_clusters(PointsHost& h_points,
                        PointsDevice& dev_points,
-                       const Kernel& kernel,
+                       const Kernel& kernel = FlatKernel{.5f},
                        std::size_t block_size = 256);
     /// @brief Construct the clusters from device points
     ///
-    /// @param dev_points Device points to cluster
-    /// @param kernel The convolutional kernel to use for clustering
     /// @param queue The queue to use for the device operations
+    /// @param dev_points Device points to cluster
+    /// @param kernel The convolutional kernel to use for computing the local densities, default is FlatKernel with height 0.5
     /// @param block_size The size of the blocks to use for clustering, default is 256
-    template <concepts::convolutional_kernel Kernel>
-    void make_clusters(PointsDevice& dev_points,
-                       const Kernel& kernel,
-                       Queue& queue,
+    template <concepts::convolutional_kernel Kernel = FlatKernel>
+    void make_clusters(Queue& queue,
+                       PointsDevice& dev_points,
+                       const Kernel& kernel = FlatKernel{.5f},
                        std::size_t block_size = 256);
 
     /// @brief Specify which coordinates are periodic

include/CLUEstering/core/detail/Clusterer.hpp

@@ -80,9 +80,9 @@ namespace clue {
 
   template <uint8_t Ndim>
   template <concepts::convolutional_kernel Kernel>
-  inline void Clusterer<Ndim>::make_clusters(PointsHost& h_points,
+  inline void Clusterer<Ndim>::make_clusters(Queue& queue,
+                                             PointsHost& h_points,
                                              const Kernel& kernel,
-                                             Queue& queue,
                                              std::size_t block_size) {
     d_points = std::make_optional<PointsDevice>(queue, h_points.size());
     auto& dev_points = *d_points;
@@ -109,10 +109,10 @@ namespace clue {
   }
   template <uint8_t Ndim>
   template <concepts::convolutional_kernel Kernel>
-  inline void Clusterer<Ndim>::make_clusters(PointsHost& h_points,
+  inline void Clusterer<Ndim>::make_clusters(Queue& queue,
+                                             PointsHost& h_points,
                                              PointsDevice& dev_points,
                                              const Kernel& kernel,
-                                             Queue& queue,
                                              std::size_t block_size) {
     setup(queue, h_points, dev_points);
     make_clusters_impl(h_points, dev_points, kernel, queue, block_size);
@@ -134,9 +134,9 @@ namespace clue {
   }
   template <uint8_t Ndim>
   template <concepts::convolutional_kernel Kernel>
-  inline void Clusterer<Ndim>::make_clusters(PointsDevice& dev_points,
+  inline void Clusterer<Ndim>::make_clusters(Queue& queue,
+                                             PointsDevice& dev_points,
                                              const Kernel& kernel,
-                                             Queue& queue,
                                              std::size_t block_size) {
     setupTiles(queue, dev_points);
     setupFollowers(queue, dev_points.size());

tests/test_clusterer.cpp

@@ -24,7 +24,7 @@ TEST_CASE("Test make_cluster interfaces") {
   auto truth_ids = truth_data.clusterIndexes();
   auto truth_isSeed = truth_data.isSeed();
   SUBCASE("Run clustering without passing device points") {
-    algo.make_clusters(h_points, clue::FlatKernel{.5f}, queue, block_size);
+    algo.make_clusters(queue, h_points, clue::FlatKernel{.5f}, block_size);
     auto clusters = h_points.clusterIndexes();
     auto isSeed = h_points.isSeed();
 
@@ -51,7 +51,7 @@ TEST_CASE("Test make_cluster interfaces") {
   }
   SUBCASE("Run clustering from device points") {
     clue::copyToDevice(queue, d_points, h_points);
-    algo.make_clusters(d_points, clue::FlatKernel{.5f}, queue, block_size);
+    algo.make_clusters(queue, d_points, clue::FlatKernel{.5f}, block_size);
     clue::copyToHost(queue, h_points, d_points);
 
     auto clusters = h_points.clusterIndexes();

tests/test_clustering.cpp

@@ -30,7 +30,7 @@ TEST_CASE("Test clustering on benchmarking datasets") {
     const float dc{1.5f}, rhoc{10.f}, outlier{1.5f};
     clue::Clusterer<2> algo(queue, dc, rhoc, outlier);
 
-    algo.make_clusters(h_points, d_points, clue::FlatKernel{.5f}, queue);
+    algo.make_clusters(queue, h_points, d_points);
     auto clusters = h_points.clusterIndexes();
     auto isSeed = h_points.isSeed();
 
@@ -54,7 +54,7 @@ TEST_CASE("Test clustering on sissa") {
   const float dc{20.f}, rhoc{10.f}, outlier{20.f};
   clue::Clusterer<2> algo(queue, dc, rhoc, outlier);
 
-  algo.make_clusters(h_points, d_points, clue::FlatKernel{.5f}, queue);
+  algo.make_clusters(queue, h_points, d_points);
   auto clusters = h_points.clusterIndexes();
   auto isSeed = h_points.isSeed();
 
@@ -76,7 +76,7 @@ TEST_CASE("Test clustering on toy detector dataset") {
   const float dc{4.5f}, rhoc{2.5f}, outlier{4.5f};
   clue::Clusterer<2> algo(queue, dc, rhoc, outlier);
 
-  algo.make_clusters(h_points, d_points, clue::FlatKernel{.5f}, queue);
+  algo.make_clusters(queue, h_points, d_points);
   auto clusters = h_points.clusterIndexes();
   auto isSeed = h_points.isSeed();
 
@@ -98,7 +98,7 @@ TEST_CASE("Test clustering on blob dataset") {
   const float dc{1.f}, rhoc{5.f}, outlier{2.f};
   clue::Clusterer<3> algo(queue, dc, rhoc, outlier);
 
-  algo.make_clusters(h_points, d_points, clue::FlatKernel{.5f}, queue);
+  algo.make_clusters(queue, h_points, d_points);
   auto clusters = h_points.clusterIndexes();
   auto isSeed = h_points.isSeed();