Update PageRank to leverage pylibcugraph (rapidsai#2467)

This PR 

1. Extends the capabilities of the `PageRank CAPI` to the `python cuGraph API`
2. Update or Add support for the parameters `personalization` `precomputed_vertex_out_weight` and `nstart` for both the SG and MG implementation

closes rapidsai#2455
closes rapidsai#2430

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

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

URL: rapidsai#2467

cpp/include/cugraph/detail/shuffle_wrappers.hpp

@@ -62,6 +62,25 @@ template <typename vertex_t>
 rmm::device_uvector<vertex_t> shuffle_ext_vertices_by_gpu_id(
   raft::handle_t const& handle, rmm::device_uvector<vertex_t>&& d_vertices);
 
+/**
+ * @brief Shuffle vertex/value tuples using the external vertex key function which returns the
+ * target GPU ID.
+ *
+ * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type.
+ * @tparam value_t Type of values.
+ *
+ * @param[in] handle RAFT handle object to encapsulate resources (e.g. CUDA stream, communicator,
+ * @param[in] d_vertices Vertex IDs to shuffle
+ * @param[in] d_values Values to shuffle
+ *
+ * @return tuple containing device vector of shuffled vertices and device vector of shuffled values
+ */
+template <typename vertex_t, typename value_t>
+std::tuple<rmm::device_uvector<vertex_t>, rmm::device_uvector<value_t>>
+shuffle_ext_vertices_and_values_by_gpu_id(raft::handle_t const& handle,
+                                          rmm::device_uvector<vertex_t>&& d_vertices,
+                                          rmm::device_uvector<value_t>&& d_values);
+
 /**
  * @brief Shuffle vertices using the internal vertex key function which returns the target GPU ID.
  *

cpp/include/cugraph_c/centrality_algorithms.h

@@ -67,19 +67,31 @@ void cugraph_centrality_result_free(cugraph_centrality_result_t* result);
  *
  * @param [in]  handle      Handle for accessing resources
  * @param [in]  graph       Pointer to graph
+ * @param [in]  precomputed_vertex_out_weight_vertices
+ *                          Optionally send in precomputed sum of vertex out weights
+ *                          (a performance optimization).  This defines the vertices.
+ *                          Set to NULL if no value is passed.
  * @param [in]  precomputed_vertex_out_weight_sums
- *                          Optionally send in precomputed sume of vertex out weights
+ *                          Optionally send in precomputed sum of vertex out weights
  *                          (a performance optimization).  Set to NULL if
  *                          no value is passed.
+ * @param [in]  initial_guess_vertices
+ *                          Optionally send in an initial guess of the pagerank values
+ *                          (a performance optimization).  This defines the vertices.
+ *                          Set to NULL if no value is passed. If NULL, initial PageRank
+ *                          values are set to 1.0 divided by the number of vertices in
+ *                          the graph.
+ * @param [in]  initial_guess_values
+ *                          Optionally send in an initial guess of the pagerank values
+ *                          (a performance optimization).  Set to NULL if
+ *                          no value is passed. If NULL, initial PageRank values are set
+ *                          to 1.0 divided by the number of vertices in the graph.
  * @param [in]  alpha       PageRank damping factor.
  * @param [in]  epsilon     Error tolerance to check convergence. Convergence is assumed
  *                          if the sum of the differences in PageRank values between two
  *                          consecutive iterations is less than the number of vertices
  *                          in the graph multiplied by @p epsilon.
  * @param [in]  max_iterations Maximum number of PageRank iterations.
- * @param [in]  has_initial_guess If set to `true`, values in the PageRank output array (pointed by
- * @p pageranks) is used as initial PageRank values. If false, initial PageRank values are set
- * to 1.0 divided by the number of vertices in the 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 pagerank results
@@ -90,11 +102,13 @@ void cugraph_centrality_result_free(cugraph_centrality_result_t* result);
 cugraph_error_code_t cugraph_pagerank(
   const cugraph_resource_handle_t* handle,
   cugraph_graph_t* graph,
+  const cugraph_type_erased_device_array_view_t* precomputed_vertex_out_weight_vertices,
   const cugraph_type_erased_device_array_view_t* precomputed_vertex_out_weight_sums,
+  const cugraph_type_erased_device_array_view_t* initial_guess_vertices,
+  const cugraph_type_erased_device_array_view_t* initial_guess_values,
   double alpha,
   double epsilon,
   size_t max_iterations,
-  bool_t has_initial_guess,
   bool_t do_expensive_check,
   cugraph_centrality_result_t** result,
   cugraph_error_t** error);
@@ -104,14 +118,27 @@ cugraph_error_code_t cugraph_pagerank(
  *
  * @param [in]  handle      Handle for accessing resources
  * @param [in]  graph       Pointer to graph
+ * @param [in]  precomputed_vertex_out_weight_vertices
+ *                          Optionally send in precomputed sum of vertex out weights
+ *                          (a performance optimization).  This defines the vertices.
+ *                          Set to NULL if no value is passed.
  * @param [in]  precomputed_vertex_out_weight_sums
- *                          Optionally send in precomputed sume of vertex out weights
+ *                          Optionally send in precomputed sum of vertex out weights
  *                          (a performance optimization).  Set to NULL if
  *                          no value is passed.
- * FIXME:  Make this just [in], copy it if I need to temporarily modify internally
- * @param [in/out]  personalization_vertices Pointer to an array storing personalization vertex
- * identifiers (compute personalized PageRank).  Array might be modified if renumbering is enabled
- * for the graph
+ * @param [in]  initial_guess_vertices
+ *                          Optionally send in an initial guess of the pagerank values
+ *                          (a performance optimization).  This defines the vertices.
+ *                          Set to NULL if no value is passed. If NULL, initial PageRank
+ *                          values are set to 1.0 divided by the number of vertices in
+ *                          the graph.
+ * @param [in]  initial_guess_values
+ *                          Optionally send in an initial guess of the pagerank values
+ *                          (a performance optimization).  Set to NULL if
+ *                          no value is passed. If NULL, initial PageRank values are set
+ *                          to 1.0 divided by the number of vertices in the graph.
+ * @param [in]  personalization_vertices Pointer to an array storing personalization vertex
+ * identifiers (compute personalized PageRank).
  * @param [in]  personalization_values Pointer to an array storing personalization values for the
  * vertices in the personalization set.
  * @param [in]  alpha       PageRank damping factor.
@@ -120,9 +147,6 @@ cugraph_error_code_t cugraph_pagerank(
  *                          consecutive iterations is less than the number of vertices
  *                          in the graph multiplied by @p epsilon.
  * @param [in]  max_iterations Maximum number of PageRank iterations.
- * @param [in]  has_initial_guess If set to `true`, values in the PageRank output array (pointed by
- * @p pageranks) is used as initial PageRank values. If false, initial PageRank values are set
- * to 1.0 divided by the number of vertices in the 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 pagerank results
@@ -133,14 +157,15 @@ cugraph_error_code_t cugraph_pagerank(
 cugraph_error_code_t cugraph_personalized_pagerank(
   const cugraph_resource_handle_t* handle,
   cugraph_graph_t* graph,
+  const cugraph_type_erased_device_array_view_t* precomputed_vertex_out_weight_vertices,
   const cugraph_type_erased_device_array_view_t* precomputed_vertex_out_weight_sums,
-  // FIXME:  Make this const, copy it if I need to temporarily modify internally
-  cugraph_type_erased_device_array_view_t* personalization_vertices,
+  const cugraph_type_erased_device_array_view_t* initial_guess_vertices,
+  const cugraph_type_erased_device_array_view_t* initial_guess_values,
+  const cugraph_type_erased_device_array_view_t* personalization_vertices,
   const cugraph_type_erased_device_array_view_t* personalization_values,
   double alpha,
   double epsilon,
   size_t max_iterations,
-  bool_t has_initial_guess,
   bool_t do_expensive_check,
   cugraph_centrality_result_t** result,
   cugraph_error_t** error);