Sampling

Contents

Sampling#

2025-05-20

11 min read time

Applies to Linux

Uniform Random Walks#

rocgraph_status rocgraph_uniform_random_walks(
const rocgraph_handle_t *handle,
rocgraph_graph_t *graph,
const rocgraph_type_erased_device_array_view_t *start_vertices,
size_t max_length,
rocgraph_random_walk_result_t **result,
rocgraph_error_t **error,
)#

Compute uniform random walks.

Parameters:

  • handle – [in] Handle for accessing resources

  • 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 – [in] 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 ROCGRAPH_SUCCESS

Returns:

error code

Biased Random Walks#

rocgraph_status rocgraph_biased_random_walks(
const rocgraph_handle_t *handle,
rocgraph_graph_t *graph,
const rocgraph_type_erased_device_array_view_t *start_vertices,
size_t max_length,
rocgraph_random_walk_result_t **result,
rocgraph_error_t **error,
)#

Compute biased random walks.

Parameters:

  • handle – [in] Handle for accessing resources

  • 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 – [in] 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 ROCGRAPH_SUCCESS

Returns:

error code

Random Walks via Node2Vec#

rocgraph_status rocgraph_node2vec_random_walks(
const rocgraph_handle_t *handle,
rocgraph_graph_t *graph,
const rocgraph_type_erased_device_array_view_t *start_vertices,
size_t max_length,
double p,
double q,
rocgraph_random_walk_result_t **result,
rocgraph_error_t **error,
)#

Compute random walks using the node2vec framework.

Parameters:

  • handle – [in] Handle for accessing resources

  • 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

  • p – [in] The return parameter

  • q – [in] The in/out parameter

  • result – [in] 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 ROCGRAPH_SUCCESS

Returns:

error code

Node2Vec#

rocgraph_status rocgraph_node2vec(
const rocgraph_handle_t *handle,
rocgraph_graph_t *graph,
const rocgraph_type_erased_device_array_view_t *sources,
size_t max_depth,
rocgraph_bool compress_result,
double p,
double q,
rocgraph_random_walk_result_t **result,
rocgraph_error_t **error,
)#

Compute random walks using the node2vec framework.

Deprecated:

This call should be replaced with rocgraph_node2vec_random_walks

Parameters:

  • handle – [in] Handle for accessing resources

  • graph – [in] Pointer to graph. NOTE: Graph might be modified if the storage needs to be transposed

  • sources – [in] Array of source vertices

  • max_depth – [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 – [in] 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 ROCGRAPH_SUCCESS

Returns:

error code

Uniform Neighbor Sampling#

rocgraph_status rocgraph_uniform_neighbor_sample(
const rocgraph_handle_t *handle,
rocgraph_graph_t *graph,
const rocgraph_type_erased_device_array_view_t *start_vertices,
const rocgraph_type_erased_device_array_view_t *start_vertex_labels,
const rocgraph_type_erased_device_array_view_t *label_list,
const rocgraph_type_erased_device_array_view_t *label_to_comm_rank,
const rocgraph_type_erased_device_array_view_t *label_offsets,
const rocgraph_type_erased_host_array_view_t *fan_out,
rocgraph_rng_state_t *rng_state,
const rocgraph_sampling_options_t *options,
rocgraph_bool do_expensive_check,
rocgraph_sample_result_t **result,
rocgraph_error_t **error,
)#

Uniform Neighborhood Sampling.

Returns a sample of the neighborhood around specified start vertices. 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

  • 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

  • start_vertex_labels – [in] Device array of start vertex labels for the sampling. The labels associated with each start vertex will be included in the output associated with results that were derived from that start vertex. We only support label of type INT32. If label is NULL, the return data will not be labeled.

  • label_list – [in] Device array of the labels included in start_vertex_labels. If label_to_comm_rank is not specified this parameter is ignored. If specified, label_list must be sorted in ascending order.

  • label_to_comm_rank – [in] Device array identifying which comm rank the output for a particular label should be shuffled in the output. If not specifed the data is not organized in output. If specified then the all data from label_list[i] will be shuffled to rank . This cannot be specified unless start_vertex_labels is also specified label_to_comm_rank[i]. If not specified then the output data will not be shuffled between ranks.

  • 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 fanout values of type INT32

  • rng_state – [inout] State of the random number generator, updated with each call

  • 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 – [in] 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 ROCGRAPH_SUCCESS

Returns:

error code

Sampling Support Functions#

size_t rocgraph_random_walk_result_get_max_path_length(
rocgraph_random_walk_result_t *result,
)#

Get the max path length from random walk result.

Parameters:

result – [in] The result from random walks

Returns:

maximum path length

rocgraph_type_erased_device_array_view_t *rocgraph_random_walk_result_get_paths(
rocgraph_random_walk_result_t *result,
)#

Get the matrix (row major order) of vertices in the paths.

Parameters:

result – [in] The result from a random walk algorithm

Returns:

type erased array pointing to the path matrix in device memory

rocgraph_type_erased_device_array_view_t *rocgraph_random_walk_result_get_weights(
rocgraph_random_walk_result_t *result,
)#

Get the matrix (row major order) of edge weights in the paths.

Parameters:

result – [in] The result from a random walk algorithm

Returns:

type erased array pointing to the path edge weights in device memory

rocgraph_type_erased_device_array_view_t *rocgraph_random_walk_result_get_path_sizes(
rocgraph_random_walk_result_t *result,
)#

If the random walk result is compressed, get the path sizes.

Deprecated:

This call will no longer be relevant once the new node2vec are called

Parameters:

result – [in] The result from a random walk algorithm

Returns:

type erased array pointing to the path sizes in device memory

void rocgraph_random_walk_result_free(
rocgraph_random_walk_result_t *result,
)#

Free random walks result.

Parameters:

result – [in] The result from random walks

rocgraph_type_erased_device_array_view_t *rocgraph_sample_result_get_majors(
const rocgraph_sample_result_t *result,
)#

Get the major vertices from the sampling algorithm result.

Parameters:

result – [in] The result from a sampling algorithm

Returns:

type erased array pointing to the major vertices in device memory

rocgraph_type_erased_device_array_view_t *rocgraph_sample_result_get_minors(
const rocgraph_sample_result_t *result,
)#

Get the minor vertices from the sampling algorithm result.

Parameters:

result – [in] The result from a sampling algorithm

Returns:

type erased array pointing to the minor vertices in device memory

rocgraph_type_erased_device_array_view_t *rocgraph_sample_result_get_major_offsets(
const rocgraph_sample_result_t *result,
)#

Get the major offsets from the sampling algorithm result.

Parameters:

result – [in] The result from a sampling algorithm

Returns:

type erased array pointing to the major offsets in device memory

rocgraph_type_erased_device_array_view_t *rocgraph_sample_result_get_start_labels(
const rocgraph_sample_result_t *result,
)#

Get the start labels from the sampling algorithm result.

Parameters:

result – [in] The result from a sampling algorithm

Returns:

type erased array pointing to the start labels

rocgraph_type_erased_device_array_view_t *rocgraph_sample_result_get_edge_id(
const rocgraph_sample_result_t *result,
)#

Get the edge_id from the sampling algorithm result.

Parameters:

result – [in] The result from a sampling algorithm

Returns:

type erased array pointing to the edge_id

rocgraph_type_erased_device_array_view_t *rocgraph_sample_result_get_edge_type(
const rocgraph_sample_result_t *result,
)#

Get the edge_type from the sampling algorithm result.

Parameters:

result – [in] The result from a sampling algorithm

Returns:

type erased array pointing to the edge_type

rocgraph_type_erased_device_array_view_t *rocgraph_sample_result_get_edge_weight(
const rocgraph_sample_result_t *result,
)#

Get the edge_weight from the sampling algorithm result.

Parameters:

result – [in] The result from a sampling algorithm

Returns:

type erased array pointing to the edge_weight

rocgraph_type_erased_device_array_view_t *rocgraph_sample_result_get_hop(
const rocgraph_sample_result_t *result,
)#

Get the hop from the sampling algorithm result.

Parameters:

result – [in] The result from a sampling algorithm

Returns:

type erased array pointing to the hop

rocgraph_type_erased_device_array_view_t *rocgraph_sample_result_get_label_hop_offsets(
const rocgraph_sample_result_t *result,
)#

Get the label-hop offsets from the sampling algorithm result.

Parameters:

result – [in] The result from a sampling algorithm

Returns:

type erased array pointing to the label-hop offsets

rocgraph_type_erased_device_array_view_t *rocgraph_sample_result_get_index(
const rocgraph_sample_result_t *result,
)#

Get the index from the sampling algorithm result.

Parameters:

result – [in] The result from a sampling algorithm

Returns:

type erased array pointing to the index

rocgraph_type_erased_device_array_view_t *rocgraph_sample_result_get_renumber_map(
const rocgraph_sample_result_t *result,
)#

Get the renumber map.

Parameters:

result – [in] The result from a sampling algorithm

Returns:

type erased array pointing to the renumber map

rocgraph_type_erased_device_array_view_t *rocgraph_sample_result_get_renumber_map_offsets(
const rocgraph_sample_result_t *result,
)#

Get the renumber map offsets.

Parameters:

result – [in] The result from a sampling algorithm

Returns:

type erased array pointing to the renumber map offsets

void rocgraph_sample_result_free(
rocgraph_sample_result_t *result,
)#

Free a sampling result.

Parameters:

result – [in] The result from a sampling algorithm

rocgraph_status rocgraph_test_sample_result_create(
const rocgraph_handle_t *handle,
const rocgraph_type_erased_device_array_view_t *srcs,
const rocgraph_type_erased_device_array_view_t *dsts,
const rocgraph_type_erased_device_array_view_t *edge_id,
const rocgraph_type_erased_device_array_view_t *edge_type,
const rocgraph_type_erased_device_array_view_t *wgt,
const rocgraph_type_erased_device_array_view_t *hop,
const rocgraph_type_erased_device_array_view_t *label,
rocgraph_sample_result_t **result,
rocgraph_error_t **error,
)#

Create a sampling result (testing API)

Parameters:

  • handle – [in] Handle for accessing resources

  • srcs – [in] Device array view to populate srcs

  • dsts – [in] Device array view to populate dsts

  • edge_id – [in] Device array view to populate edge_id (can be NULL)

  • edge_type – [in] Device array view to populate edge_type (can be NULL)

  • wgt – [in] Device array view to populate wgt (can be NULL)

  • hop – [in] Device array view to populate hop

  • label – [in] Device array view to populate label (can be NULL)

  • result – [out] Pointer to the location to store the rocgraph_sample_result_t*

  • error – [out] Pointer to an error object storing details of any error. Will be populated if error code is not ROCGRAPH_SUCCESS

Returns:

error code

rocgraph_status rocgraph_test_uniform_neighborhood_sample_result_create(
const rocgraph_handle_t *handle,
const rocgraph_type_erased_device_array_view_t *srcs,
const rocgraph_type_erased_device_array_view_t *dsts,
const rocgraph_type_erased_device_array_view_t *edge_id,
const rocgraph_type_erased_device_array_view_t *edge_type,
const rocgraph_type_erased_device_array_view_t *weight,
const rocgraph_type_erased_device_array_view_t *hop,
const rocgraph_type_erased_device_array_view_t *label,
rocgraph_sample_result_t **result,
rocgraph_error_t **error,
)#

Create a sampling result (testing API)

Parameters:

  • handle – [in] Handle for accessing resources

  • srcs – [in] Device array view to populate srcs

  • dsts – [in] Device array view to populate dsts

  • edge_id – [in] Device array view to populate edge_id

  • edge_type – [in] Device array view to populate edge_type

  • weight – [in] Device array view to populate weight

  • hop – [in] Device array view to populate hop

  • label – [in] Device array view to populate label

  • result – [out] Pointer to the location to store the rocgraph_sample_result_t*

  • error – [out] Pointer to an error object storing details of any error. Will be populated if error code is not ROCGRAPH_SUCCESS

Returns:

error code

rocgraph_status rocgraph_sampling_options_create(
rocgraph_sampling_options_t **options,
rocgraph_error_t **error,
)#

Create sampling options object.

All sampling options set to FALSE

Parameters:

  • options – [out] Opaque pointer to the sampling options

  • error – [out] Pointer to an error object storing details of any error. Will be populated if error code is not ROCGRAPH_SUCCESS

void rocgraph_sampling_set_retain_seeds(
rocgraph_sampling_options_t *options,
rocgraph_bool value,
)#

Set flag to retain seeds (original sources)

Parameters:

  • options – - opaque pointer to the sampling options

  • value – - Boolean value to assign to the option

void rocgraph_sampling_set_renumber_results(
rocgraph_sampling_options_t *options,
rocgraph_bool value,
)#

Set flag to renumber results.

Parameters:

  • options – - opaque pointer to the sampling options

  • value – - Boolean value to assign to the option

void rocgraph_sampling_set_compress_per_hop(
rocgraph_sampling_options_t *options,
rocgraph_bool value,
)#

Set whether to compress per-hop (True) or globally (False)

Parameters:

  • options – - opaque pointer to the sampling options

  • value – - Boolean value to assign to the option

void rocgraph_sampling_set_with_replacement(
rocgraph_sampling_options_t *options,
rocgraph_bool value,
)#

Set flag to sample with_replacement.

Parameters:

  • options – - opaque pointer to the sampling options

  • value – - Boolean value to assign to the option

void rocgraph_sampling_set_return_hops(
rocgraph_sampling_options_t *options,
rocgraph_bool value,
)#

Set flag to sample return_hops.

Parameters:

  • options – - opaque pointer to the sampling options

  • value – - Boolean value to assign to the option

void rocgraph_sampling_set_compression_type(
rocgraph_sampling_options_t *options,
rocgraph_compression_type value,
)#

Set compression type.

Parameters:

  • options – - opaque pointer to the sampling options

  • value – - Enum defining the compresion type

void rocgraph_sampling_set_prior_sources_behavior(
rocgraph_sampling_options_t *options,
rocgraph_prior_sources_behavior value,
)#

Set prior sources behavior.

Parameters:

  • options – - opaque pointer to the sampling options

  • value – - Enum defining prior sources behavior

void rocgraph_sampling_set_dedupe_sources(
rocgraph_sampling_options_t *options,
rocgraph_bool value,
)#

Set flag to sample dedupe_sources prior to sampling.

Parameters:

  • options – - opaque pointer to the sampling options

  • value – - Boolean value to assign to the option

void rocgraph_sampling_options_free(
rocgraph_sampling_options_t *options,
)#

Free sampling options object.

Parameters:

options – [in] Opaque pointer to sampling object

rocgraph_status rocgraph_select_random_vertices(
const rocgraph_handle_t *handle,
const rocgraph_graph_t *graph,
rocgraph_rng_state_t *rng_state,
size_t num_vertices,
rocgraph_type_erased_device_array_t **vertices,
rocgraph_error_t **error,
)#

Select random vertices from the graph.

Parameters:

  • handle – [in] Handle for accessing resources

  • graph – [in] Pointer to graph

  • rng_state – [inout] State of the random number generator, updated with each call

  • num_vertices – [in] Number of vertices to sample

  • vertices – [out] Device array view to populate label

  • error – [out] Pointer to an error object storing details of any error. Will be populated if error code is not ROCGRAPH_SUCCESS

Returns:

error code

struct rocgraph_random_walk_result_t#
#include <rocgraph_random_walk_result_t.h>

Opaque random walk result type.

Public Members

int32_t align_#

alignment variable

struct rocgraph_sample_result_t#
#include <rocgraph_sample_result_t.h>

Opaque neighborhood sampling result type.

struct rocgraph_sampling_options_t#
#include <rocgraph_sampling_options_t.h>

Opaque sampling options type.

Public Members

int32_t align_#

alignment variable

Contents