Add Louvain community detection algorithm by Becheler · Pull Request #453 · boostorg/graph

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

Done 👍🏽
I defined:

GraphPartitionQualityFunctionConcept

GraphPartitionQualityFunctionIncrementalConcept

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.

Done 👍🏽

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

…ation paths

joaquintides · 2026-02-20T10:39:16Z

doc/louvain_clustering.html

+  Weights must be non-negative.
+</blockquote>
+
+IN: <tt>URBG&amp;&amp; gen</tt>


Would it make sense to provide a default arg for this?

I am not sure what it would be. And also it would differ from what i've seen in random.hpp utilities:
https://github.com/boostorg/graph/blob/3131c24630e42c79b43c1f32558041c219ab84b8/include/boost/graph/random.hpp

joaquintides · 2026-02-20T10:40:24Z

doc/louvain_clustering.html

+  (e.g.&nbsp;<tt>std::mt19937</tt>).
+</blockquote>
+
+IN: <tt>weight_type min_improvement_inner</tt>


Is Louvain guaranteed to converge (i.e. to eventually stop)? If this is not clear, does it make sense to provide additional hard limits on the number of inner/outer iterations?

If I understand well it's guaranteed to terminate in theory:

the quality (modularity) is monotically non-decreasing through the algorithm

becasue the algorithm is supposed to only accept nodes moves and community merges that strictly improve (or does not decrease in some variations) the quality of the partition

modularity is bounded <=1

the number of partition is finite

That being said there is the case of large graphs and the trouble on floating point precision.

For very large graphs maybe it would make sense to have some sense of async task: "please dear louvain, aggregate this for some time and when I'm done with waiting give me the last aggreagated graph you had". But that sounds like a very different interface ?

The current API is still more flexible than igraph and genlouvain, that do not offer parametrization of the stopping condition (igraph has 0 for inner and outer thresholds and genlouvain has 10-6, fixed)

Am i making sense ?

joaquintides · 2026-02-20T10:41:30Z

doc/louvain_clustering.html

+
+<H3>Parameters</H3>
+
+IN: <tt>const Graph&amp; g</tt>


The algorithm has the additional requirement that vertices are copyable, hashable etc., as they're internally stored in unordered_sets.

You're right. I have been changing the vertices handling in this aspect because it was not friendly with some types of graphs. The interface now takes a VertexIndexMap but I still have to commit those changes, sorry 😓
I will update the documentation in that sense once I merged the new stuff

joaquintides · 2026-02-20T11:16:46Z

include/boost/graph/louvain_clustering.hpp

+#include <boost/unordered/unordered_flat_set.hpp>
+#include <boost/container_hash/hash.hpp>
+#include <algorithm>
+#include <iostream>


Is this #include needed?

Hem. Nope 😄

joaquintides · 2026-02-20T11:21:50Z

include/boost/graph/louvain_clustering.hpp

+#include <iostream>
+
+// Hash specialization for std::pair to use with boost::unordered containers
+namespace std {


Big no-no :-)

It's forbidden to specialize hash for types other than user-defined ones, which std::pair is not.

Boost.Unordered does not use std::hash by default, but boost::hash. Your temp_edge_weights works because boost::hash works off the shelf with pairs, so the std specialization is not even used.

Oooooh 🥲 Thank you, will remove

joaquintides · 2026-02-20T11:25:59Z

include/boost/graph/louvain_clustering.hpp

+    return Q_new;
+}
+
+/// @brief Fast version, requires the QualityFunction to implement GraphPartitionQualityFunctionIncrementalConcept


Looks like this comment is wrong, this version does not require the quality function to be incremental.

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 11 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

incremental versus non-incremental concepts

28721e1

fix wrong namespace

c5c9ac4

fix unused variables in concepts

24002db

incremental and non incremental metrics can lead to different optimiz…

a02bc0f

…ation paths

Trigger CI

0034d3f

incremental and non incremental metrics can lead to different optimiz…

e8760cf

…ation paths

fix: no hierarchy_t, free unfold function

7180cd6

docs

fb61051

joaquintides reviewed Feb 20, 2026

View reviewed changes

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


		<H3>Parameters</H3>

		IN: <tt>const Graph& g</tt>

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!

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

Uh oh!

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