Python API updates to enable explicit control of internal graph_t c…

…reation and deletion (rapidsai#2023)

Python API updates to enable explicit control of internal `graph_t` creation and deletion. These changes will allow users who need more control over how the internal `graph_t` object is managed to have additional APIs to do so.  Current cugraph algos construct the appropriate `graph_t` at the C++ boundary, run the algo, and destroy the object each time.  This is more convenient and safer in some cases since it does not require the user to understand the necessary data format requirements for each algo (CSC, CSR, etc.), but it adds overhead to each algo call. If a user knows which algos will be called ahead of time and the relevant graph creation options to use, they can reuse the underlying `graph_t` object and eliminate the redundant creation/deletion expense.  These APIs also allow for benchmarks to measure only the algo run time without the initial graph creation time.

These changes are grouped into a category of enhancements sometimes referred to as "expert mode"

Changes here include:
* Updates to `pylibcugraph` to add the APIs from the `libcugraph_c` library for `graph_t` management and calling Pagerank and SSSP
* Addition of the `experimental` namespace to `pylibcugraph`, which is where some of the new APIs will be until we finalize decisions on names, signatures, etc.
* <s>Updates to cugraph Graph classes, Pagerank, and SSSP algos to call in to `pylibcugraph`</s>

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

Approvers:
  - Chuck Hastings (https://github.com/ChuckHastings)
  - Seunghwa Kang (https://github.com/seunghwak)
  - Brad Rees (https://github.com/BradReesWork)

URL: rapidsai#2023

cpp/include/cugraph_c/algorithms.h

@@ -37,7 +37,7 @@ typedef struct {
  * @param [in] result The result from pagerank
  * @return type erased array of vertex ids
  */
-cugraph_type_erased_device_array_t* cugraph_pagerank_result_get_vertices(
+cugraph_type_erased_device_array_view_t* cugraph_pagerank_result_get_vertices(
  cugraph_pagerank_result_t* result);
 
 /**
@@ -46,7 +46,7 @@ cugraph_type_erased_device_array_t* cugraph_pagerank_result_get_vertices(
  * @param [in] result The result from pagerank
  * @return type erased array of pagerank values
  */
-cugraph_type_erased_device_array_t* cugraph_pagerank_result_get_pageranks(
+cugraph_type_erased_device_array_view_t* cugraph_pagerank_result_get_pageranks(
  cugraph_pagerank_result_t* result);
 
 /**
@@ -84,7 +84,7 @@ void cugraph_pagerank_result_free(cugraph_pagerank_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_t* precomputed_vertex_out_weight_sums,
+ const cugraph_type_erased_device_array_view_t* precomputed_vertex_out_weight_sums,
  double alpha,
  double epsilon,
  size_t max_iterations,
@@ -127,10 +127,10 @@ 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_t* precomputed_vertex_out_weight_sums,
+ 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_t* personalization_vertices,
- const cugraph_type_erased_device_array_t* personalization_values,
+ 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,
@@ -155,7 +155,7 @@ typedef struct {
  * @param [in] result The result from bfs or sssp
  * @return type erased array of vertex ids
  */
-cugraph_type_erased_device_array_t* cugraph_paths_result_get_vertices(
+cugraph_type_erased_device_array_view_t* cugraph_paths_result_get_vertices(
  cugraph_paths_result_t* result);
 
 /**
@@ -164,7 +164,7 @@ cugraph_type_erased_device_array_t* cugraph_paths_result_get_vertices(
  * @param [in] result The result from bfs or sssp
  * @return type erased array of distances
  */
-cugraph_type_erased_device_array_t* cugraph_paths_result_get_distances(
+cugraph_type_erased_device_array_view_t* cugraph_paths_result_get_distances(
  cugraph_paths_result_t* result);
 
 /**
@@ -175,7 +175,7 @@ cugraph_type_erased_device_array_t* cugraph_paths_result_get_distances(
  * compute_predecessors was FALSE in the call to bfs or sssp that
  * produced this result.
  */
-cugraph_type_erased_device_array_t* cugraph_paths_result_get_predecessors(
+cugraph_type_erased_device_array_view_t* cugraph_paths_result_get_predecessors(
  cugraph_paths_result_t* result);
 
 /**
@@ -216,7 +216,7 @@ cugraph_error_code_t cugraph_bfs(
  const cugraph_resource_handle_t* handle,
  cugraph_graph_t* graph,
  // FIXME: Make this const, copy it if I need to temporarily modify internally
- cugraph_type_erased_device_array_t* sources,
+ cugraph_type_erased_device_array_view_t* sources,
  bool_t direction_optimizing,
  size_t depth_limit,
  bool_t compute_predecessors,
@@ -280,13 +280,14 @@ typedef struct {
  * be populated if error code is not CUGRAPH_SUCCESS
  * @return error code
  */
-cugraph_error_code_t cugraph_extract_paths(const cugraph_resource_handle_t* handle,
- cugraph_graph_t* graph,
- const cugraph_type_erased_device_array_t* sources,
- const cugraph_paths_result_t* paths_result,
- const cugraph_type_erased_device_array_t* destinations,
- cugraph_extract_paths_result_t** result,
- cugraph_error_t** error);
+cugraph_error_code_t cugraph_extract_paths(
+ const cugraph_resource_handle_t* handle,
+ cugraph_graph_t* graph,
+ const cugraph_type_erased_device_array_view_t* sources,
+ const cugraph_paths_result_t* paths_result,
+ const cugraph_type_erased_device_array_view_t* destinations,
+ cugraph_extract_paths_result_t** result,
+ cugraph_error_t** error);
 
 /**
  * @brief Get the max path length from extract_paths result
@@ -302,7 +303,7 @@ size_t cugraph_extract_paths_result_get_max_path_length(cugraph_extract_paths_re
  * @param [in] result The result from extract_paths
  * @return type erased array pointing to the matrix in device memory
  */
-cugraph_type_erased_device_array_t* cugraph_extract_paths_result_get_paths(
+cugraph_type_erased_device_array_view_t* cugraph_extract_paths_result_get_paths(
  cugraph_extract_paths_result_t* result);
 
 /**

cpp/include/cugraph_c/array.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021, NVIDIA CORPORATION.
+ * Copyright (c) 2021-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.
@@ -26,25 +26,33 @@ typedef struct {
  int align_;
 } cugraph_type_erased_device_array_t;
 
+typedef struct {
+ int align_;
+} cugraph_type_erased_device_array_view_t;
+
 typedef struct {
  int align_;
 } cugraph_type_erased_host_array_t;
 
+typedef struct {
+ int align_;
+} cugraph_type_erased_host_array_view_t;
+
 /**
  * @brief Create a type erased device array
  *
  * @param [in] handle Handle for accessing resources
- * @param [in] dtype The type of array to create
  * @param [in] n_elems The number of elements in the array
+ * @param [in] dtype The type of array to create
  * @param [out] array Pointer to the location to store the pointer to the device array
  * @param [out] error Pointer to an error object storing details of any error. Will
  * be populated if error code is not CUGRAPH_SUCCESS
  * @return error code
  */
 cugraph_error_code_t cugraph_type_erased_device_array_create(
  const cugraph_resource_handle_t* handle,
- data_type_id_t dtype,
  size_t n_elems,
+ data_type_id_t dtype,
  cugraph_type_erased_device_array_t** array,
  cugraph_error_t** error);
 
@@ -55,44 +63,89 @@ cugraph_error_code_t cugraph_type_erased_device_array_create(
  */
 void cugraph_type_erased_device_array_free(cugraph_type_erased_device_array_t* p);
 
+#if 0
+// FIXME: Not implemented, need to discuss if this can work. We will either implement
+// this later or delete it from the interface once we resolve how to handle this
 /**
- * @brief Get the size of a type erased device array
+ * @brief Release the raw pointer of the type erased device array
+ *
+ * The caller is now responsible for freeing the device pointer
  *
  * @param [in] p Pointer to the type erased device array
+ * @return Pointer (device memory) for the data in the array
+ */
+void* cugraph_type_erased_device_array_release(cugraph_type_erased_device_array_t* p);
+#endif
+
+/**
+ * @brief Create a type erased device array view from
+ * a type erased device array
+ *
+ * @param [in] array Pointer to the type erased device array
+ * @return Pointer to the view of the host array
+ */
+cugraph_type_erased_device_array_view_t* cugraph_type_erased_device_array_view(
+ cugraph_type_erased_device_array_t* array);
+
+/**
+ * @brief Create a type erased device array view from
+ * a raw device pointer.
+ *
+ * @param [in] pointer Raw device pointer
+ * @param [in] n_elems The number of elements in the array
+ * @param [in] dtype The type of array to create
+ * @return Pointer to the view of the host array
+ */
+cugraph_type_erased_device_array_view_t* cugraph_type_erased_device_array_view_create(
+ void* pointer, size_t n_elems, data_type_id_t dtype);
+
+/**
+ * @brief Destroy a type erased device array view
+ *
+ * @param [in] p Pointer to the type erased device array view
+ */
+void cugraph_type_erased_device_array_view_free(cugraph_type_erased_device_array_view_t* p);
+
+/**
+ * @brief Get the size of a type erased device array view
+ *
+ * @param [in] p Pointer to the type erased device array view
  * @return The number of elements in the array
  */
-size_t cugraph_type_erased_device_array_size(const cugraph_type_erased_device_array_t* p);
+size_t cugraph_type_erased_device_array_view_size(const cugraph_type_erased_device_array_view_t* p);
 
 /**
- * @brief Get the type of a type erased device array
+ * @brief Get the type of a type erased device array view
  *
- * @param [in] p Pointer to the type erased device array
+ * @param [in] p Pointer to the type erased device array view
  * @return The type of the elements in the array
  */
-data_type_id_t cugraph_type_erased_device_array_type(const cugraph_type_erased_device_array_t* p);
+data_type_id_t cugraph_type_erased_device_array_view_type(
+ const cugraph_type_erased_device_array_view_t* p);
 
 /**
- * @brief Get the raw pointer of the type erased device array
+ * @brief Get the raw pointer of the type erased device array view
  *
- * @param [in] p Pointer to the type erased device array
+ * @param [in] p Pointer to the type erased device array view
  * @return Pointer (device memory) for the data in the array
  */
-const void* cugraph_type_erased_device_array_pointer(const cugraph_type_erased_device_array_t* p);
+const void* cugraph_type_erased_device_array_view_pointer(
+ const cugraph_type_erased_device_array_view_t* p);
 
 /**
  * @brief Create a type erased host array
  *
  * @param [in] handle Handle for accessing resources
- * @param [in] dtype The type of array to create
  * @param [in] n_elems The number of elements in the array
+ * @param [in] dtype The type of array to create
  * @param [out] array Pointer to the location to store the pointer to the host array
  * @param [out] error Pointer to an error object storing details of any error. Will
  * be populated if error code is not CUGRAPH_SUCCESS
  * @return error code
  */
 cugraph_error_code_t cugraph_type_erased_host_array_create(const cugraph_resource_handle_t* handle,
- data_type_id_t dtype,
  size_t n_elems,
+ data_type_id_t dtype,
  cugraph_type_erased_host_array_t** array,
  cugraph_error_t** error);
 
@@ -103,43 +156,86 @@ cugraph_error_code_t cugraph_type_erased_host_array_create(const cugraph_resourc
  */
 void cugraph_type_erased_host_array_free(cugraph_type_erased_host_array_t* p);
 
+#if 0
+// FIXME: Not implemented, need to discuss if this can work. We will either implement
+// this later or delete it from the interface once we resolve how to handle this
 /**
- * @brief Get the size of a type erased host array
+ * @brief Release the raw pointer of the type erased host array
+ *
+ * The caller is now responsible for freeing the host pointer
  *
  * @param [in] p Pointer to the type erased host array
+ * @return Pointer (host memory) for the data in the array
+ */
+void* cugraph_type_erased_host_array_release(cugraph_type_erased_host_array_t* p);
+#endif
+
+/**
+ * @brief Create a type erased host array view from
+ * a type erased host array
+ *
+ * @param [in] array Pointer to the type erased host array
+ * @return Pointer to the view of the host array
+ */
+cugraph_type_erased_host_array_view_t* cugraph_type_erased_host_array_view(
+ cugraph_type_erased_host_array_t* array);
+
+/**
+ * @brief Create a type erased host array view from
+ * a raw host pointer.
+ *
+ * @param [in] pointer Raw host pointer
+ * @param [in] n_elems The number of elements in the array
+ * @param [in] dtype The type of array to create
+ * @return pointer to the view of the host array
+ */
+cugraph_type_erased_host_array_view_t* cugraph_type_erased_host_array_view_create(
+ void* pointer, size_t n_elems, data_type_id_t dtype);
+
+/**
+ * @brief Destroy a type erased host array view
+ *
+ * @param [in] p Pointer to the type erased host array view
+ */
+void cugraph_type_erased_host_array_view_free(cugraph_type_erased_host_array_view_t* p);
+
+/**
+ * @brief Get the size of a type erased host array view
+ *
+ * @param [in] p Pointer to the type erased host array view
  * @return The number of elements in the array
  */
-size_t cugraph_type_erased_host_array_size(const cugraph_type_erased_host_array_t* p);
+size_t cugraph_type_erased_host_array_size(const cugraph_type_erased_host_array_view_t* p);
 
 /**
- * @brief Get the type of a type erased host array
+ * @brief Get the type of a type erased host array view
  *
- * @param [in] p Pointer to the type erased host array
+ * @param [in] p Pointer to the type erased host array view
  * @return The type of the elements in the array
  */
-data_type_id_t cugraph_type_erased_host_array_type(const cugraph_type_erased_host_array_t* p);
+data_type_id_t cugraph_type_erased_host_array_type(const cugraph_type_erased_host_array_view_t* p);
 
 /**
- * @brief Get the raw pointer of the type erased host array
+ * @brief Get the raw pointer of the type erased host array view
  *
- * @param [in] p Pointer to the type erased host array
+ * @param [in] p Pointer to the type erased host array view
  * @return Pointer (host memory) for the data in the array
  */
-void* cugraph_type_erased_host_array_pointer(const cugraph_type_erased_host_array_t* p);
+void* cugraph_type_erased_host_array_pointer(const cugraph_type_erased_host_array_view_t* p);
 
 /**
- * @brief Copy data from host to a type erased device array
+ * @brief Copy data from host to a type erased device array view
  *
  * @param [in] handle Handle for accessing resources
- * @param [out] dst Pointer to the type erased device array
+ * @param [out] dst Pointer to the type erased device array view
  * @param [in] h_src Pointer to host array to copy into device memory
  * @param [out] error Pointer to an error object storing details of any error. Will
  * be populated if error code is not CUGRAPH_SUCCESS
  * @return error code
  */
-cugraph_error_code_t cugraph_type_erased_device_array_copy_from_host(
+cugraph_error_code_t cugraph_type_erased_device_array_view_copy_from_host(
  const cugraph_resource_handle_t* handle,
- cugraph_type_erased_device_array_t* dst,
+ cugraph_type_erased_device_array_view_t* dst,
  const byte_t* h_src,
  cugraph_error_t** error);
 
@@ -148,15 +244,31 @@ cugraph_error_code_t cugraph_type_erased_device_array_copy_from_host(
  *
  * @param [in] handle Handle for accessing resources
  * @param [out] h_dst Pointer to host array
- * @param [in] src Pointer to the type erased device array to copy from
+ * @param [in] src Pointer to the type erased device array view source
  * @param [out] error Pointer to an error object storing details of any error. Will
  * be populated if error code is not CUGRAPH_SUCCESS
  * @return error code
  */
-cugraph_error_code_t cugraph_type_erased_device_array_copy_to_host(
+cugraph_error_code_t cugraph_type_erased_device_array_view_copy_to_host(
  const cugraph_resource_handle_t* handle,
  byte_t* h_dst,
- const cugraph_type_erased_device_array_t* src,
+ const cugraph_type_erased_device_array_view_t* src,
+ cugraph_error_t** error);
+
+/**
+ * @brief Copy data between two type erased device array views
+ *
+ * @param [in] handle Handle for accessing resources
+ * @param [out] dst Pointer to type erased device array view destination
+ * @param [in] src Pointer to type erased device array view source
+ * @param [out] error Pointer to an error object storing details of any error. Will
+ * be populated if error code is not CUGRAPH_SUCCESS
+ * @return error code
+ */
+cugraph_error_code_t cugraph_type_erased_device_array_view_copy(
+ const cugraph_resource_handle_t* handle,
+ cugraph_type_erased_device_array_view_t* dst,
+ const cugraph_type_erased_device_array_view_t* src,
  cugraph_error_t** error);
 
 #ifdef __cplusplus