From d4e8e2d3fb502e6e4577deae34572e117028267a Mon Sep 17 00:00:00 2001 From: Chuck Hastings <45364586+ChuckHastings@users.noreply.github.com> Date: Tue, 5 Jul 2022 16:22:09 -0400 Subject: [PATCH] Doxygen improvements to improve documentation of C API (#2355) Some doxygen improvements: * Defined a C API module * Defined submodules for each C API algorithm header * Moved sampling functions into a separate header * Moved traversal functions into a separate header * Deleted a few old nvgraph doxygen things that were interfering with a clean definition of the cugraph namespace Authors: - Chuck Hastings (https://github.com/ChuckHastings) Approvers: - Brad Rees (https://github.com/BradReesWork) - AJ Schmidt (https://github.com/ajschmidt8) URL: https://github.com/rapidsai/cugraph/pull/2355 --- ci/release/update-version.sh | 2 +- cpp/doxygen/Doxyfile | 4 +- cpp/include/cugraph/algorithms.hpp | 8 + cpp/include/cugraph/graph.hpp | 8 + cpp/include/cugraph_c/algorithms.h | 389 +----------------- cpp/include/cugraph_c/centrality_algorithms.h | 9 + cpp/include/cugraph_c/community_algorithms.h | 9 + cpp/include/cugraph_c/labeling_algorithms.h | 9 + cpp/include/cugraph_c/sampling_algorithms.h | 239 +++++++++++ cpp/include/cugraph_c/traversal_algorithms.h | 212 ++++++++++ .../community/legacy/spectral_clustering.cu | 6 - cpp/src/link_prediction/jaccard.cu | 5 - cpp/src/link_prediction/overlap.cu | 7 +- cpp/src/traversal/two_hop_neighbors.cu | 5 - cpp/src/tree/mst.cu | 8 +- 15 files changed, 507 insertions(+), 413 deletions(-) create mode 100644 cpp/include/cugraph_c/sampling_algorithms.h create mode 100644 cpp/include/cugraph_c/traversal_algorithms.h diff --git a/ci/release/update-version.sh b/ci/release/update-version.sh index f701ba6cbc4..c2062a170bd 100755 --- a/ci/release/update-version.sh +++ b/ci/release/update-version.sh @@ -62,7 +62,7 @@ for FILE in conda/environments/*.yml; do done # Doxyfile update -sed_runner "s|\(TAGFILES.*librmm/\).*|\1${NEXT_SHORT_TAG}|" cpp/doxygen/Doxyfile +sed_runner "s|PROJECT_NUMBER[[:space:]]*=.*|PROJECT_NUMBER=${NEXT_SHORT_TAG}|" cpp/doxygen/Doxyfile # ucx-py version sed_runner "s/export UCX_PY_VERSION=.*/export UCX_PY_VERSION='${NEXT_UCX_PY_VERSION}'/g" ci/benchmark/build.sh diff --git a/cpp/doxygen/Doxyfile b/cpp/doxygen/Doxyfile index f0840cfe840..f25ec774a21 100644 --- a/cpp/doxygen/Doxyfile +++ b/cpp/doxygen/Doxyfile @@ -38,13 +38,13 @@ PROJECT_NAME = "libcugraph" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 0.14 +PROJECT_NUMBER = 22.08 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = +PROJECT_BRIEF = GPU accelerated graph analytics # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 diff --git a/cpp/include/cugraph/algorithms.hpp b/cpp/include/cugraph/algorithms.hpp index 013c4c56bd9..6664978a3a1 100644 --- a/cpp/include/cugraph/algorithms.hpp +++ b/cpp/include/cugraph/algorithms.hpp @@ -30,6 +30,10 @@ #include #include +/** @ingroup cpp_api + * @{ + */ + namespace cugraph { /** @@ -1572,3 +1576,7 @@ void triangle_count(raft::handle_t const& handle, bool do_expensive_check = false); } // namespace cugraph + +/** + * @} + */ diff --git a/cpp/include/cugraph/graph.hpp b/cpp/include/cugraph/graph.hpp index 808da435235..7ab539c0cb8 100644 --- a/cpp/include/cugraph/graph.hpp +++ b/cpp/include/cugraph/graph.hpp @@ -28,6 +28,10 @@ #include #include +/** @defgroup cpp_api cuGraph C++ API + * @{ + */ + namespace cugraph { template @@ -551,3 +555,7 @@ __host__ __device__ std::enable_if_t::value, bool> is } // namespace cugraph #include "eidecl_graph.hpp" + +/** + * @} + */ diff --git a/cpp/include/cugraph_c/algorithms.h b/cpp/include/cugraph_c/algorithms.h index fdac0fe83fa..5464e875559 100644 --- a/cpp/include/cugraph_c/algorithms.h +++ b/cpp/include/cugraph_c/algorithms.h @@ -20,389 +20,16 @@ #include #include -#ifdef __cplusplus -extern "C" { -#endif - -/** - * @brief Opaque paths result type - * - * Store the output of BFS or SSSP, computing predecessors and distances - * from a seed. - */ -typedef struct { - int32_t align_; -} cugraph_paths_result_t; - -/** - * @brief Get the vertex ids from the paths result - * - * @param [in] result The result from bfs or sssp - * @return type erased array of vertex ids - */ -cugraph_type_erased_device_array_view_t* cugraph_paths_result_get_vertices( - cugraph_paths_result_t* result); - -/** - * @brief Get the distances from the paths result - * - * @param [in] result The result from bfs or sssp - * @return type erased array of distances - */ -cugraph_type_erased_device_array_view_t* cugraph_paths_result_get_distances( - cugraph_paths_result_t* result); - -/** - * @brief Get the predecessors from the paths result - * - * @param [in] result The result from bfs or sssp - * @return type erased array of predecessors. Value will be NULL if - * compute_predecessors was FALSE in the call to bfs or sssp that - * produced this result. - */ -cugraph_type_erased_device_array_view_t* cugraph_paths_result_get_predecessors( - cugraph_paths_result_t* result); - -/** - * @brief Free paths result - * - * @param [in] result The result from bfs or sssp - */ -void cugraph_paths_result_free(cugraph_paths_result_t* result); - -/** - * @brief Perform a breadth first search from a set of seed vertices. - * - * This function computes the distances (minimum number of hops to reach the vertex) from the source - * vertex. If @p predecessors is not NULL, this function calculates the predecessor of each - * vertex (parent vertex in the breadth-first search tree) as well. - * - * @param [in] handle Handle for accessing resources - * @param [in] graph Pointer to graph - * FIXME: Make this just [in], copy it if I need to temporarily modify internally - * @param [in/out] sources Array of source vertices. NOTE: Array might be modified if - * renumbering is enabled for the graph - * @param [in] direction_optimizing If set to true, this algorithm switches between the push based - * breadth-first search and pull based breadth-first search depending on the size of the - * breadth-first search frontier (currently unsupported). This option is valid only for symmetric - * input graphs. - * @param depth_limit Sets the maximum number of breadth-first search iterations. Any vertices - * farther than @p depth_limit hops from @p source_vertex will be marked as unreachable. - * @param [in] compute_predecessors A flag to indicate whether to compute the predecessors in the - * result - * @param [in] do_expensive_check A flag to run expensive checks for input arguments (if set to - * `true`). - * @param [out] result Opaque pointer to paths results - * @param [out] error Pointer to an error object storing details of any error. Will - * be populated if error code is not CUGRAPH_SUCCESS - * @return error code - */ -cugraph_error_code_t cugraph_bfs( - const cugraph_resource_handle_t* handle, - cugraph_graph_t* graph, - // FIXME: Make this const, copy it if I need to temporarily modify internally - cugraph_type_erased_device_array_view_t* sources, - bool_t direction_optimizing, - size_t depth_limit, - bool_t compute_predecessors, - bool_t do_expensive_check, - cugraph_paths_result_t** result, - cugraph_error_t** error); - -/** - * @brief Perform single-source shortest-path to compute the minimum distances - * (and predecessors) from the source vertex. - * - * This function computes the distances (minimum edge weight sums) from the source - * vertex. If @p predecessors is not NULL, this function calculates the predecessor of each - * vertex (parent vertex in the breadth-first search tree) as well. - * - * @param [in] handle Handle for accessing resources - * @param [in] graph Pointer to graph - * @param [in] source Source vertex id - * @param [in] cutoff Maximum edge weight sum to consider - * @param [in] compute_predecessors A flag to indicate whether to compute the predecessors in the - * result - * @param [in] do_expensive_check A flag to run expensive checks for input arguments (if set to - * `true`). - * @param [out] result Opaque pointer to paths results - * @param [out] error Pointer to an error object storing details of any error. Will - * be populated if error code is not CUGRAPH_SUCCESS - * @return error code +/** @defgroup c_api cuGraph C API + * @{ */ -cugraph_error_code_t cugraph_sssp(const cugraph_resource_handle_t* handle, - cugraph_graph_t* graph, - size_t source, - double cutoff, - bool_t compute_predecessors, - bool_t do_expensive_check, - cugraph_paths_result_t** result, - cugraph_error_t** error); - -/** - * @brief Opaque extract_paths result type - */ -typedef struct { - int32_t align_; -} cugraph_extract_paths_result_t; - -/** - * @brief Extract BFS or SSSP paths from a cugraph_paths_result_t - * - * This function extracts paths from the BFS or SSSP output. BFS and SSSP output - * distances and predecessors. The path from a vertex v back to the original - * source vertex can be extracted by recursively looking up the predecessor - * vertex until you arrive back at the original source vertex. - * - * @param [in] handle Handle for accessing resources - * @param [in] graph Pointer to graph. NOTE: Graph might be modified if the storage - * needs to be transposed - * @param [in] sources Array of source vertices - * @param [in] result Output from the BFS call - * @param [in] destinations Array of destination vertices. - * @param [out] result Opaque pointer to extract_paths results - * @param [out] error Pointer to an error object storing details of any error. Will - * be populated if error code is not CUGRAPH_SUCCESS - * @return error code - */ -cugraph_error_code_t cugraph_extract_paths( - const cugraph_resource_handle_t* handle, - cugraph_graph_t* graph, - const cugraph_type_erased_device_array_view_t* sources, - const cugraph_paths_result_t* paths_result, - const cugraph_type_erased_device_array_view_t* destinations, - cugraph_extract_paths_result_t** result, - cugraph_error_t** error); - -/** - * @brief Get the max path length from extract_paths result - * - * @param [in] result The result from extract_paths - * @return maximum path length - */ -size_t cugraph_extract_paths_result_get_max_path_length(cugraph_extract_paths_result_t* result); - -/** - * @brief Get the matrix (row major order) of paths - * - * @param [in] result The result from extract_paths - * @return type erased array pointing to the matrix in device memory - */ -cugraph_type_erased_device_array_view_t* cugraph_extract_paths_result_get_paths( - cugraph_extract_paths_result_t* result); - -/** - * @brief Free extract_paths result - * - * @param [in] result The result from extract_paths - */ -void cugraph_extract_paths_result_free(cugraph_extract_paths_result_t* result); - -/** - * @brief Opaque random walk result type - */ -typedef struct { - int32_t align_; -} cugraph_random_walk_result_t; - -/** - * @brief Compute random walks using the node2vec framework. - * - * @param [in] handle Handle for accessing resources - * @param [in] graph Pointer to graph. NOTE: Graph might be modified if the storage - * needs to be transposed - * @param [in] sources Array of source vertices - * @param [in] max_depth Maximum length of the generated path - * @param [in] compress_result If true, return the paths as a compressed sparse row matrix, - * otherwise return as a dense matrix - * @param [in] p The return parameter - * @param [in] q The in/out parameter - * @param [in] result Output from the node2vec call - * @param [out] error Pointer to an error object storing details of any error. Will - * be populated if error code is not CUGRAPH_SUCCESS - * @return error code - */ -cugraph_error_code_t cugraph_node2vec(const cugraph_resource_handle_t* handle, - cugraph_graph_t* graph, - const cugraph_type_erased_device_array_view_t* sources, - size_t max_depth, - bool_t compress_result, - double p, - double q, - cugraph_random_walk_result_t** result, - cugraph_error_t** error); - -/** - * @brief Get the max path length from random walk result - * - * @param [in] result The result from random walks - * @return maximum path length - */ -size_t cugraph_random_walk_result_get_max_path_length(cugraph_random_walk_result_t* result); - -// FIXME: Should this be the same as extract_paths_result_t? The only -// difference at the moment is that RW results contain weights -// and extract_paths results don't. But that's probably wrong. -/** - * @brief Get the matrix (row major order) of vertices in the paths - * - * @param [in] result The result from a random walk algorithm - * @return type erased array pointing to the path matrix in device memory - */ -cugraph_type_erased_device_array_view_t* cugraph_random_walk_result_get_paths( - cugraph_random_walk_result_t* result); - -/** - * @brief Get the matrix (row major order) of edge weights in the paths - * - * @param [in] result The result from a random walk algorithm - * @return type erased array pointing to the path edge weights in device memory - */ -cugraph_type_erased_device_array_view_t* cugraph_random_walk_result_get_weights( - cugraph_random_walk_result_t* result); - -/** - * @brief If the random walk result is compressed, get the path sizes - * - * @param [in] result The result from a random walk algorithm - * @return type erased array pointing to the path sizes in device memory - */ -cugraph_type_erased_device_array_view_t* cugraph_random_walk_result_get_path_sizes( - cugraph_random_walk_result_t* result); - -/** - * @brief Free random walks result - * - * @param [in] result The result from random walks - */ -void cugraph_random_walk_result_free(cugraph_random_walk_result_t* result); - -/** - * @brief Opaque neighborhood sampling result type - */ -typedef struct { - int32_t align_; -} cugraph_sample_result_t; - -/** - * @brief Uniform Neighborhood Sampling - * - * @param [in] handle Handle for accessing resources - * @param [in] graph Pointer to graph. NOTE: Graph might be modified if the storage - * needs to be transposed - * @param [in] start Device array of start vertices for the sampling - * @param [in] start_label Device array of start labels. These labels will propagate to the - * results so that the result can be properly organized when the input needs to be sent back to - * different callers (different processes or different gpus). - * @param [in] fanout Host array defining the fan out at each step in the sampling algorithm - * @param [in] with_replacement - * Boolean value. If true selection of edges is done with - * replacement. If false selection is done without replacement. - * @param [in] do_expensive_check - * A flag to run expensive checks for input arguments (if set to true) - * @param [in] result Output from the uniform_neighbor_sample call - * @param [out] error Pointer to an error object storing details of any error. Will - * be populated if error code is not CUGRAPH_SUCCESS - * @return error code - */ -// FIXME: This older API will be phased out this release in favor of the experimental one below -cugraph_error_code_t cugraph_uniform_neighbor_sample( - const cugraph_resource_handle_t* handle, - cugraph_graph_t* graph, - const cugraph_type_erased_device_array_view_t* start, - const cugraph_type_erased_device_array_view_t* start_label, - const cugraph_type_erased_host_array_view_t* fan_out, - bool_t with_replacement, - bool_t do_expensive_check, - cugraph_sample_result_t** result, - cugraph_error_t** error); - -/** - * @brief Uniform Neighborhood Sampling - * - * @param [in] handle Handle for accessing resources - * @param [in] graph Pointer to graph. NOTE: Graph might be modified if the storage - * needs to be transposed - * @param [in] start Device array of start vertices for the sampling - * @param [in] fanout Host array defining the fan out at each step in the sampling algorithm - * @param [in] with_replacement - * Boolean value. If true selection of edges is done with - * replacement. If false selection is done without replacement. - * @param [in] do_expensive_check - * A flag to run expensive checks for input arguments (if set to true) - * @param [in] result Output from the uniform_neighbor_sample call - * @param [out] error Pointer to an error object storing details of any error. Will - * be populated if error code is not CUGRAPH_SUCCESS - * @return error code - */ -cugraph_error_code_t cugraph_experimental_uniform_neighbor_sample( - const cugraph_resource_handle_t* handle, - cugraph_graph_t* graph, - const cugraph_type_erased_device_array_view_t* start, - const cugraph_type_erased_host_array_view_t* fan_out, - bool_t with_replacement, - bool_t do_expensive_check, - cugraph_sample_result_t** result, - cugraph_error_t** error); - -/** - * @brief Get the source vertices from the sampling algorithm result - * - * @param [in] result The result from a sampling algorithm - * @return type erased array pointing to the source vertices in device memory - */ -cugraph_type_erased_device_array_view_t* cugraph_sample_result_get_sources( - const cugraph_sample_result_t* result); - -/** - * @brief Get the destination vertices from the sampling algorithm result - * - * @param [in] result The result from a sampling algorithm - * @return type erased array pointing to the destination vertices in device memory - */ -cugraph_type_erased_device_array_view_t* cugraph_sample_result_get_destinations( - const cugraph_sample_result_t* result); - -/** - * @brief Get the start labels from the sampling algorithm result - * - * @param [in] result The result from a sampling algorithm - * @return type erased array pointing to the start labels - */ -// FIXME: This will be obsolete when the older mechanism is removed -cugraph_type_erased_device_array_view_t* cugraph_sample_result_get_start_labels( - const cugraph_sample_result_t* result); - -/** - * @brief Get the index from the sampling algorithm result - * - * @param [in] result The result from a sampling algorithm - * @return type erased array pointing to the index - */ -cugraph_type_erased_device_array_view_t* cugraph_sample_result_get_index( - const cugraph_sample_result_t* result); - -/** - * @brief Get the transaction counts from the sampling algorithm result - * - * @param [in] result The result from a sampling algorithm - * @return type erased host array pointing to the counts - */ -// FIXME: This will be obsolete when the older mechanism is removed -cugraph_type_erased_host_array_view_t* cugraph_sample_result_get_counts( - const cugraph_sample_result_t* result); - -/** - * @brief Free a sampling result - * - * @param [in] result The result from a sampling algorithm - */ -void cugraph_sample_result_free(cugraph_sample_result_t* result); - -#ifdef __cplusplus -} -#endif #include #include #include +#include +#include + +/** + * @} + */ diff --git a/cpp/include/cugraph_c/centrality_algorithms.h b/cpp/include/cugraph_c/centrality_algorithms.h index d5885f4955c..ed21fcdce52 100644 --- a/cpp/include/cugraph_c/centrality_algorithms.h +++ b/cpp/include/cugraph_c/centrality_algorithms.h @@ -21,6 +21,11 @@ #include #include +/** @defgroup centrality Centrality algorithms + * @ingroup c_api + * @{ + */ + #ifdef __cplusplus extern "C" { #endif @@ -304,3 +309,7 @@ cugraph_error_code_t cugraph_hits( #ifdef __cplusplus } #endif + +/** + * @} + */ diff --git a/cpp/include/cugraph_c/community_algorithms.h b/cpp/include/cugraph_c/community_algorithms.h index cc2c76fc071..8c2b3c4817c 100644 --- a/cpp/include/cugraph_c/community_algorithms.h +++ b/cpp/include/cugraph_c/community_algorithms.h @@ -20,6 +20,11 @@ #include #include +/** @defgroup community Community algorithms + * @ingroup c_api + * @{ + */ + #ifdef __cplusplus extern "C" { #endif @@ -127,3 +132,7 @@ void cugraph_heirarchical_clustering_result_free(cugraph_heirarchical_clustering #ifdef __cplusplus } #endif + +/** + * @} + */ diff --git a/cpp/include/cugraph_c/labeling_algorithms.h b/cpp/include/cugraph_c/labeling_algorithms.h index 1ad835e2593..f3e634dafe6 100644 --- a/cpp/include/cugraph_c/labeling_algorithms.h +++ b/cpp/include/cugraph_c/labeling_algorithms.h @@ -24,6 +24,11 @@ extern "C" { #endif +/** @defgroup labeling Labeling algorithms + * @ingroup c_api + * @{ + */ + /** * @brief Opaque labeling result type */ @@ -99,3 +104,7 @@ cugraph_error_code_t cugraph_strongly_connected_components(const cugraph_resourc #ifdef __cplusplus } #endif + +/** + * @} + */ diff --git a/cpp/include/cugraph_c/sampling_algorithms.h b/cpp/include/cugraph_c/sampling_algorithms.h new file mode 100644 index 00000000000..16c1a9011d4 --- /dev/null +++ b/cpp/include/cugraph_c/sampling_algorithms.h @@ -0,0 +1,239 @@ +/* + * Copyright (c) 2021-2022, NVIDIA CORPORATION. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#pragma once + +#include +#include +#include + +/** @defgroup sampling Sampling algorithms + * @ingroup c_api + * @{ + */ + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Opaque random walk result type + */ +typedef struct { + int32_t align_; +} cugraph_random_walk_result_t; + +/** + * @brief Compute random walks using the node2vec framework. + * + * @param [in] handle Handle for accessing resources + * @param [in] graph Pointer to graph. NOTE: Graph might be modified if the storage + * needs to be transposed + * @param [in] sources Array of source vertices + * @param [in] max_depth Maximum length of the generated path + * @param [in] compress_result If true, return the paths as a compressed sparse row matrix, + * otherwise return as a dense matrix + * @param [in] p The return parameter + * @param [in] q The in/out parameter + * @param [in] result Output from the node2vec call + * @param [out] error Pointer to an error object storing details of any error. Will + * be populated if error code is not CUGRAPH_SUCCESS + * @return error code + */ +cugraph_error_code_t cugraph_node2vec(const cugraph_resource_handle_t* handle, + cugraph_graph_t* graph, + const cugraph_type_erased_device_array_view_t* sources, + size_t max_depth, + bool_t compress_result, + double p, + double q, + cugraph_random_walk_result_t** result, + cugraph_error_t** error); + +/** + * @brief Get the max path length from random walk result + * + * @param [in] result The result from random walks + * @return maximum path length + */ +size_t cugraph_random_walk_result_get_max_path_length(cugraph_random_walk_result_t* result); + +// FIXME: Should this be the same as extract_paths_result_t? The only +// difference at the moment is that RW results contain weights +// and extract_paths results don't. But that's probably wrong. +/** + * @brief Get the matrix (row major order) of vertices in the paths + * + * @param [in] result The result from a random walk algorithm + * @return type erased array pointing to the path matrix in device memory + */ +cugraph_type_erased_device_array_view_t* cugraph_random_walk_result_get_paths( + cugraph_random_walk_result_t* result); + +/** + * @brief Get the matrix (row major order) of edge weights in the paths + * + * @param [in] result The result from a random walk algorithm + * @return type erased array pointing to the path edge weights in device memory + */ +cugraph_type_erased_device_array_view_t* cugraph_random_walk_result_get_weights( + cugraph_random_walk_result_t* result); + +/** + * @brief If the random walk result is compressed, get the path sizes + * + * @param [in] result The result from a random walk algorithm + * @return type erased array pointing to the path sizes in device memory + */ +cugraph_type_erased_device_array_view_t* cugraph_random_walk_result_get_path_sizes( + cugraph_random_walk_result_t* result); + +/** + * @brief Free random walks result + * + * @param [in] result The result from random walks + */ +void cugraph_random_walk_result_free(cugraph_random_walk_result_t* result); + +/** + * @brief Opaque neighborhood sampling result type + */ +typedef struct { + int32_t align_; +} cugraph_sample_result_t; + +/** + * @brief Uniform Neighborhood Sampling + * + * @param [in] handle Handle for accessing resources + * @param [in] graph Pointer to graph. NOTE: Graph might be modified if the storage + * needs to be transposed + * @param [in] start Device array of start vertices for the sampling + * @param [in] start_label Device array of start labels. These labels will propagate to the + * results so that the result can be properly organized when the input needs to be sent back to + * different callers (different processes or different gpus). + * @param [in] fanout Host array defining the fan out at each step in the sampling algorithm + * @param [in] with_replacement + * Boolean value. If true selection of edges is done with + * replacement. If false selection is done without replacement. + * @param [in] do_expensive_check + * A flag to run expensive checks for input arguments (if set to true) + * @param [in] result Output from the uniform_neighbor_sample call + * @param [out] error Pointer to an error object storing details of any error. Will + * be populated if error code is not CUGRAPH_SUCCESS + * @return error code + */ +// FIXME: This older API will be phased out this release in favor of the experimental one below +cugraph_error_code_t cugraph_uniform_neighbor_sample( + const cugraph_resource_handle_t* handle, + cugraph_graph_t* graph, + const cugraph_type_erased_device_array_view_t* start, + const cugraph_type_erased_device_array_view_t* start_label, + const cugraph_type_erased_host_array_view_t* fan_out, + bool_t with_replacement, + bool_t do_expensive_check, + cugraph_sample_result_t** result, + cugraph_error_t** error); + +/** + * @brief Uniform Neighborhood Sampling + * + * @param [in] handle Handle for accessing resources + * @param [in] graph Pointer to graph. NOTE: Graph might be modified if the storage + * needs to be transposed + * @param [in] start Device array of start vertices for the sampling + * @param [in] fanout Host array defining the fan out at each step in the sampling algorithm + * @param [in] with_replacement + * Boolean value. If true selection of edges is done with + * replacement. If false selection is done without replacement. + * @param [in] do_expensive_check + * A flag to run expensive checks for input arguments (if set to true) + * @param [in] result Output from the uniform_neighbor_sample call + * @param [out] error Pointer to an error object storing details of any error. Will + * be populated if error code is not CUGRAPH_SUCCESS + * @return error code + */ +cugraph_error_code_t cugraph_experimental_uniform_neighbor_sample( + const cugraph_resource_handle_t* handle, + cugraph_graph_t* graph, + const cugraph_type_erased_device_array_view_t* start, + const cugraph_type_erased_host_array_view_t* fan_out, + bool_t with_replacement, + bool_t do_expensive_check, + cugraph_sample_result_t** result, + cugraph_error_t** error); + +/** + * @brief Get the source vertices from the sampling algorithm result + * + * @param [in] result The result from a sampling algorithm + * @return type erased array pointing to the source vertices in device memory + */ +cugraph_type_erased_device_array_view_t* cugraph_sample_result_get_sources( + const cugraph_sample_result_t* result); + +/** + * @brief Get the destination vertices from the sampling algorithm result + * + * @param [in] result The result from a sampling algorithm + * @return type erased array pointing to the destination vertices in device memory + */ +cugraph_type_erased_device_array_view_t* cugraph_sample_result_get_destinations( + const cugraph_sample_result_t* result); + +/** + * @brief Get the start labels from the sampling algorithm result + * + * @param [in] result The result from a sampling algorithm + * @return type erased array pointing to the start labels + */ +// FIXME: This will be obsolete when the older mechanism is removed +cugraph_type_erased_device_array_view_t* cugraph_sample_result_get_start_labels( + const cugraph_sample_result_t* result); + +/** + * @brief Get the index from the sampling algorithm result + * + * @param [in] result The result from a sampling algorithm + * @return type erased array pointing to the index + */ +cugraph_type_erased_device_array_view_t* cugraph_sample_result_get_index( + const cugraph_sample_result_t* result); + +/** + * @brief Get the transaction counts from the sampling algorithm result + * + * @param [in] result The result from a sampling algorithm + * @return type erased host array pointing to the counts + */ +// FIXME: This will be obsolete when the older mechanism is removed +cugraph_type_erased_host_array_view_t* cugraph_sample_result_get_counts( + const cugraph_sample_result_t* result); + +/** + * @brief Free a sampling result + * + * @param [in] result The result from a sampling algorithm + */ +void cugraph_sample_result_free(cugraph_sample_result_t* result); + +#ifdef __cplusplus +} +#endif + +/** + * @} + */ diff --git a/cpp/include/cugraph_c/traversal_algorithms.h b/cpp/include/cugraph_c/traversal_algorithms.h new file mode 100644 index 00000000000..8959366ac17 --- /dev/null +++ b/cpp/include/cugraph_c/traversal_algorithms.h @@ -0,0 +1,212 @@ +/* + * Copyright (c) 2021-2022, NVIDIA CORPORATION. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#pragma once + +#include +#include +#include + +/** @defgroup traversal Traversal Algorithms + * @ingroup c_api + * @{ + */ + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Opaque paths result type + * + * Store the output of BFS or SSSP, computing predecessors and distances + * from a seed. + */ +typedef struct { + int32_t align_; +} cugraph_paths_result_t; + +/** + * @brief Get the vertex ids from the paths result + * + * @param [in] result The result from bfs or sssp + * @return type erased array of vertex ids + */ +cugraph_type_erased_device_array_view_t* cugraph_paths_result_get_vertices( + cugraph_paths_result_t* result); + +/** + * @brief Get the distances from the paths result + * + * @param [in] result The result from bfs or sssp + * @return type erased array of distances + */ +cugraph_type_erased_device_array_view_t* cugraph_paths_result_get_distances( + cugraph_paths_result_t* result); + +/** + * @brief Get the predecessors from the paths result + * + * @param [in] result The result from bfs or sssp + * @return type erased array of predecessors. Value will be NULL if + * compute_predecessors was FALSE in the call to bfs or sssp that + * produced this result. + */ +cugraph_type_erased_device_array_view_t* cugraph_paths_result_get_predecessors( + cugraph_paths_result_t* result); + +/** + * @brief Free paths result + * + * @param [in] result The result from bfs or sssp + */ +void cugraph_paths_result_free(cugraph_paths_result_t* result); + +/** + * @brief Perform a breadth first search from a set of seed vertices. + * + * This function computes the distances (minimum number of hops to reach the vertex) from the source + * vertex. If @p predecessors is not NULL, this function calculates the predecessor of each + * vertex (parent vertex in the breadth-first search tree) as well. + * + * @param [in] handle Handle for accessing resources + * @param [in] graph Pointer to graph + * FIXME: Make this just [in], copy it if I need to temporarily modify internally + * @param [in/out] sources Array of source vertices. NOTE: Array might be modified if + * renumbering is enabled for the graph + * @param [in] direction_optimizing If set to true, this algorithm switches between the push based + * breadth-first search and pull based breadth-first search depending on the size of the + * breadth-first search frontier (currently unsupported). This option is valid only for symmetric + * input graphs. + * @param depth_limit Sets the maximum number of breadth-first search iterations. Any vertices + * farther than @p depth_limit hops from @p source_vertex will be marked as unreachable. + * @param [in] compute_predecessors A flag to indicate whether to compute the predecessors in the + * result + * @param [in] do_expensive_check A flag to run expensive checks for input arguments (if set to + * `true`). + * @param [out] result Opaque pointer to paths results + * @param [out] error Pointer to an error object storing details of any error. Will + * be populated if error code is not CUGRAPH_SUCCESS + * @return error code + */ +cugraph_error_code_t cugraph_bfs( + const cugraph_resource_handle_t* handle, + cugraph_graph_t* graph, + // FIXME: Make this const, copy it if I need to temporarily modify internally + cugraph_type_erased_device_array_view_t* sources, + bool_t direction_optimizing, + size_t depth_limit, + bool_t compute_predecessors, + bool_t do_expensive_check, + cugraph_paths_result_t** result, + cugraph_error_t** error); + +/** + * @brief Perform single-source shortest-path to compute the minimum distances + * (and predecessors) from the source vertex. + * + * This function computes the distances (minimum edge weight sums) from the source + * vertex. If @p predecessors is not NULL, this function calculates the predecessor of each + * vertex (parent vertex in the breadth-first search tree) as well. + * + * @param [in] handle Handle for accessing resources + * @param [in] graph Pointer to graph + * @param [in] source Source vertex id + * @param [in] cutoff Maximum edge weight sum to consider + * @param [in] compute_predecessors A flag to indicate whether to compute the predecessors in the + * result + * @param [in] do_expensive_check A flag to run expensive checks for input arguments (if set to + * `true`). + * @param [out] result Opaque pointer to paths results + * @param [out] error Pointer to an error object storing details of any error. Will + * be populated if error code is not CUGRAPH_SUCCESS + * @return error code + */ +cugraph_error_code_t cugraph_sssp(const cugraph_resource_handle_t* handle, + cugraph_graph_t* graph, + size_t source, + double cutoff, + bool_t compute_predecessors, + bool_t do_expensive_check, + cugraph_paths_result_t** result, + cugraph_error_t** error); + +/** + * @brief Opaque extract_paths result type + */ +typedef struct { + int32_t align_; +} cugraph_extract_paths_result_t; + +/** + * @brief Extract BFS or SSSP paths from a cugraph_paths_result_t + * + * This function extracts paths from the BFS or SSSP output. BFS and SSSP output + * distances and predecessors. The path from a vertex v back to the original + * source vertex can be extracted by recursively looking up the predecessor + * vertex until you arrive back at the original source vertex. + * + * @param [in] handle Handle for accessing resources + * @param [in] graph Pointer to graph. NOTE: Graph might be modified if the storage + * needs to be transposed + * @param [in] sources Array of source vertices + * @param [in] result Output from the BFS call + * @param [in] destinations Array of destination vertices. + * @param [out] result Opaque pointer to extract_paths results + * @param [out] error Pointer to an error object storing details of any error. Will + * be populated if error code is not CUGRAPH_SUCCESS + * @return error code + */ +cugraph_error_code_t cugraph_extract_paths( + const cugraph_resource_handle_t* handle, + cugraph_graph_t* graph, + const cugraph_type_erased_device_array_view_t* sources, + const cugraph_paths_result_t* paths_result, + const cugraph_type_erased_device_array_view_t* destinations, + cugraph_extract_paths_result_t** result, + cugraph_error_t** error); + +/** + * @brief Get the max path length from extract_paths result + * + * @param [in] result The result from extract_paths + * @return maximum path length + */ +size_t cugraph_extract_paths_result_get_max_path_length(cugraph_extract_paths_result_t* result); + +/** + * @brief Get the matrix (row major order) of paths + * + * @param [in] result The result from extract_paths + * @return type erased array pointing to the matrix in device memory + */ +cugraph_type_erased_device_array_view_t* cugraph_extract_paths_result_get_paths( + cugraph_extract_paths_result_t* result); + +/** + * @brief Free extract_paths result + * + * @param [in] result The result from extract_paths + */ +void cugraph_extract_paths_result_free(cugraph_extract_paths_result_t* result); + +#ifdef __cplusplus +} +#endif + +/** + * @} + */ diff --git a/cpp/src/community/legacy/spectral_clustering.cu b/cpp/src/community/legacy/spectral_clustering.cu index 85d331c258e..558b3f78b2c 100644 --- a/cpp/src/community/legacy/spectral_clustering.cu +++ b/cpp/src/community/legacy/spectral_clustering.cu @@ -14,12 +14,6 @@ * limitations under the License. */ -/** ---------------------------------------------------------------------------* - * @brief Wrapper functions for Spectral Clustering - * - * @file spectral_clustering.cu - * ---------------------------------------------------------------------------**/ - #include #include diff --git a/cpp/src/link_prediction/jaccard.cu b/cpp/src/link_prediction/jaccard.cu index d645ee8bb15..d0b240e3c77 100644 --- a/cpp/src/link_prediction/jaccard.cu +++ b/cpp/src/link_prediction/jaccard.cu @@ -13,11 +13,6 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -/** ---------------------------------------------------------------------------* - * @brief The cugraph Jaccard core functionality - * - * @file jaccard.cu - * ---------------------------------------------------------------------------**/ #include #include diff --git a/cpp/src/link_prediction/overlap.cu b/cpp/src/link_prediction/overlap.cu index 1cfae153719..67d7cd5e4c6 100644 --- a/cpp/src/link_prediction/overlap.cu +++ b/cpp/src/link_prediction/overlap.cu @@ -1,5 +1,5 @@ /* - * Copyright (c) 2019-2021, NVIDIA CORPORATION. + * Copyright (c) 2019-2022, NVIDIA CORPORATION. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -13,11 +13,6 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -/** ---------------------------------------------------------------------------* - * @brief The cugraph Jaccard core functionality - * - * @file jaccard.cu - * ---------------------------------------------------------------------------**/ #include #include diff --git a/cpp/src/traversal/two_hop_neighbors.cu b/cpp/src/traversal/two_hop_neighbors.cu index 7b56032bcb4..0e773d9997d 100644 --- a/cpp/src/traversal/two_hop_neighbors.cu +++ b/cpp/src/traversal/two_hop_neighbors.cu @@ -13,11 +13,6 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -/** ---------------------------------------------------------------------------* - * @brief Functions for computing the two hop neighbor pairs of a graph - * - * @file two_hop_neighbors.cu - * ---------------------------------------------------------------------------**/ #include "two_hop_neighbors.cuh" #include diff --git a/cpp/src/tree/mst.cu b/cpp/src/tree/mst.cu index 8a4f1c7dc1e..44c3c9ffe72 100644 --- a/cpp/src/tree/mst.cu +++ b/cpp/src/tree/mst.cu @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020-2021, NVIDIA CORPORATION. + * Copyright (c) 2020-2022, NVIDIA CORPORATION. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -14,12 +14,6 @@ * limitations under the License. */ -/** ---------------------------------------------------------------------------* - * @brief Wrapper functions for MST - * - * @file mst.cu - * ---------------------------------------------------------------------------**/ - #include #include #include