fix(community): async label_propagation with oscillation detection#3
Merged
Conversation
The current label_propagation implementation uses synchronous batch updates: it snapshots the community map at the start of each pass, computes new labels for all nodes from that snapshot, then replaces the map. This form is vulnerable to flip-flop oscillation on graphs with high-degree hub nodes. Tied candidate scores cause groups of nodes to swap labels symmetrically every iteration, which repeats forever and blocks the caller indefinitely. Observed on a real knowledge graph with 48 entities and a central hub connected to 14+ peers: 19 nodes kept flipping between two states forever. The main `while True:` loop never terminated. Replace with the Raghavan et al. (2007) asynchronous form described in "Near linear time algorithm to detect community structures in large-scale networks": 1. Visit nodes in a fresh RANDOM order each pass (deterministic seed for reproducibility). 2. For each node, read the CURRENT community map and update it IN PLACE before moving to the next node. Neighbors immediately see the new label, which breaks the ping-pong pattern. 3. Break ties deterministically by preferring the higher community id, and only move when a candidate strictly improves on the current support — so well-connected nodes stay put under ties. 4. Terminate on natural convergence (no changes in a full pass). As a safeguard, also break if the exact community_map repeats within a short recent window — async LPA converges in O(log n) on real-world graphs but a cycle detector covers any edge case. Verified on synthetic graphs (disconnected, stars, complete graphs, rings, bridged stars, barbells) and a real-world pathological case (hub + heavy/light satellites) — all converge in milliseconds and produce sensible partitions. Adds tests/utils/maintenance/test_community_operations.py with 10 unit tests covering the regression case and common graph shapes. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The current label_propagation implementation uses synchronous batch updates: it snapshots the community map at the start of each pass, computes new labels for all nodes from that snapshot, then replaces the map. This form is vulnerable to flip-flop oscillation on graphs with high-degree hub nodes. Tied candidate scores cause groups of nodes to swap labels symmetrically every iteration, which repeats forever and blocks the caller indefinitely.
Observed on a real knowledge graph with 48 entities and a central hub connected to 14+ peers: 19 nodes kept flipping between two states forever. The main
while True:loop never terminated.Replace with the Raghavan et al. (2007) asynchronous form described in "Near linear time algorithm to detect community structures in large-scale networks":
Verified on synthetic graphs (disconnected, stars, complete graphs, rings, bridged stars, barbells) and a real-world pathological case (hub + heavy/light satellites) — all converge in milliseconds and produce sensible partitions.
Adds tests/utils/maintenance/test_community_operations.py with 10 unit tests covering the regression case and common graph shapes.
Summary
Brief description of the changes in this PR.
Type of Change
Objective
For new features and performance improvements: Clearly describe the objective and rationale for this change.
Testing
Breaking Changes
If this is a breaking change, describe:
Checklist
make lintpasses)Related Issues
Closes #[issue number]