Define and Implement C++ API for negative sampling

cpp/CMakeLists.txt

@@ -329,6 +329,12 @@ set(CUGRAPH_SOURCES
     src/sampling/neighbor_sampling_sg_v32_e64.cpp
     src/sampling/neighbor_sampling_sg_v32_e32.cpp
     src/sampling/neighbor_sampling_sg_v64_e64.cpp
+    src/sampling/negative_sampling_sg_v32_e64.cu
+    src/sampling/negative_sampling_sg_v32_e32.cu
+    src/sampling/negative_sampling_sg_v64_e64.cu
+    src/sampling/negative_sampling_mg_v32_e64.cu
+    src/sampling/negative_sampling_mg_v32_e32.cu
+    src/sampling/negative_sampling_mg_v64_e64.cu
     src/sampling/renumber_sampled_edgelist_sg_v64_e64.cu
     src/sampling/renumber_sampled_edgelist_sg_v32_e32.cu
     src/sampling/sampling_post_processing_sg_v64_e64.cu
@@ -653,6 +659,7 @@ add_library(cugraph_c
         src/c_api/louvain.cpp
         src/c_api/triangle_count.cpp
         src/c_api/neighbor_sampling.cpp
+        src/c_api/negative_sampling.cpp
         src/c_api/labeling_result.cpp
         src/c_api/weakly_connected_components.cpp
         src/c_api/strongly_connected_components.cpp

cpp/include/cugraph/detail/utility_wrappers.hpp

@@ -50,6 +50,29 @@ void uniform_random_fill(rmm::cuda_stream_view const& stream_view,
                          value_t max_value,
                          raft::random::RngState& rng_state);
 
+/**
+ * @brief    Fill a buffer with biased random values
+ *
+ * Fills a buffer with values based on the specified biases.
+ * The probability of selecting the value `i` is determined by
+ * `biases[i] / sum(biases)`.
+ *
+ * @tparam      value_t      type of the value to operate on
+ * @tparam      bias_t       type of the bias
+ *
+ * @param[in]   handle       RAFT handle object to encapsulate resources (e.g. CUDA stream,
+ * communicator, and handles to various CUDA libraries) to run graph algorithms.
+ * @param[in]   rng_state    The RngState instance holding pseudo-random number generator state.
+ * @param[out]  output       The random values
+ * @param[in]   biases       The biased values
+ *
+ */
+template <typename value_t, typename bias_t>
+void biased_random_fill(raft::handle_t const& handle,
+                        raft::random::RngState& rng_state,
+                        raft::device_span<value_t> output,
+                        raft::device_span<bias_t const> biases);
+
 /**
  * @brief    Fill a buffer with a constant value
  *

cpp/include/cugraph/graph_view.hpp

@@ -636,7 +636,7 @@ class graph_view_t<vertex_t, edge_t, store_transposed, multi_gpu, std::enable_if
                                      /* (edge_srcs, edge_dsts) should be pre-shuffled */
                                      raft::device_span<vertex_t const> edge_srcs,
                                      raft::device_span<vertex_t const> edge_dsts,
-                                     bool do_expensive_check = false);
+                                     bool do_expensive_check = false) const;
 
   rmm::device_uvector<edge_t> compute_multiplicity(
     raft::handle_t const& handle,
@@ -945,7 +945,7 @@ class graph_view_t<vertex_t, edge_t, store_transposed, multi_gpu, std::enable_if
   rmm::device_uvector<bool> has_edge(raft::handle_t const& handle,
                                      raft::device_span<vertex_t const> edge_srcs,
                                      raft::device_span<vertex_t const> edge_dsts,
-                                     bool do_expensive_check = false);
+                                     bool do_expensive_check = false) const;
 
   rmm::device_uvector<edge_t> compute_multiplicity(raft::handle_t const& handle,
                                                    raft::device_span<vertex_t const> edge_srcs,

cpp/include/cugraph/sampling_functions.hpp

@@ -743,4 +743,60 @@ lookup_endpoints_from_edge_ids_and_types(
   raft::device_span<edge_t const> edge_ids_to_lookup,
   raft::device_span<edge_type_t const> edge_types_to_lookup);
 
+/**
+ * @brief Negative Sampling
+ *
+ * This function generates negative samples for graph.
+ *
+ * Negative sampling is done by generating a random graph according to the specified
+ * parameters and optionally removing the false negatives.
+ *
+ * Sampling occurs by creating a list of source vertex ids from biased samping
+ * of the source vertex space, and destination vertex ids from biased sampling of the
+ * destination vertex space, and using this as the putative list of edges.  We
+ * then can optionally remove duplicates and remove false negatives to generate
+ * the final list.  If necessary we will repeat the process to end with a resulting
+ * edge list of the appropriate size.
+ *
+ * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type.
+ * @tparam edge_t Type of edge identifiers. Needs to be an integral type.
+ * @tparam store_transposed Flag indicating whether sources (if false) or destinations (if
+ * true) are major indices
+ * @tparam multi_gpu Flag indicating whether template instantiation should target single-GPU (false)
+ *
+ * @param handle RAFT handle object to encapsulate resources (e.g. CUDA stream, communicator, and
+ * handles to various CUDA libraries) to run graph algorithms.
+ * @param graph_view Graph View object to generate NBR Sampling for
+ * @param rng_state RNG state
+ * @param num_samples Number of negative samples to generate
+ * @param src_bias Optional bias for randomly selecting source vertices.  If std::nullopt vertices
+ * will be selected uniformly
+ * @param dst_bias Optional bias for randomly selecting destination vertices.  If std::nullopt
+ * vertices will be selected uniformly
+ * @param remove_duplicates If true, remove duplicate samples
+ * @param remove_false_negatives If true, remove false negatives (samples that are actually edges in
+ * the graph
+ * @param exact_number_of_samples If true, repeat generation until we get the exact number of
+ * negative samples
+ * @param do_expensive_check A flag to run expensive checks for input arguments (if set to `true`).
+ *
+ * @return tuple containing source vertex ids and destination vertex ids for the negative samples
+ */
+template <typename vertex_t,
+          typename edge_t,
+          typename weight_t,
+          bool store_transposed,
+          bool multi_gpu>
+std::tuple<rmm::device_uvector<vertex_t>, rmm::device_uvector<vertex_t>> negative_sampling(
+  raft::handle_t const& handle,
+  raft::random::RngState& rng_state,
+  graph_view_t<vertex_t, edge_t, store_transposed, multi_gpu> const& graph_view,
+  size_t num_samples,
+  std::optional<raft::device_span<weight_t const>> src_bias,
+  std::optional<raft::device_span<weight_t const>> dst_bias,
+  bool remove_duplicates,
+  bool remove_false_negatives,
+  bool exact_number_of_samples,
+  bool do_expensive_check);
+
 }  // namespace cugraph

cpp/include/cugraph_c/coo.h

@@ -0,0 +1,115 @@
+/*
+ * 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/random.h>
+#include <cugraph_c/resource_handle.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief       Opaque COO definition
+ */
+typedef struct {
+  int32_t align_;
+} cugraph_coo_t;
+
+/**
+ * @brief       Opaque COO list definition
+ */
+typedef struct {
+  int32_t align_;
+} cugraph_coo_list_t;
+
+/**
+ * @brief       Get the source vertex ids
+ *
+ * @param [in]     coo   Opaque pointer to COO
+ * @return type erased array view of source vertex ids
+ */
+cugraph_type_erased_device_array_view_t* cugraph_coo_get_sources(cugraph_coo_t* coo);
+
+/**
+ * @brief       Get the destination vertex ids
+ *
+ * @param [in]     coo   Opaque pointer to COO
+ * @return type erased array view of destination vertex ids
+ */
+cugraph_type_erased_device_array_view_t* cugraph_coo_get_destinations(cugraph_coo_t* coo);
+
+/**
+ * @brief       Get the edge weights
+ *
+ * @param [in]     coo   Opaque pointer to COO
+ * @return type erased array view of edge weights, NULL if no edge weights in COO
+ */
+cugraph_type_erased_device_array_view_t* cugraph_coo_get_edge_weights(cugraph_coo_t* coo);
+
+/**
+ * @brief       Get the edge id
+ *
+ * @param [in]     coo   Opaque pointer to COO
+ * @return type erased array view of edge id, NULL if no edge ids in COO
+ */
+cugraph_type_erased_device_array_view_t* cugraph_coo_get_edge_id(cugraph_coo_t* coo);
+
+/**
+ * @brief       Get the edge type
+ *
+ * @param [in]     coo   Opaque pointer to COO
+ * @return type erased array view of edge type, NULL if no edge types in COO
+ */
+cugraph_type_erased_device_array_view_t* cugraph_coo_get_edge_type(cugraph_coo_t* coo);
+
+/**
+ * @brief       Get the number of coo object in the list
+ *
+ * @param [in]     coo_list   Opaque pointer to COO list
+ * @return number of elements
+ */
+size_t cugraph_coo_list_size(const cugraph_coo_list_t* coo_list);
+
+/**
+ * @brief       Get a COO from the list
+ *
+ * @param [in]     coo_list   Opaque pointer to COO list
+ * @param [in]     index      Index of desired COO from list
+ * @return a cugraph_coo_t* object from the list
+ */
+cugraph_coo_t* cugraph_coo_list_element(cugraph_coo_list_t* coo_list, size_t index);
+
+/**
+ * @brief     Free coo object
+ *
+ * @param [in]    coo Opaque pointer to COO
+ */
+void cugraph_coo_free(cugraph_coo_t* coo);
+
+/**
+ * @brief     Free coo list
+ *
+ * @param [in]    coo_list Opaque pointer to list of COO objects
+ */
+void cugraph_coo_list_free(cugraph_coo_list_t* coo_list);
+
+#ifdef __cplusplus
+}
+#endif

cpp/include/cugraph_c/graph_generators.h

@@ -17,6 +17,7 @@
 #pragma once
 
 #include <cugraph_c/array.h>
+#include <cugraph_c/coo.h>
 #include <cugraph_c/graph.h>
 #include <cugraph_c/random.h>
 #include <cugraph_c/resource_handle.h>
@@ -27,91 +28,6 @@ extern "C" {
 
 typedef enum { POWER_LAW = 0, UNIFORM } cugraph_generator_distribution_t;
 
-/**
- * @brief       Opaque COO definition
- */
-typedef struct {
-  int32_t align_;
-} cugraph_coo_t;
-
-/**
- * @brief       Opaque COO list definition
- */
-typedef struct {
-  int32_t align_;
-} cugraph_coo_list_t;
-
-/**
- * @brief       Get the source vertex ids
- *
- * @param [in]     coo   Opaque pointer to COO
- * @return type erased array view of source vertex ids
- */
-cugraph_type_erased_device_array_view_t* cugraph_coo_get_sources(cugraph_coo_t* coo);
-
-/**
- * @brief       Get the destination vertex ids
- *
- * @param [in]     coo   Opaque pointer to COO
- * @return type erased array view of destination vertex ids
- */
-cugraph_type_erased_device_array_view_t* cugraph_coo_get_destinations(cugraph_coo_t* coo);
-
-/**
- * @brief       Get the edge weights
- *
- * @param [in]     coo   Opaque pointer to COO
- * @return type erased array view of edge weights, NULL if no edge weights in COO
- */
-cugraph_type_erased_device_array_view_t* cugraph_coo_get_edge_weights(cugraph_coo_t* coo);
-
-/**
- * @brief       Get the edge id
- *
- * @param [in]     coo   Opaque pointer to COO
- * @return type erased array view of edge id, NULL if no edge ids in COO
- */
-cugraph_type_erased_device_array_view_t* cugraph_coo_get_edge_id(cugraph_coo_t* coo);
-
-/**
- * @brief       Get the edge type
- *
- * @param [in]     coo   Opaque pointer to COO
- * @return type erased array view of edge type, NULL if no edge types in COO
- */
-cugraph_type_erased_device_array_view_t* cugraph_coo_get_edge_type(cugraph_coo_t* coo);
-
-/**
- * @brief       Get the number of coo object in the list
- *
- * @param [in]     coo_list   Opaque pointer to COO list
- * @return number of elements
- */
-size_t cugraph_coo_list_size(const cugraph_coo_list_t* coo_list);
-
-/**
- * @brief       Get a COO from the list
- *
- * @param [in]     coo_list   Opaque pointer to COO list
- * @param [in]     index      Index of desired COO from list
- * @return a cugraph_coo_t* object from the list
- */
-cugraph_coo_t* cugraph_coo_list_element(cugraph_coo_list_t* coo_list, size_t index);
-
-/**
- * @brief     Free coo object
- *
- * @param [in]    coo Opaque pointer to COO
- */
-void cugraph_coo_free(cugraph_coo_t* coo);
-
-/**
- * @brief     Free coo list
- *
- * @param [in]    coo_list Opaque pointer to list of COO objects
- */
-void cugraph_coo_list_free(cugraph_coo_list_t* coo_list);
-
 /**
  * @brief      Generate RMAT edge list
  *