Add Hopcroft-Karp algorithm for maximum bipartite matching - #15293
Conversation
algorithms-keeper
Bot
added
awaiting reviews
![algorithms-keeper[bot]](https://avatars.githubusercontent.com/in/235834?s=60&v=4){kind=small}
There was a problem hiding this comment.
Click here to look at the relevant links ⬇️
🔗 Relevant Links
Repository:
Python:
Automated review generated by algorithms-keeper. If there's any problem regarding this review, please open an issue about it.
algorithms-keeper commands and options
algorithms-keeper actions can be triggered by commenting on this PR:
@algorithms-keeper reviewto trigger the checks for only added pull request files@algorithms-keeper review-allto trigger the checks for all the pull request files, including the modified files. As we cannot post review comments on lines not part of the diff, this command will post all the messages in one comment.NOTE: Commands are in beta and so this feature is restricted only to a member or owner of the organization.
| # distance_map stores the BFS level/distance from free vertices in U | ||
| distance_map: dict[T | None, float] = {} | ||
|
|
||
| def breadth_first_search() -> bool: |
There was a problem hiding this comment.
As there is no test file in this pull request nor any test function or class in the file graphs/hopcroft_karp.py, please provide doctest for the function breadth_first_search
| # Termination condition: True if an augmenting path was found, False otherwise | ||
| return distance_map[None] != math.inf | ||
|
|
||
| def depth_first_search(left_vertex: T | None) -> bool: |
There was a problem hiding this comment.
As there is no test file in this pull request nor any test function or class in the file graphs/hopcroft_karp.py, please provide doctest for the function depth_first_search
There was a problem hiding this comment.
🟡 Changes recommended
The implementation has unresolved correctness and recursion-limit issues.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
Adds a generic Hopcroft–Karp algorithm for maximum cardinality matching in unweighted bipartite graphs.
Changes:
- Implements BFS layering and DFS augmentation.
- Adds validation, documentation, reference link, and doctests.
File summaries
| File | Summary | Findings |
|---|---|---|
graphs/hopcroft_karp.py |
New Hopcroft–Karp implementation. | Critical (3 votes): None sentinel can collide with valid vertices. Moderate (3 votes): recursive DFS can exceed Python’s recursion limit. |
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| # pair_right[v] stores the vertex in U matched to v in V (or None if free) | ||
| pair_right: dict[T, T | None] = dict.fromkeys(right_vertices) | ||
| # distance_map stores the BFS level/distance from free vertices in U | ||
| distance_map: dict[T | None, float] = {} |
| # Augmentation Condition: Only step forward along the layered DAG | ||
| if distance_map.get(matched_left, math.inf) == distance_map[ | ||
| left_vertex | ||
| ] + 1.0 and depth_first_search(matched_left): |
…tinel, iterative DFS, and tests
algorithms-keeper
Bot
removed
the
require tests
|
ON HOLD: Our focus is on merging or closing old pull requests before October 1st. |
|
@priya-sundaram-dev, please review. |
priya-sundaram-dev
left a comment
priya-sundaram-dev
left a comment
There was a problem hiding this comment.
Nice work — this is a clean, well-documented implementation. A few things I checked:
- Correctness: I ran the matching against an independent Kuhn's-algorithm reference on 2000 randomly generated bipartite graphs (0–5 vertices per side, random edges). Every result was a valid matching (no shared right vertices, every edge real) and of maximum cardinality.
- Iterative DFS: the explicit-stack approach and the
chain_length = 1500test are a good call — a recursive version would blow the stack on deep alternating paths. Verified noRecursionError. - Docs/doctests: all 29 doctests pass, and the module docstring on Berge's Lemma / the BFS-layering + DFS-augmentation phases is genuinely educational, which fits this repo well.
- Edge cases covered: empty graph, isolated vertices, competing left vertices, disjoint-partition and
None-vertex validation.
LGTM. Thanks for the thorough writeup, @Clear20-22.
algorithms-keeper
Bot
removed
the
awaiting reviews
Describe your change
Add the Hopcroft–Karp algorithm ($O(|E|\sqrt{|V|})$ time using alternating BFS layering and DFS augmenting paths.
graphs/hopcroft_karp.py) for finding maximum cardinality matchings in unweighted bipartite graphs inChecklist