Maximum bipartite matching

[mahdiehmalekian]

Code for finding maximum bipartite matching via the Hopcroft-Karp algorithm.

AI use: I used AI to generate the code, checked the code myself.

[randomir]

The implementation looks correct (when compared to the pseudo-code on Wikipedia), apart from a couple of pruning condition checks missing in your implementation, in the BFS and the DFS functions -- resulting in a greater runtime complexity in the worst case.

But my main question is what's the benefit of your implementation over the existing one in NetworkX, hopcroft_karp_matching()?

[mahdiehmalekian]

Re. the missing pruning step, thank you for flagging it. I added it in dbda40f

Re. your main question, great point.
This is indeed the same algorithm as networkx.bipartite.hopcroft_karp_matching (except for the greedy warm-start and the BFS shortest-path prune added in dbda40f in this implementation). However, the main advantage of this implementation is for usage in the clique embedder in minorminer where this function is called in a hot loop where the inputs are already in the exact form this function needs. The two vertex sets are known by construction (vertical vs horizontal runs in the clique embedder), and the edges are already a plain adjacency dict. Using networkx.bipartite.hopcroft_karp_matching instead would require constructing a nx.Graph (node/edge insertion, attribute dicts) on every call, passing the bipartition we already know as top_nodes, and then inverting the symmetric result back into the one-directional {vertical run: horizontal run} map our caller expects. This custom version skips all of that and returns the exact contract the caller consumes.

[randomir]

Re. your main question, great point. This is indeed the same algorithm as networkx.bipartite.hopcroft_karp_matching (except for the greedy warm-start and the BFS shortest-path prune added in dbda40f in this implementation). However, the main advantage of this implementation is for usage in the clique embedder in minorminer where this function is called in a hot loop where the inputs are already in the exact form this function needs. The two vertex sets are known by construction (vertical vs horizontal runs in the clique embedder), and the edges are already a plain adjacency dict. Using networkx.bipartite.hopcroft_karp_matching instead would require constructing a nx.Graph (node/edge insertion, attribute dicts) on every call, passing the bipartition we already know as top_nodes, and then inverting the symmetric result back into the one-directional {vertical run: horizontal run} map our caller expects. This custom version skips all of that and returns the exact contract the caller consumes.

Perhaps worth mentioning that in the docs?

[mahdiehmalekian]

Reverted formatting where applicable and added a note comparing with networkx.bipartite.hopcroft_karp_matching .

[randomir]

Thank you @mahdiehmalekian for addressing all the review comments.

And just to build a strong(er) case for code duplication (a code that's already tested and maintained by the networkx team) -- could you please run a quick benchmark against the nx implementation in the clique embedder hot loop -- just to get a sense if this code provides a 10% or a 10x improvement?

Also, could you please a release note?