Sampling#

Uniform Random Walks#

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

Biased Random Walks#

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

Random Walks via Node2Vec#

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

Node2Vec#

Warning

doxygenfunction: Cannot find function “cugraph_node2vec” in doxygen xml output for project “libcugraph” from directory: /tmp/tmp.J624r0ppHL

Uniform Neighbor Sampling#

Warning

doxygenfunction: Cannot find function “cugraph_uniform_neighbor_sample” in doxygen xml output for project “libcugraph” from directory: /tmp/tmp.J624r0ppHL

Sampling Support Functions#

cugraph_type_erased_device_array_view_t *cugraph_lookup_result_get_srcs(
const cugraph_lookup_result_t *result
)#

Get the edge sources from the lookup result.

Parameters:

result – [in] The result from src-dst lookup using edge ids and type(s)

Returns:

type erased array pointing to the edge sources

cugraph_type_erased_device_array_view_t *cugraph_lookup_result_get_dsts(
const cugraph_lookup_result_t *result
)#

Get the edge destinations from the lookup result.

Parameters:

result – [in] The result from src-dst lookup using edge ids and type(s)

Returns:

type erased array pointing to the edge destinations

void cugraph_lookup_result_free(cugraph_lookup_result_t *result)#

Free a src-dst lookup result.

Parameters:

result – [in] The result from src-dst lookup using edge ids and type(s)

void cugraph_lookup_container_free(
cugraph_lookup_container_t *container
)#

Free a sampling lookup map.

Parameters:

container – [in] The sampling lookup map (a.k.a. container).

size_t cugraph_random_walk_result_get_max_path_length(
cugraph_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

cugraph_type_erased_device_array_view_t *cugraph_random_walk_result_get_paths(
cugraph_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

cugraph_type_erased_device_array_view_t *cugraph_random_walk_result_get_weights(
cugraph_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

cugraph_type_erased_device_array_view_t *cugraph_random_walk_result_get_path_sizes(
cugraph_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 cugraph_random_walk_result_free(
cugraph_random_walk_result_t *result
)#

Free random walks result.

Parameters:

result – [in] The result from random walks

cugraph_error_code_t cugraph_sampling_options_create(
cugraph_sampling_options_t **options,
cugraph_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 CUGRAPH_SUCCESS

void cugraph_sampling_set_retain_seeds(
cugraph_sampling_options_t *options,
bool_t 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 cugraph_sampling_set_renumber_results(
cugraph_sampling_options_t *options,
bool_t value
)#

Set flag to renumber results.

Parameters:

  • options – - opaque pointer to the sampling options

  • value – - Boolean value to assign to the option

void cugraph_sampling_set_compress_per_hop(
cugraph_sampling_options_t *options,
bool_t 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 cugraph_sampling_set_with_replacement(
cugraph_sampling_options_t *options,
bool_t value
)#

Set flag to sample with_replacement.

Parameters:

  • options – - opaque pointer to the sampling options

  • value – - Boolean value to assign to the option

void cugraph_sampling_set_return_hops(
cugraph_sampling_options_t *options,
bool_t value
)#

Set flag to sample return_hops.

Parameters:

  • options – - opaque pointer to the sampling options

  • value – - Boolean value to assign to the option

void cugraph_sampling_set_compression_type(
cugraph_sampling_options_t *options,
cugraph_compression_type_t value
)#

Set compression type.

Parameters:

  • options – - opaque pointer to the sampling options

  • value – - Enum defining the compresion type

void cugraph_sampling_set_prior_sources_behavior(
cugraph_sampling_options_t *options,
cugraph_prior_sources_behavior_t value
)#

Set prior sources behavior.

Parameters:

  • options – - opaque pointer to the sampling options

  • value – - Enum defining prior sources behavior

void cugraph_sampling_set_dedupe_sources(
cugraph_sampling_options_t *options,
bool_t 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 cugraph_sampling_set_temporal_sampling_comparison(
cugraph_sampling_options_t *options,
cugraph_temporal_sampling_comparison_t comparison
)#

Set temporal sampling to use associated comparision.

Parameters:

  • options – - opaque pointer to the sampling options

  • comparison – - Comparison value to assign to the option

void cugraph_sampling_set_disjoint_sampling(
cugraph_sampling_options_t *options,
bool_t value
)#

Set flag to perform disjoint sampling.

Note: This flag is not supported in the current implementation.

Parameters:

  • options – - opaque pointer to the sampling options

  • value – - Boolean value to assign to the option

void cugraph_sampling_options_free(
cugraph_sampling_options_t *options
)#

Free sampling options object.

Parameters:

options – [in] Opaque pointer to sampling object

cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_majors(
const cugraph_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

cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_minors(
const cugraph_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

cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_major_offsets(
const cugraph_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

cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_start_labels(
const cugraph_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

cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_edge_id(
const cugraph_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

cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_edge_type(
const cugraph_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

cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_edge_weight(
const cugraph_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

cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_edge_start_time(
const cugraph_sample_result_t *result
)#

Get the edge_start_time from the sampling algorithm result.

Parameters:

result – [in] The result from a sampling algorithm

Returns:

type erased array pointing to the edge_start_time

cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_edge_end_time(
const cugraph_sample_result_t *result
)#

Get the edge_end_time from the sampling algorithm result.

Parameters:

result – [in] The result from a sampling algorithm

Returns:

type erased array pointing to the edge_end_time

cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_hop(
const cugraph_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

cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_label_hop_offsets(
const cugraph_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

cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_label_type_hop_offsets(
const cugraph_sample_result_t *result
)#

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

Parameters:

result – [in] The result from a sampling algorithm

Returns:

type erased array pointing to the label-type-hop offsets

cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_index(
const cugraph_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

cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_renumber_map(
const cugraph_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

cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_renumber_map_offsets(
const cugraph_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

cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_edge_renumber_map(
const cugraph_sample_result_t *result
)#

Get the edge renumber map.

Parameters:

result – [in] The result from a sampling algorithm

Returns:

type erased array pointing to the renumber map

cugraph_type_erased_device_array_view_t *cugraph_sample_result_get_edge_renumber_map_offsets(
const cugraph_sample_result_t *result
)#

Get the edge renumber map offets.

Parameters:

result – [in] The result from a sampling algorithm

Returns:

type erased array pointing to the renumber map

void cugraph_sample_result_free(cugraph_sample_result_t *result)#

Free a sampling result.

Parameters:

result – [in] The result from a sampling algorithm

cugraph_error_code_t cugraph_test_sample_result_create(
const cugraph_resource_handle_t *handle,
const cugraph_type_erased_device_array_view_t *srcs,
const cugraph_type_erased_device_array_view_t *dsts,
const cugraph_type_erased_device_array_view_t *edge_id,
const cugraph_type_erased_device_array_view_t *edge_type,
const cugraph_type_erased_device_array_view_t *wgt,
const cugraph_type_erased_device_array_view_t *hop,
const cugraph_type_erased_device_array_view_t *label,
cugraph_sample_result_t **result,
cugraph_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 cugraph_sample_result_t*

  • 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_test_uniform_neighborhood_sample_result_create(
const cugraph_resource_handle_t *handle,
const cugraph_type_erased_device_array_view_t *srcs,
const cugraph_type_erased_device_array_view_t *dsts,
const cugraph_type_erased_device_array_view_t *edge_id,
const cugraph_type_erased_device_array_view_t *edge_type,
const cugraph_type_erased_device_array_view_t *weight,
const cugraph_type_erased_device_array_view_t *hop,
const cugraph_type_erased_device_array_view_t *label,
cugraph_sample_result_t **result,
cugraph_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 cugraph_sample_result_t*

  • 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_select_random_vertices(
const cugraph_resource_handle_t *handle,
const cugraph_graph_t *graph,
cugraph_rng_state_t *rng_state,
size_t num_vertices,
cugraph_type_erased_device_array_t **vertices,
cugraph_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 CUGRAPH_SUCCESS

Returns:

error code

cugraph_error_code_t cugraph_negative_sampling(
const cugraph_resource_handle_t *handle,
cugraph_rng_state_t *rng_state,
cugraph_graph_t *graph,
const cugraph_type_erased_device_array_view_t *vertices,
const cugraph_type_erased_device_array_view_t *src_biases,
const cugraph_type_erased_device_array_view_t *dst_biases,
size_t num_samples,
bool_t remove_duplicates,
bool_t remove_existing_edges,
bool_t exact_number_of_samples,
bool_t do_expensive_check,
cugraph_coo_t **result,
cugraph_error_t **error
)#

Perform negative sampling.

Negative sampling generates a COO structure defining edges according to the specified parameters

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

  • vertices – [in] Vertex ids for the source biases. If src_bias and dst_bias are not specified this is ignored. If vertices is specified then vertices[i] is the vertex id of src_biases[i] and dst_biases[i]. If vertices is not specified then i is the vertex id if src_biases[i] and dst_biases[i]

  • src_biases – [in] Bias for selecting source vertices. If NULL, do uniform sampling, if provided probability of vertex i will be src_bias[i] / (sum of all source biases)

  • dst_biases – [in] Bias for selecting destination vertices. If NULL, do uniform sampling, if provided probability of vertex i will be dst_bias[i] / (sum of all destination biases)

  • num_samples – [in] Number of negative samples to generate

  • remove_duplicates – [in] If true, remove duplicates from sampled edges

  • remove_existing_edges – [in] If true, remove sampled edges that actually exist in the graph

  • exact_number_of_samples – [in] If true, result should contain exactly num_samples. If false the code will generate num_samples and then do any filtering as specified

  • do_expensive_check – [in] A flag to run expensive checks for input arguments (if set to true)

  • result – [out] Opaque pointer to generated coo list

  • 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

On this page