c_api and plc binding for lookup src dst using edge ids and type(s)

cpp/CMakeLists.txt

@@ -646,6 +646,7 @@ add_library(cugraph_c
         src/c_api/random.cpp
         src/c_api/similarity.cpp
         src/c_api/leiden.cpp
+        src/c_api/lookup_src_dst.cpp
         src/c_api/louvain.cpp
         src/c_api/triangle_count.cpp
         src/c_api/uniform_neighbor_sampling.cpp

cpp/include/cugraph/src_dst_lookup_container.hpp

@@ -54,8 +54,9 @@ class lookup_container_t {
   lookup_container_t(raft::handle_t const& handle,
                      std::vector<edge_type_t> types,
                      std::vector<edge_id_t> type_counts);
-  lookup_container_t(const lookup_container_t&);
 
+  lookup_container_t(lookup_container_t&& other);
+  lookup_container_t& operator=(lookup_container_t&& other);
   void insert(raft::handle_t const& handle,
               edge_type_t typ,
               raft::device_span<edge_id_t const> edge_ids_to_insert,

cpp/include/cugraph_c/algorithms.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021-2022, NVIDIA CORPORATION.
+ * Copyright (c) 2024, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -28,10 +28,10 @@
 #include <cugraph_c/community_algorithms.h>
 #include <cugraph_c/core_algorithms.h>
 #include <cugraph_c/labeling_algorithms.h>
+#include <cugraph_c/lookup_src_dst.h>
 #include <cugraph_c/sampling_algorithms.h>
 #include <cugraph_c/similarity_algorithms.h>
 #include <cugraph_c/traversal_algorithms.h>
-
 /**
  *  @}
  */

cpp/include/cugraph_c/lookup_src_dst.h

@@ -0,0 +1,141 @@
+/*
+ * Copyright (c) 2024, 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.
+ */
+
+#pragma once
+
+#include <cugraph_c/array.h>
+#include <cugraph_c/graph.h>
+#include <cugraph_c/resource_handle.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Opaque src-dst lookup container type
+ */
+
+typedef struct {
+  int32_t align_;
+} cugraph_lookup_container_t;
+
+/**
+ * @brief Opaque src-dst lookup result type
+ */
+
+typedef struct {
+  int32_t align_;
+} cugraph_lookup_result_t;
+
+/**
+ * @brief Build map to lookup source and destination using edge id and type
+ *
+ * @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 [out]  lookup_container Lookup map
+ * @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_build_edge_id_and_type_to_src_dst_lookup_map(
+  const cugraph_resource_handle_t* handle,
+  cugraph_graph_t* graph,
+  cugraph_lookup_container_t** lookup_container,
+  cugraph_error_t** error);
+
+/**
+ * @brief Lookup edge sources and destinations using edge ids and a single edge type.
+ *
+ * Use this function to lookup endpoints of edges belonging to the same edge type.
+ *
+ * @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]  lookup_container Lookup map
+ * @param[in]  edge_ids_to_lookup Edge ids to lookup
+ * @param[in]  edge_type_to_lookup Edge types corresponding to edge ids in @p edge_ids_to_lookup
+ * @param [out]  result      Output from the lookup call
+ * @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_lookup_endpoints_from_edge_ids_and_single_type(
+  const cugraph_resource_handle_t* handle,
+  cugraph_graph_t* graph,
+  const cugraph_lookup_container_t* lookup_container,
+  const cugraph_type_erased_device_array_view_t* edge_ids_to_lookup,
+  int edge_type_to_lookup,
+  cugraph_lookup_result_t** result,
+  cugraph_error_t** error);
+
+/**
+ * @brief Lookup edge sources and destinations using edge ids and edge types.
+ *
+ * Use this function to lookup endpoints of edges belonging to different edge types.
+ *
+ * @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]  lookup_container Lookup map
+ * @param[in]  edge_ids_to_lookup Edge ids to lookup
+ * @param[in]  edge_types_to_lookup Edge types corresponding to the edge ids in @p
+ * edge_ids_to_lookup
+ * @param [out]  result      Output from the lookup call
+ * @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_lookup_endpoints_from_edge_ids_and_types(
+  const cugraph_resource_handle_t* handle,
+  cugraph_graph_t* graph,
+  const cugraph_lookup_container_t* lookup_container,
+  const cugraph_type_erased_device_array_view_t* edge_ids_to_lookup,
+  const cugraph_type_erased_device_array_view_t* edge_types_to_lookup,
+  cugraph_lookup_result_t** result,
+  cugraph_error_t** error);
+
+/**
+ * @ingroup samplingC
+ * @brief  Get the edge sources from the lookup result
+ *
+ * @param [in]  result  The result from src-dst lookup using edge ids and type(s)
+ * @return type erased array pointing to the edge sources
+ */
+cugraph_type_erased_device_array_view_t* cugraph_lookup_result_get_srcs(
+  const cugraph_lookup_result_t* result);
+
+/**
+ * @ingroup samplingC
+ * @brief  Get the edge destinations from the lookup result
+ *
+ * @param [in]  result  The result from src-dst lookup using edge ids and type(s)
+ * @return type erased array pointing to the edge destinations
+ */
+cugraph_type_erased_device_array_view_t* cugraph_lookup_result_get_dsts(
+  const cugraph_lookup_result_t* result);
+
+/**
+ * @ingroup samplingC
+ * @brief     Free a src-dst lookup result
+ *
+ * @param [in] result     The result from src-dst lookup using edge ids and type(s)
+ */
+void cugraph_lookup_result_free(cugraph_lookup_result_t* result);
+
+#ifdef __cplusplus
+}
+#endif

cpp/include/cugraph_c/sampling_algorithms.h

@@ -43,7 +43,7 @@ typedef struct {
  *                              needs to be transposed
  * @param [in]  start_vertices  Array of source vertices
  * @param [in]  max_length      Maximum length of the generated path
- * @param [in]  result          Output from the node2vec call
+ * @param [out]  result         Output from the node2vec call
  * @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
@@ -64,7 +64,7 @@ cugraph_error_code_t cugraph_uniform_random_walks(
  *                              needs to be transposed
  * @param [in]  start_vertices  Array of source vertices
  * @param [in]  max_length      Maximum length of the generated path
- * @param [in]  result          Output from the node2vec call
+ * @param [out]  result         Output from the node2vec call
  * @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
@@ -89,7 +89,7 @@ cugraph_error_code_t cugraph_biased_random_walks(
  *                              otherwise return as a dense matrix
  * @param [in]  p               The return parameter
  * @param [in]  q               The in/out parameter
- * @param [in]  result          Output from the node2vec call
+ * @param [out]  result         Output from the node2vec call
  * @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
@@ -117,7 +117,7 @@ cugraph_error_code_t cugraph_node2vec_random_walks(
  *                              otherwise return as a dense matrix
  * @param [in]  p            The return parameter
  * @param [in]  q            The in/out parameter
- * @param [in]  result       Output from the node2vec call
+ * @param [out]  result      Output from the node2vec call
  * @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
@@ -353,7 +353,7 @@ void cugraph_sampling_options_free(cugraph_sampling_options_t* options);
  *                           Opaque pointer defining the sampling options.
  * @param [in]  do_expensive_check
  *                           A flag to run expensive checks for input arguments (if set to true)
- * @param [in]  result       Output from the uniform_neighbor_sample call
+ * @param [out]  result      Output from the uniform_neighbor_sample call
  * @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