[Graphbolt] Update the sampler algorithm documentation for fanout = -1. (#6114)

graphbolt/src/csc_sampling_graph.cc

@@ -329,9 +329,9 @@ c10::intrusive_ptr<CSCSamplingGraph> CSCSamplingGraph::LoadFromSharedMemory(
  * @param num_neighbors The number of neighbors to pick.
  * @param fanout The number of edges to be sampled for each node. It should be
  * >= 0 or -1.
- *  - When the value is -1, all neighbors will be chosen for sampling. It is
- * equivalent to selecting all neighbors with non-zero probability when the
- * fanout is >= the number of neighbors (and replacement is set to false).
+ *  - When the value is -1, all neighbors will be sampled once regardless of
+ * replacement. It is equivalent to selecting all neighbors when the fanout is
+ * >= the number of neighbors (and replacement is set to false).
  *  - When the value is a non-negative integer, it serves as a minimum
  * threshold for selecting neighbors.
  * @param replace Boolean indicating whether the sample is performed with or
@@ -458,9 +458,10 @@ inline torch::Tensor UniformPick(
  * @param num_neighbors The number of neighbors to pick.
  * @param fanout The number of edges to be sampled for each node. It should be
  * >= 0 or -1.
- *  - When the value is -1, all neighbors will be chosen for sampling. It is
- * equivalent to selecting all neighbors with non-zero probability when the
- * fanout is >= the number of neighbors (and replacement is set to false).
+ *  - When the value is -1, all neighbors with non-zero probability will be
+ * sampled once regardless of replacement. It is equivalent to selecting all
+ * neighbors with non-zero probability when the fanout is >= the number of
+ * neighbors (and replacement is set to false).
  *  - When the value is a non-negative integer, it serves as a minimum
  * threshold for selecting neighbors.
  * @param replace Boolean indicating whether the sample is performed with or
@@ -592,9 +593,10 @@ inline void safe_divide(T& a, U b) {
  * @param num_neighbors The number of neighbors to pick.
  * @param fanout The number of edges to be sampled for each node. It should be
  * >= 0 or -1.
- *  - When the value is -1, all neighbors will be chosen for sampling. It is
- * equivalent to selecting all neighbors with non-zero probability when the
- * fanout is >= the number of neighbors (and replacement is set to false).
+ *  - When the value is -1, all neighbors (with non-zero probability, if
+ * weighted) will be sampled once regardless of replacement. It is equivalent to
+ * selecting all neighbors with non-zero probability when the fanout is >= the
+ * number of neighbors (and replacement is set to false).
  *  - When the value is a non-negative integer, it serves as a minimum
  * threshold for selecting neighbors.
  * @param options Tensor options specifying the desired data type of the result.
@@ -612,6 +614,11 @@ inline torch::Tensor LaborPick(
     const torch::TensorOptions& options,
     const torch::optional<torch::Tensor>& probs_or_mask,
     SamplerArgs<SamplerType::LABOR> args) {
+  // TODO: fix inconsistency with Neighbor sampler.
+  // 1. Replace = true, fanout = -1. Expected: sample all neighbors with
+  // non-zero probility once regardless of replacement.
+  // 2. Replace = true, fanout > num_neighbors. Expected: sample fanout many
+  // neighbors.
   fanout = fanout < 0 ? num_neighbors : std::min(fanout, num_neighbors);
   if (!NonUniform && !Replace && fanout >= num_neighbors) {
     return torch::arange(offset, offset + num_neighbors, options);

python/dgl/graphbolt/impl/csc_sampling_graph.py

@@ -283,10 +283,11 @@ class CSCSamplingGraph:
                 types, and each fanout value corresponds to a specific edge
                 type of the nodes.
             The value of each fanout should be >= 0 or = -1.
-              - When the value is -1, all neighbors will be chosen for
-                sampling. It is equivalent to selecting all neighbors when
-                the fanout is >= the number of neighbors (and replace is set to
-                false).
+              - When the value is -1, all neighbors (with non-zero probability,
+                if weighted) will be sampled once regardless of replacement. It
+                is equivalent to selecting all neighbors with non-zero
+                probability when the fanout is >= the number of neighbors (and
+                replace is set to false).
               - When the value is a non-negative integer, it serves as a
                 minimum threshold for selecting neighbors.
         replace: bool
@@ -395,10 +396,11 @@ class CSCSamplingGraph:
                 types, and each fanout value corresponds to a specific edge
                 type of the nodes.
             The value of each fanout should be >= 0 or = -1.
-              - When the value is -1, all neighbors will be chosen for
-                sampling. It is equivalent to selecting all neighbors when
-                the fanout is >= the number of neighbors (and replace is set to
-                false).
+              - When the value is -1, all neighbors (with non-zero probability,
+                if weighted) will be sampled once regardless of replacement. It
+                is equivalent to selecting all neighbors with non-zero
+                probability when the fanout is >= the number of neighbors (and
+                replace is set to false).
               - When the value is a non-negative integer, it serves as a
                 minimum threshold for selecting neighbors.
         replace: bool
@@ -455,10 +457,11 @@ class CSCSamplingGraph:
                 types, and each fanout value corresponds to a specific edge
                 type of the nodes.
             The value of each fanout should be >= 0 or = -1.
-              - When the value is -1, all neighbors will be chosen for
-                sampling. It is equivalent to selecting all neighbors when
-                the fanout is >= the number of neighbors (and replace is set to
-                false).
+              - When the value is -1, all neighbors (with non-zero probability,
+                if weighted) will be sampled once regardless of replacement. It
+                is equivalent to selecting all neighbors with non-zero
+                probability when the fanout is >= the number of neighbors (and
+                replace is set to false).
               - When the value is a non-negative integer, it serves as a
                 minimum threshold for selecting neighbors.
         replace: bool