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

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

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.

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_times and starting_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_times instead (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 only starting_vertex_start_times on 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_times and starting_vertex_end_times may 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_times for 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_times and starting_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_times instead (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 only starting_vertex_start_times on 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_times and starting_vertex_end_times may 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_times for 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_times and starting_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_times instead (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 only starting_vertex_start_times on 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_times and starting_vertex_end_times may 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_times for 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_times and starting_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_times instead (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 only starting_vertex_start_times on 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_times and starting_vertex_end_times may 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_times for 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_#
struct cugraph_sample_result_t#
#include <sampling_algorithms.h>

Opaque neighborhood sampling result type.

Public Members

int32_t align_#
struct cugraph_sampling_options_t#
#include <sampling_algorithms.h>

Opaque sampling options type.

Public Members

int32_t align_#
struct sampling_flags_t#
#include <sampling_algorithms.h>

Opaque sampling options type.

Public Members

int32_t align_#