K-core decomposition API update (#1924)

Partially addresses #1909.

- [x] Add a K-core  function declaration.

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

Approvers:
  - Chuck Hastings (https://github.com/ChuckHastings)
  - Rick Ratzel (https://github.com/rlratzel)

URL: #1924

cpp/CMakeLists.txt

@@ -180,7 +180,9 @@ add_library(cugraph SHARED
     src/community/legacy/extract_subgraph_by_vertex.cu
     src/community/legacy/egonet.cu
     src/sampling/random_walks.cu
-    src/cores/core_number.cu
+    src/cores/legacy/core_number.cu
+    src/cores/core_number_sg.cu
+    src/cores/core_number_mg.cu
     src/traversal/two_hop_neighbors.cu
     src/components/connectivity.cu
     src/centrality/legacy/katz_centrality.cu

cpp/include/cugraph/algorithms.hpp

@@ -1440,4 +1440,37 @@ void weakly_connected_components(
   vertex_t* components,
   bool do_expensive_check = false);
 
+enum class k_core_degree_type_t { IN, OUT, INOUT };
+
+/**
+ * @brief   Compute core numbers of individual vertices from K-core decomposition.
+ *
+ * The input graph should not have self-loops nor multi-edges.
+ *
+ * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type.
+ * @tparam edge_t Type of edge identifiers. Needs to be an integral type.
+ * @tparam weight_t Type of edge weights. Needs to be a floating point type.
+ * @tparam multi_gpu Flag indicating whether template instantiation should target single-GPU (false)
+ * or multi-GPU (true).
+ * @param handle RAFT handle object to encapsulate resources (e.g. CUDA stream, communicator, and
+ * handles to various CUDA libraries) to run graph algorithms.
+ * @param graph_view Graph view object.
+ * @param core_numbers Pointer to the output core number array.
+ * @param degree_type Dictate whether to compute the K-core decomposition based on in-degrees,
+ * out-degrees, or in-degrees + out_degrees.
+ * @param k_first Find K-cores from K = k_first. Any vertices that do not belong to k_first-core
+ * will have core numbers of 0.
+ * @param k_last Find K-cores to K = k_last. Any vertices that belong to (k_last + 1) core will have
+ * core numbers of k_last.
+ * @param do_expensive_check A flag to run expensive checks for input arguments (if set to `true`).
+ */
+template <typename vertex_t, typename edge_t, typename weight_t, bool multi_gpu>
+void core_number(raft::handle_t const& handle,
+                 graph_view_t<vertex_t, edge_t, weight_t, false, multi_gpu> const& graph_view,
+                 vertex_t* core_numbers,
+                 k_core_degree_type_t degree_type,
+                 size_t k_first          = 0,
+                 size_t k_last           = std::numeric_limits<size_t>::max(),
+                 bool do_expensive_check = false);
+
 }  // namespace cugraph

cpp/src/cores/core_number_impl.cuh

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2020-2021, 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/algorithms.hpp>
+#include <cugraph/graph_view.hpp>
+#include <cugraph/utilities/error.hpp>
+
+#include <raft/handle.hpp>
+
+#include <cstddef>
+
+namespace cugraph {
+
+template <typename vertex_t, typename edge_t, typename weight_t, bool multi_gpu>
+void core_number(raft::handle_t const& handle,
+                 graph_view_t<vertex_t, edge_t, weight_t, false, multi_gpu> const& graph_view,
+                 vertex_t* core_numbers,
+                 k_core_degree_type_t degree_type,
+                 size_t k_first,
+                 size_t k_last,
+                 bool do_expensive_check)
+{
+  CUGRAPH_FAIL("unimplemented.");
+}
+
+}  // namespace cugraph

cpp/src/cores/core_number_mg.cu

@@ -0,0 +1,71 @@
+/*
+ * Copyright (c) 2021, 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 <cores/core_number_impl.cuh>
+
+namespace cugraph {
+
+// MG instantiation
+
+template void core_number(raft::handle_t const& handle,
+                          graph_view_t<int32_t, int32_t, float, false, true> const& graph_view,
+                          int32_t* core_numbers,
+                          k_core_degree_type_t degree_type,
+                          size_t k_first,
+                          size_t k_last,
+                          bool do_expensive_check);
+
+template void core_number(raft::handle_t const& handle,
+                          graph_view_t<int32_t, int32_t, double, false, true> const& graph_view,
+                          int32_t* core_numbers,
+                          k_core_degree_type_t degree_type,
+                          size_t k_first,
+                          size_t k_last,
+                          bool do_expensive_check);
+
+template void core_number(raft::handle_t const& handle,
+                          graph_view_t<int32_t, int64_t, float, false, true> const& graph_view,
+                          int32_t* core_numbers,
+                          k_core_degree_type_t degree_type,
+                          size_t k_first,
+                          size_t k_last,
+                          bool do_expensive_check);
+
+template void core_number(raft::handle_t const& handle,
+                          graph_view_t<int32_t, int64_t, double, false, true> const& graph_view,
+                          int32_t* core_numbers,
+                          k_core_degree_type_t degree_type,
+                          size_t k_first,
+                          size_t k_last,
+                          bool do_expensive_check);
+
+template void core_number(raft::handle_t const& handle,
+                          graph_view_t<int64_t, int64_t, float, false, true> const& graph_view,
+                          int64_t* core_numbers,
+                          k_core_degree_type_t degree_type,
+                          size_t k_first,
+                          size_t k_last,
+                          bool do_expensive_check);
+
+template void core_number(raft::handle_t const& handle,
+                          graph_view_t<int64_t, int64_t, double, false, true> const& graph_view,
+                          int64_t* core_numbers,
+                          k_core_degree_type_t degree_type,
+                          size_t k_first,
+                          size_t k_last,
+                          bool do_expensive_check);
+
+}  // namespace cugraph

cpp/src/cores/core_number_sg.cu

@@ -0,0 +1,71 @@
+/*
+ * Copyright (c) 2021, 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 <cores/core_number_impl.cuh>
+
+namespace cugraph {
+
+// MG instantiation
+
+template void core_number(raft::handle_t const& handle,
+                          graph_view_t<int32_t, int32_t, float, false, false> const& graph_view,
+                          int32_t* core_numbers,
+                          k_core_degree_type_t degree_type,
+                          size_t k_first,
+                          size_t k_last,
+                          bool do_expensive_check);
+
+template void core_number(raft::handle_t const& handle,
+                          graph_view_t<int32_t, int32_t, double, false, false> const& graph_view,
+                          int32_t* core_numbers,
+                          k_core_degree_type_t degree_type,
+                          size_t k_first,
+                          size_t k_last,
+                          bool do_expensive_check);
+
+template void core_number(raft::handle_t const& handle,
+                          graph_view_t<int32_t, int64_t, float, false, false> const& graph_view,
+                          int32_t* core_numbers,
+                          k_core_degree_type_t degree_type,
+                          size_t k_first,
+                          size_t k_last,
+                          bool do_expensive_check);
+
+template void core_number(raft::handle_t const& handle,
+                          graph_view_t<int32_t, int64_t, double, false, false> const& graph_view,
+                          int32_t* core_numbers,
+                          k_core_degree_type_t degree_type,
+                          size_t k_first,
+                          size_t k_last,
+                          bool do_expensive_check);
+
+template void core_number(raft::handle_t const& handle,
+                          graph_view_t<int64_t, int64_t, float, false, false> const& graph_view,
+                          int64_t* core_numbers,
+                          k_core_degree_type_t degree_type,
+                          size_t k_first,
+                          size_t k_last,
+                          bool do_expensive_check);
+
+template void core_number(raft::handle_t const& handle,
+                          graph_view_t<int64_t, int64_t, double, false, false> const& graph_view,
+                          int64_t* core_numbers,
+                          k_core_degree_type_t degree_type,
+                          size_t k_first,
+                          size_t k_last,
+                          bool do_expensive_check);
+
+}  // namespace cugraph