Added edmonds_blossom_algorithm.py. For maximum matching in the graph. #12043

graphs/edmonds_blossom_algorithm.py

@@ -0,0 +1,208 @@
+from collections import deque
+
+
+class BlossomAuxData:
+    """Class to hold auxiliary data during the blossom algorithm's execution."""
+
+    def __init__(self, queue: deque, parent: list[int], base: list[int],
+                 in_blossom: list[bool], match: list[int], in_queue: list[bool]):
+        self.queue = queue
+        self.parent = parent
+        self.base = base
+        self.in_blossom = in_blossom
+        self.match = match
+        self.in_queue = in_queue
+
+
+class BlossomData:
+    """Class to encapsulate data related to a blossom in the graph."""
+
+    def __init__(self, aux_data: BlossomAuxData, u: int, v: int, lca: int):
+        self.aux_data = aux_data
+        self.u = u
+        self.v = v
+        self.lca = lca
+
+
+class EdmondsBlossomAlgorithm:
+    UNMATCHED = -1  # Constant to represent unmatched vertices
+
+    @staticmethod
+    def maximum_matching(edges: list[list[int]], vertex_count: int) -> list[list[int]]:
+        """
+        Finds the maximum matching in a graph using the Edmonds Blossom Algorithm.
+
+        Args:
+            edges: A list of edges represented as pairs of vertices.
+            vertex_count: The total number of vertices in the graph.
+
+        Returns:
+            A list of matched pairs in the form of a list of lists.
+        """
+        # Create an adjacency list for the graph
+        graph = [[] for _ in range(vertex_count)]
+
+        # Populate the graph with the edges
+        for edge in edges:
+            u, v = edge
+            graph[u].append(v)
+            graph[v].append(u)
+
+        # All vertices are initially unmatched
+        match = [EdmondsBlossomAlgorithm.UNMATCHED] * vertex_count
+        parent = [EdmondsBlossomAlgorithm.UNMATCHED] * vertex_count
+        base = list(range(vertex_count))  # Each vertex is its own base initially
+        in_blossom = [False] * vertex_count
+        in_queue = [False] * vertex_count  # Tracks vertices in the BFS queue
+
+        # Main logic for finding maximum matching
+        for u in range(vertex_count):
+            # Only consider unmatched vertices
+            if match[u] == EdmondsBlossomAlgorithm.UNMATCHED:
+                # BFS initialization
+                parent = [EdmondsBlossomAlgorithm.UNMATCHED] * vertex_count
+                base = list(range(vertex_count))
+                in_blossom = [False] * vertex_count
+                in_queue = [False] * vertex_count
+
+                queue = deque([u])  # Start BFS from the unmatched vertex
+                in_queue[u] = True
+
+                augmenting_path_found = False
+
+                # BFS to find augmenting paths
+                while queue and not augmenting_path_found:
+                    current = queue.popleft()  # Get the current vertex
+                    for y in graph[current]:  # Explore adjacent vertices
+                        # Skip if we're looking at the current match
+                        if match[current] == y:
+                            continue
+
+                        if base[current] == base[y]:  # Avoid self-loops
+                            continue
+
+                        if parent[y] == EdmondsBlossomAlgorithm.UNMATCHED:
+                            # Case 1: y is unmatched; we've found an augmenting path
+                            if match[y] == EdmondsBlossomAlgorithm.UNMATCHED:
+                                parent[y] = current  # Update the parent
+                                augmenting_path_found = True
+                                # Augment along this path
+                                EdmondsBlossomAlgorithm.update_matching(match,
+                                                                        parent,
+                                                                        y)
+                                break
+
+                            # Case 2: y is matched; add y's match to the queue
+                            z = match[y]
+                            parent[y] = current
+                            parent[z] = y
+                            if not in_queue[z]:  # If z is not already in the queue
+                                queue.append(z)
+                                in_queue[z] = True
+                        else:
+                            # Case 3: Both current and y have a parent;
+                            # check for a cycle/blossom
+                            base_u = EdmondsBlossomAlgorithm.find_base(base,
+                                                                       parent,
+                                                                       current,
+                                                                       y)
+                            if base_u != EdmondsBlossomAlgorithm.UNMATCHED:
+                                EdmondsBlossomAlgorithm.contract_blossom(BlossomData(
+                                    BlossomAuxData(queue, parent,
+                                                   base, in_blossom,
+                                                   match, in_queue),
+                                    current, y, base_u))
+
+        # Create result list of matched pairs
+        matching_result = []
+        for v in range(vertex_count):
+            # Ensure pairs are unique
+            if match[v] != EdmondsBlossomAlgorithm.UNMATCHED and v < match[v]:
+                matching_result.append([v, match[v]])
+
+        return matching_result
+
+    @staticmethod
+    def update_matching(match: list[int], parent: list[int], u: int):
+        """
+        Updates the matching based on the augmenting path found.
+
+        Args:
+            match: The current match list.
+            parent: The parent list from BFS traversal.
+            u: The vertex where the augmenting path ends.
+        """
+        while u != EdmondsBlossomAlgorithm.UNMATCHED:
+            v = parent[u]  # Get the parent vertex
+            next_match = match[v]  # Store the next match
+            match[v] = u  # Update match for v
+            match[u] = v  # Update match for u
+            u = next_match  # Move to the next vertex
+
+    @staticmethod
+    def find_base(base: list[int], parent: list[int], u: int, v: int) -> int:
+        """
+        Finds the base of the blossom.
+
+        Args:
+            base: The base array for each vertex.
+            parent: The parent array from BFS.
+            u: One endpoint of the blossom.
+            v: The other endpoint of the blossom.
+
+        Returns:
+            The lowest common ancestor of u and v in the blossom.
+        """
+        visited = [False] * len(base)
+
+        # Mark ancestors of u
+        current_u = u
+        while True:
+            current_u = base[current_u]
+            visited[current_u] = True  # Mark this base as visited
+            if parent[current_u] == EdmondsBlossomAlgorithm.UNMATCHED:
+                break
+            current_u = parent[current_u]
+
+        # Find the common ancestor of v
+        current_v = v
+        while True:
+            current_v = base[current_v]
+            if visited[current_v]:  # Check if we've already visited this base
+                return current_v
+            current_v = parent[current_v]
+
+    @staticmethod
+    def contract_blossom(blossom_data: BlossomData):
+        """
+        Contracts a blossom found during the matching process.
+
+        Args:
+            blossom_data: The data related to the blossom to be contracted.
+        """
+        # Mark vertices in the blossom
+        for x in range(blossom_data.u,
+                       blossom_data.aux_data.base[blossom_data.u] != blossom_data.lca):
+            base_x = blossom_data.aux_data.base[x]
+            match_base_x = blossom_data.aux_data.base[blossom_data.aux_data.match[x]]
+            # Mark the base as in a blossom
+            blossom_data.aux_data.in_blossom[base_x] = True
+            blossom_data.aux_data.in_blossom[match_base_x] = True
+
+        for x in range(blossom_data.v,
+                       blossom_data.aux_data.base[blossom_data.v] != blossom_data.lca):
+            base_x = blossom_data.aux_data.base[x]
+            match_base_x = blossom_data.aux_data.base[blossom_data.aux_data.match[x]]
+            # Mark the base as in a blossom
+            blossom_data.aux_data.in_blossom[base_x] = True
+            blossom_data.aux_data.in_blossom[match_base_x] = True
+
+        # Update the base for all marked vertices
+        for i in range(len(blossom_data.aux_data.base)):
+            if blossom_data.aux_data.in_blossom[blossom_data.aux_data.base[i]]:
+                # Contract to the lowest common ancestor
+                blossom_data.aux_data.base[i] = blossom_data.lca
+                if not blossom_data.aux_data.in_queue[i]:
+                    # Add to queue if not already present
+                    blossom_data.aux_data.queue.append(i)
+                    blossom_data.aux_data.in_queue[i] = True

graphs/tests/test_edmonds_blossom_algorithm.py

@@ -0,0 +1,72 @@
+import unittest
+
+from graphs.edmonds_blossom_algorithm import EdmondsBlossomAlgorithm
+
+
+class EdmondsBlossomAlgorithmTest(unittest.TestCase):
+    def convert_matching_to_array(self, matching):
+        """Helper method to convert a
+        list of matching pairs into a sorted 2D array.
+        """
+        # Convert the list of pairs into a list of lists
+        result = [list(pair) for pair in matching]
+
+        # Sort each individual pair for consistency
+        for pair in result:
+            pair.sort()
+
+        # Sort the array of pairs to ensure consistent order
+        result.sort(key=lambda x: x[0])
+        return result
+
+    def test_case_1(self):
+        """Test Case 1: A triangle graph where vertices 0, 1, and 2 form a cycle."""
+        edges = [[0, 1], [1, 2], [2, 0]]
+        matching = EdmondsBlossomAlgorithm.maximum_matching(edges, 3)
+
+        expected = [[0, 1]]
+        assert expected == self.convert_matching_to_array(matching)
+
+    def test_case_2(self):
+        """Test Case 2: A disconnected graph with two components."""
+        edges = [[0, 1], [1, 2], [3, 4]]
+        matching = EdmondsBlossomAlgorithm.maximum_matching(edges, 5)
+
+        expected = [[0, 1], [3, 4]]
+        assert expected == self.convert_matching_to_array(matching)
+
+    def test_case_3(self):
+        """Test Case 3: A cycle graph with an additional edge outside the cycle."""
+        edges = [[0, 1], [1, 2], [2, 3], [3, 0], [4, 5]]
+        matching = EdmondsBlossomAlgorithm.maximum_matching(edges, 6)
+
+        expected = [[0, 1], [2, 3], [4, 5]]
+        assert expected == self.convert_matching_to_array(matching)
+
+    def test_case_no_matching(self):
+        """Test Case 4: A graph with no edges."""
+        edges = []  # No edges
+        matching = EdmondsBlossomAlgorithm.maximum_matching(edges, 3)
+
+        expected = []
+        assert expected == self.convert_matching_to_array(matching)
+
+    def test_case_large_graph(self):
+        """Test Case 5: A complex graph with multiple cycles and extra edges."""
+        edges = [[0, 1], [1, 2], [2, 3], [3, 4], [4, 5], [5, 0], [1, 4], [2, 5]]
+        matching = EdmondsBlossomAlgorithm.maximum_matching(edges, 6)
+
+        # Check if the size of the matching is correct (i.e., 3 pairs)
+        assert len(matching) == 3
+
+        # Check that the result contains valid pairs (any order is fine)
+        possible_matching_1 = [[0, 1], [2, 5], [3, 4]]
+        possible_matching_2 = [[0, 1], [2, 3], [4, 5]]
+        result = self.convert_matching_to_array(matching)
+
+        # Assert that the result is one of the valid maximum matchings
+        assert result in (possible_matching_1, possible_matching_2)
+
+
+if __name__ == "__main__":
+    unittest.main()