Fixed window temporal sampling by ChuckHastings · Pull Request #5625 · rapidsai/cugraph

ChuckHastings · 2026-08-12T17:41:35Z

Add fixed window temporal sampling implementation, closes #5593

Also lays the groundwork for implementing last-n sampling, updating the API framework temporal sampling to make the last-n choice orthogonal to the temporal parameters.

…n use the new primitive

…expected to fail

copy-pr-bot · 2026-08-12T17:41:39Z

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

seunghwak

Quick reviews/questions about the API changes.

More reviews on the implementation part are in progress.

seunghwak · 2026-08-12T23:30:01Z

                                time) */
-  LAST                      /** Support last n behavior */
+  FIXED_WINDOW,             /** Apply the original per-seed time window at every hop */
+  LAST = FIXED_WINDOW       /** Deprecated alias for FIXED_WINDOW */


What is this? Last-N is not a temporal sampling method, it is a neighbor selection method (as specified in neighbor_selection_t), right? Should we better delete this to avoid confusion?

Or last-N or first-N are based on time stamps, not priorities (biases)?

Last-N for the current use case is based on timestamps, but we already use timestamps to create biases, so we can easily implement with your new primitive. I think having it based on biases is a more flexible design anyway.

The LAST enum value was already defined, leaving this in place as deprecated to allow this to be a non-breaking API change. If a user previously called with LAST it would be valid, although it would have fast-failed as not implemented.

I'll change this so that it is not the same as FIXED_WINDOW (that's probably not correct) and instead returns a not implemented but deprecated error message. We'll actually delete the value in the next release.

seunghwak · 2026-08-12T23:33:29Z

+enum class neighbor_selection_t {
+  RANDOM = 0, /** Random selection. Uniform if no bias view is supplied, biased otherwise. */
+  FIRST,      /** Deterministically select the earliest edges. Not yet implemented. */
+  LAST        /** Deterministically select the latest edges. Not yet implemented. */


Similar here, last-N or first-N are based on time stamps?

In this case, does it make sense to set neighbor_selection_t to LAST and temporal_sampling_comparison_t to STRICTLY_INCREASING?

Yes, that might be a cleaner design. I'll look at that.

seunghwak · 2026-08-13T00:04:46Z

+  neighbor_selection_t neighbor_selection,
+  std::optional<temporal_sampling_comparison_t> temporal_sampling_comparison,
+  sampling_flags_t sampling_flags,


Now we have neighbor_selection_t, temporal_sampling_comparison_t, and sampling_flags_t. But aren't the first two sampling flags (or sampling options)?

Yes, I think combining them would make sense, let me look at that.

seunghwak · 2026-08-13T00:10:39Z

+ * is required and @p fan_out contains one value per (hop, edge type). Otherwise, @p fan_out
+ * contains one value per hop.
+ *
+ * RANDOM selection samples uniformly when @p edge_bias_view is absent and samples according to


RANDOM=>neighbor_selection_t::RANDOM?

or something like

neighbor_selection_t dictates a neighbor selection method. RANDOM selection samples ... ?

And documentation for template and input parameters and return values are missing here.

Will look at this

It seems like the documentation still needs updates.

seunghwak

Additional reviews.

seunghwak · 2026-08-13T00:37:51Z

-  return cugraph::c_api::run_algorithm(graph, functor, result, error);
+  auto const* options_cpp =
+    reinterpret_cast<cugraph::c_api::cugraph_sampling_options_t const*>(options);
+  return cugraph_neighbor_sample(


Any reason the biased wrappers call run_neighbor_sample() (https://github.com/rapidsai/cugraph/pull/5625/changes#diff-d268da7d4ce7574a739c9818704be440c1d2d633f087c39f8a73736b2f057859R746) directly while the uniform wrappers go through cugraph_neighbor_sample()? Better be more consistent about call chains?

It is a bit challenging to understand the call stack hierarchy.

This all should go through cugraph_neighbor_sample, I'll fix that. I tried a few things and ended up with this model, missed getting rid of some of the run_neighbor_sample() calls.

The intention is to remove the old interfaces and have everything call cugraph_neighbor_sample, but I wanted to marek them as deprecated and leave the old methods in place for a release before we delete them.

seunghwak · 2026-08-13T00:54:26Z

 * SPDX-License-Identifier: Apache-2.0
 */
+
+// Built into libcugraph_common.so: sampling common TUs (gather_one_hop / sample_outgoing_edges)


This seems to describe a build/linkage requirement rather than the implementation itself. Would it be better to keep this explanation in CMakeLists.txt next to where these sources are added to CUGRAPH_COMMON_*?

I'll move that.

Sounds great.

alexbarghi-nv · 2026-08-17T23:56:36Z

+  auto options =
+    *reinterpret_cast<cugraph::c_api::cugraph_sampling_options_t const*>(sampling_options);
+
+  auto const is_biased   = edge_biases != nullptr;


What happens when we're using the legacy functions (i.e. homogeneous_biased_temporal_neighbor_sample) and don't have a way to pass edge biases from PLC? It seems like it will just fall back to uniform neighbor sampling which we don't want. This PR needs to expose a way to pass the biases from PLC, or at least to preserve the old behavior while we work that out in a separate PR.

Good catch. I forgot that we don't yet have a good way of creating a biases array except as the edge weights when we create the graph. I'll add that back.

seunghwak

Comments about several minor cosmetic issues. Otherwise, LGTM.

seunghwak · 2026-08-17T21:11:11Z

+ * is required and @p fan_out contains one value per (hop, edge type). Otherwise, @p fan_out
+ * contains one value per hop.
+ *
+ * RANDOM selection samples uniformly when @p edge_bias_view is absent and samples according to


It seems like the documentation still needs updates.

seunghwak · 2026-08-17T23:38:22Z

+      }
+
+      // FIXME: For biased sampling, the user should pass either biases or edge weights,
+      // otherwised throw an error and suggest the user to call uniform neighbor sample instead


Any reason to delay addressing this?

Fixed. The comment was mostly obsolete, but added another CUGRAPH_EXPECTS to catch the edge case that was still wrong.

seunghwak · 2026-08-18T00:14:11Z

 };

+// FIXED_WINDOW analogue of thrust::maximum / thrust::minimum used to dedupe scalar side-table
+// times: duplicate entries for the same key are expected to be identical, so keep the first.


Minor documentation issue but we are migrating from thrust::minimum/maximum to cuda::minimum/maximum.

seunghwak · 2026-08-18T00:15:34Z

+        sorted_times.begin(),
+        thrust::make_zip_iterator(out_majors.begin(), out_labels.begin()),
+        out_times.begin(),
+        thrust::equal_to<cuda::std::tuple<vertex_t, int32_t>>{},


cuda::std::equal_to.

seunghwak · 2026-08-18T00:15:48Z

+                                        sorted_times.begin(),
+                                        out_majors.begin(),
+                                        out_times.begin(),
+                                        thrust::equal_to<vertex_t>{},


cuda::std::equal_to

seunghwak · 2026-08-18T00:17:32Z

 * SPDX-License-Identifier: Apache-2.0
 */
+
+// Built into libcugraph_common.so: sampling common TUs (gather_one_hop / sample_outgoing_edges)


Sounds great.

…ighbor_sample call. A few cosmetic changes

ChuckHastings added 5 commits August 6, 2026 15:42

Initial implementation of fixed window sampling, SG tests pass

b7ddc8d

Merge branch 'main' into fixed_window_temporal_sampling

a4e50ca

debug these changes on MG

107e8bb

Remove implementation of last_n and replace with a fast-fail so we ca…

63da458

…n use the new primitive

improve valiation of fixed window sampling, the tests currently lare …

52fac34

…expected to fail

ChuckHastings self-assigned this Aug 12, 2026

ChuckHastings added improvement Improvement / enhancement to an existing function non-breaking Non-breaking change labels Aug 12, 2026

ChuckHastings marked this pull request as ready for review August 12, 2026 17:42

ChuckHastings requested review from a team as code owners August 12, 2026 17:42

seunghwak reviewed Aug 13, 2026

View reviewed changes

ChuckHastings added 2 commits August 14, 2026 12:12

Merge branch 'main' into fixed_window_temporal_sampling

b09d545

Address PR comments, restructure C API implementation more cleanly

f5c671b

alexbarghi-nv requested changes Aug 17, 2026

View reviewed changes

seunghwak approved these changes Aug 18, 2026

View reviewed changes

ChuckHastings added 2 commits August 18, 2026 11:34

add back use of biases from edge weights. Add PLC call for cugraph_ne…

8de692c

…ighbor_sample call. A few cosmetic changes

Merge branch 'main' into fixed_window_temporal_sampling

2e8b5ec

ChuckHastings requested a review from a team as a code owner August 18, 2026 18:34

Uh oh!

Conversation

ChuckHastings commented Aug 12, 2026

Uh oh!

copy-pr-bot Bot commented Aug 12, 2026

Uh oh!

seunghwak left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seunghwak left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seunghwak left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ChuckHastings Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ChuckHastings Aug 18, 2026 •

edited

Loading