diff --git a/cpp/include/cugraph/algorithms.hpp b/cpp/include/cugraph/algorithms.hpp index 60f4d21822..5a0a835c61 100644 --- a/cpp/include/cugraph/algorithms.hpp +++ b/cpp/include/cugraph/algorithms.hpp @@ -1,5 +1,5 @@ /* - * Copyright (c) 2020-2024, NVIDIA CORPORATION. + * Copyright (c) 2020-2025, NVIDIA CORPORATION. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -36,9 +36,46 @@ * @{ */ +/** @defgroup centrality_cpp C++ centrality algorithms + */ + +/** @defgroup community_cpp C++ community Algorithms + */ + +/** @defgroup sampling_cpp C++ sampling algorithms + */ + +/** @defgroup similarity_cpp C++ similarity algorithms + */ + +/** @defgroup traversal_cpp C++ traversal algorithms + */ + +/** @defgroup labeling_cpp C++ labeling algorithms + */ + +/** @defgroup linear_cpp C++ linear assignment algorithms + */ + +/** @defgroup link_analysis_cpp C++ link Analysis algorithms + */ + +/** @defgroup layout_cpp C++ layout algorithms + */ + +/** @defgroup component_cpp C++ component algorithms + */ + +/** @defgroup tree_cpp C++ tree algorithms + */ + +/** @defgroup utility_cpp C++ utility algorithms + */ + namespace cugraph { /** + * @ingroup similarity_cpp * @brief Compute jaccard similarity coefficient for all vertices * * Computes the Jaccard similarity coefficient for every pair of vertices in the graph @@ -60,6 +97,7 @@ template void jaccard(legacy::GraphCSRView const& graph, WT const* weights, WT* result); /** + * @ingroup similarity_cpp * @brief Compute jaccard similarity coefficient for selected vertex pairs * * Computes the Jaccard similarity coefficient for each pair of specified vertices. @@ -89,6 +127,7 @@ void jaccard_list(legacy::GraphCSRView const& graph, WT* result); /** +.* @ingroup similarity_cpp * @brief Compute overlap coefficient for all vertices in the graph * * Computes the Overlap Coefficient for every pair of vertices in the graph which are @@ -110,6 +149,7 @@ template void overlap(legacy::GraphCSRView const& graph, WT const* weights, WT* result); /** + * @ingroup similarity_cpp * @brief Compute overlap coefficient for select pairs of vertices * * Computes the overlap coefficient for each pair of specified vertices. @@ -139,7 +179,7 @@ void overlap_list(legacy::GraphCSRView const& graph, WT* result); /** - * + * @ingroup layout_cpp * @brief ForceAtlas2 is a continuous graph layout algorithm * for handy network visualization. * @@ -212,6 +252,7 @@ void force_atlas2(raft::handle_t const& handle, internals::GraphBasedDimRedCallback* callback = nullptr); /** + * @ingroup centrality_cpp * @brief Compute betweenness centrality for a graph * * Betweenness centrality for a vertex is the sum of the fraction of @@ -259,6 +300,7 @@ void betweenness_centrality(const raft::handle_t& handle, vertex_t const* vertices = nullptr); /** + * @ingroup centrality_cpp * @brief Compute edge betweenness centrality for a graph * * Betweenness centrality of an edge is the sum of the fraction of all-pairs shortest paths that @@ -302,6 +344,7 @@ void edge_betweenness_centrality(const raft::handle_t& handle, vertex_t const* vertices = nullptr); /** + * @ingroup centrality_cpp * @brief Compute betweenness centrality for a graph * * Betweenness centrality for a vertex is the sum of the fraction of @@ -346,6 +389,7 @@ rmm::device_uvector betweenness_centrality( bool const do_expensive_check = false); /** + * @ingroup centrality_cpp * @brief Compute edge betweenness centrality for a graph * * Betweenness centrality of an edge is the sum of the fraction of all-pairs shortest paths that @@ -392,6 +436,7 @@ enum class cugraph_cc_t { }; /** + * @ingroup components_cpp * @brief Compute connected components. * * The weak version (for undirected graphs, only) was imported from cuML. @@ -426,6 +471,7 @@ void connected_components(legacy::GraphCSRView const& graph, VT* labels); /** + * @ingroup linear_cpp * @brief Compute Hungarian algorithm on a weighted bipartite graph * * The Hungarian algorithm computes an assigment of "jobs" to "workers". This function accepts @@ -458,6 +504,7 @@ weight_t hungarian(raft::handle_t const& handle, vertex_t* assignments); /** + * @ingroup linear_cpp * @brief Compute Hungarian algorithm on a weighted bipartite graph * * The Hungarian algorithm computes an assigment of "jobs" to "workers". This function accepts @@ -492,6 +539,7 @@ weight_t hungarian(raft::handle_t const& handle, weight_t epsilon); /** + * @ingroup community_cpp * @brief Louvain implementation * * Compute a clustering of the graph by maximizing modularity @@ -541,6 +589,7 @@ std::pair louvain( weight_t resolution = weight_t{1}); /** + * @ingroup community_cpp * @brief Louvain implementation, returning dendrogram * * Compute a clustering of the graph by maximizing modularity @@ -587,6 +636,7 @@ std::pair>, weight_t> louvain( weight_t resolution = weight_t{1}); /** + * @ingroup community_cpp * @brief Flatten a Dendrogram at a particular level * * A Dendrogram represents a hierarchical clustering/partitioning of @@ -611,6 +661,7 @@ void flatten_dendrogram(raft::handle_t const& handle, typename graph_view_t::vertex_type* clustering); /** + * @ingroup community_cpp * @brief Leiden implementation * * Compute a clustering of the graph by maximizing modularity using the Leiden improvements @@ -663,6 +714,7 @@ std::pair>, weight_t> leiden( weight_t theta = weight_t{1}); /** +.* @ingroup community_cpp * @brief Leiden implementation * * Compute a clustering of the graph by maximizing modularity using the Leiden improvements @@ -716,6 +768,7 @@ std::pair leiden( weight_t theta = weight_t{1}); /** +.* @ingroup community_cpp * @brief Computes the ecg clustering of the given graph. * * ECG runs truncated Louvain on an ensemble of permutations of the input graph, @@ -765,6 +818,7 @@ std::tuple, size_t, weight_t> ecg( weight_t resolution = weight_t{1}); /** + * @ingroup tree_cpp * @brief Generate edges in a minimum spanning forest of an undirected weighted graph. * * A minimum spanning tree is a subgraph of the graph (a tree) with the minimum sum of edge weights. @@ -792,6 +846,7 @@ std::unique_ptr> minimum_spanning_t namespace subgraph { /** +.* @ingroup utility_cpp * @brief Extract subgraph by vertices * * This function will identify all edges that connect pairs of vertices @@ -817,6 +872,7 @@ std::unique_ptr> extract_subgraph_vertex( } // namespace subgraph /** + * @ingroup community_cpp * @brief Wrapper function for Nvgraph balanced cut clustering * * @throws cugraph::logic_error when an error occurs. @@ -850,6 +906,7 @@ void balancedCutClustering(legacy::GraphCSRView const& graph, VT* clustering); /** + * @ingroup community_cpp * @brief Wrapper function for Nvgraph spectral modularity maximization algorithm * * @throws cugraph::logic_error when an error occurs. @@ -881,6 +938,7 @@ void spectralModularityMaximization(legacy::GraphCSRView const& grap VT* clustering); /** + * @ingroup community_cpp * @brief Wrapper function for Nvgraph clustering modularity metric * * @throws cugraph::logic_error when an error occurs. @@ -903,6 +961,7 @@ void analyzeClustering_modularity(legacy::GraphCSRView const& graph, WT* score); /** + * @ingroup community_cpp * @brief Wrapper function for Nvgraph clustering edge cut metric * * @throws cugraph::logic_error when an error occurs. @@ -925,6 +984,7 @@ void analyzeClustering_edge_cut(legacy::GraphCSRView const& graph, WT* score); /** + * @ingroup community_cpp * @brief Wrapper function for Nvgraph clustering ratio cut metric * * @throws cugraph::logic_error when an error occurs. @@ -950,6 +1010,7 @@ void analyzeClustering_ratio_cut(legacy::GraphCSRView const& graph, namespace dense { /** + * @ingroup linear_cpp * @brief Compute Hungarian algorithm on a weighted bipartite graph * * The Hungarian algorithm computes an assigment of "jobs" to "workers". This function accepts @@ -979,6 +1040,7 @@ weight_t hungarian(raft::handle_t const& handle, vertex_t* assignments); /** + * @ingroup linear_cpp * @brief Compute Hungarian algorithm on a weighted bipartite graph * * The Hungarian algorithm computes an assigment of "jobs" to "workers". This function accepts @@ -1013,6 +1075,7 @@ weight_t hungarian(raft::handle_t const& handle, } // namespace dense /** + * @ingroup traversal_cpp * @brief Run breadth-first search to find the distances (and predecessors) from the source * vertex. * @@ -1055,6 +1118,7 @@ void bfs(raft::handle_t const& handle, bool do_expensive_check = false); /** + * @ingroup traversal_cpp * @brief Extract paths from breadth-first search output * * This function extracts paths from the BFS output. BFS outputs distances @@ -1092,6 +1156,7 @@ std::tuple, vertex_t> extract_bfs_paths( size_t n_destinations); /** + * @ingroup traversal_cpp * @brief Run single-source shortest-path to compute the minimum distances (and predecessors) from * the source vertex. * @@ -1128,7 +1193,8 @@ void sssp(raft::handle_t const& handle, weight_t cutoff = std::numeric_limits::max(), bool do_expensive_check = false); -/* +/** +.* @ingroup traversal_cpp * @brief Compute the shortest distances from the given origins to all the given destinations. * * This algorithm is designed for large diameter graphs. For small diameter graphs, running the @@ -1168,6 +1234,7 @@ rmm::device_uvector od_shortest_distances( bool do_expensive_check = false); /** + * @ingroup link_analysis_cpp * @brief Compute PageRank scores. * * @deprecated This API will be deprecated to replaced by the new version below @@ -1240,6 +1307,7 @@ struct centrality_algorithm_metadata_t { }; /** +.* @ingroup link_analysis_cpp * @brief Compute PageRank scores. * * This function computes general (if @p personalization_vertices is `nullptr`) or personalized (if @@ -1297,6 +1365,7 @@ std::tuple, centrality_algorithm_metadata_t> pager bool do_expensive_check = false); /** +.* @ingroup centrality_cpp * @brief Compute Eigenvector Centrality scores. * * This function computes eigenvector centrality scores using the power method. @@ -1334,6 +1403,7 @@ rmm::device_uvector eigenvector_centrality( bool do_expensive_check = false); /** +.* @ingroup link_analysis_cpp * @brief Compute HITS scores. * * This function computes HITS scores for the vertices of a graph @@ -1373,6 +1443,7 @@ std::tuple hits(raft::handle_t const& handle, bool do_expensive_check); /** +.* @ingroup centrality_cpp * @brief Compute Katz Centrality scores. * * This function computes Katz Centrality scores. @@ -1425,6 +1496,7 @@ void katz_centrality(raft::handle_t const& handle, bool do_expensive_check = false); /** +.* @ingroup community_cpp * @brief returns induced EgoNet subgraph(s) of neighbors centered at nodes in source_vertex within * a given radius. * @@ -1460,6 +1532,7 @@ extract_ego(raft::handle_t const& handle, vertex_t radius); /** +.* @ingroup community_cpp * @brief returns induced EgoNet subgraph(s) of neighbors centered at nodes in source_vertex within * a given radius. * @@ -1493,6 +1566,7 @@ extract_ego(raft::handle_t const& handle, bool do_expensive_check = false); /** +.* @ingroup sampling_cpp * @brief returns random walks (RW) from starting sources, where each path is of given maximum * length. Uniform distribution is assumed for the random engine. * @@ -1537,6 +1611,7 @@ std:: std::unique_ptr sampling_strategy = nullptr); /** +.* @ingroup sampling_cpp * @brief returns uniform random walks from starting sources, where each path is of given * maximum length. * @@ -1582,6 +1657,7 @@ uniform_random_walks(raft::handle_t const& handle, size_t max_length); /** +.* @ingroup sampling_cpp * @brief returns biased random walks from starting sources, where each path is of given * maximum length. * @@ -1626,6 +1702,7 @@ biased_random_walks(raft::handle_t const& handle, size_t max_length); /** +.* @ingroup sampling_cpp * @brief returns biased random walks with node2vec biases from starting sources, * where each path is of given maximum length. * @@ -1675,6 +1752,7 @@ node2vec_random_walks(raft::handle_t const& handle, weight_t q); /** +.* @ingroup components_cpp * @brief Finds (weakly-connected-)component IDs of each vertices in the input graph. * * The input graph must be symmetric. Component IDs can be arbitrary integers (they can be @@ -1697,12 +1775,14 @@ void weakly_connected_components(raft::handle_t const& handle, bool do_expensive_check = false); /** +.* @ingroup core_cpp * @brief Identify whether the core number computation should be based off incoming edges, * outgoing edges or both. */ enum class k_core_degree_type_t { IN = 0, OUT = 1, INOUT = 2 }; /** +.* @ingroup core_cpp * @brief Compute core numbers of individual vertices from K-Core decomposition. * * The input graph should not have self-loops nor multi-edges. Currently, only undirected graphs are @@ -1734,6 +1814,7 @@ void core_number(raft::handle_t const& handle, bool do_expensive_check = false); /** +.* @ingroup core_cpp * @brief Extract K-Core of a graph * * @throws cugraph::logic_error when an error occurs. @@ -1766,7 +1847,8 @@ k_core(raft::handle_t const& handle, std::optional> core_numbers, bool do_expensive_check = false); -/* +/** + * @ingroup community_cpp * @brief Compute triangle counts. * * Compute triangle counts for the entire set of vertices (if @p vertices is std::nullopt) or the @@ -1792,7 +1874,8 @@ void triangle_count(raft::handle_t const& handle, raft::device_span counts, bool do_expensive_check = false); -/* +/** +.* @ingroup community_cpp * @brief Compute edge triangle counts. * * Compute edge triangle counts for the entire set of edges. @@ -1814,7 +1897,8 @@ edge_property_t, edge_t> edge_t graph_view_t const& graph_view, bool do_expensive_check = false); -/* +/** +.* @ingroup community_cpp * @brief Compute K-Truss. * * Extract the K-Truss subgraph of a graph @@ -1841,6 +1925,7 @@ k_truss(raft::handle_t const& handle, bool do_expensive_check = false); /** +.* @ingroup similarity_cpp * @brief Compute Jaccard similarity coefficient * * Similarity is computed for every pair of vertices specified. Note that @@ -1872,6 +1957,7 @@ rmm::device_uvector jaccard_coefficients( bool do_expensive_check = false); /** +.* @ingroup similarity_cpp * @brief Compute Cosine similarity coefficient * * Similarity is computed for every pair of vertices specified. Note that @@ -1903,6 +1989,7 @@ rmm::device_uvector cosine_similarity_coefficients( bool do_expensive_check = false); /** +.* @ingroup similarity_cpp * @brief Compute Sorensen similarity coefficient * * Similarity is computed for every pair of vertices specified. Note that @@ -1935,6 +2022,7 @@ rmm::device_uvector sorensen_coefficients( bool do_expensive_check = false); /** +.* @ingroup similarity_cpp * @brief Compute overlap similarity coefficient * * Similarity is computed for every pair of vertices specified. Note that @@ -1967,6 +2055,7 @@ rmm::device_uvector overlap_coefficients( bool do_expensive_check = false); /** +.* @ingroup similarity_cpp * @brief Compute Jaccard all pairs similarity coefficient * * Similarity is computed for all pairs of vertices. Note that in a sparse @@ -2023,6 +2112,7 @@ std:: bool do_expensive_check = false); /** +.* @ingroup similarity_cpp * @brief Compute Consine all pairs similarity coefficient * * Similarity is computed for all pairs of vertices. Note that in a sparse @@ -2079,6 +2169,7 @@ std:: bool do_expensive_check = false); /** +.* @ingroup similarity_cpp * @brief Compute Sorensen similarity coefficient * * Similarity is computed for all pairs of vertices. Note that in a sparse @@ -2134,6 +2225,7 @@ std:: bool do_expensive_check = false); /** +.* @ingroup similarity_cpp * @brief Compute overlap similarity coefficient * * Similarity is computed for all pairs of vertices. Note that in a sparse @@ -2189,6 +2281,7 @@ std:: bool do_expensive_check = false); /* +.* @ingroup utility_cpp * @brief Enumerate K-hop neighbors * * Note that the number of K-hop neighbors (and memory footprint) can grow very fast if there are @@ -2217,7 +2310,8 @@ std::tuple, rmm::device_uvector> k_hop_nbr size_t k, bool do_expensive_check = false); -/* +/** + * @ingroup tree_cpp * @brief Find a Maximal Independent Set * * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type. @@ -2235,7 +2329,8 @@ rmm::device_uvector maximal_independent_set( graph_view_t const& graph_view, raft::random::RngState& rng_state); -/* +/** + * @ingroup utility_cpp * @brief Find a Greedy Vertex Coloring * * A vertex coloring is an assignment of colors or labels to each vertex of a graph so that @@ -2262,7 +2357,8 @@ rmm::device_uvector vertex_coloring( graph_view_t const& graph_view, raft::random::RngState& rng_state); -/* +/** +.* @ingroup utility_cpp * @brief Approximate Weighted Matching * * A matching in an undirected graph G = (V, E) is a pairing of adjacent vertices