Refactor RMAT (#3662)

This PR refactors the RMAT generator, update docstrings and tests

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

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

URL: #3662

cpp/CMakeLists.txt

@@ -192,7 +192,6 @@ set(CUGRAPH_SOURCES
     src/community/detail/mis_mg.cu
     src/detail/utility_wrappers.cu
     src/structure/graph_view_mg.cu
-    src/utilities/cython.cu
     src/utilities/path_retrieval.cu
     src/structure/legacy/graph.cu
     src/linear_assignment/legacy/hungarian.cu

cpp/include/cugraph/graph_generators.hpp

@@ -66,6 +66,9 @@ namespace cugraph {
  * @param clip_and_flip Flag controlling whether to generate edges only in the lower triangular part
  * (including the diagonal) of the graph adjacency matrix (if set to `true`) or not (if set to
  * `false`).
+ * @param scramble_vertex_ids Flag controlling whether to scramble vertex ID bits (if set to `true`)
+ * or not (if set to `false`); scrambling vertex ID bits breaks correlation between vertex ID values
+ * and vertex degrees.
  * @return std::tuple<rmm::device_uvector<vertex_t>, rmm::device_uvector<vertex_t>> A tuple of
  * rmm::device_uvector objects for edge source vertex IDs and edge destination vertex IDs.
  */
@@ -74,11 +77,12 @@ std::tuple<rmm::device_uvector<vertex_t>, rmm::device_uvector<vertex_t>> generat
   raft::handle_t const& handle,
   size_t scale,
   size_t num_edges,
-  double a           = 0.57,
-  double b           = 0.19,
-  double c           = 0.19,
-  uint64_t seed      = 0,
-  bool clip_and_flip = false);
+  double a                 = 0.57,
+  double b                 = 0.19,
+  double c                 = 0.19,
+  uint64_t seed            = 0,
+  bool clip_and_flip       = false,
+  bool scramble_vertex_ids = false);
 
 /**
  * @brief generate an edge list for an R-mat graph.
@@ -113,6 +117,9 @@ std::tuple<rmm::device_uvector<vertex_t>, rmm::device_uvector<vertex_t>> generat
  * @param clip_and_flip Flag controlling whether to generate edges only in the lower triangular part
  * (including the diagonal) of the graph adjacency matrix (if set to `true`) or not (if set to
  * `false`).
+ * @param scramble_vertex_ids Flag controlling whether to scramble vertex ID bits (if set to `true`)
+ * or not (if set to `false`); scrambling vertex ID bits breaks correlation between vertex ID values
+ * and vertex degrees.
  * @return std::tuple<rmm::device_uvector<vertex_t>, rmm::device_uvector<vertex_t>> A tuple of
  * rmm::device_uvector objects for edge source vertex IDs and edge destination vertex IDs.
  */
@@ -122,10 +129,11 @@ std::tuple<rmm::device_uvector<vertex_t>, rmm::device_uvector<vertex_t>> generat
   raft::random::RngState& rng_state,
   size_t scale,
   size_t num_edges,
-  double a           = 0.57,
-  double b           = 0.19,
-  double c           = 0.19,
-  bool clip_and_flip = false);
+  double a                 = 0.57,
+  double b                 = 0.19,
+  double c                 = 0.19,
+  bool clip_and_flip       = false,
+  bool scramble_vertex_ids = false);
 
 /**
  * @brief generate an edge list for a bipartite R-mat graph.
@@ -199,6 +207,9 @@ enum class generator_distribution_t { POWER_LAW = 0, UNIFORM };
  * @param clip_and_flip Flag controlling whether to generate edges only in the lower triangular part
  * (including the diagonal) of the graph adjacency matrix (if set to `true`) or not (if set to
  * `false`).
+ * @param scramble_vertex_ids Flag controlling whether to scramble vertex ID bits (if set to `true`)
+ * or not (if set to `false`); scrambling vertex ID bits breaks correlation between vertex ID values
+ * and vertex degrees.
  * @return A vector of std::tuple<rmm::device_uvector<vertex_t>, rmm::device_uvector<vertex_t>> of
  *size @p n_edgelists, each vector element being a tuple of rmm::device_uvector objects for edge
  *source vertex IDs and edge destination vertex IDs.
@@ -214,7 +225,8 @@ generate_rmat_edgelists(
   generator_distribution_t size_distribution = generator_distribution_t::POWER_LAW,
   generator_distribution_t edge_distribution = generator_distribution_t::POWER_LAW,
   uint64_t seed                              = 0,
-  bool clip_and_flip                         = false);
+  bool clip_and_flip                         = false,
+  bool scramble_vertex_ids                   = false);
 
 /**
  * @brief generate multiple edge lists using the R-mat graph generator.
@@ -245,6 +257,9 @@ generate_rmat_edgelists(
  * @param clip_and_flip Flag controlling whether to generate edges only in the lower triangular part
  * (including the diagonal) of the graph adjacency matrix (if set to `true`) or not (if set to
  * `false`).
+ * @param scramble_vertex_ids Flag controlling whether to scramble vertex ID bits (if set to `true`)
+ * or not (if set to `false`); scrambling vertex ID bits breaks correlation between vertex ID values
+ * and vertex degrees.
  * @return A vector of std::tuple<rmm::device_uvector<vertex_t>, rmm::device_uvector<vertex_t>> of
  *size @p n_edgelists, each vector element being a tuple of rmm::device_uvector objects for edge
  *source vertex IDs and edge destination vertex IDs.
@@ -260,7 +275,8 @@ generate_rmat_edgelists(
   size_t edge_factor                         = 16,
   generator_distribution_t size_distribution = generator_distribution_t::POWER_LAW,
   generator_distribution_t edge_distribution = generator_distribution_t::POWER_LAW,
-  bool clip_and_flip                         = false);
+  bool clip_and_flip                         = false,
+  bool scramble_vertex_ids                   = false);
 
 /**
  * @brief generate an edge list for path graph

cpp/include/cugraph_c/graph_generators.h

@@ -136,6 +136,9 @@ void cugraph_coo_list_free(cugraph_coo_list_t* coo_list);
  * @param [in]     clip_and_flip      Flag controlling whether to generate edges only in the lower
  * triangular part (including the diagonal) of the graph adjacency matrix (if set to `true`) or not
  * (if set to `false`).
+ * @param [in]     scramble_vertex_ids Flag controlling whether to scramble vertex ID bits
+ * (if set to `true`) or not (if set to `false`); scrambling vertex ID bits breaks correlation
+ * between vertex ID values and vertex degrees.
  * @param [out]    result             Opaque pointer to generated coo
  * @param [out]    error              Pointer to an error object storing details of any error.  Will
  *                                    be populated if error code is not CUGRAPH_SUCCESS
@@ -149,6 +152,7 @@ cugraph_error_code_t cugraph_generate_rmat_edgelist(const cugraph_resource_handl
                                                     double b,
                                                     double c,
                                                     bool_t clip_and_flip,
+                                                    bool_t scramble_vertex_ids,
                                                     cugraph_coo_t** result,
                                                     cugraph_error_t** error);
 
@@ -172,6 +176,9 @@ cugraph_error_code_t cugraph_generate_rmat_edgelist(const cugraph_resource_handl
  * @param [in]     clip_and_flip      Flag controlling whether to generate edges only in the lower
  * triangular part (including the diagonal) of the graph adjacency matrix (if set to `true`) or not
  * (if set to `false`).
+ * @param [in]     scramble_vertex_ids Flag controlling whether to scramble vertex ID bits
+ * (if set to `true`) or not (if set to `false`); scrambling vertex ID bits breaks correlation
+ * between vertex ID values and vertex degrees.
  * @param [out]    result             Opaque pointer to generated coo list
  * @param [out]    error              Pointer to an error object storing details of any error.  Will
  *                                    be populated if error code is not CUGRAPH_SUCCESS
@@ -187,6 +194,7 @@ cugraph_error_code_t cugraph_generate_rmat_edgelists(
   cugraph_generator_distribution_t size_distribution,
   cugraph_generator_distribution_t edge_distribution,
   bool_t clip_and_flip,
+  bool_t scramble_vertex_ids,
   cugraph_coo_list_t** result,
   cugraph_error_t** error);
 

cpp/src/c_api/graph_generators.cpp

@@ -56,12 +56,13 @@ cugraph_error_code_t cugraph_generate_rmat_edgelist(raft::handle_t const& handle
                                                     double b,
                                                     double c,
                                                     bool_t clip_and_flip,
+                                                    bool_t scramble_vertex_ids,
                                                     cugraph::c_api::cugraph_coo_t** result,
                                                     cugraph::c_api::cugraph_error_t** error)
 {
   try {
     auto [src, dst] = cugraph::generate_rmat_edgelist<vertex_t>(
-      handle, rng_state, scale, num_edges, a, b, c, clip_and_flip);
+      handle, rng_state, scale, num_edges, a, b, c, clip_and_flip, scramble_vertex_ids);
 
     *result = new cugraph::c_api::cugraph_coo_t{
       std::make_unique<cugraph::c_api::cugraph_type_erased_device_array_t>(src, vertex_dtype),
@@ -90,6 +91,7 @@ cugraph_error_code_t cugraph_generate_rmat_edgelists(
   cugraph_generator_distribution_t size_distribution,
   cugraph_generator_distribution_t edge_distribution,
   bool_t clip_and_flip,
+  bool_t scramble_vertex_ids,
   cugraph::c_api::cugraph_coo_list_t** result,
   cugraph::c_api::cugraph_error_t** error)
 {
@@ -103,7 +105,8 @@ cugraph_error_code_t cugraph_generate_rmat_edgelists(
       edge_factor,
       static_cast<cugraph::generator_distribution_t>(size_distribution),
       static_cast<cugraph::generator_distribution_t>(edge_distribution),
-      clip_and_flip);
+      clip_and_flip,
+      scramble_vertex_ids);
 
     *result = new cugraph::c_api::cugraph_coo_list_t;
     (*result)->list_.resize(tuple_vector.size());
@@ -200,6 +203,7 @@ extern "C" cugraph_error_code_t cugraph_generate_rmat_edgelist(
   double b,
   double c,
   bool_t clip_and_flip,
+  bool_t scramble_vertex_ids,
   cugraph_coo_t** result,
   cugraph_error_t** error)
 {
@@ -219,6 +223,7 @@ extern "C" cugraph_error_code_t cugraph_generate_rmat_edgelist(
       b,
       c,
       clip_and_flip,
+      scramble_vertex_ids,
       reinterpret_cast<cugraph::c_api::cugraph_coo_t**>(result),
       reinterpret_cast<cugraph::c_api::cugraph_error_t**>(error));
   } else {
@@ -232,6 +237,7 @@ extern "C" cugraph_error_code_t cugraph_generate_rmat_edgelist(
       b,
       c,
       clip_and_flip,
+      scramble_vertex_ids,
       reinterpret_cast<cugraph::c_api::cugraph_coo_t**>(result),
       reinterpret_cast<cugraph::c_api::cugraph_error_t**>(error));
   }
@@ -247,6 +253,7 @@ extern "C" cugraph_error_code_t cugraph_generate_rmat_edgelists(
   cugraph_generator_distribution_t size_distribution,
   cugraph_generator_distribution_t edge_distribution,
   bool_t clip_and_flip,
+  bool_t scramble_vertex_ids,
   cugraph_coo_list_t** result,
   cugraph_error_t** error)
 {
@@ -267,6 +274,7 @@ extern "C" cugraph_error_code_t cugraph_generate_rmat_edgelists(
       size_distribution,
       edge_distribution,
       clip_and_flip,
+      scramble_vertex_ids,
       reinterpret_cast<cugraph::c_api::cugraph_coo_list_t**>(result),
       reinterpret_cast<cugraph::c_api::cugraph_error_t**>(error));
   } else {
@@ -281,6 +289,7 @@ extern "C" cugraph_error_code_t cugraph_generate_rmat_edgelists(
       size_distribution,
       edge_distribution,
       clip_and_flip,
+      scramble_vertex_ids,
       reinterpret_cast<cugraph::c_api::cugraph_coo_list_t**>(result),
       reinterpret_cast<cugraph::c_api::cugraph_error_t**>(error));
   }