Propose extract_bfs_paths C API

ci/cpu/build.sh

@@ -66,8 +66,8 @@ conda config --set ssl_verify False
 # BUILD - Conda package builds
 ###############################################################################
 
-gpuci_logger "Build conda package for libcugraph and libcugraph_etl"
 if [ "$BUILD_LIBCUGRAPH" == '1' ]; then
+  gpuci_logger "Building conda package for libcugraph and libcugraph_etl"
   if [[ -z "$PROJECT_FLASH" || "$PROJECT_FLASH" == "0" ]]; then
     gpuci_conda_retry build --no-build-id --croot ${CONDA_BLD_DIR} conda/recipes/libcugraph
     gpuci_conda_retry build --no-build-id --croot ${CONDA_BLD_DIR} conda/recipes/libcugraph_etl
@@ -76,18 +76,26 @@ if [ "$BUILD_LIBCUGRAPH" == '1' ]; then
     gpuci_conda_retry build --no-build-id --croot ${CONDA_BLD_DIR} --dirty --no-remove-work-dir conda/recipes/libcugraph_etl
     mkdir -p ${CONDA_BLD_DIR}/libcugraph/work
     cp -r ${CONDA_BLD_DIR}/work/* ${CONDA_BLD_DIR}/libcugraph/work
+    rm -rf ${CONDA_BLD_DIR}/work
   fi
+else
+  gpuci_logger "SKIPPING build of conda package for libcugraph and libcugraph_etl"
 fi
 
-gpuci_logger "Build conda packages for pylibcugraph and cugraph"
 if [ "$BUILD_CUGRAPH" == "1" ]; then
+  gpuci_logger "Building conda packages for pylibcugraph and cugraph"
   if [[ -z "$PROJECT_FLASH" || "$PROJECT_FLASH" == "0" ]]; then
-    gpuci_conda_retry build --croot ${CONDA_BLD_DIR} conda/recipes/pylibcugraph --python=$PYTHON
-    gpuci_conda_retry build --croot ${CONDA_BLD_DIR} conda/recipes/cugraph --python=$PYTHON
+    gpuci_conda_retry build --no-build-id --croot ${CONDA_BLD_DIR} conda/recipes/pylibcugraph --python=$PYTHON
+    gpuci_conda_retry build --no-build-id --croot ${CONDA_BLD_DIR} conda/recipes/cugraph --python=$PYTHON
   else
-    gpuci_conda_retry build --croot ${CONDA_BLD_DIR} conda/recipes/pylibcugraph -c ci/artifacts/cugraph/cpu/.conda-bld/ --dirty --no-remove-work-dir --python=$PYTHON
-    gpuci_conda_retry build --croot ${CONDA_BLD_DIR} conda/recipes/cugraph -c ci/artifacts/cugraph/cpu/.conda-bld/ --dirty --no-remove-work-dir --python=$PYTHON
+    gpuci_conda_retry build --no-build-id --croot ${CONDA_BLD_DIR} conda/recipes/pylibcugraph -c $CONDA_BLD_DIR --dirty --no-remove-work-dir --python=$PYTHON
+    gpuci_conda_retry build --no-build-id --croot ${CONDA_BLD_DIR} conda/recipes/cugraph -c $CONDA_BLD_DIR --dirty --no-remove-work-dir --python=$PYTHON
+    mkdir -p ${CONDA_BLD_DIR}/cugraph/work
+    cp -r ${CONDA_BLD_DIR}/work/ ${CONDA_BLD_DIR}/cugraph/work
+    rm -rf ${CONDA_BLD_DIR}/work
   fi
+else
+  gpuci_logger "SKIPPING build of conda packages for pylibcugraph and cugraph"
 fi
 
 ################################################################################

conda/environments/cugraph_dev_cuda11.5.yml

@@ -6,14 +6,14 @@ channels:
 - conda-forge
 dependencies:
 - cudatoolkit=11.5
-- cudf=21.12.*
-- libcudf=21.12.*
-- rmm=21.12.*
-- librmm=21.12.*
-- dask>=2021.09.1,<=2021.11.2
-- distributed>=2021.09.1,<=2021.11.2
-- dask-cuda=21.12.*
-- dask-cudf=21.12.*
+- cudf=22.02.*
+- libcudf=22.02.*
+- rmm=22.02.*
+- librmm=22.02.*
+- dask>=2021.09.1
+- distributed>=2021.09.1
+- dask-cuda=22.02.*
+- dask-cudf=22.02.*
 - nccl>=2.9.9
 - ucx-py=0.23.*
 - ucx-proc=*=gpu

cpp/include/cugraph_c/algorithms.h

@@ -101,6 +101,7 @@ cugraph_error_code_t cugraph_pagerank(
  *                          Optionally send in precomputed sume 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
@@ -125,6 +126,7 @@ 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,
+  // 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,
   double alpha,
@@ -136,45 +138,50 @@ cugraph_error_code_t cugraph_personalized_pagerank(
   cugraph_error_t** error);
 
 /**
- * @brief     Opaque bfs result type
+ * @brief     Opaque paths result type
+ *
+ * Store the output of BFS or SSSP, computing predecessors and distances
+ * from a seed.
  */
 typedef struct {
   int align_;
-} cugraph_bfs_result_t;
+} cugraph_paths_result_t;
 
 /**
- * @brief     Get the vertex ids from the bfs result
+ * @brief     Get the vertex ids from the paths result
  *
- * @param [in]   result   The result from bfs
+ * @param [in]   result   The result from bfs or sssp
  * @return type erased array of vertex ids
  */
-cugraph_type_erased_device_array_t* cugraph_bfs_result_get_vertices(cugraph_bfs_result_t* result);
+cugraph_type_erased_device_array_t* cugraph_paths_result_get_vertices(
+  cugraph_paths_result_t* result);
 
 /**
- * @brief     Get the distances from the bfs result
+ * @brief     Get the distances from the paths result
  *
- * @param [in]   result   The result from bfs
+ * @param [in]   result   The result from bfs or sssp
  * @return type erased array of distances
  */
-cugraph_type_erased_device_array_t* cugraph_bfs_result_get_distances(cugraph_bfs_result_t* result);
+cugraph_type_erased_device_array_t* cugraph_paths_result_get_distances(
+  cugraph_paths_result_t* result);
 
 /**
- * @brief     Get the predecessors from the bfs result
+ * @brief     Get the predecessors from the paths result
  *
- * @param [in]   result   The result from bfs
+ * @param [in]   result   The result from bfs or sssp
  * @return type erased array of predecessors.  Value will be NULL if
- *         compute_predecessors was FALSE in the call to bfs that
+ *         compute_predecessors was FALSE in the call to bfs or sssp that
  *         produced this result.
  */
-cugraph_type_erased_device_array_t* cugraph_bfs_result_get_predecessors(
-  cugraph_bfs_result_t* result);
+cugraph_type_erased_device_array_t* cugraph_paths_result_get_predecessors(
+  cugraph_paths_result_t* result);
 
 /**
- * @brief     Free bfs result
+ * @brief     Free paths result
  *
- * @param [in]   result   The result from bfs
+ * @param [in]   result   The result from bfs or sssp
  */
-void cugraph_bfs_result_free(cugraph_bfs_result_t* result);
+void cugraph_paths_result_free(cugraph_paths_result_t* result);
 
 /**
  * @brief     Perform a breadth first search from a set of seed vertices.
@@ -185,6 +192,7 @@ void cugraph_bfs_result_free(cugraph_bfs_result_t* result);
  *
  * @param [in]  handle       Handle for accessing resources
  * @param [in]  graph        Pointer to graph
+ * FIXME:  Make this just [in], copy it if I need to temporarily modify internally
  * @param [in/out]  sources  Array of source vertices.  NOTE: Array might be modified if
  *                           renumbering is enabled for the graph
  * @param [in]  direction_optimizing If set to true, this algorithm switches between the push based
@@ -194,20 +202,80 @@ void cugraph_bfs_result_free(cugraph_bfs_result_t* result);
  * @param depth_limit Sets the maximum number of breadth-first search iterations. Any vertices
  * farther than @p depth_limit hops from @p source_vertex will be marked as unreachable.
  * @param do_expensive_check A flag to run expensive checks for input arguments (if set to `true`).
- * @param [out] result       Opaque pointer to pagerank results
+ * @param [out] result       Opaque pointer to paths results
  * @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_bfs(const cugraph_resource_handle_t* handle,
-                                 cugraph_graph_t* graph,
-                                 cugraph_type_erased_device_array_t* sources,
-                                 bool_t direction_optimizing,
-                                 size_t depth_limit,
-                                 bool_t do_expensive_check,
-                                 bool_t compute_predecessors,
-                                 cugraph_bfs_result_t** result,
-                                 cugraph_error_t** error);
+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,
+  bool_t direction_optimizing,
+  size_t depth_limit,
+  bool_t do_expensive_check,
+  bool_t compute_predecessors,
+  cugraph_paths_result_t** result,
+  cugraph_error_t** error);
+
+/**
+ * @brief     Opaque extract_paths result type
+ */
+typedef struct {
+  int align_;
+} cugraph_extract_paths_result_t;
+
+/**
+ * @brief     Extract BFS paths from a BFS result
+ *
+ * This function extracts paths from the BFS output.  BFS outputs distances
+ * and predecessors.  The path from a vertex v back to the original source vertex
+ * can be extracted by recursively looking up the predecessor vertex until you arrive
+ * back at the original source vertex.
+ *
+ * @param [in]  handle       Handle for accessing resources
+ * @param [in]  graph        Pointer to graph.  NOTE: Graph might be modified if the storage
+ *                           needs to be transposed
+ * @param [in]  sources      Array of source vertices
+ * @param [in]  result       Output from the BFS call
+ * @param [in]  destinations Array of destination vertices.
+ * @param [out] result       Opaque pointer to extract_paths results
+ * @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_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);
+
+/**
+ * @brief     Get the max path length from extract_paths result
+ *
+ * @param [in]   result   The result from extract_paths
+ * @return maximum path length
+ */
+size_t cugraph_extract_paths_result_get_max_path_length(cugraph_extract_paths_result_t* result);
+
+/**
+ * @brief     Get the matrix (row major order) of paths
+ *
+ * @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_extract_paths_result_t* result);
+
+/**
+ * @brief     Free extract_paths result
+ *
+ * @param [in]   result   The result from extract_paths
+ */
+void cugraph_extract_paths_result_free(cugraph_extract_paths_result_t* result);
 
 #ifdef __cplusplus
 }

cpp/include/cugraph_c/cugraph_api.h

@@ -161,10 +161,10 @@ cugraph_error_code_t cugraph_update_host_buffer(const cugraph_resource_handle_t*
                                                 const cugraph_device_buffer_t* ptr_src);
 
 /* raft::handle_t allocator (for now; possibly a more encompassing handle in the future)*/
-cugraph_resource_handle_t* cugraph_create_handle(void);
+cugraph_resource_handle_t* cugraph_create_resource_handle(void);
 
 /* raft::handle_t deallocator*/
-void cugraph_free_handle(cugraph_resource_handle_t* p_handle);
+void cugraph_free_resource_handle(cugraph_resource_handle_t* p_handle);
 
 #ifdef __cplusplus
 }

cpp/src/c_api/bfs.cpp

@@ -29,7 +29,7 @@
 namespace cugraph {
 namespace c_api {
 
-struct cugraph_bfs_result_t {
+struct cugraph_paths_result_t {
   cugraph_type_erased_device_array_t* vertex_ids_;
   cugraph_type_erased_device_array_t* distances_;
   cugraph_type_erased_device_array_t* predecessors_;
@@ -43,7 +43,7 @@ struct bfs_functor : public abstract_functor {
   size_t depth_limit_;
   bool do_expensive_check_;
   bool compute_predecessors_;
-  cugraph_bfs_result_t* result_{};
+  cugraph_paths_result_t* result_{};
 
   bfs_functor(raft::handle_t const& handle,
               cugraph_graph_t* graph,
@@ -135,7 +135,7 @@ struct bfs_functor : public abstract_functor {
                                                      do_expensive_check_);
       }
 
-      result_ = new cugraph_bfs_result_t{
+      result_ = new cugraph_paths_result_t{
         new cugraph_type_erased_device_array_t(std::move(vertex_ids), graph_->vertex_type_),
         new cugraph_type_erased_device_array_t(std::move(distances), graph_->weight_type_),
         new cugraph_type_erased_device_array_t(std::move(predecessors), graph_->weight_type_)};
@@ -146,30 +146,30 @@ struct bfs_functor : public abstract_functor {
 }  // namespace c_api
 }  // namespace cugraph
 
-extern "C" cugraph_type_erased_device_array_t* cugraph_bfs_result_get_vertices(
-  cugraph_bfs_result_t* result)
+extern "C" cugraph_type_erased_device_array_t* cugraph_paths_result_get_vertices(
+  cugraph_paths_result_t* result)
 {
-  auto internal_pointer = reinterpret_cast<cugraph::c_api::cugraph_bfs_result_t*>(result);
+  auto internal_pointer = reinterpret_cast<cugraph::c_api::cugraph_paths_result_t*>(result);
   return reinterpret_cast<cugraph_type_erased_device_array_t*>(internal_pointer->vertex_ids_);
 }
 
-extern "C" cugraph_type_erased_device_array_t* cugraph_bfs_result_get_distances(
-  cugraph_bfs_result_t* result)
+extern "C" cugraph_type_erased_device_array_t* cugraph_paths_result_get_distances(
+  cugraph_paths_result_t* result)
 {
-  auto internal_pointer = reinterpret_cast<cugraph::c_api::cugraph_bfs_result_t*>(result);
+  auto internal_pointer = reinterpret_cast<cugraph::c_api::cugraph_paths_result_t*>(result);
   return reinterpret_cast<cugraph_type_erased_device_array_t*>(internal_pointer->distances_);
 }
 
-extern "C" cugraph_type_erased_device_array_t* cugraph_bfs_result_get_predecessors(
-  cugraph_bfs_result_t* result)
+extern "C" cugraph_type_erased_device_array_t* cugraph_paths_result_get_predecessors(
+  cugraph_paths_result_t* result)
 {
-  auto internal_pointer = reinterpret_cast<cugraph::c_api::cugraph_bfs_result_t*>(result);
+  auto internal_pointer = reinterpret_cast<cugraph::c_api::cugraph_paths_result_t*>(result);
   return reinterpret_cast<cugraph_type_erased_device_array_t*>(internal_pointer->predecessors_);
 }
 
-extern "C" void cugraph_bfs_result_free(cugraph_bfs_result_t* result)
+extern "C" void cugraph_paths_result_free(cugraph_paths_result_t* result)
 {
-  auto internal_pointer = reinterpret_cast<cugraph::c_api::cugraph_bfs_result_t*>(result);
+  auto internal_pointer = reinterpret_cast<cugraph::c_api::cugraph_paths_result_t*>(result);
   delete internal_pointer->vertex_ids_;
   delete internal_pointer->distances_;
   delete internal_pointer->predecessors_;
@@ -183,7 +183,7 @@ extern "C" cugraph_error_code_t cugraph_bfs(const cugraph_resource_handle_t* han
                                             size_t depth_limit,
                                             bool_t do_expensive_check,
                                             bool_t compute_predecessors,
-                                            cugraph_bfs_result_t** result,
+                                            cugraph_paths_result_t** result,
                                             cugraph_error_t** error)
 {
   *result = nullptr;
@@ -217,7 +217,7 @@ extern "C" cugraph_error_code_t cugraph_bfs(const cugraph_resource_handle_t* han
       return functor.error_code_;
     }
 
-    *result = reinterpret_cast<cugraph_bfs_result_t*>(functor.result_);
+    *result = reinterpret_cast<cugraph_paths_result_t*>(functor.result_);
   } catch (std::exception const& ex) {
     *error = reinterpret_cast<cugraph_error_t*>(new cugraph::c_api::cugraph_error_t{ex.what()});
     return CUGRAPH_UNKNOWN_ERROR;

cpp/src/c_api/cugraph_api.cpp

@@ -350,7 +350,7 @@ extern "C" cugraph_error_code_t cugraph_update_host_buffer(const cugraph_resourc
   return status;
 }
 
-extern "C" cugraph_resource_handle_t* cugraph_create_handle(void)
+extern "C" cugraph_resource_handle_t* cugraph_create_resource_handle(void)
 {
   try {
     return reinterpret_cast<cugraph_resource_handle_t*>(new raft::handle_t{});
@@ -359,7 +359,7 @@ extern "C" cugraph_resource_handle_t* cugraph_create_handle(void)
   }
 }
 
-extern "C" void cugraph_free_handle(cugraph_resource_handle_t* p_handle)
+extern "C" void cugraph_free_resource_handle(cugraph_resource_handle_t* p_handle)
 {
   raft::handle_t* p_raft_handle = reinterpret_cast<raft::handle_t*>(p_handle);
   delete p_raft_handle;

cpp/tests/CMakeLists.txt

@@ -588,6 +588,7 @@ ConfigureCTest(CAPI_CREATE_GRAPH_TEST c_api/create_graph_test.c)
 ConfigureCTest(CAPI_RANDOM_WALKS_TEST c_api/random_walks_test.c)
 ConfigureCTest(CAPI_PAGERANK_TEST c_api/pagerank_test.c)
 ConfigureCTest(CAPI_BFS_TEST c_api/bfs_test.c)
+#ConfigureCTest(CAPI_EXTRACT_PATHS_TEST c_api/extract_paths_test.c)
 
 ###################################################################################################
 ### enable testing ################################################################################