Skip to content

Fixed window temporal sampling #5625

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ChuckHastings wants to merge 9 commits into
base: main
Choose a base branch
from
Open

Fixed window temporal sampling #5625

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
b7ddc8d
Initial implementation of fixed window sampling, SG tests pass
ChuckHastings Aug 6, 2026
a4e50ca
Merge branch 'main' into fixed_window_temporal_sampling
ChuckHastings Aug 6, 2026
107e8bb
debug these changes on MG
ChuckHastings Aug 11, 2026
63da458
Remove implementation of last_n and replace with a fast-fail so we ca…
ChuckHastings Aug 11, 2026
52fac34
improve valiation of fixed window sampling, the tests currently lare …
ChuckHastings Aug 12, 2026
b09d545
Merge branch 'main' into fixed_window_temporal_sampling
ChuckHastings Aug 14, 2026
f5c671b
Address PR comments, restructure C API implementation more cleanly
ChuckHastings Aug 15, 2026
8de692c
add back use of biases from edge weights. Add PLC call for cugraph_n…
ChuckHastings Aug 18, 2026
2e8b5ec
Merge branch 'main' into fixed_window_temporal_sampling
ChuckHastings Aug 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions cpp/CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,10 @@ set(CUGRAPH_COMMON_DISTRIBUTED_SOURCES
set(CUGRAPH_COMMON_SAMPLING_SOURCES
src/sampling/detail/sample_outgoing_edges_common_v64_e64.cu
src/sampling/detail/sample_outgoing_edges_common_v32_e32.cu
src/sampling/detail/gather_one_hop_common_v32_e32.cu
src/sampling/detail/gather_one_hop_common_v64_e64.cu
src/sampling/detail/gather_sampled_properties_common_v32_e32.cu
src/sampling/detail/gather_sampled_properties_common_v64_e64.cu
src/sampling/detail/update_visited_utils_common_v32_e32.cu
src/sampling/detail/update_visited_utils_common_v64_e64.cu
src/sampling/detail/deduplicate_edges_by_minor_common_v32_e32.cu
Expand All @@ -196,6 +200,11 @@ set(CUGRAPH_COMMON_STRUCTURE_SOURCES
src/structure/renumber_utils_common_v32_e32.cu
src/structure/edge_partition_device_view_mask_degrees_common_v32_e32.cu
src/structure/edge_partition_device_view_mask_degrees_common_v64_e64.cu
# MG graph_view_t (needed by gather_one_hop_common_* / sample_outgoing_edges_common_*).
# Keep self-contained in libcugraph_common.so so SG test binaries that do not link
# libcugraph_mg.so can still resolve local_edge_partition_* for multi_gpu=true.
src/structure/graph_view_mg_v64_e64.cu
src/structure/graph_view_mg_v32_e32.cu
)

set(CUGRAPH_COMMON_SOURCES
Expand All @@ -219,8 +228,6 @@ set(CUGRAPH_MTMG_SOURCES
set(CUGRAPH_SG_SOURCES
src/sampling/temporal_sampling_sg_v32_e32.cu
src/sampling/temporal_sampling_sg_v64_e64.cu
src/sampling/detail/gather_sampled_properties_sg_v32_e32.cu
src/sampling/detail/gather_sampled_properties_sg_v64_e64.cu
src/utilities/validation_checks_sg_v32_e32.cu
src/utilities/validation_checks_sg_v64_e64.cu
src/detail/collect_local_vertex_values_sg_v32_e32.cu
Expand Down Expand Up @@ -275,8 +282,6 @@ set(CUGRAPH_SG_SOURCES
src/sampling/detail/prepare_next_frontier_sg_v32_e32.cu
src/sampling/detail/check_edge_bias_values_sg_v64_e64.cu
src/sampling/detail/check_edge_bias_values_sg_v32_e32.cu
src/sampling/detail/gather_one_hop_sg_v32_e32.cu
src/sampling/detail/gather_one_hop_sg_v64_e64.cu
src/sampling/detail/sample_edges_sg_v64_e64.cu
src/sampling/detail/sample_edges_sg_v32_e32.cu
src/sampling/neighbor_sampling_sg_v32_e32.cu
Expand Down Expand Up @@ -371,8 +376,6 @@ set(CUGRAPH_SG_SOURCES
set(CUGRAPH_MG_SOURCES
src/sampling/temporal_sampling_mg_v32_e32.cu
src/sampling/temporal_sampling_mg_v64_e64.cu
src/sampling/detail/gather_sampled_properties_mg_v32_e32.cu
src/sampling/detail/gather_sampled_properties_mg_v64_e64.cu
src/utilities/validation_checks_mg_v32_e32.cu
src/utilities/validation_checks_mg_v64_e64.cu
src/utilities/shuffle_local_edge_srcs_dsts_mg_v32.cu
Expand All @@ -395,8 +398,6 @@ set(CUGRAPH_MG_SOURCES
src/community/detail/maximal_independent_moves_mg_v32_e32.cu
src/link_prediction/detail/similarity_mg_v32_e32.cu
src/link_prediction/detail/similarity_mg_v64_e64.cu
src/structure/graph_view_mg_v64_e64.cu
src/structure/graph_view_mg_v32_e32.cu
src/structure/edge_partition_device_view_mg_v64_e64.cu
src/structure/edge_partition_device_view_mg_v32_e32.cu
src/link_prediction/jaccard_mg_v64_e64.cu
Expand All @@ -423,8 +424,6 @@ set(CUGRAPH_MG_SOURCES
src/sampling/detail/prepare_next_frontier_mg_v32_e32.cu
src/sampling/detail/check_edge_bias_values_mg_v64_e64.cu
src/sampling/detail/check_edge_bias_values_mg_v32_e32.cu
src/sampling/detail/gather_one_hop_mg_v32_e32.cu
src/sampling/detail/gather_one_hop_mg_v64_e64.cu
src/sampling/detail/sample_edges_mg_v64_e64.cu
src/sampling/detail/sample_edges_mg_v32_e32.cu
src/sampling/neighbor_sampling_mg_v32_e32.cu
Expand Down Expand Up @@ -680,6 +679,7 @@ add_library(cugraph_c
src/c_api/lookup_src_dst.cpp
src/c_api/louvain.cpp
src/c_api/triangle_count.cpp
src/c_api/neighbor_sample.cpp
src/c_api/neighbor_sampling.cpp
src/c_api/sampling_result.cpp
src/c_api/temporal_neighbor_sampling.cpp
Expand Down
100 changes: 95 additions & 5 deletions cpp/include/cugraph/sampling_functions.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
#include <cugraph/export.hpp>
#include <cugraph/graph_view.hpp>
#include <cugraph/src_dst_lookup_container.hpp>
#include <cugraph/utilities/error.hpp>

#include <raft/core/device_span.hpp>
#include <raft/core/handle.hpp>
Expand Down Expand Up @@ -42,10 +43,27 @@ enum class temporal_sampling_comparison_t {
STRICTLY_DECREASING, /** Time strictly decreasing (each time is before the previous one) */
MONOTONICALLY_DECREASING, /** Time monotonically decreasing (could have multiple edges with same
time) */
LAST /** Support last n behavior */
FIXED_WINDOW, /** Apply the original per-seed time window at every hop */
LAST /** Deprecated Value, we moved last-n to a different parameter */
};

struct sampling_flags_t {
/**
* @brief Selects neighbors from the set that satisfies the sampling filters.
*/
enum class neighbor_selection_t {
RANDOM = 0, /** Random selection. Uniform if no bias view is supplied, biased otherwise. */
LAST /** Deterministically select the latest edges based on the ordering criteria defined in
temporal_sampling_comparison. Not yet implemented. */
};

/**
* @brief Options controlling neighborhood sampling behavior.
*
* Temporal sampling is enabled when @p temporal_sampling_comparison has a value; leave it
* unset for non-temporal sampling. Future sampling knobs should be added here so
* `neighbor_sample` can keep a stable parameter list.
*/
struct sampling_options_t {
/**
* Specifies how to handle prior sources. Default is DEFAULT.
*/
Expand All @@ -70,19 +88,28 @@ struct sampling_flags_t {
bool with_replacement{true};

/**
* Specifies how to handle temporal sampling. Default is STRICTLY_INCREASING.
* When set, enables temporal sampling with the given comparison mode. Default is unset
* (non-temporal).
*/
temporal_sampling_comparison_t temporal_sampling_comparison{
temporal_sampling_comparison_t::STRICTLY_INCREASING};
std::optional<temporal_sampling_comparison_t> temporal_sampling_comparison{std::nullopt};

/**
* Specifies if disjoint sampling should be enforced. Default is false.
*/
bool disjoint_sampling{false};

/**
* Specifies how neighbors are selected from the eligible set. Default is RANDOM.
*/
neighbor_selection_t neighbor_selection{neighbor_selection_t::RANDOM};
};

/** @deprecated Use sampling_options_t. */
using sampling_flags_t = sampling_options_t;

/**
* @ingroup sampling_functions_cpp
* @deprecated Use neighbor_sample instead.
* @brief Homogeneous Uniform Neighborhood Sampling.
*
* This function traverses from a set of starting vertices, traversing outgoing edges and
Expand Down Expand Up @@ -158,6 +185,7 @@ homogeneous_uniform_neighbor_sample(

/**
* @ingroup sampling_functions_cpp
* @deprecated Use neighbor_sample instead.
* @brief Heterogeneous Uniform Neighborhood Sampling.
*
* This function traverses from a set of starting vertices, traversing outgoing edges and
Expand Down Expand Up @@ -238,6 +266,7 @@ heterogeneous_uniform_neighbor_sample(

/**
* @ingroup sampling_functions_cpp
* @deprecated Use neighbor_sample instead.
* @brief Homogeneous Biased Neighborhood Sampling.
*
* This function traverses from a set of starting vertices, traversing outgoing edges and
Expand Down Expand Up @@ -320,6 +349,7 @@ homogeneous_biased_neighbor_sample(

/**
* @ingroup sampling_functions_cpp
* @deprecated Use neighbor_sample instead.
* @brief Heterogeneous Biased Neighborhood Sampling.
*
* This function traverses from a set of starting vertices, traversing outgoing edges and
Expand Down Expand Up @@ -407,6 +437,7 @@ heterogeneous_biased_neighbor_sample(

/**
* @ingroup sampling_functions_cpp
* @deprecated Use neighbor_sample instead.
* @brief Homogeneous Uniform Temporal Neighborhood Sampling.
*
* This function traverses from a set of starting vertices, traversing outgoing edges and
Expand Down Expand Up @@ -522,6 +553,7 @@ homogeneous_uniform_temporal_neighbor_sample(

/**
* @ingroup sampling_functions_cpp
* @deprecated Use neighbor_sample instead.
* @brief Heterogeneous Uniform Temporal Neighborhood Sampling.
*
* This function traverses from a set of starting vertices, traversing outgoing edges and
Expand Down Expand Up @@ -642,6 +674,7 @@ heterogeneous_uniform_temporal_neighbor_sample(

/**
* @ingroup sampling_functions_cpp
* @deprecated Use neighbor_sample instead.
* @brief Homogeneous Biased Temporal Neighborhood Sampling.
*
* This function traverses from a set of starting vertices, traversing outgoing edges and
Expand Down Expand Up @@ -764,6 +797,7 @@ homogeneous_biased_temporal_neighbor_sample(

/**
* @ingroup sampling_functions_cpp
* @deprecated Use neighbor_sample instead.
* @brief Heterogeneous Biased Temporal Neighborhood Sampling.
*
* This function traverses from a set of starting vertices, traversing outgoing edges and
Expand Down Expand Up @@ -889,6 +923,62 @@ heterogeneous_biased_temporal_neighbor_sample(
sampling_flags_t sampling_flags,
bool do_expensive_check = false);

/**
* @ingroup sampling_functions_cpp
* @brief Sample a homogeneous or heterogeneous neighborhood, optionally using temporal filters.
*
* This unified API replaces the homogeneous/heterogeneous, uniform/biased, and
* temporal/non-temporal entry-point matrix above.
*
* Sampling is heterogeneous when @p num_edge_types is specified; in that case @p edge_type_view
* 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

@seunghwak seunghwak Aug 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@ChuckHastings ChuckHastings Aug 13, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will look at this

@seunghwak seunghwak Aug 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems like the documentation still needs updates.

* the supplied biases when it is present. LAST is reserved for deterministically selecting the
* latest eligible edges (temporal only; no bias; no with-replacement), but is not yet implemented.
*
* Sampling is temporal when @p sampling_options.temporal_sampling_comparison is set; in that case
* @p edge_start_time_view is required. FIXED_WINDOW applies each seed's original closed time window
* at every hop, while the increasing and decreasing modes propagate sampled edge times as the next
* frontier bound.
*/
template <typename vertex_t,
typename edge_t,
typename weight_t,
typename edge_type_t,
typename time_stamp_t,
bool store_transposed,
bool multi_gpu>
std::tuple<rmm::device_uvector<vertex_t>,
rmm::device_uvector<vertex_t>,
std::optional<rmm::device_uvector<weight_t>>,
std::optional<rmm::device_uvector<edge_t>>,
std::optional<rmm::device_uvector<edge_type_t>>,
std::optional<rmm::device_uvector<time_stamp_t>>,
std::optional<rmm::device_uvector<time_stamp_t>>,
std::optional<rmm::device_uvector<int32_t>>,
std::optional<rmm::device_uvector<size_t>>>
neighbor_sample(
raft::handle_t const& handle,
raft::random::RngState& rng_state,
graph_view_t<vertex_t, edge_t, store_transposed, multi_gpu> const& graph_view,
std::optional<edge_property_view_t<edge_t, weight_t const*>> edge_weight_view,
std::optional<edge_property_view_t<edge_t, edge_t const*>> edge_id_view,
std::optional<edge_property_view_t<edge_t, edge_type_t const*>> edge_type_view,
std::optional<edge_property_view_t<edge_t, time_stamp_t const*>> edge_start_time_view,
std::optional<edge_property_view_t<edge_t, time_stamp_t const*>> edge_end_time_view,
std::optional<edge_property_view_t<edge_t, weight_t const*>> edge_bias_view,
raft::device_span<vertex_t const> starting_vertices,
std::optional<raft::device_span<time_stamp_t const>> starting_vertex_start_times,
std::optional<raft::device_span<time_stamp_t const>> starting_vertex_end_times,
std::optional<raft::device_span<int32_t const>> starting_vertex_labels,
std::optional<raft::device_span<int32_t const>> label_to_output_comm_rank,
raft::host_span<int32_t const> fan_out,
std::optional<edge_type_t> num_edge_types,
sampling_options_t sampling_options,
bool do_expensive_check = false);

/**
* @ingroup sampling_functions_cpp
* @brief renumber sampled edge list and compress to the (D)CSR|(D)CSC format.
Expand Down
Loading
Loading