Add Louvain community detection algorithm #453

Becheler · 2026-02-02T13:01:23Z

Implement #447

Multi-level modularity optimization following Blondel et al (2008)
Supports custom quality functions (other than modularity) with policy-based design (extensions to come to propose alternative quality functions to match gen-louvain)
Incremental quality tracking
Lazy rollback
Vertex shuffling
Competitive with established implementations (I will work on making the benchmarks reproducible)

But:

documentation is not ready
example is not ready
just realized I forgot to test with different graph types + boost concepts

jeremy-murphy · 2026-02-04T22:53:34Z

Not sure why this error is occurring only for OSX 11.7 C++14. I assume this is not specific to your code.

In file included from ../../../boost/container/detail/operator_new_helpers.hpp:26:
../../../boost/container/detail/aligned_allocation.hpp:87:26: error: no member named 'aligned_alloc' in the global namespace; did you mean 'aligned_allocate'?
   return rounded_size ? ::aligned_alloc(al, rounded_size) : 0;
                         ^~~~~~~~~~~~~~~
                         aligned_allocate
../../../boost/container/detail/aligned_allocation.hpp:77:14: note: 'aligned_allocate' declared here
inline void* aligned_allocate(std::size_t al, std::size_t sz)
             ^
1 error generated.

jeremy-murphy

Just a few comments, more later.

jeremy-murphy · 2026-02-04T22:56:15Z

include/boost/graph/louvain_clustering.hpp

+// Revision History:
+//


I know embedded revision histories were a thing in the past, but I would prefer to keep all this metadata in git.

I did not like it either, I'm glad you don't ahah :)

Done 👍🏽

jeremy-murphy · 2026-02-04T22:59:53Z

include/boost/graph/louvain_clustering.hpp

+    std::map<VertexDescriptor, WeightType> internal_weights;
+    std::map<VertexDescriptor, std::set<VertexDescriptor>> vertex_mapping;


We generally try to avoid hard-coding the choice of data structure, especially std::map and std::set, so instead of templating VertexDescriptor and WeightType we should template the whole map type, so users can use boost::unordered_map or some other kind of property map of their own choice.

Mhhh I see. I felt it was not in the BGL spirit to do so, and Joaquin also mentioned it, but I was not sure how to solve it without making the API heavy. Can we default to a concrete type to simplify user's experience ? Also, is it ok to use boost::unordered_map if it adds the constraint of key_type being hashable ? That was my idea behind using std::map

Oh yes, we can still (and should) make the user experience nice with defaults. That's the great thing, we get both benefits, the cost is more work on the part of the library authors. :)
Again, I think astar is an example, but instead of using param = arg in the function definition, make an overload, like so:

auto user_friendly_foo(graph const &g) { ConcreteA a; ConcreteB b; return generic_foo(g, a, b); }

Sorry, typing on my phone, so please ignore random syntax errors.

Umm, yeah, we probably shouldn't add new constraints into the default interface. Users will too easily assume that the constraint is mandatory.
So maybe use boost::flat_map as the default and users can always use a hash map if they want to.

jeremy-murphy · 2026-02-04T23:05:44Z

include/boost/graph/louvain_clustering.hpp

+    std::set<community_type> unique_communities;
+    std::map<community_type, vertex_descriptor> comm_to_vertex;
+    std::map<vertex_descriptor, std::set<vertex_descriptor>> vertex_to_originals;


These should almost certainly be input parameters taken by non-const reference so that the user a) decides their type and b) automatically gets their value at the end.

So they gain access to the whole hierarchy. Ufff it's a lot of guts leaking out haha
Will do, and tell you in case of problemsm thanks again for your time !

I could be wrong. But have a look at the astar API for some examples of prior art.

And on second thought, this is not a priority, we can always do it later. Getting it correct and fast are higher priorities.

this was not supposed to be commited :)

joaquintides · 2026-02-06T18:27:26Z

include/boost/graph/louvain_clustering.hpp

+//=======================================================================
+// Copyright 2026 Becheler Code Labs for C++ Alliance
+// Authors: Arnaud Becheler
+//


You retain the copyright, so no need to mention the C++ Alliance. Also, is "Becheler Code Labs" a real legal entity? If this is not the case, then assigning (C) to your physical person would be best.

Done 👍🏽

joaquintides · 2026-02-06T18:48:24Z

include/boost/graph/louvain_clustering.hpp

+    auto unfold(const CommunityMap& final_partition) const
+    {
+        assert(!empty());
+


Not sure what the BGL convention is, Boost libs generally use BOOST_ASSERT instead.

I don't really mind, but yeah, better to follow whatever is common practice.

Done 👍🏽

joaquintides · 2026-02-06T18:50:51Z

include/boost/graph/louvain_clustering.hpp

+            current_nodes.insert(kv.first);
+
+            // From coarse to fine
+            for (int level = size() - 1; level >= 0; --level) {


Type mismatch, size() is a std::size_t. More idiomatic, but maybe not to your taste:

for(auto level = size(); level--; ) {

Done 👍🏽

joaquintides · 2026-02-06T19:05:01Z

include/boost/graph/louvain_clustering.hpp

+
+template <typename Graph, typename CommunityMap, typename WeightMap, typename QualityFunction = newman_and_girvan>
+typename property_traits<WeightMap>::value_type
+louvain_local_optimization(


Is this function supposed to be public?

I was not too sure, as it can theoretically be used as a one pass optimization step. But you're right it's obviously not the main usage, so I move it to details :)

Done 👍🏽

joaquintides · 2026-02-07T09:41:45Z

include/boost/graph/louvain_quality_functions.hpp

+// L_c = internal edge weight for community c
+// k_c = sum of degrees in community c
+// m = total edge weight / 2
+struct newman_and_girvan


If users can provide their own quality function other than newman_and_girvan, you probably need to define a concept LouvainQuality of sorts. Take a look at how's done at

https://github.com/boostorg/graph/blob/develop/include/boost/graph/astar_search.hpp#L56

joaquintides · 2026-02-07T10:30:22Z

include/boost/graph/louvain_clustering.hpp

+    bool has_rolled_back = false;
+
+    // Randomize vertex order once
+    std::mt19937 gen(seed);


This sould be made generic and passed by the user (with a default arg) as a URGB&&.

Done 👍🏽

joaquintides · 2026-02-07T10:34:17Z

include/boost/graph/louvain_quality_functions.hpp

+// L_c = internal edge weight for community c
+// k_c = sum of degrees in community c
+// m = total edge weight / 2
+struct newman_and_girvan


Is this modularity thing a general concept or does it apply to Louvain only?

This is a yes and no situation.

The modularity can be used outside of louvain to assess partition quality of a graph.

But the current implementation with incremental computations (remove, insert, gain) is particularly suited for Louvain.

Making it generally useful would require to disentangle the two aspects.

But I would rather do it in a clustering folder so we can have:

include/boost/graph/clustering/ ├── quality_functions.hpp # 10 incremental metrics/criterions for gen-louvain ├── label_propagation.hpp # another clustering method (future work) ├── leiden.hpp # Leiden algorithm (future work) ├── louvain.hpp # Louvain algorithm ├── girvan_newman.hpp # Edge betweenness clustering (currently in bc_clustering.hpp)

jeremy-murphy

Couple more requests, still going...

jeremy-murphy · 2026-02-08T06:15:10Z

include/boost/graph/louvain_clustering.hpp

+
+// Track hierarchy of aggregation levels for unfolding partitions.
+template <typename VertexDescriptor>
+struct hierarchy_t


Only one data member and no real invariants to speak off suggests that you don't really need this type.
I think unfold could be a free function, maybe in a private namespace depending on how reusable it is, that takes levels and final_partition as parameters.

By the way, please only use the _t suffix for type aliases, not for names of classes.

jeremy-murphy · 2026-02-08T08:04:51Z

include/boost/graph/louvain_clustering.hpp

+    auto unfold(const CommunityMap& final_partition) const
+    {
+        assert(!empty());
+


I don't really mind, but yeah, better to follow whatever is common practice.

…, type mismatch in for loop

Becheler added 3 commits February 2, 2026 13:48

Add Louvain clustering algorithm

374db7b

adding louvain tests to jamfile

6ef3267

add some comments

76efd88

jeremy-murphy self-assigned this Feb 4, 2026

jeremy-murphy added the enhancement label Feb 4, 2026

jeremy-murphy reviewed Feb 4, 2026

View reviewed changes

Becheler added 2 commits February 5, 2026 00:45

Delete scratch/benchmark/run_benchmark.sh

de9b6a8

this was not supposed to be commited :)

Delete scratch/benchmark/bgl_louvain.cpp

385e8c8

this was not supposed to be commited :)

joaquintides reviewed Feb 6, 2026

View reviewed changes

joaquintides reviewed Feb 7, 2026

View reviewed changes

jeremy-murphy requested changes Feb 8, 2026

View reviewed changes

Becheler added 3 commits February 9, 2026 16:03

PR review: fixed copyright, local optimization visibility, assertions…

78d9225

…, type mismatch in for loop

fix: URGB made generic

422d376

adding LouvainQualityFunctionConcept

6b278b8

		std::map<VertexDescriptor, WeightType> internal_weights;
		std::map<VertexDescriptor, std::set<VertexDescriptor>> vertex_mapping;

Add Louvain community detection algorithm #453

Are you sure you want to change the base?

Add Louvain community detection algorithm #453

Conversation

Becheler commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jeremy-murphy commented Feb 4, 2026

Uh oh!

jeremy-murphy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jeremy-murphy Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joaquintides Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joaquintides Feb 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joaquintides Feb 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Becheler Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jeremy-murphy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Becheler commented Feb 2, 2026 •

edited

Loading

jeremy-murphy Feb 8, 2026 •

edited

Loading

joaquintides Feb 6, 2026 •

edited

Loading

joaquintides Feb 7, 2026 •

edited

Loading

joaquintides Feb 7, 2026 •

edited

Loading

Becheler Feb 9, 2026 •

edited

Loading