Labeling algorithm updates for C API (#2185)

Several things bundled here:
 * Added C API definition, implementation and tests for weakly connected components
 * Added C API definition for strongly connected components
 * Updated the C API test functions for supporting the `is_symmetric` property
 * Added C unit tests for SCC, and an implementation that returns `NOT_IMPLEMENTED`

I could add some mock data returns, although the output from SCC is the same as the output from WCC.  So python testing could just call WCC instead until there is an SCC implementation.

Authors:
  - Chuck Hastings (https://github.com/ChuckHastings)

Approvers:
  - Seunghwa Kang (https://github.com/seunghwak)

URL: #2185

cpp/CMakeLists.txt

@@ -366,6 +366,9 @@ add_library(cugraph_c
         src/c_api/extract_paths.cpp
         src/c_api/random_walks.cpp
         src/c_api/uniform_neighbor_sampling.cpp
+        src/c_api/labeling_result.cpp
+        src/c_api/weakly_connected_components.cpp
+        src/c_api/strongly_connected_components.cpp
         )
 add_library(cugraph::cugraph_c ALIAS cugraph_c)
 

cpp/include/cugraph_c/algorithms.h

@@ -373,3 +373,5 @@ void cugraph_sample_result_free(cugraph_sample_result_t* result);
 #ifdef __cplusplus
 }
 #endif
+
+#include <cugraph_c/labeling_algorithms.h>

cpp/include/cugraph_c/labeling_algorithms.h

@@ -0,0 +1,101 @@
+/*
+ * Copyright (c) 2022, NVIDIA CORPORATION.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <cugraph_c/error.h>
+#include <cugraph_c/graph.h>
+#include <cugraph_c/resource_handle.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief     Opaque labeling result type
+ */
+typedef struct {
+  int32_t align_;
+} cugraph_labeling_result_t;
+
+/**
+ * @brief     Get the vertex ids from the labeling result
+ *
+ * @param [in]   result   The result from a labeling algorithm
+ * @return type erased array of vertex ids
+ */
+cugraph_type_erased_device_array_view_t* cugraph_labeling_result_get_vertices(
+  cugraph_labeling_result_t* result);
+
+/**
+ * @brief     Get the label values from the labeling result
+ *
+ * @param [in]   result   The result from a labeling algorithm
+ * @return type erased array of label values
+ */
+cugraph_type_erased_device_array_view_t* cugraph_labeling_result_get_labels(
+  cugraph_labeling_result_t* result);
+
+/**
+ * @brief     Free labeling result
+ *
+ * @param [in]   result   The result from a labeling algorithm
+ */
+void cugraph_labeling_result_free(cugraph_labeling_result_t* result);
+
+/**
+ * @brief Labels each vertex in the input graph with its (weakly-connected-)component ID
+ *
+ * The input graph must be symmetric. Component IDs can be arbitrary integers (they can be
+ * non-consecutive and are not ordered by component size or any other criterion).
+ *
+ * @param [in]  handle      Handle for accessing resources
+ * @param [in]  graph       Pointer to graph
+ * @param [in]  do_expensive_check A flag to run expensive checks for input arguments (if set to
+ * `true`).
+ * @param [out] result      Opaque pointer to labeling results
+ * @param [out] error       Pointer to an error object storing details of any error.  Will
+ *                          be populated if error code is not CUGRAPH_SUCCESS
+ */
+cugraph_error_code_t cugraph_weakly_connected_components(const cugraph_resource_handle_t* handle,
+                                                         cugraph_graph_t* graph,
+                                                         bool_t do_expensive_check,
+                                                         cugraph_labeling_result_t** result,
+                                                         cugraph_error_t** error);
+
+/**
+ * @brief Labels each vertex in the input graph with its (strongly-connected-)component ID
+ *
+ * The input graph may be asymmetric. Component IDs can be arbitrary integers (they can be
+ * non-consecutive and are not ordered by component size or any other criterion).
+ *
+ * @param [in]  handle      Handle for accessing resources
+ * @param [in]  graph       Pointer to graph
+ * @param [in]  do_expensive_check A flag to run expensive checks for input arguments (if set to
+ * `true`).
+ * @param [out] result      Opaque pointer to labeling results
+ * @param [out] error       Pointer to an error object storing details of any error.  Will
+ *                          be populated if error code is not CUGRAPH_SUCCESS
+ */
+cugraph_error_code_t cugraph_strongly_connected_components(const cugraph_resource_handle_t* handle,
+                                                           cugraph_graph_t* graph,
+                                                           bool_t do_expensive_check,
+                                                           cugraph_labeling_result_t** result,
+                                                           cugraph_error_t** error);
+
+#ifdef __cplusplus
+}
+#endif

cpp/src/c_api/katz.cpp

@@ -98,7 +98,7 @@ struct katz_functor : public cugraph::c_api::abstract_functor {
         cugraph::detail::sequence_fill(handle_.get_stream(),
                                        betas_vertex_ids.data(),
                                        betas_vertex_ids.size(),
-                                       graph_view.local_vertex_partition_range_size());
+                                       graph_view.local_vertex_partition_range_first());
 
         betas.resize(graph_view.local_vertex_partition_range_size(), handle_.get_stream());
 

cpp/src/c_api/labeling_result.cpp

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2022, NVIDIA CORPORATION.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <cugraph_c/labeling_algorithms.h>
+
+#include <c_api/labeling_result.hpp>
+
+extern "C" cugraph_type_erased_device_array_view_t* cugraph_labeling_result_get_vertices(
+  cugraph_labeling_result_t* result)
+{
+  auto internal_pointer = reinterpret_cast<cugraph::c_api::cugraph_labeling_result_t*>(result);
+  return reinterpret_cast<cugraph_type_erased_device_array_view_t*>(
+    internal_pointer->vertex_ids_->view());
+}
+
+extern "C" cugraph_type_erased_device_array_view_t* cugraph_labeling_result_get_labels(
+  cugraph_labeling_result_t* result)
+{
+  auto internal_pointer = reinterpret_cast<cugraph::c_api::cugraph_labeling_result_t*>(result);
+  return reinterpret_cast<cugraph_type_erased_device_array_view_t*>(
+    internal_pointer->labels_->view());
+}
+
+extern "C" void cugraph_labeling_result_free(cugraph_labeling_result_t* result)
+{
+  auto internal_pointer = reinterpret_cast<cugraph::c_api::cugraph_labeling_result_t*>(result);
+  delete internal_pointer->vertex_ids_;
+  delete internal_pointer->labels_;
+  delete internal_pointer;
+}

cpp/src/c_api/labeling_result.hpp

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2022, NVIDIA CORPORATION.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <c_api/array.hpp>
+
+namespace cugraph {
+namespace c_api {
+
+struct cugraph_labeling_result_t {
+  cugraph_type_erased_device_array_t* vertex_ids_;
+  cugraph_type_erased_device_array_t* labels_;
+};
+
+}  // namespace c_api
+}  // namespace cugraph

cpp/src/c_api/strongly_connected_components.cpp

@@ -0,0 +1,86 @@
+/*
+ * Copyright (c) 2022, NVIDIA CORPORATION.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <cugraph_c/labeling_algorithms.h>
+
+#include <c_api/abstract_functor.hpp>
+#include <c_api/graph.hpp>
+#include <c_api/labeling_result.hpp>
+#include <c_api/resource_handle.hpp>
+#include <c_api/utils.hpp>
+
+#include <cugraph/algorithms.hpp>
+#include <cugraph/detail/shuffle_wrappers.hpp>
+#include <cugraph/detail/utility_wrappers.hpp>
+#include <cugraph/graph_functions.hpp>
+
+#include <optional>
+
+namespace {
+
+struct scc_functor : public cugraph::c_api::abstract_functor {
+  raft::handle_t const& handle_;
+  cugraph::c_api::cugraph_graph_t* graph_{};
+  bool do_expensive_check_{};
+  cugraph::c_api::cugraph_labeling_result_t* result_{};
+
+  scc_functor(::cugraph_resource_handle_t const* handle,
+              ::cugraph_graph_t* graph,
+              bool do_expensive_check)
+    : abstract_functor(),
+      handle_(*reinterpret_cast<cugraph::c_api::cugraph_resource_handle_t const*>(handle)->handle_),
+      graph_(reinterpret_cast<cugraph::c_api::cugraph_graph_t*>(graph)),
+      do_expensive_check_(do_expensive_check)
+  {
+  }
+
+  template <typename vertex_t,
+            typename edge_t,
+            typename weight_t,
+            bool store_transposed,
+            bool multi_gpu>
+  void operator()()
+  {
+    if constexpr (!cugraph::is_candidate<vertex_t, edge_t, weight_t>::value) {
+      unsupported();
+    } else {
+      // SCC expects store_transposed == false
+      if constexpr (store_transposed) {
+        error_code_ = cugraph::c_api::
+          transpose_storage<vertex_t, edge_t, weight_t, store_transposed, multi_gpu>(
+            handle_, graph_, error_.get());
+        if (error_code_ != CUGRAPH_SUCCESS) return;
+      }
+
+      error_code_            = CUGRAPH_NOT_IMPLEMENTED;
+      error_->error_message_ = "SCC Not currently implemented";
+    }
+  }
+};
+
+}  // namespace
+
+extern "C" cugraph_error_code_t cugraph_strongly_connected_components(
+  const cugraph_resource_handle_t* handle,
+  cugraph_graph_t* graph,
+  bool_t do_expensive_check,
+  cugraph_labeling_result_t** result,
+  cugraph_error_t** error)
+{
+  scc_functor functor(handle, graph, do_expensive_check);
+
+  return cugraph::c_api::run_algorithm(graph, functor, result, error);
+}

cpp/src/c_api/weakly_connected_components.cpp

@@ -0,0 +1,105 @@
+/*
+ * Copyright (c) 2022, NVIDIA CORPORATION.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <cugraph_c/labeling_algorithms.h>
+
+#include <c_api/abstract_functor.hpp>
+#include <c_api/graph.hpp>
+#include <c_api/labeling_result.hpp>
+#include <c_api/resource_handle.hpp>
+#include <c_api/utils.hpp>
+
+#include <cugraph/algorithms.hpp>
+#include <cugraph/detail/shuffle_wrappers.hpp>
+#include <cugraph/detail/utility_wrappers.hpp>
+#include <cugraph/graph_functions.hpp>
+
+#include <optional>
+
+namespace {
+
+struct wcc_functor : public cugraph::c_api::abstract_functor {
+  raft::handle_t const& handle_;
+  cugraph::c_api::cugraph_graph_t* graph_{};
+  bool do_expensive_check_{};
+  cugraph::c_api::cugraph_labeling_result_t* result_{};
+
+  wcc_functor(cugraph_resource_handle_t const* handle,
+              cugraph_graph_t* graph,
+              bool do_expensive_check)
+    : abstract_functor(),
+      handle_(*reinterpret_cast<cugraph::c_api::cugraph_resource_handle_t const*>(handle)->handle_),
+      graph_(reinterpret_cast<cugraph::c_api::cugraph_graph_t*>(graph)),
+      do_expensive_check_(do_expensive_check)
+  {
+  }
+
+  template <typename vertex_t,
+            typename edge_t,
+            typename weight_t,
+            bool store_transposed,
+            bool multi_gpu>
+  void operator()()
+  {
+    if constexpr (!cugraph::is_candidate<vertex_t, edge_t, weight_t>::value) {
+      unsupported();
+    } else {
+      // WCC expects store_transposed == false
+      if constexpr (store_transposed) {
+        error_code_ = cugraph::c_api::
+          transpose_storage<vertex_t, edge_t, weight_t, store_transposed, multi_gpu>(
+            handle_, graph_, error_.get());
+        if (error_code_ != CUGRAPH_SUCCESS) return;
+      }
+
+      auto graph =
+        reinterpret_cast<cugraph::graph_t<vertex_t, edge_t, weight_t, false, multi_gpu>*>(
+          graph_->graph_);
+
+      auto graph_view = graph->view();
+
+      auto number_map = reinterpret_cast<rmm::device_uvector<vertex_t>*>(graph_->number_map_);
+
+      rmm::device_uvector<vertex_t> components(graph_view.local_vertex_partition_range_size(),
+                                               handle_.get_stream());
+
+      cugraph::weakly_connected_components<vertex_t, edge_t, weight_t, multi_gpu>(
+        handle_, graph_view, components.data(), do_expensive_check_);
+
+      rmm::device_uvector<vertex_t> vertex_ids(graph_view.local_vertex_partition_range_size(),
+                                               handle_.get_stream());
+      raft::copy(vertex_ids.data(), number_map->data(), vertex_ids.size(), handle_.get_stream());
+
+      result_ = new cugraph::c_api::cugraph_labeling_result_t{
+        new cugraph::c_api::cugraph_type_erased_device_array_t(vertex_ids, graph_->vertex_type_),
+        new cugraph::c_api::cugraph_type_erased_device_array_t(components, graph_->vertex_type_)};
+    }
+  }
+};
+
+}  // namespace
+
+extern "C" cugraph_error_code_t cugraph_weakly_connected_components(
+  const cugraph_resource_handle_t* handle,
+  cugraph_graph_t* graph,
+  bool_t do_expensive_check,
+  cugraph_labeling_result_t** result,
+  cugraph_error_t** error)
+{
+  wcc_functor functor(handle, graph, do_expensive_check);
+
+  return cugraph::c_api::run_algorithm(graph, functor, result, error);
+}