Sampling#
Typedefs
-
typedef enum cugraph_prior_sources_behavior_t cugraph_prior_sources_behavior_t
Enumeration for prior sources behavior.
-
typedef enum cugraph_compression_type_t cugraph_compression_type_t
Selects the type of compression to use for the output samples.
Enums
-
enum cugraph_prior_sources_behavior_t#
Enumeration for prior sources behavior.
Values:
-
enumerator DEFAULT#
-
enumerator CARRY_OVER#
Construct sources for hop k from destination vertices from hop k-1
-
enumerator EXCLUDE#
Construct sources for hop k from destination vertices from hop k-1 and sources from hop k-1 Construct sources for hop k from destination vertices form hop k-1, but exclude any vertex that has already been used as a source
-
enumerator DEFAULT#
-
enum cugraph_temporal_sampling_comparison_t#
Enumeration for temporal comparison options.
Values:
-
enumerator STRICTLY_INCREASING#
-
enumerator MONOTONICALLY_INCREASING#
Time strictly increasing (each time is after the previous one)
-
enumerator STRICTLY_DECREASING#
Time monotonically increasing (could have multiple edges with same time)
-
enumerator MONOTONICALLY_DECREASING#
Time strictly decreasing (each time is before the previous one)
-
enumerator LAST#
Time monotonically decreasing (could have multiple edges with same time) Support last n behavior
-
enumerator STRICTLY_INCREASING#
-
enum cugraph_compression_type_t#
Selects the type of compression to use for the output samples.
Values:
-
enumerator COO#
-
enumerator CSR#
Outputs in COO format. Default.
-
enumerator CSC#
Compresses in CSR format. This means the row (src) column is compressed into a row pointer.
-
enumerator DCSR#
Compresses in CSC format. This means the col (dst) column is compressed into a column pointer.
-
enumerator DCSC#
Compresses in DCSR format. This outputs an additional index that avoids empty entries in the row pointer. Compresses in DCSC format. This outputs an additional index that avoid empty entries in the col pointer.
-
enumerator COO#
Functions
- cugraph_error_code_t cugraph_uniform_random_walks(
- const cugraph_resource_handle_t *handle,
- cugraph_rng_state_t *rng_state,
- cugraph_graph_t *graph,
- const cugraph_type_erased_device_array_view_t *start_vertices,
- size_t max_length,
- cugraph_random_walk_result_t **result,
- cugraph_error_t **error
Compute uniform random walks.
- Parameters:
handle – [in] Handle for accessing resources
rng_state – [inout] State of the random number generator, updated with each call
graph – [in] Pointer to graph. NOTE: Graph might be modified if the storage needs to be transposed
start_vertices – [in] Array of source vertices
max_length – [in] Maximum length of the generated path
result – [out] Output from the node2vec call
error – [out] Pointer to an error object storing details of any error. Will be populated if error code is not CUGRAPH_SUCCESS
- Returns:
error code
- cugraph_error_code_t cugraph_biased_random_walks(
- const cugraph_resource_handle_t *handle,
- cugraph_rng_state_t *rng_state,
- cugraph_graph_t *graph,
- const cugraph_type_erased_device_array_view_t *start_vertices,
- size_t max_length,
- cugraph_random_walk_result_t **result,
- cugraph_error_t **error
Compute biased random walks.
- Parameters:
handle – [in] Handle for accessing resources
rng_state – [inout] State of the random number generator, updated with each call
graph – [in] Pointer to graph. NOTE: Graph might be modified if the storage needs to be transposed
start_vertices – [in] Array of source vertices
max_length – [in] Maximum length of the generated path
result – [out] Output from the node2vec call
error – [out] Pointer to an error object storing details of any error. Will be populated if error code is not CUGRAPH_SUCCESS
- Returns:
error code
- cugraph_error_code_t cugraph_node2vec_random_walks(
- const cugraph_resource_handle_t *handle,
- cugraph_rng_state_t *rng_state,
- cugraph_graph_t *graph,
- const cugraph_type_erased_device_array_view_t *start_vertices,
- size_t max_length,
- double p,
- double q,
- cugraph_random_walk_result_t **result,
- cugraph_error_t **error
Compute random walks using the node2vec framework.
- Parameters:
handle – [in] Handle for accessing resources
rng_state – [inout] State of the random number generator, updated with each call
graph – [in] Pointer to graph. NOTE: Graph might be modified if the storage needs to be transposed
start_vertices – [in] Array of source vertices
max_length – [in] Maximum length of the generated path
compress_result – [in] If true, return the paths as a compressed sparse row matrix, otherwise return as a dense matrix
p – [in] The return parameter
q – [in] The in/out parameter
result – [out] Output from the node2vec call
error – [out] Pointer to an error object storing details of any error. Will be populated if error code is not CUGRAPH_SUCCESS
- Returns:
error code
- cugraph_error_code_t cugraph_homogeneous_uniform_neighbor_sample(
- const cugraph_resource_handle_t *handle,
- cugraph_rng_state_t *rng_state,
- cugraph_graph_t *graph,
- const cugraph_type_erased_device_array_view_t *start_vertices,
- const cugraph_type_erased_device_array_view_t *starting_vertex_label_offsets,
- const cugraph_type_erased_host_array_view_t *fan_out,
- const cugraph_sampling_options_t *options,
- bool_t do_expensive_check,
- cugraph_sample_result_t **result,
- cugraph_error_t **error
Homogeneous Uniform Neighborhood Sampling.
Returns a sample of the neighborhood around specified start vertices and fan_out. The neighborhood is sampled uniformly. Optionally, each start vertex can be associated with a label, allowing the caller to specify multiple batches of sampling requests in the same function call - which should improve GPU utilization.
If label is NULL then all start vertices will be considered part of the same batch and the return value will not have a label column.
- Parameters:
handle – [in] Handle for accessing resources
rng_state – [inout] State of the random number generator, updated with each call
graph – [in] Pointer to graph. NOTE: Graph might be modified if the storage needs to be transposed
start_vertices – [in] Device array of start vertices for the sampling
starting_vertex_label_offsets – [in] Device array of the offsets for each label in the seed list. This parameter is only used with the retain_seeds option.
fan_out – [in] Host array defining the fan out at each step in the sampling algorithm. We only support fan_out values of type INT32
sampling_options – [in] Opaque pointer defining the sampling options.
do_expensive_check – [in] A flag to run expensive checks for input arguments (if set to true)
result – [out] Output from the uniform_neighbor_sample call
error – [out] Pointer to an error object storing details of any error. Will be populated if error code is not CUGRAPH_SUCCESS
- Returns:
error code
- cugraph_error_code_t cugraph_homogeneous_biased_neighbor_sample(
- const cugraph_resource_handle_t *handle,
- cugraph_rng_state_t *rng_state,
- cugraph_graph_t *graph,
- const cugraph_edge_property_view_t *edge_biases,
- const cugraph_type_erased_device_array_view_t *start_vertices,
- const cugraph_type_erased_device_array_view_t *starting_vertex_label_offsets,
- const cugraph_type_erased_host_array_view_t *fan_out,
- const cugraph_sampling_options_t *options,
- bool_t do_expensive_check,
- cugraph_sample_result_t **result,
- cugraph_error_t **error
Homogeneous Biased Neighborhood Sampling.
Returns a sample of the neighborhood around specified start vertices and fan_out. The neighborhood is sampled uniformly. Optionally, each start vertex can be associated with a label, allowing the caller to specify multiple batches of sampling requests in the same function call - which should improve GPU utilization.
If label is NULL then all start vertices will be considered part of the same batch and the return value will not have a label column.
- Parameters:
handle – [in] Handle for accessing resources
rng_state – [inout] State of the random number generator, updated with each call
graph – [in] Pointer to graph. NOTE: Graph might be modified if the storage needs to be transposed
edge_biases – [in] Device array of edge biases to use for sampling. If NULL use the edge weight as the bias. If set to NULL, edges will be sampled uniformly.
start_vertices – [in] Device array of start vertices for the sampling
starting_vertex_label_offsets – [in] Device array of the offsets for each label in the seed list. This parameter is only used with the retain_seeds option.
fan_out – [in] Host array defining the fan out at each step in the sampling algorithm. We only support fan_out values of type INT32
sampling_options – [in] Opaque pointer defining the sampling options.
do_expensive_check – [in] A flag to run expensive checks for input arguments (if set to true)
result – [out] Output from the uniform_neighbor_sample call
error – [out] Pointer to an error object storing details of any error. Will be populated if error code is not CUGRAPH_SUCCESS
- Returns:
error code
- cugraph_error_code_t cugraph_heterogeneous_uniform_neighbor_sample(
- const cugraph_resource_handle_t *handle,
- cugraph_rng_state_t *rng_state,
- cugraph_graph_t *graph,
- const cugraph_type_erased_device_array_view_t *start_vertices,
- const cugraph_type_erased_device_array_view_t *starting_vertex_label_offsets,
- const cugraph_type_erased_device_array_view_t *vertex_type_offsets,
- const cugraph_type_erased_host_array_view_t *fan_out,
- int num_edge_types,
- const cugraph_sampling_options_t *options,
- bool_t do_expensive_check,
- cugraph_sample_result_t **result,
- cugraph_error_t **error
Heterogeneous Uniform Neighborhood Sampling.
Returns a sample of the neighborhood around specified start vertices and fan_out. The neighborhood is sampled uniformly. Optionally, each start vertex can be associated with a label, allowing the caller to specify multiple batches of sampling requests in the same function call - which should improve GPU utilization.
If label is NULL then all start vertices will be considered part of the same batch and the return value will not have a label column.
- Parameters:
handle – [in] Handle for accessing resources
rng_state – [inout] State of the random number generator, updated with each call
graph – [in] Pointer to graph. NOTE: Graph might be modified if the storage needs to be transposed
start_vertices – [in] Device array of start vertices for the sampling
starting_vertex_label_offsets – [in] Device array of the offsets for each label in the seed list. This parameter is only used with the retain_seeds option.
vertex_type_offsets – [in] Device array of the offsets for each vertex type in the graph.
fan_out – [in] Host array defining the fan out at each step in the sampling algorithm. We only support fan_out values of type INT32
num_edge_types – [in] Number of edge types where a value of 1 translates to homogeneous neighbor sample whereas a value greater than 1 translates to heterogeneous neighbor sample.
sampling_options – [in] Opaque pointer defining the sampling options.
do_expensive_check – [in] A flag to run expensive checks for input arguments (if set to true)
result – [out] Output from the uniform_neighbor_sample call
error – [out] Pointer to an error object storing details of any error. Will be populated if error code is not CUGRAPH_SUCCESS
- Returns:
error code
- cugraph_error_code_t cugraph_heterogeneous_biased_neighbor_sample(
- const cugraph_resource_handle_t *handle,
- cugraph_rng_state_t *rng_state,
- cugraph_graph_t *graph,
- const cugraph_edge_property_view_t *edge_biases,
- const cugraph_type_erased_device_array_view_t *start_vertices,
- const cugraph_type_erased_device_array_view_t *starting_vertex_label_offsets,
- const cugraph_type_erased_device_array_view_t *vertex_type_offsets,
- const cugraph_type_erased_host_array_view_t *fan_out,
- int num_edge_types,
- const cugraph_sampling_options_t *options,
- bool_t do_expensive_check,
- cugraph_sample_result_t **result,
- cugraph_error_t **error
Heterogeneous Biased Neighborhood Sampling.
Returns a sample of the neighborhood around specified start vertices and fan_out. The neighborhood is sampled uniformly. Optionally, each start vertex can be associated with a label, allowing the caller to specify multiple batches of sampling requests in the same function call - which should improve GPU utilization.
If label is NULL then all start vertices will be considered part of the same batch and the return value will not have a label column.
- Parameters:
handle – [in] Handle for accessing resources
rng_state – [inout] State of the random number generator, updated with each call
graph – [in] Pointer to graph. NOTE: Graph might be modified if the storage needs to be transposed
edge_biases – [in] Device array of edge biases to use for sampling. If NULL use the edge weight as the bias. If set to NULL, edges will be sampled uniformly.
start_vertices – [in] Device array of start vertices for the sampling
starting_vertex_label_offsets – [in] Device array of the offsets for each label in the seed list. This parameter is only used with the retain_seeds option.
vertex_type_offsets – [in] Device array of the offsets for each vertex type in the graph.
fan_out – [in] Host array defining the fan out at each step in the sampling algorithm. We only support fan_out values of type INT32
num_edge_types – [in] Number of edge types where a value of 1 translates to homogeneous neighbor sample whereas a value greater than 1 translates to heterogeneous neighbor sample.
sampling_options – [in] Opaque pointer defining the sampling options.
do_expensive_check – [in] A flag to run expensive checks for input arguments (if set to true)
result – [out] Output from the uniform_neighbor_sample call
error – [out] Pointer to an error object storing details of any error. Will be populated if error code is not CUGRAPH_SUCCESS
- Returns:
error code
- cugraph_error_code_t cugraph_homogeneous_uniform_temporal_neighbor_sample(
- const cugraph_resource_handle_t *handle,
- cugraph_rng_state_t *rng_state,
- cugraph_graph_t *graph,
- const char *temporal_property_name,
- const cugraph_type_erased_device_array_view_t *start_vertices,
- const cugraph_type_erased_device_array_view_t *starting_vertex_start_times,
- const cugraph_type_erased_device_array_view_t *starting_vertex_end_times,
- const cugraph_type_erased_device_array_view_t *starting_vertex_label_offsets,
- const cugraph_type_erased_host_array_view_t *fan_out,
- const cugraph_sampling_options_t *sampling_options,
- bool_t do_expensive_check,
- cugraph_sample_result_t **result,
- cugraph_error_t **error
Homogeneous Uniform Temporal Neighborhood Sampling.
Returns a sample of the neighborhood around specified start vertices and fan_out. The neighborhood is sampled uniformly.
Temporal sampling considers the time associated with the edges. For increasing walks, if we start at vertex v1 and sample an edge that takes us to vertex v2 at time t1, when we sample in the next hop from vertex v2 we consider only edges that occur after time t1; for decreasing walks the restriction is to edges that occur before time t1.
Each seed may also supply an optional closed time window via
starting_vertex_start_timesandstarting_vertex_end_times. Eligible edge times must lie in that window for the entire walk. The window bounds additionally determine the hop-0 frontier: increasing walks begin at the start bound (or -inf if omitted), while decreasing walks begin at the end bound (or +inf if omitted). See the parameter docs below for details.Optionally, each start vertex can be associated with a label, allowing the caller to specify multiple batches of sampling requests in the same function call - which should improve GPU utilization.
If label is NULL then all start vertices will be considered part of the same batch and the return value will not have a label column.
For increasing walks (STRICTLY_INCREASING / MONOTONICALLY_INCREASING), the hop-0 frontier originates at this time (or is unbounded below if NULL), so this array is both the window’s lower bound and the initial frontier time.
For decreasing walks (STRICTLY_DECREASING / MONOTONICALLY_DECREASING), the hop-0 frontier originates at
starting_vertex_end_timesinstead (or is unbounded above if that is NULL), and this array remains only the window’s lower bound (a floor on eligible edge times). Providing onlystarting_vertex_start_timeson a decreasing walk therefore yields a window [start, +inf) whose frontier begins at +inf.- Parameters:
handle – [in] Handle for accessing resources
rng_state – [inout] State of the random number generator, updated with each call
graph – [in] Pointer to graph. NOTE: Graph might be modified if the storage needs to be transposed
temporal_property_name – [in] Name associated with the edge property in the graph that should be used as the time. Currently unused.
start_vertices – [in] Device array of start vertices for the sampling
starting_vertex_start_times – [in] Optional device array of per-seed lower bounds of the time window. Edge times must be >= this value when present. Either or both of
starting_vertex_start_timesandstarting_vertex_end_timesmay be NULL (unbounded on that side). When both are provided, each start time must be <= the corresponding end time.starting_vertex_end_times – [in] Optional device array of per-seed upper bounds of the time window. Edge times must be <= this value when present. See
starting_vertex_start_timesfor optionality and the increasing/decreasing role reversal: for decreasing walks this array is both the window’s upper bound and the hop-0 frontier time; for increasing walks it is only the upper bound (a ceiling).starting_vertex_label_offsets – [in] Device array of the offsets for each label in the seed list. This parameter is only used with the retain_seeds option.
fan_out – [in] Host array defining the fan out at each step in the sampling algorithm. We only support fan_out values of type INT32
sampling_options – [in] Opaque pointer defining the sampling options.
do_expensive_check – [in] A flag to run expensive checks for input arguments (if set to true)
result – [out] Output from the uniform_neighbor_sample call
error – [out] Pointer to an error object storing details of any error. Will be populated if error code is not CUGRAPH_SUCCESS
- Returns:
error code
- cugraph_error_code_t cugraph_homogeneous_biased_temporal_neighbor_sample(
- const cugraph_resource_handle_t *handle,
- cugraph_rng_state_t *rng_state,
- cugraph_graph_t *graph,
- const char *temporal_property_name,
- const cugraph_edge_property_view_t *edge_biases,
- const cugraph_type_erased_device_array_view_t *start_vertices,
- const cugraph_type_erased_device_array_view_t *starting_vertex_start_times,
- const cugraph_type_erased_device_array_view_t *starting_vertex_end_times,
- const cugraph_type_erased_device_array_view_t *starting_vertex_label_offsets,
- const cugraph_type_erased_host_array_view_t *fan_out,
- const cugraph_sampling_options_t *sampling_options,
- bool_t do_expensive_check,
- cugraph_sample_result_t **result,
- cugraph_error_t **error
Homogeneous Biased Temporal Neighborhood Sampling.
Returns a sample of the neighborhood around specified start vertices and fan_out. The neighborhood is sampled uniformly.
Temporal sampling considers the time associated with the edges. For increasing walks, if we start at vertex v1 and sample an edge that takes us to vertex v2 at time t1, when we sample in the next hop from vertex v2 we consider only edges that occur after time t1; for decreasing walks the restriction is to edges that occur before time t1.
Each seed may also supply an optional closed time window via
starting_vertex_start_timesandstarting_vertex_end_times. Eligible edge times must lie in that window for the entire walk. The window bounds additionally determine the hop-0 frontier: increasing walks begin at the start bound (or -inf if omitted), while decreasing walks begin at the end bound (or +inf if omitted). See the parameter docs below for details.Optionally, each start vertex can be associated with a label, allowing the caller to specify multiple batches of sampling requests in the same function call - which should improve GPU utilization.
If label is NULL then all start vertices will be considered part of the same batch and the return value will not have a label column.
For increasing walks (STRICTLY_INCREASING / MONOTONICALLY_INCREASING), the hop-0 frontier originates at this time (or is unbounded below if NULL), so this array is both the window’s lower bound and the initial frontier time.
For decreasing walks (STRICTLY_DECREASING / MONOTONICALLY_DECREASING), the hop-0 frontier originates at
starting_vertex_end_timesinstead (or is unbounded above if that is NULL), and this array remains only the window’s lower bound (a floor on eligible edge times). Providing onlystarting_vertex_start_timeson a decreasing walk therefore yields a window [start, +inf) whose frontier begins at +inf.- Parameters:
handle – [in] Handle for accessing resources
rng_state – [inout] State of the random number generator, updated with each call
graph – [in] Pointer to graph. NOTE: Graph might be modified if the storage needs to be transposed
temporal_property_name – [in] Name associated with the edge property in the graph that should be used as the time. Currently unused.
edge_biases – [in] Device array of edge biases to use for sampling. If NULL use the edge weight as the bias. If set to NULL, edges will be sampled uniformly.
start_vertices – [in] Device array of start vertices for the sampling
starting_vertex_start_times – [in] Optional device array of per-seed lower bounds of the time window. Edge times must be >= this value when present. Either or both of
starting_vertex_start_timesandstarting_vertex_end_timesmay be NULL (unbounded on that side). When both are provided, each start time must be <= the corresponding end time.starting_vertex_end_times – [in] Optional device array of per-seed upper bounds of the time window. Edge times must be <= this value when present. See
starting_vertex_start_timesfor optionality and the increasing/decreasing role reversal: for decreasing walks this array is both the window’s upper bound and the hop-0 frontier time; for increasing walks it is only the upper bound (a ceiling).starting_vertex_label_offsets – [in] Device array of the offsets for each label in the seed list. This parameter is only used with the retain_seeds option.
fan_out – [in] Host array defining the fan out at each step in the sampling algorithm. We only support fan_out values of type INT32
sampling_options – [in] Opaque pointer defining the sampling options.
do_expensive_check – [in] A flag to run expensive checks for input arguments (if set to true)
result – [out] Output from the uniform_neighbor_sample call
error – [out] Pointer to an error object storing details of any error. Will be populated if error code is not CUGRAPH_SUCCESS
- Returns:
error code
- cugraph_error_code_t cugraph_heterogeneous_uniform_temporal_neighbor_sample(
- const cugraph_resource_handle_t *handle,
- cugraph_rng_state_t *rng_state,
- cugraph_graph_t *graph,
- const char *temporal_property_name,
- const cugraph_type_erased_device_array_view_t *start_vertices,
- const cugraph_type_erased_device_array_view_t *starting_vertex_start_times,
- const cugraph_type_erased_device_array_view_t *starting_vertex_end_times,
- const cugraph_type_erased_device_array_view_t *starting_vertex_label_offsets,
- const cugraph_type_erased_device_array_view_t *vertex_type_offsets,
- const cugraph_type_erased_host_array_view_t *fan_out,
- int num_edge_types,
- const cugraph_sampling_options_t *sampling_options,
- bool_t do_expensive_check,
- cugraph_sample_result_t **result,
- cugraph_error_t **error
Heterogeneous Uniform Temporal Neighborhood Sampling.
Returns a sample of the neighborhood around specified start vertices and fan_out. The neighborhood is sampled uniformly.
Temporal sampling considers the time associated with the edges. For increasing walks, if we start at vertex v1 and sample an edge that takes us to vertex v2 at time t1, when we sample in the next hop from vertex v2 we consider only edges that occur after time t1; for decreasing walks the restriction is to edges that occur before time t1.
Each seed may also supply an optional closed time window via
starting_vertex_start_timesandstarting_vertex_end_times. Eligible edge times must lie in that window for the entire walk. The window bounds additionally determine the hop-0 frontier: increasing walks begin at the start bound (or -inf if omitted), while decreasing walks begin at the end bound (or +inf if omitted). See the parameter docs below for details.Optionally, each start vertex can be associated with a label, allowing the caller to specify multiple batches of sampling requests in the same function call - which should improve GPU utilization.
If label is NULL then all start vertices will be considered part of the same batch and the return value will not have a label column.
For increasing walks (STRICTLY_INCREASING / MONOTONICALLY_INCREASING), the hop-0 frontier originates at this time (or is unbounded below if NULL), so this array is both the window’s lower bound and the initial frontier time.
For decreasing walks (STRICTLY_DECREASING / MONOTONICALLY_DECREASING), the hop-0 frontier originates at
starting_vertex_end_timesinstead (or is unbounded above if that is NULL), and this array remains only the window’s lower bound (a floor on eligible edge times). Providing onlystarting_vertex_start_timeson a decreasing walk therefore yields a window [start, +inf) whose frontier begins at +inf.- Parameters:
handle – [in] Handle for accessing resources
rng_state – [inout] State of the random number generator, updated with each call
graph – [in] Pointer to graph. NOTE: Graph might be modified if the storage needs to be transposed
temporal_property_name – [in] Name associated with the edge property in the graph that should be used as the time. Currently unused.
start_vertices – [in] Device array of start vertices for the sampling
starting_vertex_start_times – [in] Optional device array of per-seed lower bounds of the time window. Edge times must be >= this value when present. Either or both of
starting_vertex_start_timesandstarting_vertex_end_timesmay be NULL (unbounded on that side). When both are provided, each start time must be <= the corresponding end time.starting_vertex_end_times – [in] Optional device array of per-seed upper bounds of the time window. Edge times must be <= this value when present. See
starting_vertex_start_timesfor optionality and the increasing/decreasing role reversal: for decreasing walks this array is both the window’s upper bound and the hop-0 frontier time; for increasing walks it is only the upper bound (a ceiling).starting_vertex_label_offsets – [in] Device array of the offsets for each label in the seed list. This parameter is only used with the retain_seeds option.
vertex_type_offsets – [in] Device array of the offsets for each vertex type in the graph.
fan_out – [in] Host array defining the fan out at each step in the sampling algorithm. We only support fan_out values of type INT32
num_edge_types – [in] Number of edge types where a value of 1 translates to homogeneous neighbor sample whereas a value greater than 1 translates to heterogeneous neighbor sample.
sampling_options – [in] Opaque pointer defining the sampling options.
do_expensive_check – [in] A flag to run expensive checks for input arguments (if set to true)
result – [out] Output from the uniform_neighbor_sample call
error – [out] Pointer to an error object storing details of any error. Will be populated if error code is not CUGRAPH_SUCCESS
- Returns:
error code
- cugraph_error_code_t cugraph_heterogeneous_biased_temporal_neighbor_sample(
- const cugraph_resource_handle_t *handle,
- cugraph_rng_state_t *rng_state,
- cugraph_graph_t *graph,
- const char *temporal_property_name,
- const cugraph_edge_property_view_t *edge_biases,
- const cugraph_type_erased_device_array_view_t *start_vertices,
- const cugraph_type_erased_device_array_view_t *starting_vertex_start_times,
- const cugraph_type_erased_device_array_view_t *starting_vertex_end_times,
- const cugraph_type_erased_device_array_view_t *starting_vertex_label_offsets,
- const cugraph_type_erased_device_array_view_t *vertex_type_offsets,
- const cugraph_type_erased_host_array_view_t *fan_out,
- int num_edge_types,
- const cugraph_sampling_options_t *sampling_options,
- bool_t do_expensive_check,
- cugraph_sample_result_t **result,
- cugraph_error_t **error
Heterogeneous Biased Temporal Neighborhood Sampling.
Returns a sample of the neighborhood around specified start vertices and fan_out. The neighborhood is sampled uniformly.
Temporal sampling considers the time associated with the edges. For increasing walks, if we start at vertex v1 and sample an edge that takes us to vertex v2 at time t1, when we sample in the next hop from vertex v2 we consider only edges that occur after time t1; for decreasing walks the restriction is to edges that occur before time t1.
Each seed may also supply an optional closed time window via
starting_vertex_start_timesandstarting_vertex_end_times. Eligible edge times must lie in that window for the entire walk. The window bounds additionally determine the hop-0 frontier: increasing walks begin at the start bound (or -inf if omitted), while decreasing walks begin at the end bound (or +inf if omitted). See the parameter docs below for details.Optionally, each start vertex can be associated with a label, allowing the caller to specify multiple batches of sampling requests in the same function call - which should improve GPU utilization.
If label is NULL then all start vertices will be considered part of the same batch and the return value will not have a label column.
For increasing walks (STRICTLY_INCREASING / MONOTONICALLY_INCREASING), the hop-0 frontier originates at this time (or is unbounded below if NULL), so this array is both the window’s lower bound and the initial frontier time.
For decreasing walks (STRICTLY_DECREASING / MONOTONICALLY_DECREASING), the hop-0 frontier originates at
starting_vertex_end_timesinstead (or is unbounded above if that is NULL), and this array remains only the window’s lower bound (a floor on eligible edge times). Providing onlystarting_vertex_start_timeson a decreasing walk therefore yields a window [start, +inf) whose frontier begins at +inf.- Parameters:
handle – [in] Handle for accessing resources
rng_state – [inout] State of the random number generator, updated with each call
graph – [in] Pointer to graph. NOTE: Graph might be modified if the storage needs to be transposed
temporal_property_name – [in] Name associated with the edge property in the graph that should be used as the time. Currently unused.
edge_biases – [in] Device array of edge biases to use for sampling. If NULL use the edge weight as the bias. If set to NULL, edges will be sampled uniformly.
start_vertices – [in] Device array of start vertices for the sampling
starting_vertex_start_times – [in] Optional device array of per-seed lower bounds of the time window. Edge times must be >= this value when present. Either or both of
starting_vertex_start_timesandstarting_vertex_end_timesmay be NULL (unbounded on that side). When both are provided, each start time must be <= the corresponding end time.starting_vertex_end_times – [in] Optional device array of per-seed upper bounds of the time window. Edge times must be <= this value when present. See
starting_vertex_start_timesfor optionality and the increasing/decreasing role reversal: for decreasing walks this array is both the window’s upper bound and the hop-0 frontier time; for increasing walks it is only the upper bound (a ceiling).starting_vertex_label_offsets – [in] Device array of the offsets for each label in the seed list. This parameter is only used with the retain_seeds option.
vertex_type_offsets – [in] Device array of the offsets for each vertex type in the graph.
fan_out – [in] Host array defining the fan out at each step in the sampling algorithm. We only support fan_out values of type INT32
num_edge_types – [in] Number of edge types where a value of 1 translates to homogeneous neighbor sample whereas a value greater than 1 translates to heterogeneous neighbor sample.
sampling_options – [in] Opaque pointer defining the sampling options.
do_expensive_check – [in] A flag to run expensive checks for input arguments (if set to true)
result – [out] Output from the uniform_neighbor_sample call
error – [out] Pointer to an error object storing details of any error. Will be populated if error code is not CUGRAPH_SUCCESS
- Returns:
error code
- cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_sources(
- const cugraph_sample_result_t *result
Get the source vertices from the sampling algorithm result.
- Deprecated:
This call should be replaced with cugraph_sample_result_get_majors
- Parameters:
result – [in] The result from a sampling algorithm
- Returns:
type erased array pointing to the source vertices in device memory
- cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_destinations(
- const cugraph_sample_result_t *result
Get the destination vertices from the sampling algorithm result.
- Deprecated:
This call should be replaced with cugraph_sample_result_get_minors
- Parameters:
result – [in] The result from a sampling algorithm
- Returns:
type erased array pointing to the destination vertices in device memory
- cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_offsets(
- const cugraph_sample_result_t *result
Get the result offsets from the sampling algorithm result.
- Deprecated:
This call should be replaced with cugraph_sample_get_get_label_hop_offsets
- Parameters:
result – [in] The result from a sampling algorithm
- Returns:
type erased array pointing to the result offsets
-
struct cugraph_random_walk_result_t#
- #include <sampling_algorithms.h>
Opaque random walk result type.
Public Members
-
int32_t align_#
-
int32_t align_#
-
struct cugraph_sample_result_t#
- #include <sampling_algorithms.h>
Opaque neighborhood sampling result type.
Public Members
-
int32_t align_#
-
int32_t align_#