MNMG ECG

cpp/CMakeLists.txt

@@ -1,5 +1,5 @@
 #=============================================================================
-# Copyright (c) 2018-2023, NVIDIA CORPORATION.
+# Copyright (c) 2018-2024, NVIDIA CORPORATION.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -187,6 +187,7 @@ endif()
 
 set(CUGRAPH_SOURCES
  src/detail/shuffle_vertices.cu
+ src/detail/permute_range.cu
  src/detail/shuffle_vertex_pairs.cu
  src/detail/collect_local_vertex_values.cu
  src/detail/groupby_and_count.cu
@@ -218,6 +219,8 @@ set(CUGRAPH_SOURCES
  src/community/louvain_mg.cu
  src/community/leiden_sg.cu
  src/community/leiden_mg.cu
+ src/community/ecg_sg.cu
+ src/community/ecg_mg.cu
  src/community/legacy/louvain.cu
  src/community/legacy/ktruss.cu
  src/community/legacy/ecg.cu

cpp/include/cugraph/algorithms.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020-2023, NVIDIA CORPORATION.
+ * Copyright (c) 2020-2024, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -541,30 +541,37 @@ weight_t hungarian(raft::handle_t const& handle,
  * community hierarchies in large networks, J Stat Mech P10008 (2008),
  * http://arxiv.org/abs/0803.0476
  *
- * @throws cugraph::logic_error when an error occurs.
- *
- * @tparam graph_view_t Type of graph
+ * @throws cugraph::logic_error when an error occurs.
  *
- * @param[in] handle Library handle (RAFT). If a communicator is set in the handle,
- * @param[in] graph input graph object
- * @param[out] clustering Pointer to device array where the clustering should be stored
- * @param[in] max_level (optional) maximum number of levels to run (default 100)
- * @param[in] threshold (optional) threshold for convergence at each level (default
- * 1e-7)
- * @param[in] resolution (optional) The value of the resolution parameter to use.
- * Called gamma in the modularity formula, this changes the size
- * of the communities. Higher resolutions lead to more smaller
- * communities, lower resolutions lead to fewer larger
- * communities. (default 1)
+ * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type.
+ * @tparam edge_t Type of edge identifiers. Needs to be an integral type.
+ * @tparam weight_t Type of edge weights. Needs to be a floating point type.
+ * @tparam multi_gpu Flag indicating whether template instantiation should target single-GPU (false)
  *
- * @return a pair containing:
- * 1) number of levels of the returned clustering
- * 2) modularity of the returned clustering
+ * @param[in] handle Library handle (RAFT). If a communicator is set in the handle,
+ * @param[in] rng_state The RngState instance holding pseudo-random number generator state.
+ * @param[in] graph_view Input graph view object.
+ * @param[in] edge_weight_view Optional view object holding edge weights for @p graph_view.
+ * If @pedge_weight_view.has_value() == false, edge weights
+ * are assumed to be 1.0.
+ @param[out] clustering Pointer to device array where the clustering should be stored
+ * @param[in] max_level (optional) maximum number of levels to run (default 100)
+ * @param[in] threshold (optional) threshold for convergence at each level (default 1e-7)
+ * @param[in] resolution (optional) The value of the resolution parameter to use.
+ * Called gamma in the modularity formula, this changes the size
+ * of the communities. Higher resolutions lead to more smaller
+ * communities, lower resolutions lead to fewer larger
+ * communities. (default 1)
+ *
+ * @return a pair containing:
+ * 1) number of levels of the returned clustering
+ * 2) modularity of the returned clustering
  *
  */
 template <typename vertex_t, typename edge_t, typename weight_t, bool multi_gpu>
 std::pair<size_t, weight_t> louvain(
  raft::handle_t const& handle,
+ std::optional<std::reference_wrapper<raft::random::RngState>> rng_state,
  graph_view_t<vertex_t, edge_t, false, multi_gpu> const& graph_view,
  std::optional<edge_property_view_t<edge_t, weight_t const*>> edge_weight_view,
  vertex_t* clustering,
@@ -593,25 +600,33 @@ std::pair<size_t, weight_t> louvain(
  *
  * @throws cugraph::logic_error when an error occurs.
  *
- * @tparam graph_view_t Type of graph
- *
- * @param[in] handle Library handle (RAFT)
- * @param[in] graph_view Input graph view object
- * @param[in] max_level (optional) maximum number of levels to run (default 100)
- * @param[in] resolution (optional) The value of the resolution parameter to use.
- * Called gamma in the modularity formula, this changes the size
- * of the communities. Higher resolutions lead to more smaller
- * communities, lower resolutions lead to fewer larger
- * communities. (default 1)
+ * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type.
+ * @tparam edge_t Type of edge identifiers. Needs to be an integral type.
+ * @tparam weight_t Type of edge weights. Needs to be a floating point type.
+ * @tparam multi_gpu Flag indicating whether template instantiation should target single-GPU (false)
  *
- * @return a pair containing:
- * 1) unique pointer to dendrogram
- * 2) modularity of the returned clustering
+ * @param[in] handle Library handle (RAFT). If a communicator is set in the handle,
+ * @param[in] rng_state The RngState instance holding pseudo-random number generator state.
+ * @param[in] graph_view Input graph view object.
+ * @param[in] edge_weight_view Optional view object holding edge weights for @p graph_view.
+ * If @pedge_weight_view.has_value() == false, edge weights
+ * are assumed to be 1.0.
+ * @param[in] max_level (optional) maximum number of levels to run (default 100)
+ * @param[in] threshold (optional) threshold for convergence at each level (default 1e-7)
+ * @param[in] resolution (optional) The value of the resolution parameter to use.
+ * Called gamma in the modularity formula, this changes the size
+ * of the communities. Higher resolutions lead to more smaller
+ * communities, lower resolutions lead to fewer larger
+ * communities. (default 1)
+ * @return a pair containing:
+ * 1) unique pointer to dendrogram
+ * 2) modularity of the returned clustering
  *
  */
 template <typename vertex_t, typename edge_t, typename weight_t, bool multi_gpu>
 std::pair<std::unique_ptr<Dendrogram<vertex_t>>, weight_t> louvain(
  raft::handle_t const& handle,
+ std::optional<std::reference_wrapper<raft::random::RngState>> rng_state,
  graph_view_t<vertex_t, edge_t, false, multi_gpu> const& graph_view,
  std::optional<edge_property_view_t<edge_t, weight_t const*>> edge_weight_view,
  size_t max_level = 100,
@@ -779,6 +794,55 @@ void ecg(raft::handle_t const& handle,
  vertex_t ensemble_size,
  vertex_t* clustering);
 
+/**
+ * @brief Computes the ecg clustering of the given graph.
+ *
+ * ECG runs truncated Louvain on an ensemble of permutations of the input graph,
+ * then uses the ensemble partitions to determine weights for the input graph.
+ * The final result is found by running full Louvain on the input graph using
+ * the determined weights. See https://arxiv.org/abs/1809.05578 for further
+ * information.
+ *
+ * @throws cugraph::logic_error when an error occurs.
+ *
+ * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type.
+ * @tparam edge_t Type of edge identifiers. Needs to be an integral type.
+ * @tparam weight_t Type of edge weights. Needs to be a floating point type.
+ * @tparam multi_gpu Flag indicating whether template instantiation should target single-GPU (false)
+ *
+ * @param[in] handle Library handle (RAFT). If a communicator is set in the handle,
+ * @param[in] rng_state The RngState instance holding pseudo-random number generator state.
+ * @param[in] graph_view Input graph view object
+ * @param[in] edge_weight_view View object holding edge weights for @p graph_view.
+ * @param[in] min_weight Minimum edge weight to use in the final call of the clustering
+ * algorithm if an edge does not appear in any of the ensemble runs.
+ * @param[in] ensemble_size The ensemble size parameter
+ * @param[in] max_level (optional) maximum number of levels to run (default 100)
+ * @param[in] threshold (optional) threshold for convergence at each level (default 1e-7)
+ * @param[in] resolution (optional) The value of the resolution parameter to use.
+ * Called gamma in the modularity formula, this changes the size
+ * of the communities. Higher resolutions lead to more smaller
+ * communities, lower resolutions lead to fewer larger
+ * communities. (default 1)
+ *
+ * @return a tuple containing:
+ * 1) Device vector containing clustering result
+ * 2) number of levels of the returned clustering
+ * 3) modularity of the returned clustering
+ *
+ */
+template <typename vertex_t, typename edge_t, typename weight_t, bool multi_gpu>
+std::tuple<rmm::device_uvector<vertex_t>, size_t, weight_t> ecg(
+ raft::handle_t const& handle,
+ raft::random::RngState& rng_state,
+ graph_view_t<vertex_t, edge_t, false, multi_gpu> const& graph_view,
+ std::optional<edge_property_view_t<edge_t, weight_t const*>> edge_weight_view,
+ weight_t min_weight,
+ size_t ensemble_size,
+ size_t max_level = 100,
+ weight_t threshold = weight_t{1e-7},
+ weight_t resolution = weight_t{1});
+
 /**
  * @brief Generate edges in a minimum spanning forest of an undirected weighted graph.
  *

cpp/include/cugraph/detail/collect_comm_wrapper.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023, NVIDIA CORPORATION.
+ * Copyright (c) 2023-2024, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,6 +15,7 @@
  */
 #pragma once
 
+#include <raft/core/device_span.hpp>
 #include <raft/core/handle.hpp>
 #include <rmm/device_uvector.hpp>
 

cpp/include/cugraph/detail/shuffle_wrappers.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021-2023, NVIDIA CORPORATION.
+ * Copyright (c) 2021-2024, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,6 +16,7 @@
 #pragma once
 
 #include <raft/core/handle.hpp>
+#include <raft/random/rng_state.hpp>
 #include <rmm/device_uvector.hpp>
 
 #include <optional>
@@ -138,6 +139,28 @@ shuffle_ext_vertex_value_pairs_to_local_gpu_by_vertex_partitioning(
  rmm::device_uvector<vertex_t>&& vertices,
  rmm::device_uvector<value_t>&& values);
 
+/**
+ * @brief Permute a range.
+ *
+ * @tparam vertex_t Type of vertex identifiers. Needs to be an integral type.
+ *
+ * @param[in] handle RAFT handle object to encapsulate resources (e.g. CUDA stream, communicator,
+ * and handles to various CUDA libraries) to run graph algorithms.
+ * @param[in] rng_state The RngState instance holding pseudo-random number generator state.
+ * @param[in] local_range_size Size of local range assigned to this process.
+ * @param[in] local_start Start of local range assigned to this process.
+ *
+ * @return permuted range.
+ */
+
+template <typename vertex_t>
+rmm::device_uvector<vertex_t> permute_range(raft::handle_t const& handle,
+ raft::random::RngState& rng_state,
+ vertex_t local_start,
+ vertex_t local_range_size,
+ bool multi_gpu = false,
+ bool do_expensive_check = false);
+
 /**
  * @brief Shuffle internal (i.e. renumbered) vertices to their local GPUs based on vertex
  * partitioning.

cpp/src/c_api/louvain.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022-2023, NVIDIA CORPORATION.
+ * Copyright (c) 2022-2024, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -95,18 +95,19 @@ struct louvain_functor : public cugraph::c_api::abstract_functor {
  // could add support in Louvain for std::nullopt as the edge weights behaving
  // as desired and only instantiating a real edge_property_view_t for the
  // coarsened graphs.
- auto [level, modularity] =
- cugraph::louvain(handle_,
- graph_view,
- (edge_weights != nullptr)
- ? std::make_optional(edge_weights->view())
- : std::make_optional(cugraph::c_api::create_constant_edge_property(
- handle_, graph_view, weight_t{1})
- .view()),
- clusters.data(),
- max_level_,
- static_cast<weight_t>(threshold_),
- static_cast<weight_t>(resolution_));
+ auto [level, modularity] = cugraph::louvain(
+ handle_,
+ std::optional<std::reference_wrapper<raft::random::RngState>>{std::nullopt},
+ graph_view,
+ (edge_weights != nullptr)
+ ? std::make_optional(edge_weights->view())
+ : std::make_optional(
+ cugraph::c_api::create_constant_edge_property(handle_, graph_view, weight_t{1})
+ .view()),
+ clusters.data(),
+ max_level_,
+ static_cast<weight_t>(threshold_),
+ static_cast<weight_t>(resolution_));
 
  rmm::device_uvector<vertex_t> vertices(graph_view.local_vertex_partition_range_size(),
  handle_.get_stream());