From 25f751c13170a9bce80d4f25f9dc5ab7101bdc8b Mon Sep 17 00:00:00 2001 From: acostadon Date: Thu, 9 Jan 2025 16:57:25 -0500 Subject: [PATCH 1/5] added groups so docs can clean up the API --- cpp/include/cugraph/algorithms.hpp | 111 ++++++++++++++++++++++++++--- 1 file changed, 103 insertions(+), 8 deletions(-) diff --git a/cpp/include/cugraph/algorithms.hpp b/cpp/include/cugraph/algorithms.hpp index 60f4d21822..0dcd4851f0 100644 --- a/cpp/include/cugraph/algorithms.hpp +++ b/cpp/include/cugraph/algorithms.hpp @@ -36,9 +36,45 @@ * @{ */ +/** @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 +96,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 +126,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 +148,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 +178,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 +251,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 +299,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 +343,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 +388,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 +435,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 +470,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 +503,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 +538,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 +588,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 +635,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 +660,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 +713,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 +767,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 +817,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 +845,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 +871,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 +905,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 +937,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 +960,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 +983,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 +1009,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 +1039,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 +1074,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 +1117,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 +1155,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 +1192,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 +1233,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 +1306,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 +1364,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 +1402,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 +1442,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 +1495,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 +1531,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 +1565,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 +1610,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 +1656,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 +1701,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 +1751,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 +1774,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 +1813,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 +1846,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 +1873,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 +1896,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 +1924,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 +1956,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 +1988,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 +2021,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 +2054,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 +2111,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 +2168,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 +2224,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 +2280,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 +2309,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 +2328,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 +2356,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 From 37aa65c79952816b6dc2458427d8ce236e9877af Mon Sep 17 00:00:00 2001 From: acostadon Date: Thu, 9 Jan 2025 17:19:55 -0500 Subject: [PATCH 2/5] fixed style error --- cpp/include/cugraph/algorithms.hpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cpp/include/cugraph/algorithms.hpp b/cpp/include/cugraph/algorithms.hpp index 0dcd4851f0..0f10e71815 100644 --- a/cpp/include/cugraph/algorithms.hpp +++ b/cpp/include/cugraph/algorithms.hpp @@ -69,7 +69,7 @@ /** @defgroup tree_cpp C++ tree algorithms */ - /** @defgroup utility_cpp C++ utility algorithms + /** @defgroup utility_cpp C++ utility algorithms */ namespace cugraph { From f06d87082400eafe167ed4e648e39980bb983cfb Mon Sep 17 00:00:00 2001 From: acostadon Date: Thu, 9 Jan 2025 19:32:09 -0500 Subject: [PATCH 3/5] fixed copyright --- cpp/include/cugraph/algorithms.hpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cpp/include/cugraph/algorithms.hpp b/cpp/include/cugraph/algorithms.hpp index 0f10e71815..9b5c9a2c8e 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. From 06f32f4b9f20902e7007c3fa763caccb3e1e712f Mon Sep 17 00:00:00 2001 From: acostadon Date: Fri, 10 Jan 2025 09:53:56 -0500 Subject: [PATCH 4/5] added blank line. not sure why style is failing --- cpp/include/cugraph/algorithms.hpp | 1 + 1 file changed, 1 insertion(+) diff --git a/cpp/include/cugraph/algorithms.hpp b/cpp/include/cugraph/algorithms.hpp index 9b5c9a2c8e..b974a6a665 100644 --- a/cpp/include/cugraph/algorithms.hpp +++ b/cpp/include/cugraph/algorithms.hpp @@ -71,6 +71,7 @@ /** @defgroup utility_cpp C++ utility algorithms */ + namespace cugraph { /** From 1bcefab87bf757920d8ac05d90e6593f40ad595e Mon Sep 17 00:00:00 2001 From: acostadon Date: Fri, 10 Jan 2025 10:03:21 -0500 Subject: [PATCH 5/5] change made by precommit --- cpp/include/cugraph/algorithms.hpp | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/cpp/include/cugraph/algorithms.hpp b/cpp/include/cugraph/algorithms.hpp index b974a6a665..5a0a835c61 100644 --- a/cpp/include/cugraph/algorithms.hpp +++ b/cpp/include/cugraph/algorithms.hpp @@ -42,34 +42,34 @@ /** @defgroup community_cpp C++ community Algorithms */ - /** @defgroup sampling_cpp C++ sampling algorithms +/** @defgroup sampling_cpp C++ sampling algorithms */ - /** @defgroup similarity_cpp C++ similarity algorithms +/** @defgroup similarity_cpp C++ similarity algorithms */ - /** @defgroup traversal_cpp C++ traversal algorithms +/** @defgroup traversal_cpp C++ traversal algorithms */ - /** @defgroup labeling_cpp C++ labeling algorithms +/** @defgroup labeling_cpp C++ labeling algorithms */ - /** @defgroup linear_cpp C++ linear assignment algorithms +/** @defgroup linear_cpp C++ linear assignment algorithms */ - /** @defgroup link_analysis_cpp C++ link Analysis algorithms +/** @defgroup link_analysis_cpp C++ link Analysis algorithms */ - /** @defgroup layout_cpp C++ layout algorithms +/** @defgroup layout_cpp C++ layout algorithms */ - /** @defgroup component_cpp C++ component algorithms +/** @defgroup component_cpp C++ component algorithms */ - /** @defgroup tree_cpp C++ tree algorithms +/** @defgroup tree_cpp C++ tree algorithms */ - /** @defgroup utility_cpp C++ utility algorithms +/** @defgroup utility_cpp C++ utility algorithms */ namespace cugraph {