Bindings for RMAT (#1573)

Bindings for RMAT
Bindings for the list of RMAT graphs
includes some quick fixes to address some sphinx doc-building warnings
closes #1473

Authors:
  - Joseph Nke (https://github.com/jnke2016)
  - Rick Ratzel (https://github.com/rlratzel)

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

URL: #1573

Author: jnke2016

cpp/include/utilities/cython.hpp

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 #pragma once
-
 #include <experimental/graph.hpp>
+#include <experimental/graph_generator.hpp>
 #include <graph.hpp>
 #include <raft/handle.hpp>
 #include <rmm/device_uvector.hpp>
@@ -207,6 +207,12 @@ struct random_walk_ret_t {
   std::unique_ptr<rmm::device_buffer> d_sizes_;
 };
 
+struct graph_generator_t {
+  std::unique_ptr<rmm::device_buffer> d_source;
+  std::unique_ptr<rmm::device_buffer> d_destination;
+};
+
+// enum class generator_distribution_t { POWER_LAW = 0, UNIFORM };
 // aggregate for random_walks() COO return type
 // to be exposed to cython:
 //
@@ -488,6 +494,31 @@ std::unique_ptr<cy_multi_edgelists_t> call_egonet(raft::handle_t const& handle,
                                                   vertex_t* source_vertex,
                                                   vertex_t n_subgraphs,
                                                   vertex_t radius);
+
+// Wrapper for calling graph generator
+template <typename vertex_t>
+std::unique_ptr<graph_generator_t> call_generate_rmat_edgelist(raft::handle_t const& handle,
+                                                               size_t scale,
+                                                               size_t num_edges,
+                                                               double a,
+                                                               double b,
+                                                               double c,
+                                                               uint64_t seed,
+                                                               bool clip_and_flip,
+                                                               bool scramble_vertex_ids);
+template <typename vertex_t>
+std::vector<std::pair<std::unique_ptr<rmm::device_buffer>, std::unique_ptr<rmm::device_buffer>>>
+call_generate_rmat_edgelists(raft::handle_t const& handle,
+                             size_t n_edgelists,
+                             size_t min_scale,
+                             size_t max_scale,
+                             size_t edge_factor,
+                             cugraph::experimental::generator_distribution_t size_distribution,
+                             cugraph::experimental::generator_distribution_t edge_distribution,
+                             uint64_t seed,
+                             bool clip_and_flip,
+                             bool scramble_vertex_ids);
+
 // wrapper for random_walks.
 //
 template <typename vertex_t, typename edge_t>

cpp/src/utilities/cython.cu

@@ -13,7 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
+#include <experimental/graph_generator.hpp>
+//#include <experimental/generate_rmat_edgelist.cu>
 #include <algorithms.hpp>
 #include <experimental/detail/graph_utils.cuh>
 #include <experimental/graph_functions.hpp>
@@ -789,6 +790,70 @@ std::unique_ptr<cy_multi_edgelists_t> call_egonet(raft::handle_t const& handle,
     CUGRAPH_FAIL("vertexType/edgeType combination unsupported");
   }
 }
+// Wrapper for graph generate_rmat_edgelist()
+// to expose the API to cython
+// enum class generator_distribution_t { POWER_LAW = 0, UNIFORM };
+template <typename vertex_t>
+std::unique_ptr<graph_generator_t> call_generate_rmat_edgelist(raft::handle_t const& handle,
+                                                               size_t scale,
+                                                               size_t num_edges,
+                                                               double a,
+                                                               double b,
+                                                               double c,
+                                                               uint64_t seed,
+                                                               bool clip_and_flip,
+                                                               bool scramble_vertex_ids)
+{
+  auto src_dst_tuple = cugraph::experimental::generate_rmat_edgelist<vertex_t>(
+    handle, scale, num_edges, a, b, c, seed, clip_and_flip, scramble_vertex_ids);
+
+  graph_generator_t gg_vals{
+    std::make_unique<rmm::device_buffer>(std::get<0>(src_dst_tuple).release()),
+    std::make_unique<rmm::device_buffer>(std::get<1>(src_dst_tuple).release())};
+
+  return std::make_unique<graph_generator_t>(std::move(gg_vals));
+}
+
+template <typename vertex_t>
+std::vector<std::pair<std::unique_ptr<rmm::device_buffer>, std::unique_ptr<rmm::device_buffer>>>
+call_generate_rmat_edgelists(raft::handle_t const& handle,
+                             size_t n_edgelists,
+                             size_t min_scale,
+                             size_t max_scale,
+                             size_t edge_factor,
+                             cugraph::experimental::generator_distribution_t size_distribution,
+                             cugraph::experimental::generator_distribution_t edge_distribution,
+                             uint64_t seed,
+                             bool clip_and_flip,
+                             bool scramble_vertex_ids)
+{
+  auto src_dst_vec_tuple =
+    cugraph::experimental::generate_rmat_edgelists<vertex_t>(handle,
+                                                             n_edgelists,
+                                                             min_scale,
+                                                             max_scale,
+                                                             edge_factor,
+                                                             size_distribution,
+                                                             edge_distribution,
+                                                             seed,
+                                                             clip_and_flip,
+                                                             scramble_vertex_ids);
+
+  std::vector<std::pair<std::unique_ptr<rmm::device_buffer>, std::unique_ptr<rmm::device_buffer>>>
+    gg_vec;
+
+  std::transform(
+    src_dst_vec_tuple.begin(),
+    src_dst_vec_tuple.end(),
+    std::back_inserter(gg_vec),
+    [](auto& tpl_dev_uvec) {
+      return std::make_pair(
+        std::move(std::make_unique<rmm::device_buffer>(std::get<0>(tpl_dev_uvec).release())),
+        std::move(std::make_unique<rmm::device_buffer>(std::get<1>(tpl_dev_uvec).release())));
+    });
+
+  return gg_vec;
+}
 
 // Wrapper for random_walks() through a graph container
 // to expose the API to cython.
@@ -1360,5 +1425,55 @@ template std::unique_ptr<renum_quad_t<int64_t, int64_t>> call_renumber(
   bool do_expensive_check,
   bool multi_gpu);
 
+template std::unique_ptr<graph_generator_t> call_generate_rmat_edgelist<int32_t>(
+  raft::handle_t const& handle,
+  size_t scale,
+  size_t num_edges,
+  double a,
+  double b,
+  double c,
+  uint64_t seed,
+  bool clip_and_flip,
+  bool scramble_vertex_ids);
+
+template std::unique_ptr<graph_generator_t> call_generate_rmat_edgelist<int64_t>(
+  raft::handle_t const& handle,
+  size_t scale,
+  size_t num_edges,
+  double a,
+  double b,
+  double c,
+  uint64_t seed,
+  bool clip_and_flip,
+  bool scramble_vertex_ids);
+
+template std::vector<
+  std::pair<std::unique_ptr<rmm::device_buffer>, std::unique_ptr<rmm::device_buffer>>>
+call_generate_rmat_edgelists<int32_t>(
+  raft::handle_t const& handle,
+  size_t n_edgelists,
+  size_t min_scale,
+  size_t max_scale,
+  size_t edge_factor,
+  cugraph::experimental::generator_distribution_t size_distribution,
+  cugraph::experimental::generator_distribution_t edge_distribution,
+  uint64_t seed,
+  bool clip_and_flip,
+  bool scramble_vertex_ids);
+
+template std::vector<
+  std::pair<std::unique_ptr<rmm::device_buffer>, std::unique_ptr<rmm::device_buffer>>>
+call_generate_rmat_edgelists<int64_t>(
+  raft::handle_t const& handle,
+  size_t n_edgelists,
+  size_t min_scale,
+  size_t max_scale,
+  size_t edge_factor,
+  cugraph::experimental::generator_distribution_t size_distribution,
+  cugraph::experimental::generator_distribution_t edge_distribution,
+  uint64_t seed,
+  bool clip_and_flip,
+  bool scramble_vertex_ids);
+
 }  // namespace cython
 }  // namespace cugraph

docs/cugraph/source/api.rst

@@ -10,7 +10,7 @@ Structure
 Graph
 -----
 
-.. autoclass:: cugraph.structure.graph.Graph
+.. autoclass:: cugraph.structure.graph_classes.Graph
     :members:
     :undoc-members:
 
@@ -143,7 +143,7 @@ Core Number
 .. automodule:: cugraph.cores.core_number
     :members:
     :undoc-members:
-    
+
 K-Core
 ------
 
@@ -196,7 +196,7 @@ Pagerank (MG)
 
 .. automodule:: cugraph.dask.link_analysis.pagerank
     :members: pagerank
-    :undoc-members: 
+    :undoc-members:
 
 
 Link Prediction

python/cugraph/generators/__init__.py

@@ -0,0 +1,14 @@
+# 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.
+
+from .rmat import rmat, multi_rmat

python/cugraph/generators/rmat.pxd

@@ -0,0 +1,45 @@
+# 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.
+from libcpp cimport bool
+from cugraph.structure.graph_utilities cimport *
+from libcpp.vector cimport vector
+
+cdef extern from "experimental/graph_generator.hpp" namespace "cugraph::experimental":
+    ctypedef enum generator_distribution_t:
+        POWER_LAW "cugraph::experimental::generator_distribution_t::POWER_LAW"
+        UNIFORM "cugraph::experimental::generator_distribution_t::UNIFORM"
+
+
+cdef extern from "utilities/cython.hpp" namespace "cugraph::cython":
+    cdef unique_ptr[graph_generator_t] call_generate_rmat_edgelist[vertex_t] (
+        const handle_t &handle,
+        size_t scale,
+        size_t num_edges,
+        double a,
+        double b,
+        double c,
+        int seed,
+        bool clip_and_flip,
+        bool scramble_vertex_ids) except +
+
+    cdef vector[pair[unique_ptr[device_buffer], unique_ptr[device_buffer]]] call_generate_rmat_edgelists[vertex_t](
+        const handle_t &handle,
+        size_t n_edgelists,
+        size_t min_scale,
+        size_t max_scale,
+        size_t edge_factor,
+        generator_distribution_t size_distribution,
+        generator_distribution_t edge_distribution,
+        int seed,
+        bool clip_and_flip,
+        bool scramble_vertex_ids) except +